What is in an alert mail, and how do digests and rate limits work?

Notification is deliberately asymmetric: what is certain and urgent arrives immediately, what is uncertain arrives collected.

Immediate mail, digest mail

• malicious — an administrator mail goes out immediately. A signature or hash hit is evidence, and evidence should not wait for a schedule.
• suspicious — collected into a digest. Heuristic findings only report by default, and a stream of single mails about arguable findings is the fastest way to train an administrator to ignore them.
• Customer mail — optional, through the CyberPanel contact address of the account.
• Webhooks — restricted to an allowlist of targets.

Which of these apply in a given scope is the notify.targets policy key, and like every policy it can be set globally, per account or per domain.

What an alert contains

Enough to decide without logging in: the verdict, the site and account, the object, the engine that produced the hit and — for rule-based findings — the rule's author, source and licence attribution where the rule provides them. That attribution is a licence obligation for some third-party rule sets, which is why it travels into the mail as well as into the panel.

What it does not contain: file contents, secrets or customer data beyond the identifying metadata. Logs and mail are built on the same principle as the rest of the product — no file leaves your server.

Rate limits, and why they exist

A compromised account can produce hundreds of findings in a minute, and an unbounded notifier turns that into an unbounded mail flood — which gets your own server rate-limited by the receiving side, exactly when you need the mail to arrive. So notifications are aggregated: repeated findings of the same kind on the same scope collapse into one message with a count, and suspicious findings go into the periodic digest instead of individual mail.

The same idea governs licence warnings: in the grace state you get one administrator notification per day, not one per failed renewal attempt.

Alert on metrics too, not only on mail

Mail is for humans; metrics are for monitoring. Health and metrics are available in Prometheus text format on a local socket:

shelltrap metrics
shelltrap health

Worth an alert rule, from our own observation checklist: watcher overflows near zero, queue age under 60 seconds in steady state, clean dominating the verdict spread, zero worker restarts, stable worker memory over days, a stable feed age, and an unbroken audit chain. Stop and investigate if overflows persist, queue age exceeds ten minutes, workers restart in a loop, worker RSS grows without bound, or customers complain about I/O load.

Turning the volume down properly

If a specific finding class is noisy on your host, the answer is an ignore rule or a per-domain policy, not a mail filter. A mail filter hides the finding from you; an ignore rule suppresses the action while the finding stays on record.