Alerts to a JSON webhook, with a cooldown and an hourly summary (closes #26)

SWWAF_ALERT_WEBHOOK_URL gets one JSON POST per alert, in SPEC.md's
schema, with SWWAF_ALERT_WEBHOOK_HEADERS: ban and permanent_ban, with
the ban's notes, in observe mode too, marked mode observe and worked
out only when the alert would be sent; source_failure for GeoJS;
file_error for a rule or state file with an error. SWWAF_ALERT_EVENTS
chooses; SWWAF_ALERT_COOLDOWN holds back repeats by netblock, file or
source; past SWWAF_ALERT_MAX_PER_HOUR the hour ends in one summary. A
bounded queue, retried with backoff, holds up no request; a 4xx other
than 408 and 429 gives the alert up. alerts.json keeps the queue, the
cooldowns and the hour. Nothing shows the URL's path or query.

Judgement call: the summary's event is summary, which SPEC.md omits.
Judgement call: an admin's ban raises no alert.

Model: opus-5-5

internal/proxy/bans.go

@@ -4,6 +4,7 @@ import (
 	"net/netip"
 	"time"
 
+	"sneak.berlin/go/smallwebwaf/internal/alerts"
 	"sneak.berlin/go/smallwebwaf/internal/bans"
 	"sneak.berlin/go/smallwebwaf/internal/requestlog"
 	"sneak.berlin/go/smallwebwaf/internal/rules"
@@ -16,18 +17,25 @@ func (rq *request) banResponse(action string) *refusal {
 }
 
 // banned reports whether a ban on a netblock the client is in covers the
-// request at now, and notes for the log line when that ban ends.
+// request at now, and notes for the log line when that ban ends. A
+// request that makes the ban permanent, or in observe mode would have,
+// raises the alert for it.
 func (rq *request) banned(now time.Time) bool {
 	check := rq.h.ledger.Check
 	if rq.h.config.Observe {
-		check = rq.h.ledger.Find // in observe mode the ban refuses nothing
+		check = rq.h.ledger.Find // the ban refuses nothing, and stays as it is
 	}
 
-	ban, banned := check(rq.client, now)
+	ban, banned, madePermanent := check(rq.client, now)
 	if banned {
 		rq.line.BanExpires = banExpires(ban)
 	}
 
+	if madePermanent {
+		ban.Expires = time.Time{} // the ban made permanent, which Find leaves as it is
+		rq.alertBan(ban)
+	}
+
 	return banned
 }
 
@@ -35,7 +43,8 @@ func (rq *request) banned(now time.Time) bool {
 // client's counts for the log line, and reports whether the request takes
 // the client over a limit. In enforce mode such a request bans the
 // client's netblock, and sets the client's counters back to zero; in
-// observe mode it does neither.
+// observe mode it does neither, and raises the alert for the ban it would
+// have made, if that alert would be sent.
 func (rq *request) limitBroken(now time.Time) bool {
 	group := clientGroup(rq.client)
 
@@ -49,41 +58,122 @@ func (rq *request) limitBroken(now time.Time) bool {
 	rq.line.LimitHit = hit.Window
 	rq.line.Offence = requestlog.OffenceLimit
 
-	if rq.h.config.Observe {
+	netblock := rq.h.netblock(rq.client)
+	if rq.h.config.Observe && !rq.wouldAlertBan(netblock, now, bans.CauseLimit) {
 		return true
 	}
 
-	netblock := rq.h.netblock(rq.client)
-	ban := rq.h.ledger.BanForLimit(netblock, now, bans.Notes{
+	notes := bans.Notes{
 		Country:  rq.line.Country,
 		Limit:    hit.Limit,
 		Window:   hit.Window,
 		Count:    hit.Requests,
 		Request:  rq.noted(now),
 		Requests: rq.netblockRequests(netblock),
-	})
+	}
+
+	if rq.h.config.Observe {
+		ban, wouldBan := rq.h.ledger.WouldBanForLimit(netblock, now, notes)
+		if wouldBan {
+			rq.alertBan(ban)
+		}
+
+		return true
+	}
+
+	ban, made := rq.h.ledger.BanForLimit(netblock, now, notes)
 	rq.h.limiter.Reset(group)
 	rq.line.BanExpires = banExpires(ban)
 
+	if made {
+		rq.alertBan(ban)
+	}
+
 	return true
 }
 
 // banForAttack bans the client's netblock at now for a clear sign of
-// attack, the match of rule, a ban rule.
+// attack, the match of rule, a ban rule. In observe mode it makes no ban,
+// and raises the alert for the ban it would have made, if that alert
+// would be sent.
 func (rq *request) banForAttack(now time.Time, rule rules.Rule) {
 	netblock := rq.h.netblock(rq.client)
-	ban := rq.h.ledger.BanForAttack(netblock, now, bans.Notes{
+	if rq.h.config.Observe && !rq.wouldAlertBan(netblock, now, bans.CauseAttack) {
+		return
+	}
+
+	notes := bans.Notes{
 		Country:  rq.line.Country,
 		RuleID:   rule.ID,
 		Target:   rule.Target,
 		Request:  rq.noted(now),
 		Requests: rq.netblockRequests(netblock),
-	})
+	}
+
+	if rq.h.config.Observe {
+		ban, wouldBan := rq.h.ledger.WouldBanForAttack(netblock, now, notes)
+		if wouldBan {
+			rq.alertBan(ban)
+		}
+
+		return
+	}
+
+	ban, made := rq.h.ledger.BanForAttack(netblock, now, notes)
 	rq.line.BanExpires = banExpires(ban)
+
+	if made {
+		rq.alertBan(ban)
+	}
 }
 
-// noted is the request, refused at now with SWWAF_BAN_RESPONSE, as the
-// notes of the ban it makes keep it.
+// wouldAlertBan reports whether the alert for a ban on netblock for cause
+// made at now would be sent. In observe mode the ban the request would
+// have made is worked out only then, at most once per
+// SWWAF_ALERT_COOLDOWN and never with no webhook set: its notes count the
+// netblock's requests, which can mean going through every client.
+func (rq *request) wouldAlertBan(
+	netblock netip.Prefix, now time.Time, cause string,
+) bool {
+	event := alerts.EventBan
+	if rq.h.ledger.WouldBePermanent(netblock, now, cause) {
+		event = alerts.EventPermanentBan
+	}
+
+	return rq.h.alerts.WouldSend(event, netblock)
+}
+
+// alertBan raises the alert for ban, which the request made, or made
+// permanent: permanent_ban for a permanent ban, ban for another. Its
+// detail gives the ban's cause, when it ends, and its notes, and in
+// observe mode, where ban is the ban that would have been made, or made
+// permanent, mode, observe.
+func (rq *request) alertBan(ban bans.Ban) {
+	event := alerts.EventBan
+	if ban.Permanent() {
+		event = alerts.EventPermanentBan
+	}
+
+	detail := map[string]any{
+		"cause": ban.Cause, "ban_expires": banExpires(ban), "notes": ban.Notes,
+	}
+	if rq.h.config.Observe {
+		detail["mode"] = "observe"
+	}
+
+	rq.h.alerts.Raise(alerts.Alert{
+		Event:    event,
+		Client:   rq.client,
+		Netblock: ban.Netblock,
+		Country:  ban.Notes.Country,
+		Reason:   ban.Reason,
+		Detail:   detail,
+	})
+}
+
+// noted is the request, refused at now with SWWAF_BAN_RESPONSE, or in
+// observe mode as it would have been, as the notes of the ban it makes
+// keep it.
 func (rq *request) noted(now time.Time) bans.Request {
 	return bans.Request{
 		Time:      now,