Anomaly thresholds: alerts for unusual traffic, nothing refused (closes #101)

SWWAF_ANOMALY_CLIENT_*, _NET_*, _ASN_*, _TOTAL_* and SWWAF_WATCH_* with
SWWAF_WATCH_NETS: requests and bytes per minute and per hour, each off by
default. Every request but the health check is counted, allow-listed and
exempt ones included, in the buckets the rate limits use; a count over its
threshold raises an anomaly alert, with a cooldown per scope. At most
20,000 counters, kept in alerts.json. A per-AS-number threshold with
lookups off, or a malformed SWWAF_WATCH_NETS, stops the start.

Judgement call: refused requests are counted too.
Judgement call: per-client counters are kept in alerts.json, which SPEC.md does not list.
Judgement call: a request counts for an AS number only if the lookup answered before it ended.

Model: opus-5-5

internal/state/state.go

@@ -2,7 +2,8 @@
 // SWWAF_STATE_DIR, as the "Persistent state" section of SPEC.md describes:
 // bans.json holds the bans, clients.json each client's counters and
 // history, lookups.json GeoJS's answers, and alerts.json the cooldowns,
-// the hour under way and the alerts waiting for each destination. Load
+// the hour under way, the alerts waiting for each destination and the
+// anomaly counters. Load
 // reads them at start, Watch takes in an admin's edit of one while
 // smallwebwaf runs, and Run and WriteAll write them. The disk is read and
 // written outside the parts' locks, which are held only to take a
@@ -29,6 +30,7 @@ import (
 
 	"github.com/fsnotify/fsnotify"
 	"sneak.berlin/go/smallwebwaf/internal/alerts"
+	"sneak.berlin/go/smallwebwaf/internal/anomaly"
 	"sneak.berlin/go/smallwebwaf/internal/bans"
 	"sneak.berlin/go/smallwebwaf/internal/lookup"
 	"sneak.berlin/go/smallwebwaf/internal/metrics"
@@ -56,6 +58,7 @@ var (
 	errMissing     = errors.New("has no")
 	errCause       = errors.New("is not limit, attack or admin")
 	errDestination = errors.New("is not webhook, slack or ntfy")
+	errScope       = errors.New("is not client, net, asn, total or watch")
 	errWaitingList = errors.New(`waiting is a list, but now lists the alerts by ` +
 		`destination: put the list under "webhook", as "waiting": {"webhook": [...]}, ` +
 		`or remove the file`)
@@ -70,13 +73,14 @@ type Params struct {
 	// is (SWWAF_STATE_COUNTER_INTERVAL).
 	WriteDelay      time.Duration
 	CounterInterval time.Duration
-	// Ledger, Limiter, GeoJS and Alerts hold the state. Alerts also
-	// receive a file_error alert for an edit set aside, and for a write
-	// that fails while smallwebwaf runs.
-	Ledger  *bans.Ledger
-	Limiter *ratelimit.Limiter
-	GeoJS   *lookup.GeoJS
-	Alerts  *alerts.Queue
+	// Ledger, Limiter, GeoJS, Alerts and Anomalies hold the state. Alerts
+	// also receive a file_error alert for an edit set aside, and for a
+	// write that fails while smallwebwaf runs.
+	Ledger    *bans.Ledger
+	Limiter   *ratelimit.Limiter
+	GeoJS     *lookup.GeoJS
+	Alerts    *alerts.Queue
+	Anomalies *anomaly.Counters
 	// Now tells the time by which the counters' buckets run out, normally
 	// time.Now in UTC.
 	Now func() time.Time
@@ -135,11 +139,14 @@ type lookupsFile struct {
 }
 
 // alertsFile is alerts.json, indented for an admin to read and edit.
+//
+//nolint:tagliatelle // the state files use snake_case, as the request log does
 type alertsFile struct {
-	Version   int                       `json:"version"`
-	Cooldowns []alerts.Cooldown         `json:"cooldowns"`
-	Hour      alerts.Hour               `json:"hour"`
-	Waiting   map[string][]alerts.Alert `json:"waiting"`
+	Version         int                       `json:"version"`
+	Cooldowns       []alerts.Cooldown         `json:"cooldowns"`
+	Hour            alerts.Hour               `json:"hour"`
+	Waiting         map[string][]alerts.Alert `json:"waiting"`
+	AnomalyCounters []anomaly.Counter         `json:"anomaly_counters"`
 }
 
 // stateFile is the struct of a state file. Once the file is decoded, its
@@ -420,6 +427,7 @@ func (f *Files) takeIn(name string, data []byte, edit bool) (int, error) {
 		f.params.Alerts.Load(alerts.State{
 			Cooldowns: file.Cooldowns, Hour: file.Hour, Waiting: file.Waiting,
 		})
+		f.params.Anomalies.Load(file.AnomalyCounters, f.params.Now())
 
 		for _, waiting := range file.Waiting {
 			entries += len(waiting)
@@ -522,7 +530,7 @@ func (f *Files) encode(name string) ([]byte, error) {
 		held := f.params.Alerts.Snapshot()
 		file := alertsFile{
 			Version: version, Cooldowns: held.Cooldowns, Hour: held.Hour,
-			Waiting: held.Waiting,
+			Waiting: held.Waiting, AnomalyCounters: f.params.Anomalies.Snapshot(),
 		}
 
 		data, err := json.MarshalIndent(file, "", "    ")
@@ -673,8 +681,9 @@ func (f *lookupsFile) check(data []byte) error {
 
 // check refuses a cooldown without its event or when its alert was sent,
 // which would hold back no repeat, alerts waiting for a destination with
-// another name than webhook, slack or ntfy, most likely misspelt, and an
-// alert waiting without its event or its time.
+// another name than webhook, slack or ntfy, most likely misspelt, an
+// alert waiting without its event or its time, and an anomaly counter as
+// checkAnomalyCounters does.
 func (f *alertsFile) check([]byte) error {
 	for i, cooldown := range f.Cooldowns {
 		switch {
@@ -700,9 +709,58 @@ func (f *alertsFile) check([]byte) error {
 		}
 	}
 
+	return checkAnomalyCounters(f.AnomalyCounters)
+}
+
+// checkAnomalyCounters refuses an anomaly counter whose scope is not
+// client, net, asn, total or watch, most likely misspelt, and one without
+// a field it needs, as missingFromCounter tells.
+func checkAnomalyCounters(counters []anomaly.Counter) error {
+	for i, counter := range counters {
+		if !slices.Contains(anomaly.Scopes(), counter.Scope) {
+			return fmt.Errorf("anomaly_counters entry %d's scope %q %w", i+1,
+				counter.Scope, errScope)
+		}
+
+		field := missingFromCounter(counter)
+		if field != "" {
+			return fmt.Errorf("anomaly_counters %w", missing(i, field))
+		}
+	}
+
 	return nil
 }
 
+// missingFromCounter returns the first field counter, an anomaly counter,
+// needs and has not, or "" when it has them all: what tells it from the
+// others in its scope, without which it would never be counted again, the
+// netblock of a client, net or watch counter, the AS number of an asn one
+// and the name of a watch one; and the start of a window in which it has
+// requests or bytes, without which they would be dropped.
+func missingFromCounter(counter anomaly.Counter) string {
+	scope := counter.Scope
+
+	switch {
+	case scope != anomaly.ScopeASN && scope != anomaly.ScopeTotal &&
+		!counter.Netblock.IsValid():
+		return "netblock"
+	case scope == anomaly.ScopeASN && counter.ASN == "":
+		return "asn"
+	case scope == anomaly.ScopeWatch && counter.Name == "":
+		return "name"
+	case countsWithoutStart(counter.Minute):
+		return "minute.start"
+	case countsWithoutStart(counter.Hour):
+		return "hour.start"
+	case countsWithoutStart(counter.MinuteBytes):
+		return "minute_bytes.start"
+	case countsWithoutStart(counter.HourBytes):
+		return "hour_bytes.start"
+	default:
+		return ""
+	}
+}
+
 // countsWithoutStart reports whether b holds requests, or bytes, but no
 // start, which places them in time.
 func countsWithoutStart(b ratelimit.Buckets) bool {