From 23eaa869dd7d7023e1d71bb7587b1adb43c0b73d Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Fri, 20 Nov 2026 06:42:25 +0100 Subject: [PATCH] Default the netblock and AS number anomaly thresholds (closes #410) The alert-only thresholds per netblock and per AS number now have defaults that alert on obvious abuse alone: per netblock 1200 and 15000 requests a minute and an hour, 5G and 50G a minute and an hour; per AS number five times those. The AS number ones default to off while SWW_WAF_LOOKUP_SOURCE is off. The other scopes stay off. The README says to tune them to the site's traffic. Model: opus-5-5 --- README.md | 20 ++++++----- SPEC.md | 14 ++++---- docs/settings.md | 23 +++++++++++-- internal/config/waf.go | 64 ++++++++++++++++++++++++++++-------- internal/config/waf_test.go | 41 ++++++++++++++++++++++- internal/waf/anomaly_test.go | 16 +++++++++ internal/waf/proxy_test.go | 5 ++- internal/waf/request.go | 2 +- 8 files changed, 152 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 48322ec..c1cdb12 100644 --- a/README.md +++ b/README.md @@ -288,7 +288,9 @@ account, a key, a token or an alert destination stays off until you give one. - An anomaly is more requests or bytes than an `SWW_WAF_ANOMALY_` threshold allows. Crossing a threshold sends one `anomaly` alert to the alert destinations, and does nothing else: no client is banned, rate limited or - blocked. + blocked. The thresholds per netblock and per AS number are on by default, set + high enough to alert only on obvious abuse. They are a starting point: tune + them to your own site's traffic, which the metrics show. - An invalid setting stops the process at start with one log line naming the variable and what is wrong with the value. The settings in effect are logged on one line at start, with tokens, keys and webhook paths shown as `********`. @@ -396,16 +398,16 @@ Every setting the code reads, with its default: | `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when one client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | | `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | | `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_NET_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_NET_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_MINUTE` | `1200` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_HOUR` | `15000` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_NET_BYTES_PER_MINUTE` | `5G` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_NET_BYTES_PER_HOUR` | `50G` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | | `SWW_WAF_ANOMALY_NET_V4_PREFIX` | `24` | The prefix length of the netblock around an IPv4 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 32. Those thresholds only send alerts. | | `SWW_WAF_ANOMALY_NET_V6_PREFIX` | `48` | The prefix length of the netblock around an IPv6 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 128. Those thresholds only send alerts. | -| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_ASN_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_ASN_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_MINUTE` | `6000`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_HOUR` | `75000`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_ASN_BYTES_PER_MINUTE` | `25G`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_ASN_BYTES_PER_HOUR` | `250G`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | | `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when the whole service gets more requests than this in a minute, a count. No client is banned, rate limited or blocked. | | `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when the whole service gets more requests than this in an hour, a count. No client is banned, rate limited or blocked. | | `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the whole service in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | diff --git a/SPEC.md b/SPEC.md index 6838078..219b778 100644 --- a/SPEC.md +++ b/SPEC.md @@ -2113,12 +2113,14 @@ host, sharing one address, would often fetch too close together. ### Anomaly thresholds -These only alert; nothing is blocked. None is set by default, and a threshold -left unset sends no alert. An alert needs a destination only the operator can -supply, and what counts as unusual depends on each service's normal traffic, -which the metrics show. They reveal a widely distributed scraper, thousands of -addresses at low rates each, which the per-client limits do not see. A low -percentage for its `asn=` tag in `SWW_WAF_TAG_LIMIT_PERCENT` is the response. +These only alert; nothing is blocked. The thresholds per netblock and per AS +number have defaults high enough to alert only on obvious abuse. The others are +off by default. What counts as unusual depends on each service's normal traffic, +which the metrics show, so the defaults are a starting point for the operator to +tune. An alert goes nowhere until the operator sets a destination. The +thresholds reveal a widely distributed scraper, thousands of addresses at low +rates each, which the per-client limits do not see. A low percentage for its +`asn=` tag in `SWW_WAF_TAG_LIMIT_PERCENT` is the response. - Requests and body bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted per minute and per hour, for each of: diff --git a/docs/settings.md b/docs/settings.md index 7062bb8..41a52f6 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -378,8 +378,9 @@ Crossing a threshold sends one `anomaly` alert to the destinations under Each scope has four thresholds: the most requests and the most body bytes counted in a minute and in an hour. The bytes are those `SWW_WAF_BYTES_COUNTED` -names. Requests are counts, bytes are sizes. Each is `off` by default. The four -thresholds per client are: +names. Requests are counts, bytes are sizes. Each is `off` by default, except +those per netblock and per AS number listed below. The four thresholds per +client are: - `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE`; - `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR`; @@ -403,6 +404,24 @@ as `REQUESTS_PER_MINUTE`: `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. An item without `=` or a name, or with a bad netblock, is refused. So is a name used twice. +The thresholds per netblock and per AS number have defaults set high enough to +alert only on obvious abuse: + +- per netblock: + - `REQUESTS_PER_MINUTE` `1200` and `REQUESTS_PER_HOUR` `15000`, ten clients + at the default rate limits; + - `BYTES_PER_HOUR` `50G`, one client at the default byte limit per hour; + - `BYTES_PER_MINUTE` `5G`, a tenth of that. +- per AS number, five times those: `REQUESTS_PER_MINUTE` `6000`, + `REQUESTS_PER_HOUR` `75000`, `BYTES_PER_HOUR` `250G` and `BYTES_PER_MINUTE` + `25G`. + +While `SWW_WAF_LOOKUP_SOURCE` is `off`, no request has an AS number, so the +thresholds per AS number are `off` by default. Setting one then stops the start. + +These defaults are a starting point. Tune them to your own site's traffic, which +the metrics show. + ## Settings given as files To give a token as a file, as "Tokens" under "Deployment" in diff --git a/internal/config/waf.go b/internal/config/waf.go index fd77328..f6329f2 100644 --- a/internal/config/waf.go +++ b/internal/config/waf.go @@ -313,7 +313,9 @@ type WAF struct { // per netblock around a client (SWW_WAF_ANOMALY_NET_*), per AS number // (SWW_WAF_ANOMALY_ASN_*), for the whole service (SWW_WAF_ANOMALY_TOTAL_*) // and per watched netblock (SWW_WAF_ANOMALY_WATCHED_NET_*), each 0 while - // it is off. AnomalyNetV4Prefix and AnomalyNetV6Prefix are the lengths + // it is off. Only the thresholds per netblock and per AS number are on by + // default, those per AS number only while clients are looked up. + // AnomalyNetV4Prefix and AnomalyNetV6Prefix are the lengths // of the netblock around a client (SWW_WAF_ANOMALY_NET_V4_PREFIX and // SWW_WAF_ANOMALY_NET_V6_PREFIX), and AnomalyWatchedNets the watched // netblocks (SWW_WAF_ANOMALY_WATCHED_NETS). @@ -555,11 +557,6 @@ func WAFFromEnvironment(v *viper.Viper) (*WAF, error) { "SWW_WAF_ALERT_MAX_PER_HOUR", "60", ), - AnomalyClient: env.thresholds("SWW_WAF_ANOMALY_CLIENT_"), - AnomalyNet: env.thresholds("SWW_WAF_ANOMALY_NET_"), - AnomalyASN: env.thresholds("SWW_WAF_ANOMALY_ASN_"), - AnomalyTotal: env.thresholds("SWW_WAF_ANOMALY_TOTAL_"), - AnomalyWatchedNet: env.thresholds("SWW_WAF_ANOMALY_WATCHED_NET_"), AnomalyNetV4Prefix: env.v4Prefix( "SWW_WAF_ANOMALY_NET_V4_PREFIX", "24", @@ -578,6 +575,7 @@ func WAFFromEnvironment(v *viper.Viper) (*WAF, error) { // The app gets the headers by default, unless no client is looked up. cfg.AddLookupHeaders = env.boolean("SWW_WAF_ADD_LOOKUP_HEADERS", strconv.FormatBool(cfg.LookupSource != LookupSourceOff)) + env.anomalyThresholds(cfg) cfg.BlocklistAction, cfg.BlocklistLimitPercent = env.action( BlocklistActionSetting, string(ReputationActionDeny)) cfg.DNSBLAbuseIPDBAction, cfg.DNSBLAbuseIPDBLimitPercent = env.action( @@ -2693,15 +2691,55 @@ func (e *environment) duration(name, defaultValue string) time.Duration { return duration } +// thresholdDefaults are the defaults of a scope's four anomaly thresholds, +// each a count, a size or off. +type thresholdDefaults struct { + requestsPerMinute, requestsPerHour, bytesPerMinute, bytesPerHour string +} + +// anomalyThresholds reads the anomaly thresholds of every scope into cfg. +// Only those per netblock and per AS number are on by default, high +// enough to alert on obvious abuse alone. Those per netblock count the +// requests of ten clients at the default per-client rate limits, and the +// bytes of one client at its default byte limit per hour, a tenth of +// that in a minute. Those per AS number are five times those per +// netblock. They are off by default while no client is looked up, since +// no request then has an AS number. +func (e *environment) anomalyThresholds(cfg *WAF) { + allOff := thresholdDefaults{off, off, off, off} + asnDefaults := thresholdDefaults{ + requestsPerMinute: "6000", requestsPerHour: "75000", + bytesPerMinute: "25G", bytesPerHour: "250G", + } + + if cfg.LookupSource == LookupSourceOff { + asnDefaults = allOff + } + + cfg.AnomalyClient = e.thresholds("SWW_WAF_ANOMALY_CLIENT_", allOff) + cfg.AnomalyNet = e.thresholds("SWW_WAF_ANOMALY_NET_", thresholdDefaults{ + requestsPerMinute: "1200", requestsPerHour: "15000", + bytesPerMinute: "5G", bytesPerHour: "50G", + }) + cfg.AnomalyASN = e.thresholds("SWW_WAF_ANOMALY_ASN_", asnDefaults) + cfg.AnomalyTotal = e.thresholds("SWW_WAF_ANOMALY_TOTAL_", allOff) + cfg.AnomalyWatchedNet = e.thresholds("SWW_WAF_ANOMALY_WATCHED_NET_", + allOff) +} + // thresholds reads the four anomaly thresholds whose settings' names -// start with prefix: requests and bytes per minute and per hour. Each is -// off by default. -func (e *environment) thresholds(prefix string) anomaly.Thresholds { +// start with prefix: requests and bytes per minute and per hour. +func (e *environment) thresholds( + prefix string, defaults thresholdDefaults, +) anomaly.Thresholds { return anomaly.Thresholds{ - RequestsPerMinute: e.count(prefix+"REQUESTS_PER_MINUTE", off), - RequestsPerHour: e.count(prefix+"REQUESTS_PER_HOUR", off), - BytesPerMinute: e.size(prefix+"BYTES_PER_MINUTE", off), - BytesPerHour: e.size(prefix+"BYTES_PER_HOUR", off), + RequestsPerMinute: e.count(prefix+"REQUESTS_PER_MINUTE", + defaults.requestsPerMinute), + RequestsPerHour: e.count(prefix+"REQUESTS_PER_HOUR", + defaults.requestsPerHour), + BytesPerMinute: e.size(prefix+"BYTES_PER_MINUTE", + defaults.bytesPerMinute), + BytesPerHour: e.size(prefix+"BYTES_PER_HOUR", defaults.bytesPerHour), } } diff --git a/internal/config/waf_test.go b/internal/config/waf_test.go index cb6f8df..1f8189a 100644 --- a/internal/config/waf_test.go +++ b/internal/config/waf_test.go @@ -178,6 +178,17 @@ func loggedAnomalyDefaults() map[string]string { logged[name] = off } + maps.Copy(logged, map[string]string{ + anomalyNet + requestsPerMinute: "1200", + anomalyNet + requestsPerHour: "15000", + anomalyNet + bytesPerMinute: "5G", + anomalyNet + bytesPerHour: "50G", + anomalyASN + requestsPerMinute: "6000", + anomalyASN + requestsPerHour: "75000", + anomalyASN + bytesPerMinute: "25G", + anomalyASN + bytesPerHour: "250G", + }) + return logged } @@ -1565,7 +1576,35 @@ func TestAnomalySettingsDefaults(t *testing.T) { t.Parallel() cfg := wafFromEnvironment(t, environment{}) - wantAllOff(t, cfg) + + const gibibyte = int64(1) << 30 + + want := map[string]anomaly.Thresholds{ + anomalyClient: {}, + anomalyNet: { + RequestsPerMinute: 1200, RequestsPerHour: 15000, + BytesPerMinute: 5 * gibibyte, BytesPerHour: 50 * gibibyte, + }, + anomalyASN: { + RequestsPerMinute: 6000, RequestsPerHour: 75000, + BytesPerMinute: 25 * gibibyte, BytesPerHour: 250 * gibibyte, + }, + anomalyTotal: {}, anomalyWatchedNet: {}, + } + + if got := thresholdsByScope(cfg); !maps.Equal(got, want) { + t.Errorf("thresholds by scope\n%+v\nwant\n%+v", got, want) + } + + // With no client looked up, the thresholds per AS number are off. + want[anomalyASN] = anomaly.Thresholds{} + + got := thresholdsByScope( + wafFromEnvironment(t, environment{lookupSource: off})) + if !maps.Equal(got, want) { + t.Errorf("with %s off, thresholds by scope\n%+v\nwant\n%+v", + lookupSource, got, want) + } if cfg.AnomalyNetV4Prefix != 24 || cfg.AnomalyNetV6Prefix != 48 || len(cfg.AnomalyWatchedNets) != 0 { diff --git a/internal/waf/anomaly_test.go b/internal/waf/anomaly_test.go index 470df40..dc2078a 100644 --- a/internal/waf/anomaly_test.go +++ b/internal/waf/anomaly_test.go @@ -32,6 +32,22 @@ const ( bytesPerHour = "BYTES_PER_HOUR" ) +// netAndASNThresholdsOff returns the anomaly thresholds per netblock and +// per AS number, the ones on by default, each set to off. +func netAndASNThresholdsOff() map[string]string { + settings := map[string]string{} + + for _, scope := range []string{anomalyNet, anomalyASN} { + for _, end := range []string{ + requestsPerMinute, requestsPerHour, bytesPerMinute, bytesPerHour, + } { + settings[scope+end] = off + } + } + + return settings +} + // The other anomaly settings. const ( anomalyNetV4Prefix = "SWW_WAF_ANOMALY_NET_V4_PREFIX" diff --git a/internal/waf/proxy_test.go b/internal/waf/proxy_test.go index 0811fbf..6993d64 100644 --- a/internal/waf/proxy_test.go +++ b/internal/waf/proxy_test.go @@ -456,7 +456,9 @@ func (w *wafAndParts) banAbuseIPDBBlacklist( // at abuseIPDBURL while env sets SWW_WAF_ABUSEIPDB_KEY, and its blacklist is // fetched from abuseIPDBBlacklistURL. // SWW_WAF_CORE_RULE_SET_MODE is off unless env sets it, so that only the tests of the -// Core Rule Set have their requests inspected by it. +// Core Rule Set have their requests inspected by it. Likewise the anomaly thresholds +// per netblock and per AS number are off unless env sets them, so that only the tests +// of the anomaly thresholds count requests. func newWAF( t *testing.T, geojsURL string, @@ -486,6 +488,7 @@ func newWAFWith( settings[lookupSource] = off } + maps.Copy(settings, netAndASNThresholdsOff()) maps.Copy(settings, env) cfg, err := config.WAFFromEnvironment(configtest.Viper(settings)) diff --git a/internal/waf/request.go b/internal/waf/request.go index 1555704..e3f7d5a 100644 --- a/internal/waf/request.go +++ b/internal/waf/request.go @@ -405,7 +405,7 @@ func (rq *request) addToHistory() { // SWW_WAF_RATE_LIMIT_EXEMPT_NETS, and one for a path in // SWW_WAF_RATE_LIMIT_EXEMPT_PATHS are counted too. It is counted for its // client's AS number when answerAtTheEnd gives one. With every anomaly -// threshold off, the default, it does nothing. +// threshold off, it does nothing. func (rq *request) countAnomalies() { if !anomalyThresholdsSet(rq.h.config) { return