Alerting

Alerting

secwatch pushes high-severity events to Discord via an incoming webhook. Everything it detects is always on the dashboard and in the database — alerting is just the push channel for the things worth interrupting you.

Set up a Discord webhook

1. In Discord, on the channel you want alerts in: Edit Channel → Integrations → Webhooks → New Webhook → Copy Webhook URL.
2. Give the URL to secwatch. Three ways, pick one:

A — a secrets file (recommended; keeps the secret out of your config):

cp discord-webhook.env.example .secrets/discord-webhook.env
chmod 600 .secrets/discord-webhook.env
# paste the URL after SECWATCH_DISCORD_WEBHOOK_URL=

# secwatch.yaml
alerting:
  discord_webhook_file: /path/to/.secrets/discord-webhook.env
  discord_webhook_file_key: SECWATCH_DISCORD_WEBHOOK_URL

secwatch also checks ./.secrets/discord-webhook.env by default, so if you use that path you can omit the discord_webhook_file line entirely.

B — inline in the config:

alerting:
  discord_webhook_url: "https://discord.com/api/webhooks/..."

C — environment variable: SECWATCH_DISCORD_WEBHOOK_URL=https://...

Keep the webhook URL secret — anyone with it can post to that channel. Put it in a gitignored file (like .secrets/), never commit it. secwatch coexists fine with other integrations (bots, other webhooks) in the same channel.

What alerts (and what doesn't)

Only events at or above SECWATCH_ALERT_MIN_SEVERITY (default high) push an alert, and each (ip, rule) has a cooldown so you aren't spammed by the same thing repeatedly.

Quieting routine scanner noise

Every public host gets a constant stream of opportunistic scanning — probes for .env/.git/wp-config.php, path scans, floods, hits on /admin that get a 403. secwatch bans and records all of it, but alerting on each one is pure noise that buries the events that actually matter (host/EDR activity, a probe that succeeded, credential stuffing).

So these rules ban + log but don't push a Discord alert by default:

alerting:
  quiet_rules: [secret_probe, scan, flood, privileged_access]
  quiet_except_private: true   # ...but DO alert if the source is internal/LAN

• quiet_except_private: true means a quiet rule still alerts when the source is a private/internal IP — a probe from inside your network could be lateral movement, and that's worth hearing about immediately.
• Set quiet_rules: [] to alert on everything (the old behavior).
• Everything not in the list still alerts: credential stuffing, a vuln probe that returned 2xx, new egress/C2, all host/EDR/FIM events, CVE-KEV findings, config-integrity changes, edge-silence, and dashboard brute-force.

The principle: banworthy ≠ alertworthy. A blocked opportunistic probe is the former, not the latter.

Delivery notes

• Discord requires a User-Agent header and rejects requests without one with a 403 — secwatch sends secwatch/0.1, so this only bites you if you test the webhook by hand with a bare curl/urllib call (add a UA and you'll get the expected 204).
• A failed webhook post never crashes secwatch — it logs and moves on.