From 48edab5dad711f0348750de4613ca1fc49387b3a Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Thu, 19 Nov 2026 10:20:07 +0100 Subject: [PATCH 1/7] Test rproxy's 32 KiB header limit at its edge (closes #415) The limit was already a constant with no setting. These tests pin it: a request line and headers of exactly 32 KiB reach the app, and one byte more is answered 431 with the connection closed and waf not asked. Model: opus-5-5 --- internal/rproxy/limits_test.go | 53 ++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/internal/rproxy/limits_test.go b/internal/rproxy/limits_test.go index ce326f5..8035e4e 100644 --- a/internal/rproxy/limits_test.go +++ b/internal/rproxy/limits_test.go @@ -71,6 +71,59 @@ func TestServerHasTheFixedLimits(t *testing.T) { } } +// getOfSize is a GET whose request line and headers, the blank line that ends +// them included, are size bytes long. +func getOfSize(size int) string { + const start, end = "GET / HTTP/1.1\r\nHost: site.example\r\nX-Pad: ", "\r\n\r\n" + + return start + strings.Repeat("x", size-len(start)-len(end)) + end +} + +func TestARequestLineAndHeadersOf32KiBReachTheApp(t *testing.T) { + t.Parallel() + + standIn := startWAF(t, allow) + app := startApp(t, greet) + addr, _ := startRProxy(t, standIn.URL, app.URL, nil) + + conn := dial(t, addr) + send(t, conn, getOfSize(32<<10)) + + if status := readStatus(t, conn); status != http.StatusOK { + t.Errorf("status %d, want the app's 200", status) + } +} + +func TestARequestLineAndHeadersOver32KiBAreRefusedAndTheConnectionClosed( + t *testing.T, +) { + t.Parallel() + + standIn := startWAF(t, allow) + app := startApp(t, func(http.ResponseWriter, *http.Request) { + t.Error("the app was asked") + }) + addr, _ := startRProxy(t, standIn.URL, app.URL, nil) + + conn := dial(t, addr) + send(t, conn, getOfSize(32<<10+1)) + + // io.ReadAll returns without an error only once rproxy has closed the + // connection. + text, err := io.ReadAll(conn) + if err != nil || !strings.HasPrefix(string(text), "HTTP/1.1 431 ") { + t.Errorf( + "read %q (%v), want 431 and the connection closed", + text, + err, + ) + } + + if len(standIn.questions) != 0 { + t.Error("waf was asked") + } +} + func TestABodyAnnouncedOverItsLimitIsRefusedOnceWAFAllowsIt(t *testing.T) { t.Parallel() -- 2.54.0 From 9cb8f362bc7eb39ae845087feb34e0700f7718a4 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Thu, 19 Nov 2026 10:44:53 +0100 Subject: [PATCH 2/7] sww: lift waf's check time limit and rproxy's wait in tests (closes #418) Under heavy host load the sww tests got 503 where they expected 200 or 403: waf refused requests whose trap paths, rule files and Core Rule Set took longer than 500 ms, and rproxy gave up on waf after 2 s. waf.Params and sww.Params gain BesideLookupTimeLimit; zero keeps the 500 ms limit, so the binary is unchanged. The sww tests' run gives waf an hour, and startRProxy sets SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS to 60000, as the rproxy package's tests do. waf's own tests set the limit through the new field instead of SetBesideLookupTimeLimit, which is gone. Model: opus-5-5 --- internal/sww/rproxy_test.go | 5 ++++- internal/sww/sww.go | 14 ++++++++++---- internal/sww/sww_test.go | 3 +++ internal/waf/besidelookup_test.go | 2 +- internal/waf/export_test.go | 9 --------- internal/waf/proxy.go | 14 ++++++++++++-- internal/waf/proxy_test.go | 8 +++----- 7 files changed, 33 insertions(+), 22 deletions(-) diff --git a/internal/sww/rproxy_test.go b/internal/sww/rproxy_test.go index 267704e..00b154b 100644 --- a/internal/sww/rproxy_test.go +++ b/internal/sww/rproxy_test.go @@ -51,7 +51,9 @@ func runRProxy(ctx context.Context, env map[string]string, out *output) int { // startRProxy runs rproxy with waf at backend and the app at appURL, and // returns its URL and what it writes. It believes X-Forwarded-For from the -// tests. It stops as the test ends, and that it stopped in order is checked. +// tests. It waits a minute for waf's answer, so that a slow answer on a busy +// host is not taken for no answer. It stops as the test ends, and that it +// stopped in order is checked. func startRProxy(t *testing.T, backend, appURL string) (string, *output) { t.Helper() @@ -65,6 +67,7 @@ func startRProxy(t *testing.T, backend, appURL string) (string, *output) { "SWW_RPROXY_UPSTREAM_URL": appURL, "SWW_RPROXY_TRUSTED_PROXIES": localhost + "/32", wafBackend: backend, + wafBackendTimeout: "60000", }, out) }() diff --git a/internal/sww/sww.go b/internal/sww/sww.go index 7befcde..6dc2d10 100644 --- a/internal/sww/sww.go +++ b/internal/sww/sww.go @@ -67,6 +67,9 @@ type Params struct { Viper *viper.Viper // Stdout receives the request log and the process's own messages. Stdout io.Writer + // BesideLookupTimeLimit is the waf.Params.BesideLookupTimeLimit RunWAF + // gives waf. Main leaves it zero, waf's own limit; tests lengthen it. + BesideLookupTimeLimit time.Duration } // Main runs the command os.Args names, and returns the process's exit status. @@ -146,7 +149,7 @@ func RunWAF(ctx context.Context, params Params) int { return runWAFWithSettings( ctx, - params.Version, + params, cfg, stdout, remote, @@ -159,7 +162,7 @@ func RunWAF(ctx context.Context, params Params) int { // SWW_WAF_LOG_REMOTE_URL is set. func runWAFWithSettings( ctx context.Context, - version string, + params Params, cfg *config.WAF, stdout io.Writer, remote *remotelog.Sender, @@ -193,6 +196,7 @@ func runWAFWithSettings( ruleFiles, alertQueue, crs, + params.BesideLookupTimeLimit, ) if err != nil { return cannotStart(processLog, "cannot use the lookup database", err) @@ -221,7 +225,7 @@ func runWAFWithSettings( } processLog.Info("starting", - "version", version, + "version", params.Version, "address", listener.Addr().String(), "settings", cfg) @@ -249,7 +253,7 @@ func cannotStart(processLog *slog.Logger, message string, err error) int { func newServer( cfg *config.WAF, stdout io.Writer, processLog *slog.Logger, now func() time.Time, ruleFiles *rules.Files, alertQueue *alerts.Queue, - crs *coreruleset.CoreRuleSet, + crs *coreruleset.CoreRuleSet, besideLookupTimeLimit time.Duration, ) (*waf.Server, error) { var lookupFile *lookup.File @@ -278,6 +282,8 @@ func newServer( Now: now, Rules: ruleFiles, Alerts: alertQueue, + + BesideLookupTimeLimit: besideLookupTimeLimit, }) server.Metrics.AddAlerts(alertQueue) diff --git a/internal/sww/sww_test.go b/internal/sww/sww_test.go index 4cfa9a7..dbe7571 100644 --- a/internal/sww/sww_test.go +++ b/internal/sww/sww_test.go @@ -173,6 +173,9 @@ func run(ctx context.Context, env map[string]string, out *output) int { Version: testVersion, Viper: v, Stdout: out, + // The race detector and a busy host can slow the Core Rule Set's + // inspections past waf's own limit. + BesideLookupTimeLimit: time.Hour, }) } diff --git a/internal/waf/besidelookup_test.go b/internal/waf/besidelookup_test.go index 7ecb49e..4d4f6f6 100644 --- a/internal/waf/besidelookup_test.go +++ b/internal/waf/besidelookup_test.go @@ -73,10 +73,10 @@ func newWAFHoldingTheCoreRuleSet( server, out, queue := newWAFWith(t, func(params waf.Params) *waf.Server { params.CoreRuleSet = crs + params.BesideLookupTimeLimit = waf.BesideLookupTimeLimit return waf.New(params) }, silentGeoJSURL, time.Now, settings) - server.SetBesideLookupTimeLimit(waf.BesideLookupTimeLimit) return server, out, queue } diff --git a/internal/waf/export_test.go b/internal/waf/export_test.go index 60b6e9b..24cb414 100644 --- a/internal/waf/export_test.go +++ b/internal/waf/export_test.go @@ -1,13 +1,4 @@ package waf -import "time" - // BesideLookupTimeLimit is besideLookupTimeLimit. const BesideLookupTimeLimit = besideLookupTimeLimit - -// SetBesideLookupTimeLimit gives the heuristics of besideLookup limit on s in -// place of besideLookupTimeLimit. -func (s *Server) SetBesideLookupTimeLimit(limit time.Duration) { - h := s.Handler.(*handler) //nolint:forcetypeassert // New makes it one - h.besideLookupLimit = limit -} diff --git a/internal/waf/proxy.go b/internal/waf/proxy.go index 9179ae4..f377216 100644 --- a/internal/waf/proxy.go +++ b/internal/waf/proxy.go @@ -4,6 +4,7 @@ package waf import ( + "cmp" "fmt" "io" "log/slog" @@ -83,6 +84,11 @@ type Params struct { // failing, a query to a DNSBL zone or a check with AbuseIPDB failing, // or the day's AbuseIPDB checks used up. Alerts *alerts.Queue + // BesideLookupTimeLimit is how long the heuristics of besideLookup have + // for a request. Zero means besideLookupTimeLimit. Tests that run the + // Core Rule Set lengthen it, since the race detector and a busy host can + // slow an inspection past besideLookupTimeLimit. + BesideLookupTimeLimit time.Duration } // CoreRuleSetInspector inspects a request with the Core Rule Set, as @@ -168,7 +174,10 @@ func newHandler(params Params) *handler { coreRuleSet: params.CoreRuleSet, alerts: params.Alerts, - besideLookupLimit: besideLookupTimeLimit, + besideLookupLimit: cmp.Or( + params.BesideLookupTimeLimit, + besideLookupTimeLimit, + ), } if params.Config.RouteWatchURL != "" { h.routeWatch = routewatch.New(routewatch.Params{ @@ -292,7 +301,8 @@ type handler struct { // waitForGeoJS is true when a setting needs each request's answer from // GeoJS before the request goes on. waitForGeoJS bool - // besideLookupLimit is besideLookupTimeLimit. Only tests change it. + // besideLookupLimit is how long the heuristics of besideLookup have for a + // request, as Params.BesideLookupTimeLimit says. besideLookupLimit time.Duration // awaitingReport holds the decision on each answered question by its id // until its report comes, and nil for a question still being handled. diff --git a/internal/waf/proxy_test.go b/internal/waf/proxy_test.go index 054b46b..b002620 100644 --- a/internal/waf/proxy_test.go +++ b/internal/waf/proxy_test.go @@ -510,13 +510,11 @@ func newWAFWith( Now: now, Rules: ruleFiles, Alerts: alertQueue, + // The tests of the limit set it back, and hold the Core Rule Set + // with a stand-in. + BesideLookupTimeLimit: time.Hour, }) - // The race detector and a busy host can slow the Core Rule Set's - // inspections past the time limit. The tests of the limit set it back, and - // hold the Core Rule Set with a stand-in. - server.SetBesideLookupTimeLimit(time.Hour) - return server, out, alertQueue } -- 2.54.0 From 9f42460f70b9032afeb29d616e47c5cea3c8f5a7 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Thu, 19 Nov 2026 10:58:27 +0100 Subject: [PATCH 3/7] Say the anomaly thresholds only send an alert (closes #412) Each SWW_WAF_ANOMALY_ threshold's description now says crossing it sends one alert to the alert destinations and bans, rate limits and blocks no client. The prefix and watched-netblock settings say their thresholds only alert. README's configuration notes and docs/settings.md explain "anomaly" once. Model: opus-5-5 --- README.md | 50 ++++++++++++++++++++++++++---------------------- docs/settings.md | 5 +++++ 2 files changed, 32 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index c947ac5..ca798b5 100644 --- a/README.md +++ b/README.md @@ -284,6 +284,10 @@ account, a key, a token or an alert destination stays off until you give one. `SWW_WAF_BYTES_COUNTED` says. Headers are never counted. What the visitor sent over a WebSocket counts as request bytes, and what the app sent as response bytes. +- 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. - 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 `********`. @@ -384,29 +388,29 @@ Every setting the code reads, with its default: | `SWW_WAF_ALERT_EVENTS` | `ban,permanent_ban,core_rule_set_match,anomaly,reputation_hit,source_failure,file_error` | The events alerts are sent for; the hourly `summary` is sent whatever it says. | | `SWW_WAF_ALERT_COOLDOWN` | `15m` | How long after an alert its repeats are held back and counted, a duration or `off`. | | `SWW_WAF_ALERT_MAX_PER_HOUR` | `60` | The most alerts sent in an hour, a number or `off`; the rest are counted in the hour's `summary`. | -| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE` | `off` | Alert when one client makes more requests than this in a minute, a count. | -| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR` | `off` | Alert when one client makes more requests than this in an hour, a count. | -| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one client in a minute, a size. | -| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one client in an hour, a size. | -| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_MINUTE` | `off` | Alert when the netblock around a client makes more requests than this in a minute, a count. | -| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_HOUR` | `off` | Alert when the netblock around a client makes more requests than this in an hour, a count. | -| `SWW_WAF_ANOMALY_NET_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the netblock around a client in a minute, a size. | -| `SWW_WAF_ANOMALY_NET_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the netblock around a client in an hour, a size. | -| `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. | -| `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. | -| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_MINUTE` | `off` | Alert when one AS number makes more requests than this in a minute, a count. | -| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_HOUR` | `off` | Alert when one AS number makes more requests than this in an hour, a count. | -| `SWW_WAF_ANOMALY_ASN_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one AS number in a minute, a size. | -| `SWW_WAF_ANOMALY_ASN_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one AS number in an hour, a size. | -| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_MINUTE` | `off` | Alert when the whole service gets more requests than this in a minute, a count. | -| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_HOUR` | `off` | Alert when the whole service gets more requests than this in an hour, a count. | -| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the whole service in a minute, a size. | -| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the whole service in an hour, a size. | -| `SWW_WAF_ANOMALY_WATCHED_NETS` | empty | Named netblocks the `SWW_WAF_ANOMALY_WATCHED_NET_` thresholds count each as a whole, such as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. | -| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_MINUTE` | `off` | Alert when a watched netblock makes more requests than this in a minute, a count. | -| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_HOUR` | `off` | Alert when a watched netblock makes more requests than this in an hour, a count. | -| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for a watched netblock in a minute, a size. | -| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for a watched netblock in an hour, a size. | +| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when one client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | +| `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_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_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. | +| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the whole service in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NETS` | empty | Named netblocks the `SWW_WAF_ANOMALY_WATCHED_NET_` thresholds count each as a whole, such as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. Those thresholds only send alerts. | +| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | [`docs/settings.md`](docs/settings.md) gives the values each setting takes in full, and the limits that are fixed rather than settings. diff --git a/docs/settings.md b/docs/settings.md index 0f07055..3658d72 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -364,6 +364,11 @@ tag that no request can get stops the start. A request can get only these: ## Anomaly thresholds +An anomaly is more requests or bytes than one of these thresholds allows. +Crossing a threshold sends one `anomaly` alert to the destinations under +"Alerting", and does nothing else: no client is banned, rate limited or blocked. +`SWW_WAF_ALERT_COOLDOWN` holds back repeats of that alert. + 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 -- 2.54.0 From eb48796f2791ae6c6644eb9ff47f1fdbb155b5a1 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Thu, 19 Nov 2026 11:16:15 +0100 Subject: [PATCH 4/7] README: compose example for the open internet, with common waf settings (closes #381) A new example puts one gitea behind traefik, rproxy and waf. waf sets nine settings most sites use, then eight more commented out, each with what it does and when to set it. Model: opus-5-5 --- README.md | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ca798b5..9fac8cf 100644 --- a/README.md +++ b/README.md @@ -420,8 +420,8 @@ full, and the limits that are fixed rather than settings. Each example is a complete `compose.yaml`. `smallwebwaf` is the tag `make docker` gives the image; on another host, use the name you pushed it under, by digest. Docker Compose puts the services on a private network of its -own, where each reaches the others by service name. Each example publishes -`rproxy`'s port on the host, for trying it out. +own, where each reaches the others by service name. Each example but "On the +open internet" publishes `rproxy`'s port on the host, for trying it out. ### Smallest setup @@ -453,6 +453,142 @@ volumes: waf-state: ``` +### On the open internet + +One gitea at `git.example.com`, with traefik in front of `rproxy`. traefik gets +the certificate from Let's Encrypt and is the only service with published ports. +`waf` sets what most sites set. More `waf` settings follow, commented out, each +with what it does and when to set it. + +```yaml +services: + traefik: + # traefik v3.7.19, 2026-11-13 + image: traefik@sha256:a6c0194dda77bcb804824580f36fa7edc56e315b1acfe933366c8b52844a78a4 + restart: unless-stopped + command: + - --providers.docker=true + - --providers.docker.exposedByDefault=false + - --entryPoints.web.address=:80 + - --entryPoints.websecure.address=:443 + # Redirect plain HTTP to HTTPS. + - --entryPoints.web.http.redirections.entryPoint.to=websecure + - --entryPoints.web.http.redirections.entryPoint.scheme=https + # A Let's Encrypt certificate for each site, by the TLS-ALPN + # challenge on port 443. + - --entryPoints.websecure.http.tls.certResolver=le + - --certificatesResolvers.le.acme.email=hostmaster@example.com + - --certificatesResolvers.le.acme.storage=/letsencrypt/acme.json + - --certificatesResolvers.le.acme.tlsChallenge=true + # Give a request 10 minutes to arrive, rather than 1, for the + # large git pushes the rproxy lines below accept. + # - --entryPoints.websecure.transport.respondingTimeouts.readTimeout=600s + ports: + - "80:80" + - "443:443" + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - acme:/letsencrypt + + app: + # Your app: here a gitea, which listens on port 3000. + image: registry.example/app@sha256:0000000000000000000000000000000000000000000000000000000000000000 + restart: unless-stopped + + rproxy: + image: smallwebwaf + restart: unless-stopped + environment: + SWW_RPROXY_WAF_BACKEND: http://waf:8080 + SWW_RPROXY_UPSTREAM_URL: http://app:3000 + # Accept git pushes up to 1 GiB, rather than 100 MiB, sent in + # up to 10 minutes, rather than 1, with traefik's readTimeout + # line above. + # SWW_RPROXY_MAX_REQUEST_SIZE: 1G + # SWW_RPROXY_MAX_REQUEST_TIME_MS: "600000" + labels: + - traefik.enable=true + - traefik.http.routers.git.rule=Host(`git.example.com`) + - traefik.http.routers.git.entryPoints=websecure + - traefik.http.services.git.loadBalancer.server.port=8080 + + waf: + image: smallwebwaf + restart: unless-stopped + environment: + SWW_COMMAND: waf + # The name in every log line, alert and metric. The default, + # the container's host name, is a random id under Compose. + SWW_WAF_INSTANCE_NAME: host1/waf + # The app each hostname serves. Only that app's fixes to the + # Core Rule Set apply there. + SWW_WAF_APPS: git.example.com:gitea + # Monitoring skips every check. + SWW_WAF_ALLOW_NETS: 192.0.2.10 + # The office and the CI runner, which would exceed the rate + # limits, are never rate limited. + SWW_WAF_RATE_LIMIT_EXEMPT_NETS: 203.0.113.0/24,198.51.100.7 + # WordPress paths, which only scanners ask a gitea for. One + # request for one bans the client. + SWW_WAF_TRAP_PATHS: /wp-login.php,/xmlrpc.php + # Spamhaus's list of netblocks hijacked or leased by + # criminals. Their clients are refused. + SWW_WAF_BLOCKLIST_URLS: https://www.spamhaus.org/drop/drop.txt + # The token for the ban endpoints, to lift a ban without + # editing bans.json. + SWW_WAF_ADMIN_TOKEN_FILE: /etc/sww/tokens/admin + # Alerts, such as one for each ban, to an ntfy topic. + SWW_WAF_ALERT_NTFY_URL: https://ntfy.example.com/smallwebwaf + + # Refuse nothing and ban no one, for the first days. Each log + # line says what enforce mode would have done. + # SWW_WAF_MODE: observe + # The access token for an ntfy topic that is not public. + # SWW_WAF_ALERT_NTFY_TOKEN_FILE: /etc/sww/tokens/ntfy + # The token for /_sww/metrics, for Prometheus. Unset, the + # metrics are off. + # SWW_WAF_METRICS_TOKEN_FILE: /etc/sww/tokens/metrics + # 600 requests an hour rather than 1500, to ban slower + # scrapers. A fast human reader can reach it too. + # SWW_WAF_RATE_LIMIT_PER_HOUR: "600" + # A quarter of every limit for clients in two hosting + # networks, where scrapers run rather than people. + # SWW_WAF_TAG_LIMIT_PERCENT: asn=14061:25,asn=16276:25 + # For a site only for people in a few countries. Clients + # elsewhere are refused, and so are any the lookup cannot place. + # SWW_WAF_EXCLUSIVELY_ALLOWED_COUNTRIES: de,at,ch + # Close a refused request's connection rather than answer + # 403. traefik then answers 502, so a scraper cannot tell a + # ban from a broken site. + # SWW_WAF_BAN_RESPONSE: close + # A copy of every log line to a syslog server. + # SWW_WAF_LOG_REMOTE_URL: syslog+tls://logs.example.com:6514 + volumes: + - waf-state:/var/lib/sww + - /srv/sww/tokens:/etc/sww/tokens:ro + +volumes: + acme: + waf-state: +``` + +Change these before the first start: + +- `git.example.com`, in the router rule and in `SWW_WAF_APPS`; +- the email address for Let's Encrypt; +- the ntfy topic's URL; +- the app's image and port; +- the netblocks, which are documentation addresses. + +Make the admin token file first, as for any token file: + +```sh +mkdir -p /srv/sww/tokens +openssl rand -hex 32 > /srv/sww/tokens/admin +chown 65532:65532 /srv/sww/tokens/admin +chmod 0400 /srv/sww/tokens/admin +``` + ### Custom per-address limits For a site with no API: -- 2.54.0 From 5099448f79a287fa633be238236d8abce16a4836 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Thu, 19 Nov 2026 11:43:01 +0100 Subject: [PATCH 5/7] Keep the sww and rproxy tests from failing on a busy host (closes #420) The rproxy package's tests and sww's startRProxyProcess give rproxy a minute for waf's answers unless a test sets SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS. At the 2-second default, a slow host made rproxy drop questions and reports. TestMainRunsWAF runs waf with the Core Rule Set off. Main keeps waf's 500 ms limit for its checks, and under the race detector the Core Rule Set's inspection could pass it and get 503. Model: opus-5-5 --- internal/rproxy/rproxy_test.go | 4 +++- internal/sww/rproxy_test.go | 7 +++++-- internal/sww/waf_test.go | 5 ++++- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/internal/rproxy/rproxy_test.go b/internal/rproxy/rproxy_test.go index d45e5f6..74e8eae 100644 --- a/internal/rproxy/rproxy_test.go +++ b/internal/rproxy/rproxy_test.go @@ -324,7 +324,8 @@ func greet(w http.ResponseWriter, r *http.Request) { // startRProxy starts rproxy with waf at backend and the app at appURL, and // the settings in env on top of the defaults. It returns where rproxy listens -// and what it writes. +// and what it writes. SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS is a minute unless env +// sets it, so that a busy host cannot make rproxy drop a question or a report. func startRProxy( t *testing.T, backend, appURL string, env map[string]string, ) (string, *output) { @@ -357,6 +358,7 @@ func startServerLogging( settings := map[string]string{ "SWW_RPROXY_WAF_BACKEND": backend, "SWW_RPROXY_UPSTREAM_URL": appURL, + wafBackendTimeout: "60000", } maps.Copy(settings, env) diff --git a/internal/sww/rproxy_test.go b/internal/sww/rproxy_test.go index 00b154b..8d54d66 100644 --- a/internal/sww/rproxy_test.go +++ b/internal/sww/rproxy_test.go @@ -552,7 +552,9 @@ func TestAStatusWAFDoesNotTakeIsReportedAs599(t *testing.T) { // startRProxyProcess runs `sww rproxy` in a process of its own, with the // settings in env, each as NAME=value. It returns where rproxy listens and a // function that sends rproxy SIGTERM and fails the test unless it exits with -// status 0 within waitLimit. +// status 0 within waitLimit. It waits a minute for waf's answers unless env +// sets SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS, so that a busy host cannot make it +// drop a question. func startRProxyProcess(t *testing.T, env ...string) (string, func()) { t.Helper() @@ -568,7 +570,8 @@ func startRProxyProcess(t *testing.T, env ...string) (string, func()) { cmd.Env = append(os.Environ(), commandForMain+"=rproxy", - "SWW_RPROXY_LISTEN_ADDR="+localhost+":0") + "SWW_RPROXY_LISTEN_ADDR="+localhost+":0", + wafBackendTimeout+"=60000") cmd.Env = append(cmd.Env, env...) exited := startProcess(t, cmd) diff --git a/internal/sww/waf_test.go b/internal/sww/waf_test.go index ab825cf..8ad703c 100644 --- a/internal/sww/waf_test.go +++ b/internal/sww/waf_test.go @@ -90,6 +90,8 @@ func TestMainRunsWAF(t *testing.T) { cmd := exec.CommandContext(t.Context(), binary) cmd.Stdout = out + // The Core Rule Set is off. Main keeps waf's own limit for its checks, + // and on a busy host the Core Rule Set's inspection can pass it. cmd.Env = append(os.Environ(), "TZ="+zone, commandForMain+"="+wafCommand, @@ -97,7 +99,8 @@ func TestMainRunsWAF(t *testing.T) { stateDir+"="+dir, cacheDir+"="+dir, ruleFilesDir+"="+t.TempDir(), - lookupSource+"=off") + lookupSource+"=off", + "SWW_WAF_CORE_RULE_SET_MODE=off") exited := startProcess(t, cmd) -- 2.54.0 From 01e6b5d47e14c4fe45a987732ea890401ec84097 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Thu, 19 Nov 2026 11:58:20 +0100 Subject: [PATCH 6/7] sww: wire the daemons with fx (closes #414) go.uber.org/fx builds the parts of waf and rproxy in internal/sww, one provider per part. Each background loop is a lifecycle hook added where its part is built. waf.Params takes every part built, and waf.New builds none. GeoJS calls back into waf, so waf exports AddLookup and GeoJSFailed, and clientGroup and banNetblock take the settings. newServer, loadStateFiles, the inBackground list and serveRProxy are gone. serve is the one hook that serves both daemons, and reports a failure to run on a channel of its own; fx's signal handling is not used. Once fx has stopped, run takes each daemon's last step: waf writes the state files, and rproxy waits for its reports. Model: opus-5-5 --- README.md | 2 + SPEC.md | 4 +- go.mod | 4 + go.sum | 8 + internal/sww/lifecycle.go | 198 ++++++++++++ internal/sww/rproxy.go | 105 +++---- internal/sww/sww.go | 399 +----------------------- internal/sww/waf.go | 490 ++++++++++++++++++++++++++++++ internal/waf/abuseipdb.go | 2 +- internal/waf/admin.go | 10 +- internal/waf/answertime_test.go | 19 +- internal/waf/bans.go | 15 +- internal/waf/besidelookup_test.go | 2 +- internal/waf/bytelimits.go | 2 +- internal/waf/client.go | 6 +- internal/waf/coreruleset.go | 2 +- internal/waf/lookup.go | 38 ++- internal/waf/proxy.go | 165 +++------- internal/waf/proxy_test.go | 156 +++++++++- internal/waf/ratelimits.go | 9 +- internal/waf/refusallimit.go | 7 +- internal/waf/reputation.go | 2 +- internal/waf/request.go | 10 +- internal/waf/routewatchtags.go | 2 +- 24 files changed, 1008 insertions(+), 649 deletions(-) create mode 100644 internal/sww/lifecycle.go create mode 100644 internal/sww/waf.go diff --git a/README.md b/README.md index 9fac8cf..a5004f5 100644 --- a/README.md +++ b/README.md @@ -890,6 +890,8 @@ stops the running process (see [`docs/state-files.md`](docs/state-files.md)). - `cmd/sww`: the binary, which only calls `internal/sww`. - `internal/sww`: the process, as the command it is given, and the health check. + It is the only package that imports `go.uber.org/fx`, which builds the parts + of `waf` and `rproxy`. - `internal/config`: reads the settings, the one place they are read. - `internal/rproxy`: the reverse proxy in front of one app. - `internal/waf`: `waf`'s server, which runs the checks and answers its own diff --git a/SPEC.md b/SPEC.md index ca67a0a..a2fbb45 100644 --- a/SPEC.md +++ b/SPEC.md @@ -69,7 +69,9 @@ never as a time. that command's settings, and runs `internal/rproxy` until `SIGTERM` or `SIGINT` (see "`rproxy`"). `sww healthcheck` is the image's health check. With no command, or one it does not know, the binary prints the commands - and exits with status 2. + and exits with status 2. `internal/sww` is the only package that imports + `go.uber.org/fx`. fx builds the parts of `waf` and `rproxy`, and starts + and stops their background work. - `internal/config`: reads the settings, the one place they are read. - `internal/waf`: `waf`'s server. It runs the checks in `check`, and holds `waf`'s question, answer and report. It answers `waf`'s own endpoints in diff --git a/go.mod b/go.mod index 5f24224..959cd68 100644 --- a/go.mod +++ b/go.mod @@ -12,6 +12,7 @@ require ( github.com/oschwald/maxminddb-golang/v2 v2.7.0 github.com/prometheus/client_golang v1.24.1 github.com/spf13/viper v1.21.0 + go.uber.org/fx v1.24.0 golang.org/x/sys v0.48.0 ) @@ -44,6 +45,9 @@ require ( github.com/tidwall/match v1.1.1 // indirect github.com/tidwall/pretty v1.2.1 // indirect github.com/valllabh/ocsf-schema-golang v1.0.3 // indirect + go.uber.org/dig v1.19.0 // indirect + go.uber.org/multierr v1.10.0 // indirect + go.uber.org/zap v1.26.0 // indirect go.yaml.in/yaml/v3 v3.0.5 // indirect go4.org/netipx v0.0.0-20231129151722-fdeea329fbba // indirect golang.org/x/net v0.60.0 // indirect diff --git a/go.sum b/go.sum index 0f8ac76..f9328ba 100644 --- a/go.sum +++ b/go.sum @@ -97,8 +97,16 @@ github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4= github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU= github.com/valllabh/ocsf-schema-golang v1.0.3 h1:eR8k/3jP/OOqB8LRCtdJ4U+vlgd/gk5y3KMXoodrsrw= github.com/valllabh/ocsf-schema-golang v1.0.3/go.mod h1:sZ3as9xqm1SSK5feFWIR2CuGeGRhsM7TR1MbpBctzPk= +go.uber.org/dig v1.19.0 h1:BACLhebsYdpQ7IROQ1AGPjrXcP5dF80U3gKoFzbaq/4= +go.uber.org/dig v1.19.0/go.mod h1:Us0rSJiThwCv2GteUN0Q7OKvU7n5J4dxZ9JKUXozFdE= +go.uber.org/fx v1.24.0 h1:wE8mruvpg2kiiL1Vqd0CC+tr0/24XIB10Iwp2lLWzkg= +go.uber.org/fx v1.24.0/go.mod h1:AmDeGyS+ZARGKM4tlH4FY2Jr63VjbEDJHtqXTGP5hbo= go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= +go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ= +go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= +go.uber.org/zap v1.26.0 h1:sI7k6L95XOKS281NhVKOFCUNIvv9e0w4BF8N3u+tCRo= +go.uber.org/zap v1.26.0/go.mod h1:dtElttAiwGvoJ/vj4IwHBS/gXsEu/pZ50mUIRWuG0so= go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ= go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ= go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= diff --git a/internal/sww/lifecycle.go b/internal/sww/lifecycle.go new file mode 100644 index 0000000..bea8d3f --- /dev/null +++ b/internal/sww/lifecycle.go @@ -0,0 +1,198 @@ +package sww + +import ( + "context" + "errors" + "io" + "log/slog" + "net" + "net/http" + "time" + + "go.uber.org/fx" + "go.uber.org/fx/fxevent" +) + +// shutdownTimeout is how long requests in progress may take to finish +// once sww is told to stop, before their connections are closed. +// runit and docker wait a little longer before they kill the process. +const shutdownTimeout = 5 * time.Second + +// requestLog is where a daemon's server writes the request log: stdout, and +// the remote log sender while there is one. fx tells parts apart by type, so +// it has a type of its own. +type requestLog struct { + io.Writer +} + +// servingFailed gets why serving failed, for run, which then stops the +// daemon. fx tells parts apart by type, so it has a type of its own. +type servingFailed chan error + +// utcNow is the time the state files, the alerts and the rate limits go by. +func utcNow() time.Time { + return time.Now().UTC() +} + +// startError is why a daemon cannot start: the message its process log gives, +// and the error it logs with it. +type startError struct { + message string + err error +} + +func (e startError) Error() string { + return e.message + ": " + e.err.Error() +} + +func (e startError) Unwrap() error { + return e.err +} + +// cannotStart logs why a daemon cannot start, with the message of the +// startError in err, and returns its exit status. +func cannotStart(processLog *slog.Logger, err error) int { + message, cause := "cannot start", err + + failed, ok := errors.AsType[startError](err) + if ok { + message, cause = failed.message, failed.err + } + + processLog.Error(message, "error", cause.Error()) + + return 1 +} + +// listen listens on address, which the setting names. +func listen(address, setting string) (net.Listener, error) { + listener, err := (&net.ListenConfig{}).Listen( + context.Background(), "tcp", address) + if err != nil { + return nil, startError{"cannot listen on " + setting, err} + } + + return listener, nil +} + +// background returns the hook that runs loop on a goroutine of its own from +// the start, and at the stop ends it and waits for it to return. +func background(loop func(context.Context)) fx.Hook { + running, stop := context.WithCancel(context.Background()) + ended := make(chan struct{}) + + return fx.StartStopHook( + func() { + go func() { + loop(running) + close(ended) + }() + }, + func() { + stop() + <-ended + }, + ) +} + +// serve serves requests on listener from the start. At the stop it gives the +// requests in progress shutdownTimeout to finish, then closes their +// connections. When serving fails, it logs why and sends the error to +// failed. +func serve( + lc fx.Lifecycle, server *http.Server, listener net.Listener, + processLog *slog.Logger, failed servingFailed, +) { + served := make(chan error, 1) + + lc.Append(fx.Hook{ + OnStart: func(context.Context) error { + go func() { + err := server.Serve(listener) + if !errors.Is(err, http.ErrServerClosed) { + processLog.Error("serving failed", "error", err.Error()) + + failed <- err + } + + served <- err + }() + + return nil + }, + OnStop: func(ctx context.Context) error { + processLog.Info("stopping") + + shutdownCtx, cancel := context.WithTimeout(ctx, shutdownTimeout) + defer cancel() + + err := server.Shutdown(shutdownCtx) + if err != nil { + processLog.Warn("requests still in progress were cut off", + "error", err.Error()) + + _ = server.Close() + } + + err = <-served + if !errors.Is(err, http.ErrServerClosed) { + return err + } + + return nil + }, + }) +} + +// run starts app, which serves until ctx is done or serving fails, as +// failed tells. Then it stops app and takes the daemon's last step. It +// returns the process's exit status, 1 when serving failed, a part could +// not stop in order or the last step failed; each logs why. +func run( + ctx context.Context, app *fx.App, failed servingFailed, + processLog *slog.Logger, lastStep func() error, +) int { + // The hooks only start goroutines, and end them at the stop, so neither + // is cut short by a deadline or by ctx. + err := app.Start(context.WithoutCancel(ctx)) + if err != nil { + return cannotStart(processLog, err) + } + + status := 0 + + select { + case <-ctx.Done(): + case <-failed: + status = 1 + } + + err = app.Stop(context.WithoutCancel(ctx)) + if err != nil { + status = 1 + } + + err = lastStep() + if err != nil { + status = 1 + } + + if status == 0 { + processLog.Info("stopped") + } + + return status +} + +// fxEventLogger returns what fx.WithLogger takes to write fx's own events to +// processLog at debug, which the daemons' log levels normally hold back. Its +// errors are at debug too: the daemon logs each one itself. +func fxEventLogger(processLog *slog.Logger) func() fxevent.Logger { + return func() fxevent.Logger { + logger := &fxevent.SlogLogger{Logger: processLog} + logger.UseLogLevel(slog.LevelDebug) + logger.UseErrorLevel(slog.LevelDebug) + + return logger + } +} diff --git a/internal/sww/rproxy.go b/internal/sww/rproxy.go index f3f4dd3..1f886fa 100644 --- a/internal/sww/rproxy.go +++ b/internal/sww/rproxy.go @@ -2,12 +2,13 @@ package sww import ( "context" - "errors" "log/slog" "net" "net/http" "os" + "go.uber.org/fx" + "sneak.berlin/go/smallwebwaf/internal/config" "sneak.berlin/go/smallwebwaf/internal/requestlog" "sneak.berlin/go/smallwebwaf/internal/rproxy" @@ -30,26 +31,31 @@ func RunRProxy(ctx context.Context, params Params) int { cfg, err := config.RProxyFromEnvironment(params.Viper) if err != nil { - processLog.Error("invalid setting", "error", err.Error()) - - return 1 + return cannotStart(processLog, startError{"invalid setting", err}) } - server := rproxy.New(rproxy.Params{ - Config: cfg, - RequestLog: params.Stdout, - ProcessLog: processLog, - }) + var ( + server *rproxy.Server + listener net.Listener + ) - listener, err := (&net.ListenConfig{}).Listen(ctx, "tcp", cfg.ListenAddr) + failed := make(servingFailed, 1) + + app := fx.New( + fx.Supply(cfg, processLog, requestLog{params.Stdout}, failed), + fx.Provide( + newRProxyServer, + func(server *rproxy.Server) *http.Server { return server.Server }, + newRProxyListener, + ), + fx.Invoke(serve), + fx.Populate(&server, &listener), + fx.WithLogger(fxEventLogger(processLog)), + ) + + err = app.Err() if err != nil { - processLog.Error( - "cannot listen on SWW_RPROXY_LISTEN_ADDR", - "error", - err.Error(), - ) - - return 1 + return cannotStart(processLog, err) } processLog.Info("starting", @@ -57,52 +63,25 @@ func RunRProxy(ctx context.Context, params Params) int { "address", listener.Addr().String(), "settings", cfg) - return serveRProxy(ctx, server, listener, processLog) + return run(ctx, app, failed, processLog, func() error { + server.WaitForReports() + + return nil + }) } -// serveRProxy serves requests on listener until ctx is done, and then stops as -// RunRProxy says. -func serveRProxy( - ctx context.Context, server *rproxy.Server, listener net.Listener, - processLog *slog.Logger, -) int { - served := make(chan error, 1) - - go func() { - served <- server.Serve(listener) - }() - - select { - case err := <-served: - processLog.Error("serving failed", "error", err.Error()) - - return 1 - case <-ctx.Done(): - } - - processLog.Info("stopping") - - shutdownCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), - shutdownTimeout) - defer cancel() - - err := server.Shutdown(shutdownCtx) - if err != nil { - processLog.Warn("requests still in progress were cut off", - "error", err.Error()) - - _ = server.Close() - } - - err = <-served - if !errors.Is(err, http.ErrServerClosed) { - processLog.Error("serving failed", "error", err.Error()) - - return 1 - } - - server.WaitForReports() - processLog.Info("stopped") - - return 0 +// newRProxyServer returns the server rproxy runs. +func newRProxyServer( + cfg *config.RProxy, out requestLog, processLog *slog.Logger, +) *rproxy.Server { + return rproxy.New(rproxy.Params{ + Config: cfg, + RequestLog: out, + ProcessLog: processLog, + }) +} + +// newRProxyListener listens on SWW_RPROXY_LISTEN_ADDR. +func newRProxyListener(cfg *config.RProxy) (net.Listener, error) { + return listen(cfg.ListenAddr, "SWW_RPROXY_LISTEN_ADDR") } diff --git a/internal/sww/sww.go b/internal/sww/sww.go index 6dc2d10..c526ec9 100644 --- a/internal/sww/sww.go +++ b/internal/sww/sww.go @@ -4,17 +4,14 @@ // stop, and then stops in an orderly way, writing the state and cache files. // `sww rproxy` reads rproxy's settings alone, and runs the reverse proxy in // front of one app that asks waf about each request. `sww healthcheck` is the -// container's health check. +// container's health check. fx builds the parts of each daemon, starts their +// background work and stops it. package sww import ( "context" - "errors" "fmt" "io" - "log/slog" - "net" - "net/http" "os" "os/signal" "syscall" @@ -22,29 +19,9 @@ import ( "github.com/spf13/viper" - "sneak.berlin/go/smallwebwaf/internal/alerts" "sneak.berlin/go/smallwebwaf/internal/config" - "sneak.berlin/go/smallwebwaf/internal/coreruleset" - "sneak.berlin/go/smallwebwaf/internal/geojs" - "sneak.berlin/go/smallwebwaf/internal/lookup" - "sneak.berlin/go/smallwebwaf/internal/remotelog" - "sneak.berlin/go/smallwebwaf/internal/reputation" - "sneak.berlin/go/smallwebwaf/internal/requestlog" - "sneak.berlin/go/smallwebwaf/internal/rules" - "sneak.berlin/go/smallwebwaf/internal/state" - "sneak.berlin/go/smallwebwaf/internal/waf" ) -// shutdownTimeout is how long requests in progress may take to finish -// once sww is told to stop, before their connections are closed. -// runit and docker wait a little longer before they kill the process. -const shutdownTimeout = 5 * time.Second - -// remoteLogStopTimeout is how long, as waf stops, the log lines still -// waiting are sent to SWW_WAF_LOG_REMOTE_URL before they are given up. stdout has -// carried them. -const remoteLogStopTimeout = 2 * time.Second - // usageStatus is the exit status with no command, or one sww does not // know. const usageStatus = 2 @@ -110,375 +87,3 @@ func printUsage(w io.Writer) int { return usageStatus } - -// RunWAF is `sww waf`: it reads the settings, the rule files, -// the lookup database and the state and cache files, then serves requests until -// ctx is done. It returns the process's exit status, 1 when waf cannot start. -func RunWAF(ctx context.Context, params Params) int { - // Until the settings are read, the one message is an invalid setting's - // error, which every SWW_WAF_LOG_LEVEL lets through. - processLog := requestlog.NewProcessLogger(params.Stdout, - config.InstanceName(params.Viper), slog.LevelError) - - cfg, err := config.WAFFromEnvironment(params.Viper) - if err != nil { - return cannotStart(processLog, "invalid setting", err) - } - - // While SWW_WAF_LOG_REMOTE_URL is set, every line on stdout from here on - // is sent there too. - stdout := params.Stdout - - var remote *remotelog.Sender - - if cfg.LogRemoteURL != nil { - remote = newRemoteLogSender(cfg) - stdout = io.MultiWriter(params.Stdout, remote) - } - - processLog = requestlog.NewProcessLogger( - stdout, - cfg.InstanceName, - cfg.LogLevel, - ) - - if remote != nil { - stopSending := startSending(ctx, remote, processLog) - defer stopSending() - } - - return runWAFWithSettings( - ctx, - params, - cfg, - stdout, - remote, - processLog, - ) -} - -// runWAFWithSettings is the rest of RunWAF once the settings are read and -// the process log goes where they say. remote is nil unless -// SWW_WAF_LOG_REMOTE_URL is set. -func runWAFWithSettings( - ctx context.Context, - params Params, - cfg *config.WAF, - stdout io.Writer, - remote *remotelog.Sender, - processLog *slog.Logger, -) int { - // The state files and the alerts give times in UTC. - now := func() time.Time { return time.Now().UTC() } - - alertQueue := newAlertQueue(cfg, now, processLog) - - ruleFiles, err := rules.Load(rules.Params{ - Dir: cfg.RuleFilesDir, - Enabled: cfg.RuleFilesEnabled, - ProcessLog: processLog, - Alerts: alertQueue, - }) - if err != nil { - return cannotStart(processLog, "cannot use the rule files", err) - } - - crs, err := waf.NewCoreRuleSet(cfg) - if err != nil { - return cannotStart(processLog, "cannot use the Core Rule Set", err) - } - - server, err := newServer( - cfg, - stdout, - processLog, - now, - ruleFiles, - alertQueue, - crs, - params.BesideLookupTimeLimit, - ) - if err != nil { - return cannotStart(processLog, "cannot use the lookup database", err) - } - - if remote != nil { - server.Metrics.AddRemoteLog(remote) - } - - files, err := loadStateFiles(cfg, server, alertQueue, now, processLog) - if err != nil { - return cannotStart( - processLog, - "cannot use the state and cache files", - err, - ) - } - - listener, err := (&net.ListenConfig{}).Listen(ctx, "tcp", cfg.ListenAddr) - if err != nil { - return cannotStart( - processLog, - "cannot listen on SWW_WAF_LISTEN_ADDR", - err, - ) - } - - processLog.Info("starting", - "version", params.Version, - "address", listener.Addr().String(), - "settings", cfg) - - return serve( - ctx, - server, - listener, - files, - ruleFiles, - alertQueue, - processLog, - ) -} - -// cannotStart logs why waf cannot start, and returns its exit status. -func cannotStart(processLog *slog.Logger, message string, err error) int { - processLog.Error(message, "error", err.Error()) - - return 1 -} - -// newServer returns the server waf runs, with the metrics of the alerts, -// after reading the lookup database while SWW_WAF_LOOKUP_SOURCE is file. A lookup -// database that cannot be read is an error. -func newServer( - cfg *config.WAF, stdout io.Writer, processLog *slog.Logger, - now func() time.Time, ruleFiles *rules.Files, alertQueue *alerts.Queue, - crs *coreruleset.CoreRuleSet, besideLookupTimeLimit time.Duration, -) (*waf.Server, error) { - var lookupFile *lookup.File - - if cfg.LookupSource == "file" { - var err error - - lookupFile, err = lookup.OpenFile(lookup.FileParams{ - Path: cfg.LookupDBPath, - Now: now, - ProcessLog: processLog, - Alerts: alertQueue, - }) - if err != nil { - return nil, err - } - } - - server := waf.New(waf.Params{ - Config: cfg, - RequestLog: stdout, - ProcessLog: processLog, - GeoJSURL: geojs.URL, - AbuseIPDBURL: reputation.AbuseIPDBURL, - LookupFile: lookupFile, - CoreRuleSet: crs, - Now: now, - Rules: ruleFiles, - Alerts: alertQueue, - - BesideLookupTimeLimit: besideLookupTimeLimit, - }) - server.Metrics.AddAlerts(alertQueue) - - if lookupFile != nil { - server.Metrics.AddLookupFile( - lookupFile.LastRead, - lookupFile.ReadFailures, - ) - } - - return server, nil -} - -// loadStateFiles reads the state and cache files into the parts of server and -// into alertQueue, as state.Load does. -func loadStateFiles( - cfg *config.WAF, server *waf.Server, alertQueue *alerts.Queue, - now func() time.Time, processLog *slog.Logger, -) (*state.Files, error) { - return state.Load(state.Params{ - Dir: cfg.StateDir, - CacheDir: cfg.CacheDir, - BansWriteDelay: cfg.BansWriteDelay, - WriteInterval: cfg.StateWriteInterval, - Ledger: server.Ledger, - Limiter: server.Limiter, - GeoJS: server.GeoJS, - Lists: server.Lists, - DNSBL: server.DNSBL, - AbuseIPDB: server.AbuseIPDB, - RouteWatch: server.RouteWatch, - Alerts: alertQueue, - Anomalies: server.Anomalies, - Now: now, - ProcessLog: processLog, - Metrics: server.Metrics, - }) -} - -// newAlertQueue returns the queue of the alerts to the webhook, Slack and -// ntfy, with the settings for them. -func newAlertQueue( - cfg *config.WAF, now func() time.Time, processLog *slog.Logger, -) *alerts.Queue { - return alerts.New(alerts.Params{ - WebhookURL: cfg.AlertWebhookURL, - WebhookHeaders: cfg.AlertWebhookHeaders, - SlackURL: cfg.AlertSlackWebhookURL, - NtfyURL: cfg.AlertNtfyURL, - NtfyToken: cfg.AlertNtfyToken, - Events: cfg.AlertEvents, - Cooldown: cfg.AlertCooldown, - MaxPerHour: cfg.AlertMaxPerHour, - Instance: cfg.InstanceName, - Now: now, - ProcessLog: processLog, - }) -} - -// newRemoteLogSender returns a sender of the log lines to -// SWW_WAF_LOG_REMOTE_URL, with the settings for it. -func newRemoteLogSender(cfg *config.WAF) *remotelog.Sender { - return remotelog.New(remotelog.Params{ - URL: cfg.LogRemoteURL, - RootCAs: cfg.LogRemoteTLSCAs, - BufferLines: cfg.LogRemoteBufferLines, - Facility: cfg.LogRemoteFacility, - AppName: cfg.LogRemoteAppName, - }) -} - -// startSending runs remote until the function it returns is called, which -// then waits at most remoteLogStopTimeout for the lines still waiting to -// be sent. Sending goes on after ctx is done, so that the lines written -// while sww stops are sent too. -func startSending( - ctx context.Context, remote *remotelog.Sender, processLog *slog.Logger, -) func() { - sending, stop := context.WithCancel(context.WithoutCancel(ctx)) - sent := make(chan struct{}) - - go func() { - remote.Run(sending, processLog) - close(sent) - }() - - return func() { - stop() - - select { - case <-sent: - case <-time.After(remoteLogStopTimeout): - } - } -} - -// serve serves requests on listener, writes the state and cache files as they -// are due, takes in an admin's edits of them, reads the rule files again as -// they change, and the lookup database when it is replaced, fetches the -// lists the settings name by URL as they are due, and sends the alerts, -// until ctx is done. Then it gives the requests in progress -// shutdownTimeout to finish, and writes every state and cache file, -// alerts.json with the alerts still waiting. -func serve( - ctx context.Context, server *waf.Server, listener net.Listener, - files *state.Files, ruleFiles *rules.Files, alertQueue *alerts.Queue, - processLog *slog.Logger, -) int { - served := make(chan error, 1) - - go func() { - served <- server.Serve(listener) - }() - - writing, stopWriting := context.WithCancel(ctx) - defer stopWriting() - - written := inBackground(func() { files.Run(writing) }) - watched := inBackground(func() { files.Watch(writing) }) - rulesWatched := inBackground(func() { ruleFiles.Watch(writing) }) - lookupFileWatched := inBackground(func() { - if server.LookupFile != nil { - server.LookupFile.Watch(writing) - } - }) - listsFetched := inBackground(func() { server.Lists.Run(writing) }) - alertsSent := inBackground(func() { alertQueue.Run(writing) }) - - select { - case err := <-served: - processLog.Error("serving failed", "error", err.Error()) - - return 1 - case <-ctx.Done(): - } - - processLog.Info("stopping") - - shutdownCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), - shutdownTimeout) - defer cancel() - - err := server.Shutdown(shutdownCtx) - if err != nil { - processLog.Warn("requests still in progress were cut off", - "error", err.Error()) - - _ = server.Close() - } - - err = <-served - if !errors.Is(err, http.ErrServerClosed) { - processLog.Error("serving failed", "error", err.Error()) - - return 1 - } - - // Run and Watch have ended, so nothing else reads or writes the - // files, and no alert is being sent, so that alerts.json keeps every - // alert not yet sent. Every request has ended too, but for one cut off - // because Shutdown timed out, which adds to its client's history only as - // it ends. That can be after this write, and then that request is missing - // from clients.json. - <-written - <-watched - <-rulesWatched - <-lookupFileWatched - <-listsFetched - <-alertsSent - - err = files.WriteAll() - if err != nil { - processLog.Error( - "writing the state and cache files failed", - "error", - err.Error(), - ) - - return 1 - } - - processLog.Info("stopped") - - return 0 -} - -// inBackground runs task on a goroutine of its own, and returns a channel -// that is closed once task has returned. -func inBackground(task func()) <-chan struct{} { - done := make(chan struct{}) - - go func() { - task() - close(done) - }() - - return done -} diff --git a/internal/sww/waf.go b/internal/sww/waf.go new file mode 100644 index 0000000..e6dbefd --- /dev/null +++ b/internal/sww/waf.go @@ -0,0 +1,490 @@ +package sww + +import ( + "context" + "io" + "log/slog" + "net" + "net/http" + "time" + + "go.uber.org/fx" + + "sneak.berlin/go/smallwebwaf/internal/alerts" + "sneak.berlin/go/smallwebwaf/internal/anomaly" + "sneak.berlin/go/smallwebwaf/internal/bans" + "sneak.berlin/go/smallwebwaf/internal/config" + "sneak.berlin/go/smallwebwaf/internal/coreruleset" + "sneak.berlin/go/smallwebwaf/internal/geojs" + "sneak.berlin/go/smallwebwaf/internal/lookup" + "sneak.berlin/go/smallwebwaf/internal/metrics" + "sneak.berlin/go/smallwebwaf/internal/ratelimit" + "sneak.berlin/go/smallwebwaf/internal/remotelog" + "sneak.berlin/go/smallwebwaf/internal/reputation" + "sneak.berlin/go/smallwebwaf/internal/requestlog" + "sneak.berlin/go/smallwebwaf/internal/routewatch" + "sneak.berlin/go/smallwebwaf/internal/rules" + "sneak.berlin/go/smallwebwaf/internal/state" + "sneak.berlin/go/smallwebwaf/internal/waf" +) + +// remoteLogStopTimeout is how long, as waf stops, the log lines still +// waiting are sent to SWW_WAF_LOG_REMOTE_URL before they are given up. stdout has +// carried them. +const remoteLogStopTimeout = 2 * time.Second + +// RunWAF is `sww waf`: it reads the settings, the rule files, +// the lookup database and the state and cache files, then serves requests until +// ctx is done. Then it gives the requests in progress shutdownTimeout to +// finish, ends its background work and writes every state and cache file, +// alerts.json with the alerts still waiting. It returns the process's exit +// status, 1 when waf cannot start or stop in order. +func RunWAF(ctx context.Context, params Params) int { + // Until the settings are read, the one message is an invalid setting's + // error, which every SWW_WAF_LOG_LEVEL lets through. + processLog := requestlog.NewProcessLogger(params.Stdout, + config.InstanceName(params.Viper), slog.LevelError) + + cfg, err := config.WAFFromEnvironment(params.Viper) + if err != nil { + return cannotStart(processLog, startError{"invalid setting", err}) + } + + // While SWW_WAF_LOG_REMOTE_URL is set, every line on stdout from here on + // is sent there too. The sender runs before any part is built, so that it + // sends why waf cannot start. + stdout := params.Stdout + + var remote *remotelog.Sender + + if cfg.LogRemoteURL != nil { + remote = newRemoteLogSender(cfg) + stdout = io.MultiWriter(params.Stdout, remote) + } + + processLog = requestlog.NewProcessLogger( + stdout, + cfg.InstanceName, + cfg.LogLevel, + ) + + if remote != nil { + stopSending := startSending(ctx, remote, processLog) + defer stopSending() + } + + var ( + files *state.Files + listener net.Listener + ) + + failed := make(servingFailed, 1) + + app := fx.New( + fx.Supply( + params, + cfg, + processLog, + requestLog{stdout}, + remote, + failed, + ), + fx.Provide( + newAlertQueue, newRuleFiles, newCoreRuleSet, newLookupFile, + newLimiter, newLedger, newAnomalyCounters, + newLists, newDNSBL, newAbuseIPDB, newRouteWatch, + newMetrics, newGeoJS, newWAFServer, + func(server *waf.Server) *http.Server { return server.Server }, + newWAFListener, newStateFiles, + ), + // fx stops hooks in the reverse of the order they were added in. The + // state files are read before serving is set up, so that serving + // stops before their loops do. + fx.Populate(&files), + fx.Invoke(serve), + fx.Populate(&listener), + fx.WithLogger(fxEventLogger(processLog)), + ) + + err = app.Err() + if err != nil { + return cannotStart(processLog, err) + } + + processLog.Info("starting", + "version", params.Version, + "address", listener.Addr().String(), + "settings", cfg) + + // The last write follows the stop of every hook, and so the end of every + // loop that changes the state or raises an alert. A hook of the state + // files would stop before the loops of the parts built ahead of them. + return run(ctx, app, failed, processLog, func() error { + err := files.WriteAll() + if err != nil { + processLog.Error("writing the state and cache files failed", + "error", err.Error()) + } + + return err + }) +} + +// newAlertQueue returns the queue of the alerts to the webhook, Slack and +// ntfy, with the settings for them. Until waf stops, it sends them. +func newAlertQueue( + lc fx.Lifecycle, cfg *config.WAF, processLog *slog.Logger, +) *alerts.Queue { + alertQueue := alerts.New(alerts.Params{ + WebhookURL: cfg.AlertWebhookURL, + WebhookHeaders: cfg.AlertWebhookHeaders, + SlackURL: cfg.AlertSlackWebhookURL, + NtfyURL: cfg.AlertNtfyURL, + NtfyToken: cfg.AlertNtfyToken, + Events: cfg.AlertEvents, + Cooldown: cfg.AlertCooldown, + MaxPerHour: cfg.AlertMaxPerHour, + Instance: cfg.InstanceName, + Now: utcNow, + ProcessLog: processLog, + }) + + lc.Append(background(alertQueue.Run)) + + return alertQueue +} + +// newRuleFiles reads the rule files, and reads them again as they change +// until waf stops. +func newRuleFiles( + lc fx.Lifecycle, cfg *config.WAF, processLog *slog.Logger, + alertQueue *alerts.Queue, +) (*rules.Files, error) { + ruleFiles, err := rules.Load(rules.Params{ + Dir: cfg.RuleFilesDir, + Enabled: cfg.RuleFilesEnabled, + ProcessLog: processLog, + Alerts: alertQueue, + }) + if err != nil { + return nil, startError{"cannot use the rule files", err} + } + + lc.Append(background(ruleFiles.Watch)) + + return ruleFiles, nil +} + +// newCoreRuleSet returns the Core Rule Set, as waf.NewCoreRuleSet does. +func newCoreRuleSet(cfg *config.WAF) (*coreruleset.CoreRuleSet, error) { + crs, err := waf.NewCoreRuleSet(cfg) + if err != nil { + return nil, startError{"cannot use the Core Rule Set", err} + } + + return crs, nil +} + +// newLookupFile reads the lookup database while SWW_WAF_LOOKUP_SOURCE is +// file, and reads it again when it is replaced until waf stops. It returns +// nil while the source is anything else. +func newLookupFile( + lc fx.Lifecycle, cfg *config.WAF, processLog *slog.Logger, + alertQueue *alerts.Queue, +) (*lookup.File, error) { + if cfg.LookupSource != "file" { + return nil, nil //nolint:nilnil // no lookup database, and no error + } + + lookupFile, err := lookup.OpenFile(lookup.FileParams{ + Path: cfg.LookupDBPath, + Now: utcNow, + ProcessLog: processLog, + Alerts: alertQueue, + }) + if err != nil { + return nil, startError{"cannot use the lookup database", err} + } + + lc.Append(background(lookupFile.Watch)) + + return lookupFile, nil +} + +// newLimiter returns the table of clients, with the rate and byte limits. +func newLimiter(cfg *config.WAF) *ratelimit.Limiter { + return ratelimit.New(ratelimit.Limits{ + PerMinute: cfg.RateLimitPerMinute, + PerHour: cfg.RateLimitPerHour, + PerDay: cfg.RateLimitPerDay, + BytesPerMinute: cfg.BytesLimitPerMinute, + BytesPerHour: cfg.BytesLimitPerHour, + BytesPerDay: cfg.BytesLimitPerDay, + }, cfg.MaxTrackedClients) +} + +// newLedger returns the ledger of the bans, with the settings for them. +func newLedger(cfg *config.WAF) *bans.Ledger { + return bans.New(bans.Params{ + LimitBanDuration: cfg.LimitBanDuration, + LimitBanRepeatWindow: cfg.LimitBanRepeatWindow, + LimitBanPermanentAbove: cfg.LimitBanPermanentAbove, + AttackBanDuration: cfg.AttackBanDuration, + MaxBans: cfg.MaxBans, + }) +} + +// newAnomalyCounters returns the counters of the anomaly thresholds. +func newAnomalyCounters( + cfg *config.WAF, alertQueue *alerts.Queue, +) *anomaly.Counters { + return anomaly.New(anomaly.Params{ + Client: cfg.AnomalyClient, + Net: cfg.AnomalyNet, + ASN: cfg.AnomalyASN, + Total: cfg.AnomalyTotal, + WatchedNet: cfg.AnomalyWatchedNet, + NetV4Prefix: cfg.AnomalyNetV4Prefix, + NetV6Prefix: cfg.AnomalyNetV6Prefix, + NamedNetblocks: cfg.AnomalyWatchedNets, + Alerts: alertQueue, + }) +} + +// newLists returns the lists the settings name by URL, none fetched yet. +// Until waf stops, it fetches them as they are due. +func newLists( + lc fx.Lifecycle, cfg *config.WAF, processLog *slog.Logger, + alertQueue *alerts.Queue, +) *reputation.Lists { + lists := reputation.New(reputation.Params{ + BlocklistURLs: cfg.BlocklistURLs, + Refresh: cfg.BlocklistRefresh, + ASNLimitPercentURL: cfg.ASNLimitPercentURL, + TagLists: cfg.TagLists, + Now: utcNow, + ProcessLog: processLog, + Alerts: alertQueue, + }) + + lc.Append(background(lists.Run)) + + return lists +} + +// newDNSBL returns what asks the DNSBL zones, none asked yet. +func newDNSBL( + cfg *config.WAF, processLog *slog.Logger, alertQueue *alerts.Queue, +) *reputation.DNSBL { + return reputation.NewDNSBL(reputation.DNSBLParams{ + Zones: cfg.DNSBLZones, + Resolver: cfg.DNSBLResolver, + CacheTTL: cfg.IPReputationCacheTTL, + Timeout: cfg.DNSBLAbuseIPDBTimeout, + Now: utcNow, + ProcessLog: processLog, + Alerts: alertQueue, + }) +} + +// newAbuseIPDB returns what checks clients with AbuseIPDB while +// SWW_WAF_ABUSEIPDB_KEY is set, none checked yet. +func newAbuseIPDB( + cfg *config.WAF, processLog *slog.Logger, alertQueue *alerts.Queue, +) *reputation.AbuseIPDB { + return reputation.NewAbuseIPDB(reputation.AbuseIPDBParams{ + URL: reputation.AbuseIPDBURL, + Key: cfg.AbuseIPDBKey, + MinScore: cfg.AbuseIPDBMinScore, + DailyBudget: cfg.AbuseIPDBDailyBudget, + CacheTTL: cfg.IPReputationCacheTTL, + Timeout: cfg.DNSBLAbuseIPDBTimeout, + Now: utcNow, + ProcessLog: processLog, + Alerts: alertQueue, + }) +} + +// newRouteWatch returns what asks routewatch about clients, or nil while +// SWW_WAF_ROUTEWATCH_URL is unset. +func newRouteWatch( + cfg *config.WAF, processLog *slog.Logger, +) *routewatch.Client { + if cfg.RouteWatchURL == "" { + return nil + } + + return routewatch.New(routewatch.Params{ + URL: cfg.RouteWatchURL, + Now: utcNow, + ProcessLog: processLog, + }) +} + +// newMetrics returns the metrics, with those read from the other parts as +// the metrics are asked for: AbuseIPDB's while SWW_WAF_ABUSEIPDB_KEY is set, +// the lookup database's while there is one, and the remote log sender's +// while there is one. +func newMetrics( + cfg *config.WAF, ledger *bans.Ledger, limiter *ratelimit.Limiter, + ruleFiles *rules.Files, lists *reputation.Lists, + dnsbl *reputation.DNSBL, abuseIPDB *reputation.AbuseIPDB, + alertQueue *alerts.Queue, lookupFile *lookup.File, + remote *remotelog.Sender, +) *metrics.Metrics { + m := metrics.New(cfg.MetricsBusiestCountriesAndASNs, cfg.InstanceName) + m.AddBansAndClients(ledger, limiter, utcNow) + m.AddRules(ruleFiles) + m.AddReputation(lists, dnsbl) + + if cfg.AbuseIPDBKey != "" { + m.AddAbuseIPDB(abuseIPDB) + } + + m.AddAlerts(alertQueue) + + if lookupFile != nil { + m.AddLookupFile(lookupFile.LastRead, lookupFile.ReadFailures) + } + + if remote != nil { + m.AddRemoteLog(remote) + } + + return m +} + +// newGeoJS returns what looks clients up at GeoJS, none looked up yet. Each +// answer goes to the limiter and the ledger, as waf.AddLookup says, and each +// failure is handled as waf.GeoJSFailed says. +func newGeoJS( + cfg *config.WAF, m *metrics.Metrics, limiter *ratelimit.Limiter, + ledger *bans.Ledger, alertQueue *alerts.Queue, processLog *slog.Logger, +) *geojs.GeoJS { + return geojs.New(geojs.Params{ + URL: geojs.URL, + Answered: func(answer geojs.Answer) { + waf.AddLookup(cfg, limiter, ledger, answer) + }, + Now: utcNow, + Asked: m.GeoJSRequests.Inc, + Failed: func(err error, askingAgainIn time.Duration) { + waf.GeoJSFailed(processLog, alertQueue, m, err, askingAgainIn) + }, + WentWithoutAnswer: m.RequestsWithoutGeoJSAnswer.Inc, + }) +} + +// newWAFServer returns the server waf runs, with its parts and the time +// limit params gives. +func newWAFServer( + params Params, cfg *config.WAF, out requestLog, processLog *slog.Logger, + m *metrics.Metrics, limiter *ratelimit.Limiter, ledger *bans.Ledger, + anomalies *anomaly.Counters, lists *reputation.Lists, + dnsbl *reputation.DNSBL, abuseIPDB *reputation.AbuseIPDB, + routeWatch *routewatch.Client, geoJS *geojs.GeoJS, + lookupFile *lookup.File, crs *coreruleset.CoreRuleSet, + ruleFiles *rules.Files, alertQueue *alerts.Queue, +) *waf.Server { + return waf.New(waf.Params{ + Config: cfg, + RequestLog: out, + ProcessLog: processLog, + Metrics: m, + Limiter: limiter, + Ledger: ledger, + Anomalies: anomalies, + Lists: lists, + DNSBL: dnsbl, + AbuseIPDB: abuseIPDB, + RouteWatch: routeWatch, + GeoJS: geoJS, + LookupFile: lookupFile, + CoreRuleSet: crs, + Now: utcNow, + Rules: ruleFiles, + Alerts: alertQueue, + + BesideLookupTimeLimit: params.BesideLookupTimeLimit, + }) +} + +// newWAFListener listens on SWW_WAF_LISTEN_ADDR. +func newWAFListener(cfg *config.WAF) (net.Listener, error) { + return listen(cfg.ListenAddr, "SWW_WAF_LISTEN_ADDR") +} + +// newStateFiles reads the state and cache files into the parts and the +// alert queue, as state.Load does. Until waf stops, it writes them as they +// are due and takes in an admin's edits of them. +func newStateFiles( + lc fx.Lifecycle, cfg *config.WAF, processLog *slog.Logger, + m *metrics.Metrics, ledger *bans.Ledger, limiter *ratelimit.Limiter, + geoJS *geojs.GeoJS, lists *reputation.Lists, dnsbl *reputation.DNSBL, + abuseIPDB *reputation.AbuseIPDB, routeWatch *routewatch.Client, + alertQueue *alerts.Queue, anomalies *anomaly.Counters, +) (*state.Files, error) { + files, err := state.Load(state.Params{ + Dir: cfg.StateDir, + CacheDir: cfg.CacheDir, + BansWriteDelay: cfg.BansWriteDelay, + WriteInterval: cfg.StateWriteInterval, + Ledger: ledger, + Limiter: limiter, + GeoJS: geoJS, + Lists: lists, + DNSBL: dnsbl, + AbuseIPDB: abuseIPDB, + RouteWatch: routeWatch, + Alerts: alertQueue, + Anomalies: anomalies, + Now: utcNow, + ProcessLog: processLog, + Metrics: m, + }) + if err != nil { + return nil, startError{"cannot use the state and cache files", err} + } + + lc.Append(background(files.Run)) + lc.Append(background(files.Watch)) + + return files, nil +} + +// newRemoteLogSender returns a sender of the log lines to +// SWW_WAF_LOG_REMOTE_URL, with the settings for it. +func newRemoteLogSender(cfg *config.WAF) *remotelog.Sender { + return remotelog.New(remotelog.Params{ + URL: cfg.LogRemoteURL, + RootCAs: cfg.LogRemoteTLSCAs, + BufferLines: cfg.LogRemoteBufferLines, + Facility: cfg.LogRemoteFacility, + AppName: cfg.LogRemoteAppName, + }) +} + +// startSending runs remote until the function it returns is called, which +// then waits at most remoteLogStopTimeout for the lines still waiting to +// be sent. Sending goes on after ctx is done, so that the lines written +// while sww stops are sent too. +func startSending( + ctx context.Context, remote *remotelog.Sender, processLog *slog.Logger, +) func() { + sending, stop := context.WithCancel(context.WithoutCancel(ctx)) + sent := make(chan struct{}) + + go func() { + remote.Run(sending, processLog) + close(sent) + }() + + return func() { + stop() + + select { + case <-sent: + case <-time.After(remoteLogStopTimeout): + } + } +} diff --git a/internal/waf/abuseipdb.go b/internal/waf/abuseipdb.go index 50f64a0..0802ee2 100644 --- a/internal/waf/abuseipdb.go +++ b/internal/waf/abuseipdb.go @@ -35,7 +35,7 @@ func (abuseIPDB) check( return nil } - client := rq.h.clientGroup(rq.client) + client := clientGroup(rq.h.config, rq.client) held, _ := rq.h.limiter.Client(client) offender := held.History.Offences != ratelimit.Offences{} diff --git a/internal/waf/admin.go b/internal/waf/admin.go index d1c9278..99ddec2 100644 --- a/internal/waf/admin.go +++ b/internal/waf/admin.go @@ -139,7 +139,7 @@ func (rq *request) addBan() { ) if err == nil { - netblock, err = rq.h.banNetblock(toAdd.Netblock) + netblock, err = rq.h.parseBanNetblock(toAdd.Netblock) } if err == nil { @@ -190,12 +190,12 @@ func (rq *request) readBanToAdd() (banToAdd, error) { return toAdd, nil } -// banNetblock reads value, a netblock such as 203.0.113.0/24, or a +// parseBanNetblock reads value, a netblock such as 203.0.113.0/24, or a // client's address, which stands for the netblock a ban on that client // covers. An IPv4-mapped netblock, such as ::ffff:203.0.113.0/120, is // refused, since a client's address is looked up as IPv4 and a ban on it // would refuse nothing, and so is a value with a zone. -func (h *handler) banNetblock(value string) (netip.Prefix, error) { +func (h *handler) parseBanNetblock(value string) (netip.Prefix, error) { netblock, err := netip.ParsePrefix(value) if err == nil { if netblock.Addr().Is4In6() { @@ -224,7 +224,7 @@ func (h *handler) banNetblock(value string) (netip.Prefix, error) { return netip.Prefix{}, fmt.Errorf("netblock %q %w", value, errZone) } - return h.netblock(addr), nil + return banNetblock(h.config, addr), nil } // expiry returns when a ban made at now for duration ends: duration @@ -295,7 +295,7 @@ func (rq *request) showClient() { Bans: state.BanEntries(rq.h.ledger.Covering(addr)), } - client, seen := rq.h.limiter.Client(rq.h.clientGroup(addr)) + client, seen := rq.h.limiter.Client(clientGroup(rq.h.config, addr)) if seen { answer.Client = &client } diff --git a/internal/waf/answertime_test.go b/internal/waf/answertime_test.go index 3e184a0..c3e16b5 100644 --- a/internal/waf/answertime_test.go +++ b/internal/waf/answertime_test.go @@ -877,18 +877,13 @@ func TestWAFAnswersWithinTheTimeLimitWhileEveryOutsideSourceHangs( held, _, _ := startHeldGeoJS(t) resolver, releaseResolver := startHeldResolver(t) - server, out, _ := newWAFWith(t, func( - params waf.Params, - ) *waf.Server { - params.AbuseIPDBURL = silentAbuseIPDBURL - - return waf.New(params) - }, silentGeoJSURL, time.Now, map[string]string{ - tagDeny: "country=KP", coreRuleSetMode: block, - dnsblZones: dnsblZone, dnsblResolver: resolver, - abuseIPDBKey: accountKey, - blocklistURLs: held + "/drop.txt", asnLimitPercentURL: held + "/asn.txt", - }) + server, out, _ := newWAFWith(t, waf.New, + silentGeoJSURL, silentAbuseIPDBURL, time.Now, map[string]string{ + tagDeny: "country=KP", coreRuleSetMode: block, + dnsblZones: dnsblZone, dnsblResolver: resolver, + abuseIPDBKey: accountKey, + blocklistURLs: held + "/drop.txt", asnLimitPercentURL: held + "/asn.txt", + }) // The lists are fetched outside the synctest bubble below: a wait on the // network inside it would keep its clock from moving on. diff --git a/internal/waf/bans.go b/internal/waf/bans.go index 2da3361..bf19d96 100644 --- a/internal/waf/bans.go +++ b/internal/waf/bans.go @@ -10,6 +10,7 @@ import ( "sneak.berlin/go/smallwebwaf/internal/alerts" "sneak.berlin/go/smallwebwaf/internal/bans" + "sneak.berlin/go/smallwebwaf/internal/config" "sneak.berlin/go/smallwebwaf/internal/ratelimit" "sneak.berlin/go/smallwebwaf/internal/requestlog" ) @@ -121,7 +122,7 @@ func (rq *request) banForLimit( rq.line.Offence = requestlog.OffenceLimit rq.h.metrics.LimitHit(hit) - netblock := rq.h.netblock(rq.client) + netblock := banNetblock(rq.h.config, rq.client) if rq.h.config.Observe && !rq.wouldAlertBan(netblock, now, bans.CauseLimit) { return @@ -157,7 +158,7 @@ func (rq *request) banForLimit( } ban, made := rq.h.ledger.BanForLimit(netblock, now, notes) - rq.h.limiter.Reset(rq.h.clientGroup(rq.client)) + rq.h.limiter.Reset(clientGroup(rq.h.config, rq.client)) rq.line.BanExpires = banExpires(ban) if made { @@ -171,7 +172,7 @@ func (rq *request) banForLimit( // no ban, and raises the alert for the ban it would have made, if that // alert would be sent. It returns the action for that ban. func (rq *request) banForAttack(now time.Time, notes bans.Notes) string { - netblock := rq.h.netblock(rq.client) + netblock := banNetblock(rq.h.config, rq.client) if rq.h.config.Observe && !rq.wouldAlertBan(netblock, now, bans.CauseAttack) { return banAction( @@ -273,16 +274,16 @@ func (rq *request) netblockRequests(netblock netip.Prefix) int64 { return rq.h.limiter.Requests(netblock) + 1 } -// netblock is the netblock a ban on client covers: its IPv4 address, +// banNetblock is the netblock a ban on client covers: its IPv4 address, // widened to SWW_WAF_BAN_SCOPE_V4_PREFIX, or the IPv6 group clientGroup // counts it in. -func (h *handler) netblock(client netip.Addr) netip.Prefix { +func banNetblock(cfg *config.WAF, client netip.Addr) netip.Prefix { addr := client.Unmap() if addr.Is4() { - return netip.PrefixFrom(addr, h.config.BanScopeV4Prefix).Masked() + return netip.PrefixFrom(addr, cfg.BanScopeV4Prefix).Masked() } - return h.clientGroup(addr) + return clientGroup(cfg, addr) } // banExpires is when ban ends, as the log line gives it: a time, or diff --git a/internal/waf/besidelookup_test.go b/internal/waf/besidelookup_test.go index 4d4f6f6..1a78738 100644 --- a/internal/waf/besidelookup_test.go +++ b/internal/waf/besidelookup_test.go @@ -76,7 +76,7 @@ func newWAFHoldingTheCoreRuleSet( params.BesideLookupTimeLimit = waf.BesideLookupTimeLimit return waf.New(params) - }, silentGeoJSURL, time.Now, settings) + }, silentGeoJSURL, abuseIPDBURL, time.Now, settings) return server, out, queue } diff --git a/internal/waf/bytelimits.go b/internal/waf/bytelimits.go index 7ad1ca4..c1f3c32 100644 --- a/internal/waf/bytelimits.go +++ b/internal/waf/bytelimits.go @@ -30,7 +30,7 @@ func (byteLimits) check( } counts, hit, over := rq.h.limiter.CountBytes( - rq.h.clientGroup(rq.client), + clientGroup(rq.h.config, rq.client), now, rq.countedBytes(), rq.bytesLimitPercent.percent, diff --git a/internal/waf/client.go b/internal/waf/client.go index 9b02334..8381f0a 100644 --- a/internal/waf/client.go +++ b/internal/waf/client.go @@ -5,6 +5,8 @@ import ( "net/http" "net/netip" "slices" + + "sneak.berlin/go/smallwebwaf/internal/config" ) // peerAddress is the address of the request's TCP peer. @@ -45,10 +47,10 @@ func scheme(r *http.Request, isQuestion bool) string { // address, or its IPv6 group, the netblock its IPv6 address is in of the // length SWW_WAF_IPV6_GROUP_PREFIX sets, a /64 by default, since one abuser // usually holds a whole /64. An IPv4 address in IPv6 form counts as IPv4. -func (h *handler) clientGroup(addr netip.Addr) netip.Prefix { +func clientGroup(cfg *config.WAF, addr netip.Addr) netip.Prefix { addr = addr.Unmap() if addr.Is6() { - return netip.PrefixFrom(addr, h.config.IPv6GroupPrefix).Masked() + return netip.PrefixFrom(addr, cfg.IPv6GroupPrefix).Masked() } return netip.PrefixFrom(addr, addr.BitLen()) diff --git a/internal/waf/coreruleset.go b/internal/waf/coreruleset.go index 4acc2cc..049bc6c 100644 --- a/internal/waf/coreruleset.go +++ b/internal/waf/coreruleset.go @@ -108,7 +108,7 @@ func (rq *request) alertCoreRuleSetMatch(result coreruleset.Result) { Event: alerts.EventCoreRuleSetMatch, Host: rq.site, Client: rq.client, - Netblock: rq.h.clientGroup(rq.client), + Netblock: clientGroup(rq.h.config, rq.client), ASN: rq.line.ASN, ASName: rq.line.ASName, Country: rq.line.Country, diff --git a/internal/waf/lookup.go b/internal/waf/lookup.go index 8250667..a6fc5e4 100644 --- a/internal/waf/lookup.go +++ b/internal/waf/lookup.go @@ -2,14 +2,18 @@ package waf import ( "context" + "log/slog" "net/http" "net/netip" "strings" "time" "sneak.berlin/go/smallwebwaf/internal/alerts" + "sneak.berlin/go/smallwebwaf/internal/bans" "sneak.berlin/go/smallwebwaf/internal/config" "sneak.berlin/go/smallwebwaf/internal/geojs" + "sneak.berlin/go/smallwebwaf/internal/metrics" + "sneak.berlin/go/smallwebwaf/internal/ratelimit" ) // The headers in which an answer of allow gives rproxy the client's AS number @@ -51,7 +55,7 @@ func (rq *request) startLookUp( return result } - client := rq.h.clientGroup(rq.client) + client := clientGroup(rq.h.config, rq.client) if rq.h.config.LookupSource == "file" { result <- lookupResult{ @@ -128,22 +132,30 @@ func countryTag(country string) string { return config.CountryTagPrefix + country } -// addLookup adds answer, an answer about a client from the lookup -// database or GeoJS, to the client's history, and to the notes of the bans -// on its netblock that have no AS number, AS name or country yet. -func (h *handler) addLookup(answer geojs.Answer) { - h.limiter.AddLookup(answer.Client, answer.Answered, +// AddLookup adds answer, an answer about a client from the lookup database +// or GeoJS, to the client's history in limiter, and to the notes of the bans +// in ledger on its netblock that have no AS number, AS name or country yet. +// cfg sets the netblock's size. +func AddLookup( + cfg *config.WAF, limiter *ratelimit.Limiter, ledger *bans.Ledger, + answer geojs.Answer, +) { + limiter.AddLookup(answer.Client, answer.Answered, answer.ASN, answer.ASName, answer.Country) - h.ledger.AddLookup(h.netblock(answer.Client.Addr()), + ledger.AddLookup(banNetblock(cfg, answer.Client.Addr()), answer.ASN, answer.ASName, answer.Country) } -// geojsFailed logs a failure of GeoJS, raises a source_failure alert for it -// and counts it. askingAgainIn is how long GeoJS is left alone after it. -func (h *handler) geojsFailed(err error, askingAgainIn time.Duration) { - h.processLog.Warn("asking GeoJS failed", +// GeoJSFailed logs a failure of GeoJS to processLog, raises a +// source_failure alert for it on alertQueue and counts it in m. +// askingAgainIn is how long GeoJS is left alone after it. +func GeoJSFailed( + processLog *slog.Logger, alertQueue *alerts.Queue, m *metrics.Metrics, + err error, askingAgainIn time.Duration, +) { + processLog.Warn("asking GeoJS failed", "error", err.Error(), "asking_again_in", askingAgainIn.String()) - h.alerts.Raise(alerts.Alert{ + alertQueue.Raise(alerts.Alert{ Event: alerts.EventSourceFailure, Reason: "asking GeoJS failed", Detail: map[string]any{ @@ -151,7 +163,7 @@ func (h *handler) geojsFailed(err error, askingAgainIn time.Duration) { "asking_again_in": askingAgainIn.String(), }, }) - h.metrics.GeoJSFailures.Inc() + m.GeoJSFailures.Inc() } // setLookupHeaders sets the headers that give the client's AS number and diff --git a/internal/waf/proxy.go b/internal/waf/proxy.go index f377216..e1bd713 100644 --- a/internal/waf/proxy.go +++ b/internal/waf/proxy.go @@ -57,12 +57,28 @@ type Params struct { RequestLog io.Writer // ProcessLog receives the process's own messages. ProcessLog *slog.Logger - // GeoJSURL is where clients' AS numbers and countries are looked up - // while SWW_WAF_LOOKUP_SOURCE is geojs, normally geojs.URL. - GeoJSURL string - // AbuseIPDBURL is where clients are checked with AbuseIPDB while - // SWW_WAF_ABUSEIPDB_KEY is set, normally reputation.AbuseIPDBURL. - AbuseIPDBURL string + // Metrics count what waf does. Whoever builds them adds the metrics + // read from the other parts. + Metrics *metrics.Metrics + // Limiter is the table of clients the rate limits count, with each + // client's history. + Limiter *ratelimit.Limiter + // Ledger holds the bans. + Ledger *bans.Ledger + // Anomalies are the counters of the anomaly thresholds. + Anomalies *anomaly.Counters + // Lists are the lists fetched from URLs, DNSBL the DNSBL zones' + // verdicts, and AbuseIPDB AbuseIPDB's scores and the checks spent. + Lists *reputation.Lists + DNSBL *reputation.DNSBL + AbuseIPDB *reputation.AbuseIPDB + // RouteWatch asks routewatch about clients, and is nil while + // SWW_WAF_ROUTEWATCH_URL is unset. + RouteWatch *routewatch.Client + // GeoJS looks clients' AS numbers and countries up while + // SWW_WAF_LOOKUP_SOURCE is geojs. It is given AddLookup as its Answered + // and GeoJSFailed as its Failed. + GeoJS *geojs.GeoJS // LookupFile is the lookup database they are looked up in while // SWW_WAF_LOOKUP_SOURCE is file, and nil otherwise. LookupFile *lookup.File @@ -99,11 +115,8 @@ type CoreRuleSetInspector interface { ) (coreruleset.Result, []byte, error) } -// Server is the server waf runs, with the parts whose state the state -// files keep, the lookup database, nil unless SWW_WAF_LOOKUP_SOURCE is file, the -// lists fetched from URLs, which its Run fetches, the DNSBL zones' verdicts, -// AbuseIPDB's scores and checks spent, routewatch's answers, and the metrics. -// RouteWatch is nil while SWW_WAF_ROUTEWATCH_URL is unset. +// Server is the server waf runs, with the parts of its Params. The tests +// read them. type Server struct { *http.Server @@ -119,129 +132,45 @@ type Server struct { Metrics *metrics.Metrics } -// newHandler returns the handler with what every request shares, as the -// settings in params make it. +// newHandler returns the handler with what every request shares, the parts +// in params among it. func newHandler(params Params) *handler { - m := metrics.New( - params.Config.MetricsBusiestCountriesAndASNs, - params.Config.InstanceName, - ) - lists, dnsbl, abuseIPDB := newReputation(params, m) - awaitingReport, err := lru.New[string, *decision](maxAwaitingReport) if err != nil { panic(err) // New fails only for a size below one } - h := &handler{ + return &handler{ config: params.Config, requestLog: params.RequestLog, processLog: params.ProcessLog, now: params.Now, - metrics: m, + metrics: params.Metrics, awaitingReport: awaitingReport, - limiter: ratelimit.New(ratelimit.Limits{ - PerMinute: params.Config.RateLimitPerMinute, - PerHour: params.Config.RateLimitPerHour, - PerDay: params.Config.RateLimitPerDay, - BytesPerMinute: params.Config.BytesLimitPerMinute, - BytesPerHour: params.Config.BytesLimitPerHour, - BytesPerDay: params.Config.BytesLimitPerDay, - }, params.Config.MaxTrackedClients), - ledger: bans.New(bans.Params{ - LimitBanDuration: params.Config.LimitBanDuration, - LimitBanRepeatWindow: params.Config.LimitBanRepeatWindow, - LimitBanPermanentAbove: params.Config.LimitBanPermanentAbove, - AttackBanDuration: params.Config.AttackBanDuration, - MaxBans: params.Config.MaxBans, - }), - anomalies: anomaly.New(anomaly.Params{ - Client: params.Config.AnomalyClient, - Net: params.Config.AnomalyNet, - ASN: params.Config.AnomalyASN, - Total: params.Config.AnomalyTotal, - WatchedNet: params.Config.AnomalyWatchedNet, - NetV4Prefix: params.Config.AnomalyNetV4Prefix, - NetV6Prefix: params.Config.AnomalyNetV6Prefix, - NamedNetblocks: params.Config.AnomalyWatchedNets, - Alerts: params.Alerts, - }), - lookupFile: params.LookupFile, - lists: lists, - dnsbl: dnsbl, - abuseIPDB: abuseIPDB, - rules: params.Rules, - coreRuleSet: params.CoreRuleSet, - alerts: params.Alerts, - + limiter: params.Limiter, + ledger: params.Ledger, + geojs: params.GeoJS, + anomalies: params.Anomalies, + lookupFile: params.LookupFile, + lists: params.Lists, + dnsbl: params.DNSBL, + abuseIPDB: params.AbuseIPDB, + routeWatch: params.RouteWatch, + rules: params.Rules, + coreRuleSet: params.CoreRuleSet, + alerts: params.Alerts, + // The country list, the headers, the tag settings that name an asn= + // or country= tag and the biased thresholds act on the answer before + // the request goes on. + waitForGeoJS: len(params.Config.ExclusivelyAllowedCountries) > 0 || + params.Config.AddLookupHeaders || + params.Config.TagsNeedLookup() || + biasedThresholdsSet(params.Config), besideLookupLimit: cmp.Or( params.BesideLookupTimeLimit, besideLookupTimeLimit, ), } - if params.Config.RouteWatchURL != "" { - h.routeWatch = routewatch.New(routewatch.Params{ - URL: params.Config.RouteWatchURL, Now: params.Now, ProcessLog: params.ProcessLog, - }) - } - - // The country list, the headers, the tag settings that name an asn= or - // country= tag and the biased thresholds act on the answer before the - // request goes on. - h.waitForGeoJS = len(params.Config.ExclusivelyAllowedCountries) > 0 || - params.Config.AddLookupHeaders || params.Config.TagsNeedLookup() || - biasedThresholdsSet(params.Config) - h.geojs = geojs.New(geojs.Params{ - URL: params.GeoJSURL, - Answered: h.addLookup, - Now: params.Now, - Asked: m.GeoJSRequests.Inc, - Failed: h.geojsFailed, - WentWithoutAnswer: m.RequestsWithoutGeoJSAnswer.Inc, - }) - m.AddBansAndClients(h.ledger, h.limiter, params.Now) - m.AddRules(params.Rules) - - return h -} - -// newReputation returns the lists fetched from URLs, the DNSBL zones' -// verdicts and AbuseIPDB's scores, as the settings in params name them, -// with none fetched, asked for or checked yet, and adds their metrics to -// m, AbuseIPDB's while SWW_WAF_ABUSEIPDB_KEY is set. -func newReputation( - params Params, m *metrics.Metrics, -) (*reputation.Lists, *reputation.DNSBL, *reputation.AbuseIPDB) { - cfg := params.Config - lists := reputation.New(reputation.Params{ - BlocklistURLs: cfg.BlocklistURLs, - Refresh: cfg.BlocklistRefresh, - ASNLimitPercentURL: cfg.ASNLimitPercentURL, - TagLists: cfg.TagLists, - Now: params.Now, - ProcessLog: params.ProcessLog, - Alerts: params.Alerts, - }) - dnsbl := reputation.NewDNSBL(reputation.DNSBLParams{ - Zones: cfg.DNSBLZones, Resolver: cfg.DNSBLResolver, - CacheTTL: cfg.IPReputationCacheTTL, - Timeout: cfg.DNSBLAbuseIPDBTimeout, Now: params.Now, ProcessLog: params.ProcessLog, - Alerts: params.Alerts, - }) - abuseIPDB := reputation.NewAbuseIPDB(reputation.AbuseIPDBParams{ - URL: params.AbuseIPDBURL, Key: cfg.AbuseIPDBKey, MinScore: cfg.AbuseIPDBMinScore, - DailyBudget: cfg.AbuseIPDBDailyBudget, CacheTTL: cfg.IPReputationCacheTTL, - Timeout: cfg.DNSBLAbuseIPDBTimeout, Now: params.Now, ProcessLog: params.ProcessLog, - Alerts: params.Alerts, - }) - - m.AddReputation(lists, dnsbl) - - if cfg.AbuseIPDBKey != "" { - m.AddAbuseIPDB(abuseIPDB) - } - - return lists, dnsbl, abuseIPDB } // NewCoreRuleSet returns the Core Rule Set at SWW_WAF_CORE_RULE_SET_PARANOIA_LEVEL, diff --git a/internal/waf/proxy_test.go b/internal/waf/proxy_test.go index b002620..3951d33 100644 --- a/internal/waf/proxy_test.go +++ b/internal/waf/proxy_test.go @@ -16,10 +16,17 @@ import ( "time" "sneak.berlin/go/smallwebwaf/internal/alerts" + "sneak.berlin/go/smallwebwaf/internal/anomaly" + "sneak.berlin/go/smallwebwaf/internal/bans" "sneak.berlin/go/smallwebwaf/internal/config" "sneak.berlin/go/smallwebwaf/internal/config/configtest" + "sneak.berlin/go/smallwebwaf/internal/geojs" "sneak.berlin/go/smallwebwaf/internal/lookup" + "sneak.berlin/go/smallwebwaf/internal/metrics" + "sneak.berlin/go/smallwebwaf/internal/ratelimit" + "sneak.berlin/go/smallwebwaf/internal/reputation" "sneak.berlin/go/smallwebwaf/internal/requestlog" + "sneak.berlin/go/smallwebwaf/internal/routewatch" "sneak.berlin/go/smallwebwaf/internal/rproxy" "sneak.berlin/go/smallwebwaf/internal/rules" "sneak.berlin/go/smallwebwaf/internal/waf" @@ -435,13 +442,15 @@ func newWAF( ) (*waf.Server, *output, *alerts.Queue) { t.Helper() - return newWAFWith(t, waf.New, geojsURL, now, env) + return newWAFWith(t, waf.New, geojsURL, abuseIPDBURL, now, env) } -// newWAFWith is newWAF for the server build makes. +// newWAFWith is newWAF for the server build makes, with clients checked with +// AbuseIPDB at abuseIPDBCheckURL. func newWAFWith( t *testing.T, build func(waf.Params) *waf.Server, - geojsURL string, now func() time.Time, env map[string]string, + geojsURL, abuseIPDBCheckURL string, now func() time.Time, + env map[string]string, ) (*waf.Server, *output, *alerts.Queue) { t.Helper() @@ -499,25 +508,142 @@ func newWAFWith( t.Fatalf("Core Rule Set: %v", err) } - server := build(waf.Params{ - Config: cfg, - RequestLog: out, - ProcessLog: processLog, - GeoJSURL: geojsURL, - AbuseIPDBURL: abuseIPDBURL, - LookupFile: lookupFile, - CoreRuleSet: coreRuleSet, - Now: now, - Rules: ruleFiles, - Alerts: alertQueue, + params := waf.Params{ + Config: cfg, + RequestLog: out, + ProcessLog: processLog, + LookupFile: lookupFile, + CoreRuleSet: coreRuleSet, + Now: now, + Rules: ruleFiles, + Alerts: alertQueue, // The tests of the limit set it back, and hold the Core Rule Set // with a stand-in. BesideLookupTimeLimit: time.Hour, - }) + } + addCounters(¶ms) + addOutsideSources(¶ms, geojsURL, abuseIPDBCheckURL) + + server := build(params) return server, out, alertQueue } +// addCounters adds to params the metrics, the table of clients, the ledger +// and the anomaly counters, as sww builds them from params' settings. The +// metrics read the ledger, the table of clients and the rules. +func addCounters(params *waf.Params) { + cfg := params.Config + + params.Metrics = metrics.New( + cfg.MetricsBusiestCountriesAndASNs, + cfg.InstanceName, + ) + params.Limiter = ratelimit.New(ratelimit.Limits{ + PerMinute: cfg.RateLimitPerMinute, + PerHour: cfg.RateLimitPerHour, + PerDay: cfg.RateLimitPerDay, + BytesPerMinute: cfg.BytesLimitPerMinute, + BytesPerHour: cfg.BytesLimitPerHour, + BytesPerDay: cfg.BytesLimitPerDay, + }, cfg.MaxTrackedClients) + params.Ledger = bans.New(bans.Params{ + LimitBanDuration: cfg.LimitBanDuration, + LimitBanRepeatWindow: cfg.LimitBanRepeatWindow, + LimitBanPermanentAbove: cfg.LimitBanPermanentAbove, + AttackBanDuration: cfg.AttackBanDuration, + MaxBans: cfg.MaxBans, + }) + params.Anomalies = anomaly.New(anomaly.Params{ + Client: cfg.AnomalyClient, + Net: cfg.AnomalyNet, + ASN: cfg.AnomalyASN, + Total: cfg.AnomalyTotal, + WatchedNet: cfg.AnomalyWatchedNet, + NetV4Prefix: cfg.AnomalyNetV4Prefix, + NetV6Prefix: cfg.AnomalyNetV6Prefix, + NamedNetblocks: cfg.AnomalyWatchedNets, + Alerts: params.Alerts, + }) + + params.Metrics.AddBansAndClients( + params.Ledger, + params.Limiter, + params.Now, + ) + params.Metrics.AddRules(params.Rules) +} + +// addOutsideSources adds to params the lists fetched from URLs, the DNSBL +// zones' verdicts, AbuseIPDB's scores from abuseIPDBCheckURL, routewatch's +// answers while its setting is set, and GeoJS at geojsURL, as sww builds +// them from params' settings and the parts addCounters added. The metrics +// read the lists, the zones' verdicts, and AbuseIPDB's while its key is set. +func addOutsideSources( + params *waf.Params, geojsURL, abuseIPDBCheckURL string, +) { + cfg := params.Config + m, limiter, ledger := params.Metrics, params.Limiter, params.Ledger + processLog, alertQueue := params.ProcessLog, params.Alerts + + params.Lists = reputation.New(reputation.Params{ + BlocklistURLs: cfg.BlocklistURLs, + Refresh: cfg.BlocklistRefresh, + ASNLimitPercentURL: cfg.ASNLimitPercentURL, + TagLists: cfg.TagLists, + Now: params.Now, + ProcessLog: processLog, + Alerts: alertQueue, + }) + params.DNSBL = reputation.NewDNSBL(reputation.DNSBLParams{ + Zones: cfg.DNSBLZones, + Resolver: cfg.DNSBLResolver, + CacheTTL: cfg.IPReputationCacheTTL, + Timeout: cfg.DNSBLAbuseIPDBTimeout, + Now: params.Now, + ProcessLog: processLog, + Alerts: alertQueue, + }) + params.AbuseIPDB = reputation.NewAbuseIPDB(reputation.AbuseIPDBParams{ + URL: abuseIPDBCheckURL, + Key: cfg.AbuseIPDBKey, + MinScore: cfg.AbuseIPDBMinScore, + DailyBudget: cfg.AbuseIPDBDailyBudget, + CacheTTL: cfg.IPReputationCacheTTL, + Timeout: cfg.DNSBLAbuseIPDBTimeout, + Now: params.Now, + ProcessLog: processLog, + Alerts: alertQueue, + }) + + if cfg.RouteWatchURL != "" { + params.RouteWatch = routewatch.New(routewatch.Params{ + URL: cfg.RouteWatchURL, + Now: params.Now, + ProcessLog: processLog, + }) + } + + params.GeoJS = geojs.New(geojs.Params{ + URL: geojsURL, + Answered: func(answer geojs.Answer) { + waf.AddLookup(cfg, limiter, ledger, answer) + }, + Now: params.Now, + Asked: m.GeoJSRequests.Inc, + Failed: func(err error, askingAgainIn time.Duration) { + waf.GeoJSFailed(processLog, alertQueue, m, err, askingAgainIn) + }, + WentWithoutAnswer: m.RequestsWithoutGeoJSAnswer.Inc, + }) + + m.AddReputation(params.Lists, params.DNSBL) + + if cfg.AbuseIPDBKey != "" { + m.AddAbuseIPDB(params.AbuseIPDB) + } +} + // newClient returns an HTTP client that sends requests as they are made, // with no compression of its own. func newClient(t *testing.T) *http.Client { diff --git a/internal/waf/ratelimits.go b/internal/waf/ratelimits.go index 286cf1f..28ba812 100644 --- a/internal/waf/ratelimits.go +++ b/internal/waf/ratelimits.go @@ -38,8 +38,11 @@ func (rateLimits) check( rq.line.BytesLimitPercent, rq.line.BytesLimitPercentSetting = rq.bytesLimitPercent.logged() - counts, hit, over := rq.h.limiter.Count(rq.h.clientGroup(rq.client), now, - rq.rateLimitPercent.percent) + counts, hit, over := rq.h.limiter.Count( + clientGroup(rq.h.config, rq.client), + now, + rq.rateLimitPercent.percent, + ) rq.line.Counts = counts if !over { @@ -59,7 +62,7 @@ func (rateLimits) check( // limit. It counts nothing. func (rq *request) overAWholeRateLimit(now time.Time) bool { return rq.countedByRateLimits() && - rq.h.limiter.OverARateLimit(rq.h.clientGroup(rq.client), now) + rq.h.limiter.OverARateLimit(clientGroup(rq.h.config, rq.client), now) } // countedByRateLimits reports whether the rate limits count the request: its diff --git a/internal/waf/refusallimit.go b/internal/waf/refusallimit.go index cb30c2f..1c8a4ee 100644 --- a/internal/waf/refusallimit.go +++ b/internal/waf/refusallimit.go @@ -36,8 +36,11 @@ func (refusalLimit) check( return nil } - hit, over := rq.h.limiter.CountRefusal(rq.h.clientGroup(rq.client), now, - cfg.RefusalsLimitPerMinute) + hit, over := rq.h.limiter.CountRefusal( + clientGroup(rq.h.config, rq.client), + now, + cfg.RefusalsLimitPerMinute, + ) if !over { return nil } diff --git a/internal/waf/reputation.go b/internal/waf/reputation.go index 06bd4f5..b760666 100644 --- a/internal/waf/reputation.go +++ b/internal/waf/reputation.go @@ -37,7 +37,7 @@ func (rq *request) noteHit(hit bans.ReputationHit, reason string) { Event: alerts.EventReputationHit, Host: rq.site, Client: rq.client, - Netblock: rq.h.clientGroup(rq.client), + Netblock: clientGroup(rq.h.config, rq.client), ASN: rq.line.ASN, ASName: rq.line.ASName, Country: rq.line.Country, diff --git a/internal/waf/request.go b/internal/waf/request.go index 06bec96..9c6dbc8 100644 --- a/internal/waf/request.go +++ b/internal/waf/request.go @@ -122,7 +122,7 @@ func (h *handler) startRequest( RequestID: requestID(r, isQuestion), PeerIP: peer.String(), ForwardedFor: strings.Join(forwardedFor, ", "), - ClientGroup: h.clientGroup(client).String(), + ClientGroup: clientGroup(h.config, client).String(), ContentType: r.Header.Get("Content-Type"), RequestHeaders: requestHeaders( r, @@ -365,7 +365,7 @@ func (rq *request) addToHistory() { } rq.h.limiter.AddToHistory( - rq.h.clientGroup(rq.client), + clientGroup(rq.h.config, rq.client), rq.h.now(), request, ) @@ -373,7 +373,7 @@ func (rq *request) addToHistory() { answer, found := rq.answerAtTheEnd() if found { - rq.h.addLookup(answer) + AddLookup(rq.h.config, rq.h.limiter, rq.h.ledger, answer) } } @@ -394,7 +394,7 @@ func (rq *request) countAnomalies() { rq.h.anomalies.Count(rq.h.now(), anomaly.Request{ Host: rq.site, Client: rq.client, - ClientGroup: rq.h.clientGroup(rq.client), + ClientGroup: clientGroup(rq.h.config, rq.client), ASN: answer.ASN, ASName: answer.ASName, Country: answer.Country, @@ -425,7 +425,7 @@ func (rq *request) answerAtTheEnd() (geojs.Answer, bool) { return rq.lookupAnswer, true } - return rq.h.geojs.Kept(rq.h.clientGroup(rq.client)) + return rq.h.geojs.Kept(clientGroup(rq.h.config, rq.client)) } // responseWriter is waf's answer to a request. It notes the status and diff --git a/internal/waf/routewatchtags.go b/internal/waf/routewatchtags.go index 65af428..d1a528c 100644 --- a/internal/waf/routewatchtags.go +++ b/internal/waf/routewatchtags.go @@ -32,7 +32,7 @@ func (routeWatchTags) check( route, missing := rq.h.routeWatch.Route( ctx, - rq.h.clientGroup(rq.client), + clientGroup(rq.h.config, rq.client), rq.client, ) if missing != "" { -- 2.54.0 From 809d2664d72562aeb4fa0531d3d65e1523260e93 Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Thu, 19 Nov 2026 12:42:41 +0100 Subject: [PATCH 7/7] waf: ban the clients on AbuseIPDB's blacklist (closes #411) While SWW_WAF_ABUSEIPDB_KEY is set, waf fetches AbuseIPDB's blacklist at the start and every SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS (60), cut at SWW_WAF_ABUSEIPDB_THRESHOLD (90, from 25 to 100). Each listed client's netblock gets a ban of SWW_WAF_ABUSEIPDB_BAN_DAYS (30) with the new cause abuseipdb. The blacklist itself is not kept. These bans do not count toward SWW_WAF_MAX_BANS, so a 10,000-address blacklist cannot push out the bans for limits and attacks. An ended abuseipdb ban is forgotten at each fetch and each read of bans.json. A netblock with an active ban is left alone, and so is one whose abuseipdb ban an admin lifted, until that ban would have ended. Observe mode makes no ban. Model: opus-5-5 --- README.md | 246 ++++++++++++----------- SPEC.md | 62 ++++-- docs/alerts.md | 5 +- docs/settings.md | 11 +- docs/state-files.md | 24 ++- internal/bans/abuseipdb_test.go | 165 ++++++++++++++++ internal/bans/bans.go | 195 ++++++++++++++---- internal/config/waf.go | 61 ++++++ internal/config/waf_test.go | 75 +++++++ internal/metrics/metrics.go | 2 +- internal/reputation/abuseipdb.go | 148 +++++++++++++- internal/reputation/blacklist_test.go | 252 ++++++++++++++++++++++++ internal/reputation/reputation.go | 3 +- internal/state/state.go | 9 +- internal/state/state_test.go | 38 +++- internal/sww/waf.go | 39 ++-- internal/waf/abuseipdbblacklist.go | 46 +++++ internal/waf/abuseipdbblacklist_test.go | 100 ++++++++++ internal/waf/export_test.go | 9 + internal/waf/proxy.go | 3 +- internal/waf/proxy_test.go | 34 ++-- internal/waf/reputation_test.go | 33 +++- 22 files changed, 1338 insertions(+), 222 deletions(-) create mode 100644 internal/bans/abuseipdb_test.go create mode 100644 internal/reputation/blacklist_test.go create mode 100644 internal/waf/abuseipdbblacklist.go create mode 100644 internal/waf/abuseipdbblacklist_test.go diff --git a/README.md b/README.md index a5004f5..9ab4147 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,8 @@ Together, `rproxy` and `waf` protect against: - give the clients of chosen networks and countries a fraction of every limit, so that they are banned sooner; - refuse or limit clients on a blocklist, a DNS blocklist, or with a high - AbuseIPDB score. + AbuseIPDB score; + - ban the clients on AbuseIPDB's blacklist before they send a request. For the operator, it: @@ -294,123 +295,126 @@ account, a key, a token or an alert destination stays off until you give one. Every setting the code reads, with its default: -| Variable | Default | What it does | -| ------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `SWW_COMMAND` | `rproxy` | Which command the image runs, and its health check checks: `rproxy` or `waf`. | -| `SWW_RPROXY_WAF_BACKEND` | required | `waf`'s URL, such as `http://waf:8080`. | -| `SWW_RPROXY_UPSTREAM_URL` | `http://127.0.0.1:8081` | The app's URL: a scheme, a host and an optional port, nothing more. | -| `SWW_RPROXY_LISTEN_ADDR` | `:8080` | Where `rproxy` listens; leave the host part empty. | -| `SWW_RPROXY_TRUSTED_PROXIES` | `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16` | The netblocks whose `X-Forwarded-For` `rproxy` believes; set but empty, it believes none. | -| `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS` | `2000` | How long `rproxy` waits for `waf`'s answer to a question and to a report, in milliseconds. | -| `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` | `allow` | What `rproxy` does with a request when `waf` gives no answer in time, and while the circuit breaker for asks to `waf` is open: `allow` passes it to the app, `deny` answers `503`. | -| `SWW_RPROXY_MAX_REQUEST_SIZE` | `100M` | The largest request body, a size or `off`; a larger one is answered `413`. | -| `SWW_RPROXY_MAX_RESPONSE_SIZE` | `1G` | The largest response body, a size or `off`. The visitor gets `502` in place of a larger one, or it is cut off if it has already started. | -| `SWW_RPROXY_MAX_REQUEST_TIME_MS` | `60000` | Two time limits, each this long, in milliseconds or `off`: one for the visitor to send its request line and headers, then one for the whole request to reach the app. | -| `SWW_RPROXY_MAX_RESPONSE_TIME_MS` | `1800000` | How long the answer may take, from the end of the request to its last byte reaching the visitor, in milliseconds or `off`. | -| `SWW_WAF_LISTEN_ADDR` | `:8080` | Where `waf` listens; leave the host part empty. | -| `SWW_WAF_INSTANCE_NAME` | the container's host name | The name in every line `waf` logs, and in every alert and metric, such as `host1/waf`. | -| `SWW_WAF_MODE` | `enforce` | `observe` refuses nothing and makes no ban; each log line says what `enforce` would have done. | -| `SWW_WAF_IPV6_GROUP_PREFIX` | `64` | The prefix length of the IPv6 netblock that counts as one client, from 32 to 128. | -| `SWW_WAF_MAX_TRACKED_CLIENTS` | `20000` | The most clients kept, in memory and in `clients.json`; the least recently seen is dropped first. | -| `SWW_WAF_MAX_BANS` | `5000` | The most bans `waf` keeps of its own; bans an admin made do not count. | -| `SWW_WAF_ALLOW_NETS` | empty | Netblocks whose clients skip every check, such as your monitoring. | -| `SWW_WAF_RATE_LIMIT_EXEMPT_NETS` | empty | Netblocks whose clients are exempt from rate limiting and the byte limits. | -| `SWW_WAF_DENY_NETS` | empty | Netblocks whose clients are refused. | -| `SWW_WAF_RATE_LIMIT_PER_MINUTE` | `120` | The most requests a client may make in a minute, a count or `off`; the next request is refused and bans the client. | -| `SWW_WAF_RATE_LIMIT_PER_HOUR` | `1500` | The most requests a client may make in an hour, a count or `off`; the next request is refused and bans the client. | -| `SWW_WAF_RATE_LIMIT_PER_DAY` | `6000` | The most requests a client may make in a day, a count or `off`; the next request is refused and bans the client. | -| `SWW_WAF_RATE_LIMIT_EXEMPT_PATHS` | empty | Path prefixes exempt from rate limiting and the byte limits, such as `/assets/`. | -| `SWW_WAF_BYTES_LIMIT_PER_MINUTE` | `off` | The most bytes counted for a client in a minute, a size or `off`. `SWW_WAF_BYTES_COUNTED` says which bytes count: response bodies, request bodies or both. The request that passes the limit is not cut off, and the client is banned when its response ends. | -| `SWW_WAF_BYTES_LIMIT_PER_HOUR` | `50G` | The most bytes counted for a client in an hour, a size or `off`. `SWW_WAF_BYTES_COUNTED` says which bytes count: response bodies, request bodies or both. The request that passes the limit is not cut off, and the client is banned when its response ends. | -| `SWW_WAF_BYTES_LIMIT_PER_DAY` | `100G` | The most bytes counted for a client in a day, a size or `off`. `SWW_WAF_BYTES_COUNTED` says which bytes count: response bodies, request bodies or both. The request that passes the limit is not cut off, and the client is banned when its response ends. | -| `SWW_WAF_BYTES_COUNTED` | `both` | What the byte limits and the byte anomaly thresholds count: `response`, the app's response bodies; `request`, the visitors' request bodies; or `both`. What the visitor sent over a WebSocket counts as request bytes, and what the app sent as response bytes. | -| `SWW_WAF_REFUSALS_LIMIT_PER_MINUTE` | `30` | The most refusals a client may get in a minute from a rule file, a trap path or the Core Rule Set, a count or `off`. The next one bans the client. | -| `SWW_WAF_BAN_RESPONSE` | `403` | How a refused client is answered: `403`, `429` or `close`, which drops the connection. | -| `SWW_WAF_LIMIT_BAN_DURATION` | `1h` | The ban for a first broken limit. | -| `SWW_WAF_LIMIT_BAN_REPEAT_WINDOW` | `24h` | A client that breaks a limit again within this time after its last such ban ended gets a ban three times as long. | -| `SWW_WAF_LIMIT_BAN_PERMANENT_ABOVE` | `7d` | A ban for a broken limit that would be longer than this is permanent instead. | -| `SWW_WAF_ATTACK_BAN_DURATION` | `7d` | The ban for a first clear sign of attack: a `ban` rule or a trap path. | -| `SWW_WAF_BAN_SCOPE_V4_PREFIX` | `32` | The prefix length of the netblock a ban on an IPv4 client covers, from 0 to 32. | -| `SWW_WAF_LOOKUP_SOURCE` | `geojs` | Where each client's AS number and country come from: `geojs` (a web service), `file` (a local database) or `off`. | -| `SWW_WAF_LOOKUP_DB_PATH` | empty | The IPinfo Lite database file, in its `.mmdb` form, read while the source is `file`. | -| `SWW_WAF_ASN_AND_COUNTRY_LOOKUP_TIMEOUT_MS` | `800` | How long a request waits for its client's first GeoJS answer when a setting needs it, in milliseconds. The request to GeoJS goes on, and a later answer is kept. | -| `SWW_WAF_ADD_LOOKUP_HEADERS` | `true`, or `false` while the lookup source is `off` | `true` passes the app the client's AS number and country in `X-Client-ASN` and `X-Client-Country`. | -| `SWW_WAF_EXCLUSIVELY_ALLOWED_COUNTRIES` | empty | When set, the only countries whose clients get through; a client the lookup cannot place is refused too. | -| `SWW_WAF_TAG_LISTS` | empty | Address lists that each add a tag to their clients' requests, as `name=URL` pairs, such as `torexit=https://example.com/tor.txt`. | -| `SWW_WAF_TAG_DENY` | empty | Tags whose requests are refused, such as `torexit,country=CN`. | -| `SWW_WAF_TAG_LIMIT_PERCENT` | empty | Tags whose clients get a percentage, from 1 to 99, of every request and byte limit, such as `vpn:50,asn=14061:25`; the lowest applies. | -| `SWW_WAF_ROUTEWATCH_URL` | unset | The URL of a routewatch instance, which gives each client's `asn=` and `prefix=` tags. Unset, nothing asks routewatch. | -| `SWW_WAF_ASN_BYTES_LIMIT_PERCENT` | empty | A percentage of the byte limits alone for the AS numbers listed, in place of their `asn=` tag's percentage. | -| `SWW_WAF_COUNTRY_BYTES_LIMIT_PERCENT` | empty | A percentage of the byte limits alone for the countries listed, in place of their `country=` tag's percentage. | -| `SWW_WAF_UNKNOWN_COUNTRY_LIMIT_PERCENT` | `100` | The percentage of every limit a client without a country gets. | -| `SWW_WAF_ASN_LIMIT_PERCENT_URL` | unset | The URL of a text file of `AS:` lines, fetched like a blocklist; each line counts as an `asn=` tag in `SWW_WAF_TAG_LIMIT_PERCENT` (the lowest wins). | -| `SWW_WAF_RULE_FILES_DIR` | `/etc/sww/rules.d` | The directory of the rule files, read at start and again when a file there changes. | -| `SWW_WAF_RULE_FILES_ENABLED` | `true` | `false` reads no rule file. | -| `SWW_WAF_TRAP_PATHS` | empty | Paths only scanners ask for, such as `/wp-login.php,/xmlrpc.php`; a request for one bans the client. | -| `SWW_WAF_CORE_RULE_SET_MODE` | `block` | What the Core Rule Set does with a match: `block` refuses it with `403`, `detect` only logs and alerts it, `off` runs no rule. | -| `SWW_WAF_CORE_RULE_SET_PARANOIA_LEVEL` | `1` | The Core Rule Set's paranoia level, from 1 to 4; each level up finds more attacks and takes more ordinary requests for attacks. | -| `SWW_WAF_CORE_RULE_SET_SCORE_THRESHOLD` | `5` | The Core Rule Set score at which a request is a match, a whole number or `off`; one critical rule scores 5. | -| `SWW_WAF_CORE_RULE_SET_DISABLED_RULES` | `920340,920420,920440,920640,930130,930140` | Core Rule Set rule ids switched off; a list you give replaces the default, so repeat these six to keep them off. | -| `SWW_WAF_CORE_RULE_SET_EXEMPT_PATHS` | empty | Path prefixes the Core Rule Set does not inspect. | -| `SWW_WAF_CORE_RULE_SET_BODY_INSPECTION_SIZE` | `off` | How much of a request body the Core Rule Set reads, a size up to `8K`; `off` reads none. | -| `SWW_WAF_CORE_RULE_SET_EXCLUSIONS_FILE` | unset | A file of Core Rule Set exclusions, as Coraza directives, that switch rules off for some fields or paths only. | -| `SWW_WAF_APPS` | unset | The apps each hostname serves, such as `git.example.com:gitea;blog.example.com:wordpress`; only those apps' fixes apply there. "Attack detection" lists the apps. Listing `forgejo` brings gitea's fixes too. Unset, every app's fixes apply to every hostname. | -| `SWW_WAF_BLOCKLIST_URLS` | empty | Blocklists to fetch, text files of addresses and netblocks one to a line, such as `https://www.spamhaus.org/drop/drop.txt`. | -| `SWW_WAF_BLOCKLIST_REFRESH` | `24h` | How long after a list was last tried it is fetched again, `1h` or more. | -| `SWW_WAF_BLOCKLIST_ACTION` | `deny` | What a client on a blocklist gets: `deny`, `limit:` of every limit, or `log`. | -| `SWW_WAF_DNSBL_ZONES` | empty | DNS blocklists asked about each new client in the background, such as `dnsbl.dronebl.org`. | -| `SWW_WAF_DNSBL_RESOLVER` | unset | The resolver the zones are asked through, an IP address with an optional port; unset, the host's resolver is used. | -| `SWW_WAF_ABUSEIPDB_KEY` | unset | The key of your AbuseIPDB account; set, a client that has committed an offence is checked in the background. | -| `SWW_WAF_ABUSEIPDB_MIN_SCORE` | `75` | The least AbuseIPDB abuse confidence score, from 0 to 100, that is a hit. | -| `SWW_WAF_ABUSEIPDB_DAILY_BUDGET` | `900` | The most AbuseIPDB checks made in a day. | -| `SWW_WAF_DNSBL_ABUSEIPDB_ACTION` | `limit:25` | What a client listed by a DNS blocklist, or scored a hit by AbuseIPDB, gets: `deny`, `limit:` or `log`. | -| `SWW_WAF_IP_REPUTATION_CACHE_TTL` | `24h` | How long a DNS blocklist verdict or an AbuseIPDB score is used. | -| `SWW_WAF_DNSBL_ABUSEIPDB_TIMEOUT_MS` | `2000` | How long a DNS blocklist query or an AbuseIPDB check may take, in milliseconds. | -| `SWW_WAF_STATE_DIR` | `/var/lib/sww` | The directory of the state files, an absolute path. | -| `SWW_WAF_BANS_WRITE_DELAY` | `10s` | How long `bans.json` waits to be written after a ban is made, lifted or made permanent. | -| `SWW_WAF_STATE_WRITE_INTERVAL` | `15m` | How often every state and cache file is written. | -| `SWW_WAF_CACHE_DIR` | `/var/cache/sww` | The directory of the cache files, an absolute path. | -| `SWW_WAF_LOG_LEVEL` | `info` | The least severe of `waf`'s own messages that are written: `debug`, `info`, `warn` or `error`; request lines are always written. | -| `SWW_WAF_LOG_REQUEST_HEADERS` | `accept,accept-language,accept-encoding,content-type,origin,range` | The request headers whose values the request log records; `Authorization` and `Cookie` are never recorded. | -| `SWW_WAF_LOG_REMOTE_URL` | unset | A syslog server that also gets every line `waf` writes: `syslog+udp://`, `syslog+tcp://` or `syslog+tls://` with a host and a port. | -| `SWW_WAF_LOG_REMOTE_TLS_CA_FILE` | unset | A file of PEM certificates a `syslog+tls` server's certificate must chain to, instead of the host's own. | -| `SWW_WAF_LOG_REMOTE_BUFFER_LINES` | `10000` | The most lines held while they wait to be sent; past it, the oldest is dropped. | -| `SWW_WAF_LOG_REMOTE_FACILITY` | `local0` | The syslog facility of each record sent. | -| `SWW_WAF_LOG_REMOTE_APP_NAME` | `SWW_WAF_INSTANCE_NAME` | The app name in each syslog record, 1 to 48 printable ASCII characters without a space. | -| `SWW_WAF_ADMIN_TOKEN` | unset | The bearer token for the ban and client endpoints, at least 32 characters; unset, they answer `404`. | -| `SWW_WAF_METRICS_TOKEN` | unset | The bearer token for `/_sww/metrics`, at least 32 characters; unset, the metrics are off. | -| `SWW_WAF_METRICS_BUSIEST_COUNTRIES_AND_ASNS` | `50` | How many AS numbers and how many countries get metric series of their own; the rest are summed as `other`. | -| `SWW_WAF_ALERT_WEBHOOK_URL` | unset | A webhook each alert is posted to as a JSON object. | -| `SWW_WAF_ALERT_WEBHOOK_HEADERS` | empty | Headers sent with each post, a list of `Name:value`, such as `Authorization:Bearer `. | -| `SWW_WAF_ALERT_SLACK_WEBHOOK_URL` | unset | A Slack incoming webhook each alert is posted to as a message. | -| `SWW_WAF_ALERT_NTFY_URL` | unset | An ntfy topic each alert is published to, as its full URL, such as `https://ntfy.sh/my-alerts`. | -| `SWW_WAF_ALERT_NTFY_TOKEN` | unset | An ntfy access token sent with each alert. | -| `SWW_WAF_ALERT_EVENTS` | `ban,permanent_ban,core_rule_set_match,anomaly,reputation_hit,source_failure,file_error` | The events alerts are sent for; the hourly `summary` is sent whatever it says. | -| `SWW_WAF_ALERT_COOLDOWN` | `15m` | How long after an alert its repeats are held back and counted, a duration or `off`. | -| `SWW_WAF_ALERT_MAX_PER_HOUR` | `60` | The most alerts sent in an hour, a number or `off`; the rest are counted in the hour's `summary`. | -| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when one client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | -| `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_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_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. | -| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the whole service in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_WATCHED_NETS` | empty | Named netblocks the `SWW_WAF_ANOMALY_WATCHED_NET_` thresholds count each as a whole, such as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. Those thresholds only send alerts. | -| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | -| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| Variable | Default | What it does | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `SWW_COMMAND` | `rproxy` | Which command the image runs, and its health check checks: `rproxy` or `waf`. | +| `SWW_RPROXY_WAF_BACKEND` | required | `waf`'s URL, such as `http://waf:8080`. | +| `SWW_RPROXY_UPSTREAM_URL` | `http://127.0.0.1:8081` | The app's URL: a scheme, a host and an optional port, nothing more. | +| `SWW_RPROXY_LISTEN_ADDR` | `:8080` | Where `rproxy` listens; leave the host part empty. | +| `SWW_RPROXY_TRUSTED_PROXIES` | `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16` | The netblocks whose `X-Forwarded-For` `rproxy` believes; set but empty, it believes none. | +| `SWW_RPROXY_WAF_BACKEND_TIMEOUT_MS` | `2000` | How long `rproxy` waits for `waf`'s answer to a question and to a report, in milliseconds. | +| `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` | `allow` | What `rproxy` does with a request when `waf` gives no answer in time, and while the circuit breaker for asks to `waf` is open: `allow` passes it to the app, `deny` answers `503`. | +| `SWW_RPROXY_MAX_REQUEST_SIZE` | `100M` | The largest request body, a size or `off`; a larger one is answered `413`. | +| `SWW_RPROXY_MAX_RESPONSE_SIZE` | `1G` | The largest response body, a size or `off`. The visitor gets `502` in place of a larger one, or it is cut off if it has already started. | +| `SWW_RPROXY_MAX_REQUEST_TIME_MS` | `60000` | Two time limits, each this long, in milliseconds or `off`: one for the visitor to send its request line and headers, then one for the whole request to reach the app. | +| `SWW_RPROXY_MAX_RESPONSE_TIME_MS` | `1800000` | How long the answer may take, from the end of the request to its last byte reaching the visitor, in milliseconds or `off`. | +| `SWW_WAF_LISTEN_ADDR` | `:8080` | Where `waf` listens; leave the host part empty. | +| `SWW_WAF_INSTANCE_NAME` | the container's host name | The name in every line `waf` logs, and in every alert and metric, such as `host1/waf`. | +| `SWW_WAF_MODE` | `enforce` | `observe` refuses nothing and makes no ban; each log line says what `enforce` would have done. | +| `SWW_WAF_IPV6_GROUP_PREFIX` | `64` | The prefix length of the IPv6 netblock that counts as one client, from 32 to 128. | +| `SWW_WAF_MAX_TRACKED_CLIENTS` | `20000` | The most clients kept, in memory and in `clients.json`; the least recently seen is dropped first. | +| `SWW_WAF_MAX_BANS` | `5000` | The most bans `waf` keeps for broken limits and attacks; bans an admin made and bans for AbuseIPDB's blacklist do not count. | +| `SWW_WAF_ALLOW_NETS` | empty | Netblocks whose clients skip every check, such as your monitoring. | +| `SWW_WAF_RATE_LIMIT_EXEMPT_NETS` | empty | Netblocks whose clients are exempt from rate limiting and the byte limits. | +| `SWW_WAF_DENY_NETS` | empty | Netblocks whose clients are refused. | +| `SWW_WAF_RATE_LIMIT_PER_MINUTE` | `120` | The most requests a client may make in a minute, a count or `off`; the next request is refused and bans the client. | +| `SWW_WAF_RATE_LIMIT_PER_HOUR` | `1500` | The most requests a client may make in an hour, a count or `off`; the next request is refused and bans the client. | +| `SWW_WAF_RATE_LIMIT_PER_DAY` | `6000` | The most requests a client may make in a day, a count or `off`; the next request is refused and bans the client. | +| `SWW_WAF_RATE_LIMIT_EXEMPT_PATHS` | empty | Path prefixes exempt from rate limiting and the byte limits, such as `/assets/`. | +| `SWW_WAF_BYTES_LIMIT_PER_MINUTE` | `off` | The most bytes counted for a client in a minute, a size or `off`. `SWW_WAF_BYTES_COUNTED` says which bytes count: response bodies, request bodies or both. The request that passes the limit is not cut off, and the client is banned when its response ends. | +| `SWW_WAF_BYTES_LIMIT_PER_HOUR` | `50G` | The most bytes counted for a client in an hour, a size or `off`. `SWW_WAF_BYTES_COUNTED` says which bytes count: response bodies, request bodies or both. The request that passes the limit is not cut off, and the client is banned when its response ends. | +| `SWW_WAF_BYTES_LIMIT_PER_DAY` | `100G` | The most bytes counted for a client in a day, a size or `off`. `SWW_WAF_BYTES_COUNTED` says which bytes count: response bodies, request bodies or both. The request that passes the limit is not cut off, and the client is banned when its response ends. | +| `SWW_WAF_BYTES_COUNTED` | `both` | What the byte limits and the byte anomaly thresholds count: `response`, the app's response bodies; `request`, the visitors' request bodies; or `both`. What the visitor sent over a WebSocket counts as request bytes, and what the app sent as response bytes. | +| `SWW_WAF_REFUSALS_LIMIT_PER_MINUTE` | `30` | The most refusals a client may get in a minute from a rule file, a trap path or the Core Rule Set, a count or `off`. The next one bans the client. | +| `SWW_WAF_BAN_RESPONSE` | `403` | How a refused client is answered: `403`, `429` or `close`, which drops the connection. | +| `SWW_WAF_LIMIT_BAN_DURATION` | `1h` | The ban for a first broken limit. | +| `SWW_WAF_LIMIT_BAN_REPEAT_WINDOW` | `24h` | A client that breaks a limit again within this time after its last such ban ended gets a ban three times as long. | +| `SWW_WAF_LIMIT_BAN_PERMANENT_ABOVE` | `7d` | A ban for a broken limit that would be longer than this is permanent instead. | +| `SWW_WAF_ATTACK_BAN_DURATION` | `7d` | The ban for a first clear sign of attack: a `ban` rule or a trap path. | +| `SWW_WAF_BAN_SCOPE_V4_PREFIX` | `32` | The prefix length of the netblock a ban on an IPv4 client covers, from 0 to 32. | +| `SWW_WAF_LOOKUP_SOURCE` | `geojs` | Where each client's AS number and country come from: `geojs` (a web service), `file` (a local database) or `off`. | +| `SWW_WAF_LOOKUP_DB_PATH` | empty | The IPinfo Lite database file, in its `.mmdb` form, read while the source is `file`. | +| `SWW_WAF_ASN_AND_COUNTRY_LOOKUP_TIMEOUT_MS` | `800` | How long a request waits for its client's first GeoJS answer when a setting needs it, in milliseconds. The request to GeoJS goes on, and a later answer is kept. | +| `SWW_WAF_ADD_LOOKUP_HEADERS` | `true`, or `false` while the lookup source is `off` | `true` passes the app the client's AS number and country in `X-Client-ASN` and `X-Client-Country`. | +| `SWW_WAF_EXCLUSIVELY_ALLOWED_COUNTRIES` | empty | When set, the only countries whose clients get through; a client the lookup cannot place is refused too. | +| `SWW_WAF_TAG_LISTS` | empty | Address lists that each add a tag to their clients' requests, as `name=URL` pairs, such as `torexit=https://example.com/tor.txt`. | +| `SWW_WAF_TAG_DENY` | empty | Tags whose requests are refused, such as `torexit,country=CN`. | +| `SWW_WAF_TAG_LIMIT_PERCENT` | empty | Tags whose clients get a percentage, from 1 to 99, of every request and byte limit, such as `vpn:50,asn=14061:25`; the lowest applies. | +| `SWW_WAF_ROUTEWATCH_URL` | unset | The URL of a routewatch instance, which gives each client's `asn=` and `prefix=` tags. Unset, nothing asks routewatch. | +| `SWW_WAF_ASN_BYTES_LIMIT_PERCENT` | empty | A percentage of the byte limits alone for the AS numbers listed, in place of their `asn=` tag's percentage. | +| `SWW_WAF_COUNTRY_BYTES_LIMIT_PERCENT` | empty | A percentage of the byte limits alone for the countries listed, in place of their `country=` tag's percentage. | +| `SWW_WAF_UNKNOWN_COUNTRY_LIMIT_PERCENT` | `100` | The percentage of every limit a client without a country gets. | +| `SWW_WAF_ASN_LIMIT_PERCENT_URL` | unset | The URL of a text file of `AS:` lines, fetched like a blocklist; each line counts as an `asn=` tag in `SWW_WAF_TAG_LIMIT_PERCENT` (the lowest wins). | +| `SWW_WAF_RULE_FILES_DIR` | `/etc/sww/rules.d` | The directory of the rule files, read at start and again when a file there changes. | +| `SWW_WAF_RULE_FILES_ENABLED` | `true` | `false` reads no rule file. | +| `SWW_WAF_TRAP_PATHS` | empty | Paths only scanners ask for, such as `/wp-login.php,/xmlrpc.php`; a request for one bans the client. | +| `SWW_WAF_CORE_RULE_SET_MODE` | `block` | What the Core Rule Set does with a match: `block` refuses it with `403`, `detect` only logs and alerts it, `off` runs no rule. | +| `SWW_WAF_CORE_RULE_SET_PARANOIA_LEVEL` | `1` | The Core Rule Set's paranoia level, from 1 to 4; each level up finds more attacks and takes more ordinary requests for attacks. | +| `SWW_WAF_CORE_RULE_SET_SCORE_THRESHOLD` | `5` | The Core Rule Set score at which a request is a match, a whole number or `off`; one critical rule scores 5. | +| `SWW_WAF_CORE_RULE_SET_DISABLED_RULES` | `920340,920420,920440,920640,930130,930140` | Core Rule Set rule ids switched off; a list you give replaces the default, so repeat these six to keep them off. | +| `SWW_WAF_CORE_RULE_SET_EXEMPT_PATHS` | empty | Path prefixes the Core Rule Set does not inspect. | +| `SWW_WAF_CORE_RULE_SET_BODY_INSPECTION_SIZE` | `off` | How much of a request body the Core Rule Set reads, a size up to `8K`; `off` reads none. | +| `SWW_WAF_CORE_RULE_SET_EXCLUSIONS_FILE` | unset | A file of Core Rule Set exclusions, as Coraza directives, that switch rules off for some fields or paths only. | +| `SWW_WAF_APPS` | unset | The apps each hostname serves, such as `git.example.com:gitea;blog.example.com:wordpress`; only those apps' fixes apply there. "Attack detection" lists the apps. Listing `forgejo` brings gitea's fixes too. Unset, every app's fixes apply to every hostname. | +| `SWW_WAF_BLOCKLIST_URLS` | empty | Blocklists to fetch, text files of addresses and netblocks one to a line, such as `https://www.spamhaus.org/drop/drop.txt`. | +| `SWW_WAF_BLOCKLIST_REFRESH` | `24h` | How long after a list was last tried it is fetched again, `1h` or more. | +| `SWW_WAF_BLOCKLIST_ACTION` | `deny` | What a client on a blocklist gets: `deny`, `limit:` of every limit, or `log`. | +| `SWW_WAF_DNSBL_ZONES` | empty | DNS blocklists asked about each new client in the background, such as `dnsbl.dronebl.org`. | +| `SWW_WAF_DNSBL_RESOLVER` | unset | The resolver the zones are asked through, an IP address with an optional port; unset, the host's resolver is used. | +| `SWW_WAF_ABUSEIPDB_KEY` | unset | The key of your AbuseIPDB account. Set, a client that has committed an offence is checked in the background, and the clients on AbuseIPDB's blacklist are banned. | +| `SWW_WAF_ABUSEIPDB_MIN_SCORE` | `75` | The least AbuseIPDB abuse confidence score, from 0 to 100, that is a hit. | +| `SWW_WAF_ABUSEIPDB_DAILY_BUDGET` | `900` | The most AbuseIPDB checks made in a day. | +| `SWW_WAF_DNSBL_ABUSEIPDB_ACTION` | `limit:25` | What a client listed by a DNS blocklist, or scored a hit by AbuseIPDB, gets: `deny`, `limit:` or `log`. | +| `SWW_WAF_IP_REPUTATION_CACHE_TTL` | `24h` | How long a DNS blocklist verdict or an AbuseIPDB score is used. | +| `SWW_WAF_DNSBL_ABUSEIPDB_TIMEOUT_MS` | `2000` | How long a DNS blocklist query or an AbuseIPDB check may take, in milliseconds. | +| `SWW_WAF_ABUSEIPDB_THRESHOLD` | `90` | The least AbuseIPDB score, from 25 to 100, at which a client on its blacklist is banned. Do not set it below 50 to 75: lower scores list ordinary visitors. | +| `SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS` | `60` | How often AbuseIPDB's blacklist is fetched again, in minutes. | +| `SWW_WAF_ABUSEIPDB_BAN_DAYS` | `30` | How long a client on AbuseIPDB's blacklist is banned, in days. | +| `SWW_WAF_STATE_DIR` | `/var/lib/sww` | The directory of the state files, an absolute path. | +| `SWW_WAF_BANS_WRITE_DELAY` | `10s` | How long `bans.json` waits to be written after a ban is made, lifted or made permanent. | +| `SWW_WAF_STATE_WRITE_INTERVAL` | `15m` | How often every state and cache file is written. | +| `SWW_WAF_CACHE_DIR` | `/var/cache/sww` | The directory of the cache files, an absolute path. | +| `SWW_WAF_LOG_LEVEL` | `info` | The least severe of `waf`'s own messages that are written: `debug`, `info`, `warn` or `error`; request lines are always written. | +| `SWW_WAF_LOG_REQUEST_HEADERS` | `accept,accept-language,accept-encoding,content-type,origin,range` | The request headers whose values the request log records; `Authorization` and `Cookie` are never recorded. | +| `SWW_WAF_LOG_REMOTE_URL` | unset | A syslog server that also gets every line `waf` writes: `syslog+udp://`, `syslog+tcp://` or `syslog+tls://` with a host and a port. | +| `SWW_WAF_LOG_REMOTE_TLS_CA_FILE` | unset | A file of PEM certificates a `syslog+tls` server's certificate must chain to, instead of the host's own. | +| `SWW_WAF_LOG_REMOTE_BUFFER_LINES` | `10000` | The most lines held while they wait to be sent; past it, the oldest is dropped. | +| `SWW_WAF_LOG_REMOTE_FACILITY` | `local0` | The syslog facility of each record sent. | +| `SWW_WAF_LOG_REMOTE_APP_NAME` | `SWW_WAF_INSTANCE_NAME` | The app name in each syslog record, 1 to 48 printable ASCII characters without a space. | +| `SWW_WAF_ADMIN_TOKEN` | unset | The bearer token for the ban and client endpoints, at least 32 characters; unset, they answer `404`. | +| `SWW_WAF_METRICS_TOKEN` | unset | The bearer token for `/_sww/metrics`, at least 32 characters; unset, the metrics are off. | +| `SWW_WAF_METRICS_BUSIEST_COUNTRIES_AND_ASNS` | `50` | How many AS numbers and how many countries get metric series of their own; the rest are summed as `other`. | +| `SWW_WAF_ALERT_WEBHOOK_URL` | unset | A webhook each alert is posted to as a JSON object. | +| `SWW_WAF_ALERT_WEBHOOK_HEADERS` | empty | Headers sent with each post, a list of `Name:value`, such as `Authorization:Bearer `. | +| `SWW_WAF_ALERT_SLACK_WEBHOOK_URL` | unset | A Slack incoming webhook each alert is posted to as a message. | +| `SWW_WAF_ALERT_NTFY_URL` | unset | An ntfy topic each alert is published to, as its full URL, such as `https://ntfy.sh/my-alerts`. | +| `SWW_WAF_ALERT_NTFY_TOKEN` | unset | An ntfy access token sent with each alert. | +| `SWW_WAF_ALERT_EVENTS` | `ban,permanent_ban,core_rule_set_match,anomaly,reputation_hit,source_failure,file_error` | The events alerts are sent for; the hourly `summary` is sent whatever it says. | +| `SWW_WAF_ALERT_COOLDOWN` | `15m` | How long after an alert its repeats are held back and counted, a duration or `off`. | +| `SWW_WAF_ALERT_MAX_PER_HOUR` | `60` | The most alerts sent in an hour, a number or `off`; the rest are counted in the hour's `summary`. | +| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when one client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | +| `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_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_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. | +| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the whole service in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NETS` | empty | Named netblocks the `SWW_WAF_ANOMALY_WATCHED_NET_` thresholds count each as a whole, such as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. Those thresholds only send alerts. | +| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | +| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. | [`docs/settings.md`](docs/settings.md) gives the values each setting takes in full, and the limits that are fixed rather than settings. @@ -766,8 +770,10 @@ status for a size or time limit, such as `413` for a body too large. - A client is one IPv4 address or one IPv6 netblock of `SWW_WAF_IPV6_GROUP_PREFIX`, since one abuser usually controls a whole /64. - Each limit is counted over a sliding window with a few integers per client. - The table of clients and the table of bans each have a bound - (`SWW_WAF_MAX_TRACKED_CLIENTS`, `SWW_WAF_MAX_BANS`), so memory is bounded too. + The table of clients and the bans for limits and attacks each have a bound + (`SWW_WAF_MAX_TRACKED_CLIENTS`, `SWW_WAF_MAX_BANS`). The bans for AbuseIPDB's + blacklist are bounded by the clients it listed over the last + `SWW_WAF_ABUSEIPDB_BAN_DAYS` days. So memory is bounded too. - A ban refuses every request from its netblock until it ends. Requests refused under a ban count toward no limit. A permanent ban ends only when an admin lifts it. diff --git a/SPEC.md b/SPEC.md index a2fbb45..5849f66 100644 --- a/SPEC.md +++ b/SPEC.md @@ -94,7 +94,8 @@ never as a time. to count and report failures. - `internal/lookup`: looks clients up in the lookup database. - `internal/reputation`: fetches the lists, asks the DNS blocklists and - AbuseIPDB in the background, and keeps their answers. + AbuseIPDB in the background, and keeps their answers. It also fetches + AbuseIPDB's blacklist, which `internal/waf` bans. - `internal/routewatch`: asks a routewatch instance about clients in the background, and keeps its answers. - `internal/anomaly`: the anomaly counters and their alerts. @@ -240,13 +241,15 @@ apply. load. - Memory is bounded. When the table of clients holds `SWW_WAF_MAX_TRACKED_CLIENTS`, the least recently seen client is dropped - first, with its history. The bans are bounded by `SWW_WAF_MAX_BANS` (see - "Bans"). The GeoJS answers, the reputation verdicts and scores, the DNS - queries under way and the anomaly counters have fixed bounds, listed under - "Fixed limits" in `docs/settings.md`. Past its bound, the GeoJS answer or - anomaly counter used longest ago goes first, and the verdict or score fetched - longest ago. Past the bound on DNS queries under way, a zone is asked at the - client's next request. + first, with its history. The bans for broken limits and clear signs of attack + are bounded by `SWW_WAF_MAX_BANS` (see "Bans"). Those for AbuseIPDB's + blacklist are bounded by the clients it listed over the last + `SWW_WAF_ABUSEIPDB_BAN_DAYS` days (see "Reputation"). The GeoJS answers, the + reputation verdicts and scores, the DNS queries under way and the anomaly + counters have fixed bounds, listed under "Fixed limits" in `docs/settings.md`. + Past its bound, the GeoJS answer or anomaly counter used longest ago goes + first, and the verdict or score fetched longest ago. Past the bound on DNS + queries under way, a zone is asked at the client's next request. ## Bans @@ -301,6 +304,9 @@ to a ban, each by its own rule: Once it ends, only new requests can break a limit again. The client's history keeps its totals. +A client on AbuseIPDB's blacklist is banned before it sends a request, with the +cause `abuseipdb` (see "Reputation"). + A Core Rule Set match refuses only the request it matched, with `403` and without a ban, because the Core Rule Set has false positives. A `block` rule does the same. Those refusals count toward the refusal limit, so a client that @@ -327,11 +333,12 @@ does not count toward a longer ban; it refuses nothing. Deleting its entry from A permanent ban does not run out. It ends when an admin lifts it, or when `waf` drops it from a full table, as below. When `waf` holds `SWW_WAF_MAX_BANS` bans -of its own, it drops the earliest ban of one netblock: the netblock that has -gone longest without a request. A past, active or permanent ban is dropped -alike. A scanner whose ban was dropped that way is refused and banned again by -its next probe. A ban whose cause is `admin` is never dropped and does not count -toward `SWW_WAF_MAX_BANS`, so such bans can never fill the table. +for broken limits and clear signs of attack, it drops the earliest such ban of +one netblock: the netblock that has gone longest without a request. A past, +active or permanent ban is dropped alike. A scanner whose ban was dropped that +way is refused and banned again by its next probe. Bans whose cause is `admin` +or `abuseipdb` do not count toward `SWW_WAF_MAX_BANS` and are never dropped to +make room, so they can never push out the others. A request refused under a ban that runs out is logged with the action `temporarily_banned`. Under a permanent ban the action is `permanently_banned`. @@ -2038,6 +2045,26 @@ host, sharing one address, would often fetch too close together. - AbuseIPDB answers other than `200`; - the answer gives no score; - no answer comes within `SWW_WAF_DNSBL_ABUSEIPDB_TIMEOUT_MS`. +- While `SWW_WAF_ABUSEIPDB_KEY` is set, AbuseIPDB's blacklist is fetched at the + start and every `SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS` minutes + (default `60`). It lists the clients AbuseIPDB scores at + `SWW_WAF_ABUSEIPDB_THRESHOLD` (default `90`) or more. The blacklist itself is + not kept. + - Each client on it is banned for `SWW_WAF_ABUSEIPDB_BAN_DAYS` days (default + `30`), with the cause `abuseipdb`. The ban covers the client's netblock, + as any ban does. + - A netblock that already has an active ban is left as it is. So is one + whose `abuseipdb` ban an admin lifted, until that ban would have ended. + - An `abuseipdb` ban that has ended is forgotten at the next of these: + - a fetch of the blacklist in `enforce` mode; + - a read of `bans.json`, at the start or after an admin's edit. + - In `observe` mode the blacklist makes no ban. + - The threshold takes 25 to 100. It should not be set below 50 to 75, since + lower scores list ordinary visitors. AbuseIPDB serves free accounts the + blacklist at the threshold 100, whatever is asked for. + - AbuseIPDB limits the fetches of the blacklist a day: 5 for a free account. + A fetch over the limit fails, and is logged and alerted. The default + refresh fetches it 24 times a day. - `SWW_WAF_DNSBL_ABUSEIPDB_ACTION`, for DNS blocklist and AbuseIPDB hits, is `limit:25` by default. Such verdicts are less certain than a blocklist, so a listed client gets a quarter of every request and byte limit rather than a @@ -2052,9 +2079,10 @@ host, sharing one address, would often fetch too close together. - Alerts go to a webhook as JSON, and to Slack and ntfy as formatted messages. `docs/alerts.md` lists the events, the JSON object and the messages. `SWW_WAF_ALERT_EVENTS` chooses which of the seven event types are sent; the - hourly `summary` is sent whatever it says. The bans an admin makes raise no - alert. In `observe` mode, a request that would have made a ban still raises - the ban's alert, with `mode` set to `observe` in its `detail`. + hourly `summary` is sent whatever it says. The bans an admin makes, and the + bans for AbuseIPDB's blacklist, raise no alert. In `observe` mode, a request + that would have made a ban still raises the ban's alert, with `mode` set to + `observe` in its `detail`. - A repeat is an alert with the same event, and the same netblock, source, file or anomaly scope, as one sent less than `SWW_WAF_ALERT_COOLDOWN` before. An anomaly scope is one of the things counted under "Anomaly thresholds". A @@ -2202,7 +2230,7 @@ lists the files, what each holds, and their sizes. these stop the process with a message naming the file and position: - a file that does not parse, or has an unknown `version`; - an entry without a field it needs; - - a ban whose cause is not one of the four; + - a ban whose cause is not `limit`, `attack`, `admin` or `abuseipdb`; - a ban whose `expires` is not after its `start`. Starting with empty state would silently forgive every repeat offender. diff --git a/docs/alerts.md b/docs/alerts.md index 6f14a37..d692915 100644 --- a/docs/alerts.md +++ b/docs/alerts.md @@ -6,7 +6,7 @@ back or dropped. ## Events -- `ban`: a ban `waf` made. +- `ban`: a ban `waf` made for a broken limit or a clear sign of attack. - `permanent_ban`: a permanent ban it made, or an existing ban made permanent by a request. - `core_rule_set_match`: the Core Rule Set scored a request at or over the @@ -68,7 +68,8 @@ on one line: "earlier_bans": { "limit": 0, "attack": 0, - "admin": 0 + "admin": 0, + "abuseipdb": 0 } } }, diff --git a/docs/settings.md b/docs/settings.md index 3658d72..7062bb8 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -42,8 +42,8 @@ chooses between the two (see "The image's command" below). client's group, from 32 to 128. - `SWW_WAF_MAX_TRACKED_CLIENTS` (default `20000`): the most clients kept, a whole number above zero. -- `SWW_WAF_MAX_BANS` (default `5000`): how many of its own bans `waf` keeps, a - whole number above zero. +- `SWW_WAF_MAX_BANS` (default `5000`): the most bans `waf` keeps for broken + limits and attacks, a whole number above zero. ## Tokens @@ -338,6 +338,13 @@ tag that no request can get stops the start. A request can get only these: or AbuseIPDB's score is used. A duration. - `SWW_WAF_DNSBL_ABUSEIPDB_TIMEOUT_MS` (default `2000`): how long a query to a zone or a check with AbuseIPDB may take. A time in milliseconds. +- `SWW_WAF_ABUSEIPDB_THRESHOLD` (default `90`): the least abuse confidence score + of the clients on AbuseIPDB's blacklist, a whole number from 25 to 100. It + should not be set below 50 to 75, since lower scores list ordinary visitors. +- `SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS` (default `60`): how often + the blacklist is fetched again, in minutes. A whole number above zero. +- `SWW_WAF_ABUSEIPDB_BAN_DAYS` (default `30`): how long the ban of a client on + the blacklist lasts, in days. A whole number above zero. ## Alerting diff --git a/docs/state-files.md b/docs/state-files.md index af6643d..fbe8371 100644 --- a/docs/state-files.md +++ b/docs/state-files.md @@ -21,11 +21,22 @@ top-level `version` of 1. ## `bans.json` -Active and past bans: every ban an admin made, and up to `SWW_WAF_MAX_BANS` of -those `waf` made. Per entry: +Active and past bans: + +- every ban an admin made; +- up to `SWW_WAF_MAX_BANS` of those `waf` made for a broken limit or an attack; +- the bans for AbuseIPDB's blacklist. + +A ban for AbuseIPDB's blacklist that has ended is forgotten at the next of +these: + +- a fetch of the blacklist in `enforce` mode; +- a read of `bans.json`, at the start or after an admin's edit. + +Per entry: - `netblock`, `start` and `expires` (`null` for a permanent ban); -- `cause`: `attack`, `limit` or `admin`; +- `cause`: `attack`, `limit`, `admin` or `abuseipdb`; - `reason`: a short reason; - `lifted`: when an admin lifted it, if one did; - `notes`: the notes below. @@ -60,7 +71,8 @@ ban. The notes: - for a clear sign of attack, `rule_id` and `target`, or `trap_path`; - `reputation`: the sources the client was on, each with its `source` and, for AbuseIPDB, its `score`; -- `request`: the request that caused the ban, each text cut to 256 bytes: +- `request`: the request that caused the ban, each text cut to 256 bytes, and + empty for a ban for AbuseIPDB's blacklist: - `time`, `method` and `host`; - `path`, with its query string; - `status` and `user_agent`; @@ -151,7 +163,9 @@ A cache file. routewatch's answers from the last hour, one per line: - `bans.json`: about 1.2 KiB per ban, at most about 2.5 KiB, so about 6 MiB at the default `SWW_WAF_MAX_BANS`. Written every 15 minutes, a full file comes to about 600 MiB of writes a day, and a hundred new bans a day add about 600 MiB - more. + more. A ban for AbuseIPDB's blacklist takes about 1 KiB. A free account's + blacklist lists 10,000 clients, so it adds at least 10 MiB, and 1 GiB of + writes a day. - `lookups.json`: about 150 bytes per answer, under 1.5 GiB of writes a day when full. - `routewatch.json`: about 120 bytes per answer, at most about 12 MiB. diff --git a/internal/bans/abuseipdb_test.go b/internal/bans/abuseipdb_test.go new file mode 100644 index 0000000..71c670a --- /dev/null +++ b/internal/bans/abuseipdb_test.go @@ -0,0 +1,165 @@ +package bans_test + +import ( + "net/netip" + "testing" + "time" + + "sneak.berlin/go/smallwebwaf/internal/bans" +) + +func TestBlacklistedNetblockIsBannedUntilTheGivenEnd(t *testing.T) { + t.Parallel() + + ledger := bans.New(defaultParams()) + netblock := netip.MustParsePrefix("203.0.113.9/32") + now := midnight() + expires := now.Add(30 * day) + + made := ledger.BanForAbuseIPDB( + now, expires, map[netip.Prefix]int64{netblock: 95}, + ) + if made != 1 || ledger.Made(bans.CauseAbuseIPDB) != 1 { + t.Fatalf("made %d bans, %d counted, want 1 and 1", + made, ledger.Made(bans.CauseAbuseIPDB)) + } + + ban, banned, madePermanent := ledger.Check(netblock.Addr(), now) + if !banned || madePermanent || !ban.Expires.Equal(expires) || + ban.Cause != bans.CauseAbuseIPDB || + ban.Reason != "on AbuseIPDB's blacklist with a score of 95" || + len(ban.Notes.Reputation) != 1 || + ban.Notes.Reputation[0].Source != "abuseipdb" || + *ban.Notes.Reputation[0].Score != 95 { + t.Errorf( + "ban %+v, banned %t, made permanent %t, want the blacklist's "+ + "ban until %s", + ban, + banned, + madePermanent, + expires, + ) + } + + if _, banned, _ := ledger.Check(netblock.Addr(), expires); banned { + t.Error("the ban refuses a request at its end") + } +} + +func TestBlacklistLeavesANetblockWithAnActiveBanAsItIs(t *testing.T) { + t.Parallel() + + ledger := bans.New(defaultParams()) + netblock := netip.MustParsePrefix("203.0.113.9/32") + now := midnight() + scores := map[netip.Prefix]int64{netblock: 100} + + limitBan, _ := ledger.BanForLimit(netblock, now, bans.Notes{}) + + if made := ledger.BanForAbuseIPDB(now, now.Add(30*day), scores); made != 0 { + t.Errorf("made %d bans over a ban for a limit, want none", made) + } + + // Once that ban has ended the netblock is banned, and the blacklist + // fetched again makes no second ban while the first lasts. + later := limitBan.Expires + if made := ledger.BanForAbuseIPDB(later, later.Add(30*day), scores); made != 1 { + t.Errorf("made %d bans after the ban for a limit, want 1", made) + } + + later = later.Add(time.Hour) + if made := ledger.BanForAbuseIPDB(later, later.Add(30*day), scores); made != 0 { + t.Errorf("made %d bans while the blacklist's lasts, want none", made) + } + + wantBans(t, ledger, map[netip.Prefix]int{netblock: 2}) + + if got := ledger.Bans(netblock)[1].Notes.EarlierBans; got != (bans.EarlierBans{ + Limit: 1, + }) { + t.Errorf("earlier bans %+v, want 1 for a limit", got) + } +} + +func TestLiftedBlacklistBanHoldsUntilItsEnd(t *testing.T) { + t.Parallel() + + ledger := bans.New(defaultParams()) + netblock := netip.MustParsePrefix("203.0.113.9/32") + now := midnight() + expires := now.Add(30 * day) + scores := map[netip.Prefix]int64{netblock: 100} + + ledger.BanForAbuseIPDB(now, expires, scores) + ledger.Lift(netblock.Addr(), now) + + // The admin lifted it: the blacklist fetched again until its end bans + // nothing. + later := expires.Add(-time.Hour) + if made := ledger.BanForAbuseIPDB(later, later.Add(30*day), scores); made != 0 { + t.Errorf("made %d bans before the lifted ban's end, want none", made) + } + + // From its end on, the blacklist bans the netblock again, and the + // lifted ban, ended, is forgotten. + if made := ledger.BanForAbuseIPDB(expires, expires.Add(30*day), scores); made != 1 { + t.Errorf("made %d bans at the lifted ban's end, want 1", made) + } + + wantBans(t, ledger, map[netip.Prefix]int{netblock: 1}) +} + +func TestEndedBlacklistBansAreForgottenAtTheNextFetch(t *testing.T) { + t.Parallel() + + ledger := bans.New(defaultParams()) + listed := netip.MustParsePrefix("203.0.113.9/32") + limited := netip.MustParsePrefix("203.0.113.10/32") + now := midnight() + expires := now.Add(30 * day) + + ledger.BanForAbuseIPDB(now, expires, map[netip.Prefix]int64{listed: 100}) + ledger.BanForLimit(limited, now, bans.Notes{}) + + // listed is off the blacklist when it is fetched after the ban's end. + if made := ledger.BanForAbuseIPDB(expires, expires.Add(30*day), nil); made != 0 { + t.Errorf("made %d bans for an empty blacklist, want none", made) + } + + wantBans(t, ledger, map[netip.Prefix]int{listed: 0, limited: 1}) +} + +func TestBlacklistBansDoNotCountTowardMaxBans(t *testing.T) { + t.Parallel() + + params := defaultParams() + params.MaxBans = 1 + ledger := bans.New(params) + limited := netip.MustParsePrefix("203.0.113.1/32") + attacker := netip.MustParsePrefix("203.0.113.2/32") + now := midnight() + + scores := map[netip.Prefix]int64{} + for i := range 3 { + scores[netip.PrefixFrom(netip.AddrFrom4([4]byte{198, 51, 100, byte(i)}), 32)] = 100 + } + + ledger.BanForLimit(limited, now, bans.Notes{}) + + if made := ledger.BanForAbuseIPDB(now, now.Add(30*day), scores); made != 3 { + t.Errorf("made %d bans for 3 netblocks, want 3", made) + } + + wantBans(t, ledger, map[netip.Prefix]int{limited: 1}) + + // The ban for an attack takes the place of the one for a limit, and no + // blacklist ban goes. + ledger.BanForAttack(attacker, now, bans.Notes{}) + + want := map[netip.Prefix]int{limited: 0, attacker: 1} + for netblock := range scores { + want[netblock] = 1 + } + + wantBans(t, ledger, want) +} diff --git a/internal/bans/bans.go b/internal/bans/bans.go index b581382..a558c82 100644 --- a/internal/bans/bans.go +++ b/internal/bans/bans.go @@ -1,8 +1,9 @@ // Package bans is the ban ledger: the bans sww makes on the // netblocks of clients that break a rate limit, a byte limit or the refusal -// limit or show a clear sign of attack, and those an admin makes, with their -// notes, as the "Bans" section of SPEC.md describes. The bans are kept in -// memory, and written to bans.json and read from it by the state package. +// limit or show a clear sign of attack, or are on AbuseIPDB's blacklist, and +// those an admin makes, with their notes, as the "Bans" section of SPEC.md +// describes. The bans are kept in memory, and written to bans.json and read +// from it by the state package. package bans import ( @@ -26,6 +27,9 @@ const ( // CauseAdmin is a ban an admin made, or one sww made that an // admin keeps. It is never dropped. CauseAdmin = "admin" + // CauseAbuseIPDB is a ban sww made for a client on AbuseIPDB's + // blacklist. It is forgotten once it has ended. + CauseAbuseIPDB = "abuseipdb" ) // repeatFactor is how many times as long as the netblock's last ban a ban @@ -50,10 +54,11 @@ type Params struct { // AttackBanDuration is how long a first ban for a clear sign of attack // lasts. AttackBanDuration time.Duration - // MaxBans is the most bans held whose cause is not CauseAdmin, at - // least one. Past it, the earliest such ban of the netblock that has - // gone longest without a request is dropped. Bans whose cause is - // CauseAdmin are held besides, and never dropped. + // MaxBans is the most bans held whose cause is CauseLimit or + // CauseAttack, at least one. Past it, the earliest such ban of the + // netblock that has gone longest without a request is dropped. Bans + // whose cause is CauseAdmin or CauseAbuseIPDB are held besides, and + // never dropped this way. MaxBans int } @@ -63,10 +68,11 @@ type Ban struct { Start time.Time // Expires is when the ban ends, zero for a permanent ban. Expires time.Time - // Cause is CauseLimit, CauseAttack or CauseAdmin. + // Cause is CauseLimit, CauseAttack, CauseAdmin or CauseAbuseIPDB. Cause string - // Reason is a short text: for a ban sww made, the limit broken or - // the rule that matched; for an admin's, what the admin wrote. + // Reason is a short text: for a ban sww made, the limit broken, the + // rule that matched or AbuseIPDB's score; for an admin's, what the + // admin wrote. Reason string // Lifted is when an admin lifted the ban, zero while no admin has. A // lifted ban refuses nothing, and does not make the netblock's next @@ -127,7 +133,8 @@ type Notes struct { // log's reputation names them. It is left out when none did. Reputation []ReputationHit `json:"reputation,omitempty"` // Request is the request that broke the limit, or whose bytes broke - // it, or that was the clear sign of attack. + // it, or that was the clear sign of attack. A ban for AbuseIPDB's + // blacklist has none, and leaves it zero. Request Request `json:"request"` // Requests is how many requests the netblock has sent since it was // first seen, and Refused how many of them the ban has refused so @@ -150,9 +157,10 @@ type ReputationHit struct { // EarlierBans counts a netblock's bans before a ban, by cause. type EarlierBans struct { - Limit int `json:"limit"` - Attack int `json:"attack"` - Admin int `json:"admin"` + Limit int `json:"limit"` + Attack int `json:"attack"` + Admin int `json:"admin"` + AbuseIPDB int `json:"abuseipdb"` } // Request is a request in a ban's notes. Each text is cut to 256 bytes. @@ -180,8 +188,8 @@ type Ledger struct { // netblocks holds each banned netblock's bans, oldest first. Check and // Find make each netblock they find the most recently seen. netblocks *simplelru.LRU[netip.Prefix, *[]Ban] - // held is how many bans netblocks holds whose cause is not CauseAdmin, - // at most params.MaxBans. + // held is how many bans netblocks holds whose cause is CauseLimit or + // CauseAttack, at most params.MaxBans. held int // made is how many bans have been made since the start, by cause: by // the ledger, and by an admin, through BanForAdmin or in an edit of @@ -198,8 +206,9 @@ type Ledger struct { // New returns a Ledger with no ban yet. func New(params Params) *Ledger { // The ledger drops bans itself, and never those whose cause is - // CauseAdmin, however many there are, so the LRU has no limit of its - // own: it keeps the netblocks in the order they were last seen. + // CauseAdmin or CauseAbuseIPDB to make room, however many there are, so + // the LRU has no limit of its own: it keeps the netblocks in the order + // they were last seen. netblocks, err := simplelru.NewLRU[netip.Prefix, *[]Ban]( math.MaxInt, nil, @@ -429,6 +438,88 @@ func (l *Ledger) BanForAdmin( return ban } +// BanForAbuseIPDB bans each netblock in scores at now until expires, and +// returns how many bans it made. scores are the netblocks of the clients +// on AbuseIPDB's blacklist, each with the highest score of its clients. +// A netblock is left as it is while a ban on it is active, or while a ban +// for the blacklist that an admin lifted has not reached its end: the +// admin's lift holds that long. Each ban whose cause is CauseAbuseIPDB +// and that has ended is forgotten first, so that the bans held for the +// blacklist are those of the clients listed within one ban's length. +func (l *Ledger) BanForAbuseIPDB( + now, expires time.Time, scores map[netip.Prefix]int64, +) int { + l.mu.Lock() + defer l.mu.Unlock() + + changed := l.forgetEndedAbuseIPDBBans(now) + made := 0 + + for netblock, score := range scores { + netblock = netblock.Masked() + + var notes Notes + + if held, found := l.netblocks.Peek(netblock); found { + if activeBan(*held, now) != nil || + liftedAbuseIPDBBan(*held, now) { + continue + } + + notes.EarlierBans = earlierBans(*held) + } + + // The source is named as the request log names AbuseIPDB. + notes.Reputation = []ReputationHit{ + {Source: CauseAbuseIPDB, Score: &score}, + } + + l.add(Ban{ + Netblock: netblock, + Start: now, + Expires: expires, + Cause: CauseAbuseIPDB, + Reason: fmt.Sprintf( + "on AbuseIPDB's blacklist with a score of %d", score, + ), + Notes: notes, + }) + + made++ + } + + l.made[CauseAbuseIPDB] += made + + if changed || made > 0 { + l.markChanged() + } + + return made +} + +// ForgetEndedAbuseIPDBBans forgets the bans whose cause is CauseAbuseIPDB +// and that have ended at now, as BanForAbuseIPDB does first. The state +// package calls it each time it reads bans.json, so that these bans are +// also forgotten while no fetch of the blacklist reaches the ledger. +func (l *Ledger) ForgetEndedAbuseIPDBBans(now time.Time) { + l.mu.Lock() + defer l.mu.Unlock() + + if l.forgetEndedAbuseIPDBBans(now) { + l.markChanged() + } +} + +// liftedAbuseIPDBBan reports whether bans, a netblock's, hold a ban whose +// cause is CauseAbuseIPDB that an admin lifted, and whose end is not +// reached at now. +func liftedAbuseIPDBBan(bans []Ban, now time.Time) bool { + return slices.ContainsFunc(bans, func(ban Ban) bool { + return ban.Cause == CauseAbuseIPDB && !ban.Lifted.IsZero() && + (ban.Permanent() || now.Before(ban.Expires)) + }) +} + // Lift lifts, at now, every ban active then on a netblock client is in, // as an admin does, and returns those bans. A lifted ban is kept, refuses // nothing, and does not make the netblock's next ban longer. @@ -515,9 +606,9 @@ func (l *Ledger) AddLookup( } // Made returns how many bans for cause have been made since the start: -// for CauseLimit and CauseAttack, by the ledger; for CauseAdmin, by an -// admin, with BanForAdmin or in an edit of bans.json, as LoadEdit counts -// them. The bans read from bans.json at the start are not among them. +// for CauseLimit, CauseAttack and CauseAbuseIPDB, by the ledger; for +// CauseAdmin, by an admin, with BanForAdmin or in an edit of bans.json, as +// LoadEdit counts them. The bans read from bans.json at the start are not among them. func (l *Ledger) Made(cause string) int { l.mu.Lock() defer l.mu.Unlock() @@ -574,8 +665,8 @@ func (l *Ledger) Snapshot() []Ban { // seen. A ban without a cause is an admin's, and gets CauseAdmin. Each // netblock is masked to its length, so that 203.0.113.9/24 is // 203.0.113.0/24, and each text in the notes is cut to 256 bytes. Past -// MaxBans the earliest bans whose cause is not CauseAdmin are dropped, as -// when they are made. +// MaxBans the earliest bans that count toward it are dropped, as when they +// are made. func (l *Ledger) Load(bans []Ban) { l.mu.Lock() defer l.mu.Unlock() @@ -639,6 +730,35 @@ func (l *Ledger) holds(netblock netip.Prefix, start time.Time) bool { }) } +// forgetEndedAbuseIPDBBans forgets each ban whose cause is CauseAbuseIPDB +// and whose end is reached at now, lifted or not, and each netblock left +// without a ban. It reports whether it forgot one. +func (l *Ledger) forgetEndedAbuseIPDBBans(now time.Time) bool { + forgot := false + + for _, netblock := range l.netblocks.Keys() { + bans, _ := l.netblocks.Peek(netblock) + + kept := slices.DeleteFunc(*bans, func(ban Ban) bool { + return ban.Cause == CauseAbuseIPDB && !ban.Permanent() && + !now.Before(ban.Expires) + }) + if len(kept) == len(*bans) { + continue + } + + forgot = true + + if len(kept) == 0 { + l.netblocks.Remove(netblock) + } else { + *bans = kept + } + } + + return forgot +} + // ban bans netblock at now for cause, CauseLimit or CauseAttack, with // reason and notes, as BanForLimit and BanForAttack describe, and returns // the ban, and whether it made it. Unless keep is true, the ban is not @@ -714,13 +834,16 @@ func earlierBans(held []Ban) EarlierBans { fromHere.Attack++ case CauseAdmin: fromHere.Admin++ + case CauseAbuseIPDB: + fromHere.AbuseIPDB++ } notes := ban.Notes.EarlierBans count := EarlierBans{ - Limit: notes.Limit + fromHere.Limit, - Attack: notes.Attack + fromHere.Attack, - Admin: notes.Admin + fromHere.Admin, + Limit: notes.Limit + fromHere.Limit, + Attack: notes.Attack + fromHere.Attack, + Admin: notes.Admin + fromHere.Admin, + AbuseIPDB: notes.AbuseIPDB + fromHere.AbuseIPDB, } // Of counts that name as many bans, the earlier ban's is taken: it @@ -735,7 +858,7 @@ func earlierBans(held []Ban) EarlierBans { // total returns how many bans e counts, of all causes. func (e EarlierBans) total() int { - return e.Limit + e.Attack + e.Admin + return e.Limit + e.Attack + e.Admin + e.AbuseIPDB } // markChanged has Changed receive a value, unless one is waiting already. @@ -806,9 +929,9 @@ func (l *Ledger) covering(client netip.Addr) []*[]Ban { // add adds ban to its netblock's bans, after the last, and makes its // netblock the most recently seen. With MaxBans held, it drops one first, -// unless ban's cause is CauseAdmin, which does not count toward MaxBans. +// unless ban does not count toward MaxBans. func (l *Ledger) add(ban Ban) { - counted := ban.Cause != CauseAdmin + counted := countsTowardMaxBans(ban) if counted && l.held == l.params.MaxBans { l.dropOne() } @@ -889,7 +1012,13 @@ func (l *Ledger) attackExpiry(held []Ban, now time.Time) time.Time { return now.Add(l.params.AttackBanDuration) } -// dropOne drops the earliest ban whose cause is not CauseAdmin of the +// countsTowardMaxBans reports whether ban counts toward MaxBans: its cause +// is CauseLimit or CauseAttack. +func countsTowardMaxBans(ban Ban) bool { + return ban.Cause == CauseLimit || ban.Cause == CauseAttack +} + +// dropOne drops the earliest ban that counts toward MaxBans of the // netblock that has gone longest without a request, of those that hold // such a ban, and the netblock with it if that was its only ban. It is // called with at least one such ban held. It looks at each netblock once @@ -898,11 +1027,9 @@ func (l *Ledger) dropOne() { for range l.netblocks.Len() { netblock, bans, _ := l.netblocks.GetOldest() - i := slices.IndexFunc(*bans, func(ban Ban) bool { - return ban.Cause != CauseAdmin - }) + i := slices.IndexFunc(*bans, countsTowardMaxBans) if i < 0 { - // Its bans are all an admin's, and never dropped. Get makes + // None of its bans is dropped to make room. Get makes // it the most recently seen, so that the next netblock is // looked at; when it was seen matters only for dropping a // ban, and a ban added to it makes it the most recently seen diff --git a/internal/config/waf.go b/internal/config/waf.go index 513d253..0691438 100644 --- a/internal/config/waf.go +++ b/internal/config/waf.go @@ -158,6 +158,14 @@ type WAF struct { DNSBLAbuseIPDBLimitPercent int64 IPReputationCacheTTL time.Duration DNSBLAbuseIPDBTimeout time.Duration + // While AbuseIPDBKey is set, AbuseIPDB's blacklist of the clients it + // scores AbuseIPDBThreshold or more (SWW_WAF_ABUSEIPDB_THRESHOLD), from + // 25 to 100, is fetched at the start and every AbuseIPDBBlacklistRefresh + // (SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS). Each client on it + // is banned for AbuseIPDBBanDuration (SWW_WAF_ABUSEIPDB_BAN_DAYS). + AbuseIPDBThreshold int64 + AbuseIPDBBlacklistRefresh time.Duration + AbuseIPDBBanDuration time.Duration // BanResponse is the status a refused client is answered with, 403 // or 429, or 0 to close the connection without an answer // (SWW_WAF_BAN_RESPONSE). It answers a banned client, a request that @@ -330,6 +338,9 @@ const ( // netblock a provider is usually given: a shorter one would make one // client of the customers of several providers. minIPv6GroupPrefix = 32 + // minAbuseIPDBThreshold is the lowest score AbuseIPDB's blacklist can + // be cut at. + minAbuseIPDBThreshold = 25 // minTokenLength is the fewest characters a token may have. minTokenLength = 32 // maxParanoiaLevel is the Core Rule Set's highest paranoia level. @@ -446,6 +457,13 @@ var ( errNotPercent = errors.New( "is not a percentage, a whole number from 0 to 100", ) + errNotAbuseIPDBThreshold = errors.New( + "is not a whole number from 25 to 100, the scores AbuseIPDB's " + + "blacklist can be cut at", + ) + errNotWholeUnits = errors.New( + "is not a whole number above zero, such as 30, that fits a duration", + ) errListedTwice = errors.New("is listed twice") errNotListURL = errors.New( "is not an http or https URL without a user or a fragment, " + @@ -587,6 +605,20 @@ func WAFFromEnvironment(v *viper.Viper) (*WAF, error) { "SWW_WAF_DNSBL_ABUSEIPDB_TIMEOUT_MS", "2000", ), + AbuseIPDBThreshold: env.abuseIPDBThreshold( + "SWW_WAF_ABUSEIPDB_THRESHOLD", + "90", + ), + AbuseIPDBBlacklistRefresh: env.wholeUnits( + "SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS", + "60", + time.Minute, + ), + AbuseIPDBBanDuration: env.wholeUnits( + "SWW_WAF_ABUSEIPDB_BAN_DAYS", + "30", + day, + ), BanResponse: env.banResponse("SWW_WAF_BAN_RESPONSE", "403"), LimitBanDuration: env.durationNotOff( "SWW_WAF_LIMIT_BAN_DURATION", @@ -957,6 +989,35 @@ func (e *environment) percent(name, defaultValue string) int64 { return percent } +// abuseIPDBThreshold reads the setting that is the least score of the +// clients on AbuseIPDB's blacklist: a whole number from 25 to 100, the +// range AbuseIPDB takes. +func (e *environment) abuseIPDBThreshold(name, defaultValue string) int64 { + value := e.value(name, defaultValue) + + threshold, err := strconv.ParseInt(value, 10, 64) + if err != nil || threshold < minAbuseIPDBThreshold || threshold > 100 { + e.check(name, fmt.Errorf("%q %w", value, errNotAbuseIPDBThreshold)) + } + + return threshold +} + +// wholeUnits reads a setting that is a whole number above zero of unit, +// such as minutes or days, and returns it as a duration. +func (e *environment) wholeUnits( + name, defaultValue string, unit time.Duration, +) time.Duration { + value := e.value(name, defaultValue) + + n, err := strconv.ParseInt(value, 10, 64) + if err != nil || n <= 0 || n > math.MaxInt64/int64(unit) { + e.check(name, fmt.Errorf("%q %w", value, errNotWholeUnits)) + } + + return time.Duration(n) * unit +} + // listURL reads a setting that is the URL a list is fetched from, "" while // it is unset or empty. func (e *environment) listURL(name string) string { diff --git a/internal/config/waf_test.go b/internal/config/waf_test.go index f3ea741..2f98d7f 100644 --- a/internal/config/waf_test.go +++ b/internal/config/waf_test.go @@ -61,6 +61,9 @@ const ( abuseIPDBKey = "SWW_WAF_ABUSEIPDB_KEY" abuseIPDBMinScore = "SWW_WAF_ABUSEIPDB_MIN_SCORE" abuseIPDBDailyBudget = "SWW_WAF_ABUSEIPDB_DAILY_BUDGET" + abuseIPDBThreshold = "SWW_WAF_ABUSEIPDB_THRESHOLD" + abuseIPDBBlacklistRefresh = "SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS" + abuseIPDBBanDays = "SWW_WAF_ABUSEIPDB_BAN_DAYS" dnsblAbuseIPDBAction = "SWW_WAF_DNSBL_ABUSEIPDB_ACTION" ipReputationCacheTTL = "SWW_WAF_IP_REPUTATION_CACHE_TTL" dnsblAbuseIPDBTimeout = "SWW_WAF_DNSBL_ABUSEIPDB_TIMEOUT_MS" @@ -2399,6 +2402,75 @@ func TestAbuseIPDBSettingsAsSet(t *testing.T) { } } +func TestAbuseIPDBBlacklistSettingsAsSet(t *testing.T) { + t.Parallel() + + cfg := wafFromEnvironment(t, environment{}) + if cfg.AbuseIPDBThreshold != 90 || + cfg.AbuseIPDBBlacklistRefresh != time.Hour || + cfg.AbuseIPDBBanDuration != 30*24*time.Hour { + t.Errorf( + "by default, the threshold %d, the refresh %s and the ban %s, "+ + "want 90, 1h and 720h", + cfg.AbuseIPDBThreshold, + cfg.AbuseIPDBBlacklistRefresh, + cfg.AbuseIPDBBanDuration, + ) + } + + cfg = wafFromEnvironment(t, environment{ + abuseIPDBThreshold: "25", abuseIPDBBlacklistRefresh: "1440", + abuseIPDBBanDays: "1", + }) + if cfg.AbuseIPDBThreshold != 25 || + cfg.AbuseIPDBBlacklistRefresh != 24*time.Hour || + cfg.AbuseIPDBBanDuration != 24*time.Hour { + t.Errorf( + "set, the threshold %d, the refresh %s and the ban %s, "+ + "want 25, 24h and 24h", + cfg.AbuseIPDBThreshold, + cfg.AbuseIPDBBlacklistRefresh, + cfg.AbuseIPDBBanDuration, + ) + } +} + +func TestInvalidAbuseIPDBBlacklistSettingStopsTheStartSayingWhatIsWrong( + t *testing.T, +) { + t.Parallel() + + const ( + notThreshold = " is not a whole number from 25 to 100, the scores " + + "AbuseIPDB's blacklist can be cut at" + notWhole = " is not a whole number above zero, such as 30, that fits " + + "a duration" + ) + + for _, tc := range []struct{ name, value, want string }{ + {abuseIPDBThreshold, "24", `"24"` + notThreshold}, + {abuseIPDBThreshold, "101", `"101"` + notThreshold}, + {abuseIPDBThreshold, off, `"off"` + notThreshold}, + {abuseIPDBBlacklistRefresh, "0", `"0"` + notWhole}, + {abuseIPDBBlacklistRefresh, "1h", `"1h"` + notWhole}, + {abuseIPDBBanDays, "-1", `"-1"` + notWhole}, + {abuseIPDBBanDays, "200000", `"200000"` + notWhole}, + } { + t.Run(tc.name+"="+tc.value, func(t *testing.T) { + t.Parallel() + + _, err := config.WAFFromEnvironment( + environment{tc.name: tc.value}.viper(), + ) + + want := tc.name + ": " + tc.want + if err == nil || err.Error() != want { + t.Errorf("error %v, want %s", err, want) + } + }) + } +} + func TestInvalidAbuseIPDBSettingStopsTheStartSayingWhatIsWrong( t *testing.T, ) { @@ -2951,6 +3023,9 @@ func TestLogsEachSettingWithItsValue(t *testing.T) { abuseIPDBKey: "", abuseIPDBMinScore: "75", abuseIPDBDailyBudget: "900", + abuseIPDBThreshold: "90", + abuseIPDBBlacklistRefresh: "60", + abuseIPDBBanDays: "30", dnsblAbuseIPDBAction: "limit:25", ipReputationCacheTTL: defaultIPReputationCacheTTL, dnsblAbuseIPDBTimeout: "2000", diff --git a/internal/metrics/metrics.go b/internal/metrics/metrics.go index 2f787e6..6e66332 100644 --- a/internal/metrics/metrics.go +++ b/internal/metrics/metrics.go @@ -185,7 +185,7 @@ func (m *Metrics) AddBansAndClients( ledger *bans.Ledger, limiter *ratelimit.Limiter, now func() time.Time, ) { for _, cause := range []string{ - bans.CauseLimit, bans.CauseAttack, bans.CauseAdmin, + bans.CauseLimit, bans.CauseAttack, bans.CauseAdmin, bans.CauseAbuseIPDB, } { m.registry.MustRegister( prometheus.NewCounterFunc(prometheus.CounterOpts{ diff --git a/internal/reputation/abuseipdb.go b/internal/reputation/abuseipdb.go index f6e6ff0..4e16f11 100644 --- a/internal/reputation/abuseipdb.go +++ b/internal/reputation/abuseipdb.go @@ -11,6 +11,7 @@ import ( "net/netip" "net/url" "slices" + "strconv" "sync" "time" @@ -23,6 +24,9 @@ const ( // AbuseIPDBURL is where clients are checked: the check endpoint of // AbuseIPDB's API. AbuseIPDBURL = "https://api.abuseipdb.com/api/v2/check" + // AbuseIPDBBlacklistURL is where AbuseIPDB's blacklist is fetched from: + // the blacklist endpoint of AbuseIPDB's API. + AbuseIPDBBlacklistURL = "https://api.abuseipdb.com/api/v2/blacklist" // AbuseIPDBSource is how the request log, the alerts and the metrics // name AbuseIPDB. AbuseIPDBSource = "abuseipdb" @@ -32,6 +36,8 @@ const ( var ( errNoScore = errors.New("the answer gives no abuseConfidenceScore") + errNoBlacklist = errors.New("the answer gives no data") + errNotAddress = errors.New("is not an address") errBudgetUsedUp = errors.New( "checks spent; none is made until the day ends at 00:00 UTC") ) @@ -53,6 +59,13 @@ type ChecksSpent struct { Spent int } +// BlacklistEntry is a client on AbuseIPDB's blacklist: its address and its +// abuse confidence score. +type BlacklistEntry struct { + Addr netip.Addr + Score int64 +} + // AbuseIPDBParams are what NewAbuseIPDB needs. type AbuseIPDBParams struct { // URL is where clients are checked, normally AbuseIPDBURL, with Key, @@ -69,10 +82,19 @@ type AbuseIPDBParams struct { // take (SWW_WAF_DNSBL_ABUSEIPDB_TIMEOUT_MS). CacheTTL time.Duration Timeout time.Duration + // BlacklistURL is where the blacklist is fetched from, normally + // AbuseIPDBBlacklistURL, with the clients scored Threshold or more + // (SWW_WAF_ABUSEIPDB_THRESHOLD), every BlacklistRefresh + // (SWW_WAF_ABUSEIPDB_BLACKLIST_REFRESH_INTERVAL_MINS). Blacklisted + // receives the clients on each blacklist fetched. + BlacklistURL string + Threshold int64 + BlacklistRefresh time.Duration + Blacklisted func([]BlacklistEntry) // Now tells the time, normally time.Now in UTC. Now func() time.Time - // ProcessLog receives each check that fails, and why, and the day's - // budget used up. + // ProcessLog receives each check or fetch of the blacklist that fails, + // and why, and the day's budget used up. ProcessLog *slog.Logger // Alerts receive a source_failure alert for each. Alerts *alerts.Queue @@ -256,6 +278,40 @@ func (a *AbuseIPDB) LoadChecksSpent(checks ChecksSpent) { a.day, a.spent = checks.Day, checks.Spent } +// RunBlacklist fetches AbuseIPDB's blacklist at once, and again every +// BlacklistRefresh, until ctx is done, and gives the clients on each copy +// fetched to Blacklisted. While Key is unset it does nothing. A fetch that +// fails is logged and raised as a source_failure alert, unless it was cut +// off as ctx ended. +func (a *AbuseIPDB) RunBlacklist(ctx context.Context) { + if a.params.Key == "" { + return + } + + for { + listed, err := a.fetchBlacklist(ctx) + + switch { + case ctx.Err() != nil: + return + case err != nil: + a.alert("fetching AbuseIPDB's blacklist failed", err) + default: + a.params.Blacklisted(listed) + } + + timer := time.NewTimer(a.params.BlacklistRefresh) + + select { + case <-ctx.Done(): + timer.Stop() + + return + case <-timer.C: + } + } +} + // check checks client with AbuseIPDB by addr, one of its addresses, keeps // the score as client's, and notes the check as no longer under way. A // check that fails gives no score: it is counted, logged and raised as a @@ -344,6 +400,94 @@ func (a *AbuseIPDB) ask( return *answer.Data.AbuseConfidenceScore, nil } +// fetchBlacklist fetches the clients on AbuseIPDB's blacklist scored +// Threshold or more, sending the key in the header Key. An answer other +// than 200, one longer than maxListBytes or without the list, an entry +// whose address does not read, and none within fetchTimeout, fail. +func (a *AbuseIPDB) fetchBlacklist( + ctx context.Context, +) ([]BlacklistEntry, error) { + ctx, cancel := context.WithTimeout(ctx, fetchTimeout) + defer cancel() + + query := url.Values{ + "confidenceMinimum": {strconv.FormatInt(a.params.Threshold, 10)}, + } + + req, err := http.NewRequestWithContext(ctx, http.MethodGet, + a.params.BlacklistURL+"?"+query.Encode(), http.NoBody) + if err != nil { + return nil, fmt.Errorf("make the request: %w", err) + } + + req.Header.Set("Key", a.params.Key) + req.Header.Set("Accept", "application/json") + + res, err := a.httpClient.Do(req) + if err != nil { + return nil, fmt.Errorf("fetch the blacklist: %w", errors.Unwrap(err)) + } + + defer func() { + _ = res.Body.Close() + }() + + if res.StatusCode != http.StatusOK { + return nil, fmt.Errorf("%w %s", errStatus, res.Status) + } + + body, err := io.ReadAll(io.LimitReader(res.Body, maxListBytes+1)) + if err != nil { + return nil, fmt.Errorf("read the blacklist: %w", err) + } + + if len(body) > maxListBytes { + return nil, errTooLong + } + + return parseBlacklist(body) +} + +// parseBlacklist reads body, AbuseIPDB's answer with its blacklist. +func parseBlacklist(body []byte) ([]BlacklistEntry, error) { + var answer struct { + Data *[]struct { + IPAddress string `json:"ipAddress"` + AbuseConfidenceScore int64 `json:"abuseConfidenceScore"` + } `json:"data"` + } + + err := json.Unmarshal(body, &answer) + if err != nil { + return nil, fmt.Errorf("read the blacklist: %w", err) + } + + if answer.Data == nil { + return nil, errNoBlacklist + } + + listed := make([]BlacklistEntry, 0, len(*answer.Data)) + + for i, entry := range *answer.Data { + addr, err := netip.ParseAddr(entry.IPAddress) + if err != nil || addr.Zone() != "" { + // The error leaves out what the entry holds, as it does a + // client's address. + return nil, fmt.Errorf( + "entry %d's ipAddress %w", + i+1, + errNotAddress, + ) + } + + listed = append(listed, BlacklistEntry{ + Addr: addr.Unmap(), Score: entry.AbuseConfidenceScore, + }) + } + + return listed, nil +} + // alert raises a source_failure alert from AbuseIPDB with reason and err, // and logs them. func (a *AbuseIPDB) alert(reason string, err error) { diff --git a/internal/reputation/blacklist_test.go b/internal/reputation/blacklist_test.go new file mode 100644 index 0000000..894135b --- /dev/null +++ b/internal/reputation/blacklist_test.go @@ -0,0 +1,252 @@ +package reputation_test + +import ( + "context" + "fmt" + "io" + "net/http" + "net/netip" + "slices" + "strings" + "sync" + "testing" + "testing/synctest" + "time" + + "sneak.berlin/go/smallwebwaf/internal/alerts" + "sneak.berlin/go/smallwebwaf/internal/reputation" +) + +// The tests of the blacklist run in synctest bubbles, as those of the +// checks do, with AbuseIPDB a stand-in reached without the network. + +// blacklistURL is where the tests fetch the blacklist from. +const blacklistURL = "https://abuseipdb.example/api/v2/blacklist" + +func TestBlacklistIsFetchedAtOnceAndEveryRefresh(t *testing.T) { + t.Parallel() + + synctest.Test(t, func(t *testing.T) { + abuseIPDB := &blacklistStandIn{body: `{"meta":{},"data":[` + + `{"ipAddress":"203.0.113.9","abuseConfidenceScore":100},` + + `{"ipAddress":"::ffff:198.51.100.7","abuseConfidenceScore":95},` + + `{"ipAddress":"2001:db8::9","abuseConfidenceScore":90}]}`} + got := runBlacklist(t, abuseIPDB, key, newQueue()) + + want := []reputation.BlacklistEntry{ + {Addr: netip.MustParseAddr("203.0.113.9"), Score: 100}, + {Addr: netip.MustParseAddr("198.51.100.7"), Score: 95}, + {Addr: netip.MustParseAddr("2001:db8::9"), Score: 90}, + } + + synctest.Wait() + got.want(t, want) + + time.Sleep(time.Hour - time.Nanosecond) + synctest.Wait() + got.want(t, want) + + time.Sleep(time.Nanosecond) + synctest.Wait() + got.want(t, want, want) + + // Each fetch asks for the clients scored 90 or more, with the key + // in the header Key alone. + abuseIPDB.mu.Lock() + defer abuseIPDB.mu.Unlock() + + for _, req := range abuseIPDB.asked { + if req.URL.String() != blacklistURL+"?confidenceMinimum=90" || + req.Header.Get("Key") != key { + t.Errorf( + "asked %s with the key %q, want %s?confidenceMinimum=90 "+ + "with %q", + req.URL, + req.Header.Get("Key"), + blacklistURL, + key, + ) + } + } + }) +} + +func TestFailedBlacklistFetchIsAlertedAndTriedAgainAtTheNextRefresh( + t *testing.T, +) { + t.Parallel() + + for _, tc := range []struct{ name, body, error string }{ + { + "a refusal", "", + "the server answered 429 Too Many Requests", + }, + { + "an answer without the list", `{"errors":[]}`, + "the answer gives no data", + }, + { + "an entry that is not an address", + `{"data":[{"ipAddress":"203.0.113.9"},{"ipAddress":"example"}]}`, + "entry 2's ipAddress is not an address", + }, + } { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + + synctest.Test(t, func(t *testing.T) { + abuseIPDB := &blacklistStandIn{body: tc.body} + if tc.body == "" { + abuseIPDB.status = http.StatusTooManyRequests + } + + queue := newQueue() + got := runBlacklist(t, abuseIPDB, key, queue) + + synctest.Wait() + + got.want(t) + + alerted := waiting(queue) + if len(alerted) != 1 || + alerted[0].Event != alerts.EventSourceFailure || + alerted[0].Reason != "fetching AbuseIPDB's blacklist failed" || + alerted[0].Detail["source"] != reputation.AbuseIPDBSource || + alerted[0].Detail["error"] != tc.error { + t.Errorf( + "alerts %+v, want the failure %q", + alerted, + tc.error, + ) + } + + abuseIPDB.answer(`{"data":[]}`) + time.Sleep(time.Hour) + synctest.Wait() + got.want(t, []reputation.BlacklistEntry{}) + }) + }) + } +} + +func TestBlacklistIsNotFetchedWithoutAKey(t *testing.T) { + t.Parallel() + + synctest.Test(t, func(t *testing.T) { + abuseIPDB := &blacklistStandIn{body: `{"data":[]}`} + got := runBlacklist(t, abuseIPDB, "", newQueue()) + + time.Sleep(time.Hour) + synctest.Wait() + got.want(t) + + if len(abuseIPDB.asked) != 0 { + t.Errorf("fetched the blacklist %d times, want none", + len(abuseIPDB.asked)) + } + }) +} + +// blacklistStandIn is a stand-in for AbuseIPDB that answers each fetch of +// the blacklist with status, 200 when it is zero, and body, and keeps the +// requests. +type blacklistStandIn struct { + mu sync.Mutex + status int + body string + asked []*http.Request +} + +// RoundTrip has the stand-in answer req, in place of the network. +func (s *blacklistStandIn) RoundTrip( + req *http.Request, +) (*http.Response, error) { + s.mu.Lock() + s.asked = append(s.asked, req) + status, body := s.status, s.body + s.mu.Unlock() + + if status == 0 { + status = http.StatusOK + } + + return &http.Response{ + StatusCode: status, + Status: fmt.Sprintf("%d %s", status, http.StatusText(status)), + Header: http.Header{}, + Body: io.NopCloser(strings.NewReader(body)), + Request: req, + }, nil +} + +// answer has the stand-in answer each fetch with 200 and body. +func (s *blacklistStandIn) answer(body string) { + s.mu.Lock() + defer s.mu.Unlock() + + s.status, s.body = 0, body +} + +// blacklisted holds the clients on each blacklist given to Blacklisted. +type blacklisted struct { + mu sync.Mutex + fetched [][]reputation.BlacklistEntry +} + +// want checks the clients on each blacklist given so far. +func (b *blacklisted) want( + t *testing.T, + want ...[]reputation.BlacklistEntry, +) { + t.Helper() + + b.mu.Lock() + defer b.mu.Unlock() + + if !slices.EqualFunc(b.fetched, want, slices.Equal) { + t.Errorf("blacklists %v, want %v", b.fetched, want) + } +} + +// runBlacklist runs RunBlacklist, until the test ends, with the key +// accountKey, the threshold 90 and a refresh of an hour, fetching from +// abuseIPDB and raising alerts into queue, and returns what it gives +// Blacklisted. +func runBlacklist( + t *testing.T, abuseIPDB *blacklistStandIn, accountKey string, + queue *alerts.Queue, +) *blacklisted { + t.Helper() + + got := &blacklisted{} + p := abuseIPDBParams() + p.Key = accountKey + p.BlacklistURL = blacklistURL + p.Threshold = 90 + p.BlacklistRefresh = time.Hour + p.Alerts = queue + p.Blacklisted = func(listed []reputation.BlacklistEntry) { + got.mu.Lock() + defer got.mu.Unlock() + + got.fetched = append(got.fetched, listed) + } + + checker := reputation.NewAbuseIPDB(p) + checker.SetTransport(abuseIPDB) + + ctx, cancel := context.WithCancel(t.Context()) + done := make(chan struct{}) + + go func() { + checker.RunBlacklist(ctx) + close(done) + }() + + t.Cleanup(func() { + cancel() + <-done + }) + + return got +} diff --git a/internal/reputation/reputation.go b/internal/reputation/reputation.go index 2b22cf7..a8790e9 100644 --- a/internal/reputation/reputation.go +++ b/internal/reputation/reputation.go @@ -7,7 +7,8 @@ // SWW_WAF_DNSBL_ZONES about clients, and keeps their verdicts, and checks // clients with AbuseIPDB, and keeps their scores and the checks spent // today. The state package writes all of these to files and reads them -// from there, so that a restart keeps them too. +// from there, so that a restart keeps them too. Last, it fetches +// AbuseIPDB's blacklist, which it does not keep. package reputation import ( diff --git a/internal/state/state.go b/internal/state/state.go index 9a04cc9..20f0046 100644 --- a/internal/state/state.go +++ b/internal/state/state.go @@ -104,7 +104,7 @@ var ( errVersion = errors.New("unknown version") // errMissing is for an entry without a field it needs. errMissing = errors.New("has no") - errCause = errors.New("is not limit, attack or admin") + errCause = errors.New("is not limit, attack, admin or abuseipdb") errExpires = errors.New("is not after its start") errDestination = errors.New("is not webhook, slack or ntfy") errScope = errors.New( @@ -638,6 +638,8 @@ func (f *Files) takeInState( f.params.Ledger.Load(held) } + f.params.Ledger.ForgetEndedAbuseIPDBBans(f.params.Now()) + entries = len(held) case clientsJSON: var file clientsFile @@ -967,7 +969,7 @@ func (e BanEntry) ban() bans.Ban { // each expires is read again as written. An expires not after the start // is refused too, since the netblock's next ban for a broken limit, three // times as long as this one, would then refuse nothing; and so is a cause -// other than limit, attack or admin, most likely misspelt. +// other than limit, attack, admin or abuseipdb, most likely misspelt. func (f *bansFile) check(data []byte) error { var written struct { Bans []struct { @@ -991,7 +993,8 @@ func (f *bansFile) check(data []byte) error { case entry.Expires != nil && !entry.Expires.After(entry.Start): return fmt.Errorf("entry %d's expires %w", i+1, errExpires) case entry.Cause != "" && entry.Cause != bans.CauseLimit && - entry.Cause != bans.CauseAttack && entry.Cause != bans.CauseAdmin: + entry.Cause != bans.CauseAttack && entry.Cause != bans.CauseAdmin && + entry.Cause != bans.CauseAbuseIPDB: return fmt.Errorf( "entry %d's cause %q %w", i+1, diff --git a/internal/state/state_test.go b/internal/state/state_test.go index 2ee13d9..d1861b9 100644 --- a/internal/state/state_test.go +++ b/internal/state/state_test.go @@ -114,7 +114,8 @@ const permanentBansJSON = `{ "earlier_bans": { "limit": 3, "attack": 1, - "admin": 1 + "admin": 1, + "abuseipdb": 0 } } } @@ -1190,7 +1191,7 @@ func TestBanWithAnotherCauseStopsTheStart(t *testing.T) { `"expires": "2026-10-06T04:00:00Z", "cause": "limit"}, `+ `{"netblock": "203.0.113.12/32", "start": "2026-10-06T00:00:00Z", `+ `"expires": null, "cause": "atack"}]}`, - `: entry 4's cause "atack" is not limit, attack or admin`) + `: entry 4's cause "atack" is not limit, attack, admin or abuseipdb`) } func TestBanThatDoesNotEndAfterItsStartStopsTheStart(t *testing.T) { @@ -2090,6 +2091,39 @@ func TestLiftedBanReadAtTheStart(t *testing.T) { wantLiftedBanKept(t, load(t, params), dir, params.Ledger) } +func TestEndedAbuseIPDBBanForgottenWhenBansJSONIsReadAtTheStart( + t *testing.T, +) { + t.Parallel() + + ended := netip.MustParsePrefix("203.0.113.9/32") + lasting := netip.MustParsePrefix("203.0.113.10/32") + limited := netip.MustParsePrefix("203.0.113.11/32") + + // At midnight, the start's time, the first ban has ended and the second + // lasts. The third has ended too, but is for a limit. + dir := t.TempDir() + edit(t, dir, bansJSON, `{"version": 1, "bans": [`+ + `{"netblock": "203.0.113.9/32", "start": "2026-09-06T00:00:00Z", `+ + `"expires": "2026-10-06T00:00:00Z", "cause": "abuseipdb"}, `+ + `{"netblock": "203.0.113.10/32", "start": "2026-09-07T00:00:00Z", `+ + `"expires": "2026-10-07T00:00:00Z", "cause": "abuseipdb"}, `+ + `{"netblock": "203.0.113.11/32", "start": "2026-10-05T00:00:00Z", `+ + `"expires": "2026-10-05T01:00:00Z", "cause": "limit"}]}`) + + params := newParams(dir) + load(t, params) + + for netblock, want := range map[netip.Prefix]int{ + ended: 0, lasting: 1, limited: 1, + } { + if got := len(params.Ledger.Bans(netblock)); got != want { + t.Errorf("the ledger holds %d bans on %s, want %d", + got, netblock, want) + } + } +} + func TestBanLiftedByAnEditWhileRunning(t *testing.T) { t.Parallel() diff --git a/internal/sww/waf.go b/internal/sww/waf.go index e6dbefd..72f8685 100644 --- a/internal/sww/waf.go +++ b/internal/sww/waf.go @@ -288,21 +288,36 @@ func newDNSBL( } // newAbuseIPDB returns what checks clients with AbuseIPDB while -// SWW_WAF_ABUSEIPDB_KEY is set, none checked yet. +// SWW_WAF_ABUSEIPDB_KEY is set, none checked yet. Until waf stops, it +// fetches AbuseIPDB's blacklist as it is due, and bans the clients on it in +// ledger, as waf.BanAbuseIPDBBlacklist says. func newAbuseIPDB( - cfg *config.WAF, processLog *slog.Logger, alertQueue *alerts.Queue, + lc fx.Lifecycle, cfg *config.WAF, processLog *slog.Logger, + alertQueue *alerts.Queue, ledger *bans.Ledger, ) *reputation.AbuseIPDB { - return reputation.NewAbuseIPDB(reputation.AbuseIPDBParams{ - URL: reputation.AbuseIPDBURL, - Key: cfg.AbuseIPDBKey, - MinScore: cfg.AbuseIPDBMinScore, - DailyBudget: cfg.AbuseIPDBDailyBudget, - CacheTTL: cfg.IPReputationCacheTTL, - Timeout: cfg.DNSBLAbuseIPDBTimeout, - Now: utcNow, - ProcessLog: processLog, - Alerts: alertQueue, + abuseIPDB := reputation.NewAbuseIPDB(reputation.AbuseIPDBParams{ + URL: reputation.AbuseIPDBURL, + Key: cfg.AbuseIPDBKey, + MinScore: cfg.AbuseIPDBMinScore, + DailyBudget: cfg.AbuseIPDBDailyBudget, + CacheTTL: cfg.IPReputationCacheTTL, + Timeout: cfg.DNSBLAbuseIPDBTimeout, + BlacklistURL: reputation.AbuseIPDBBlacklistURL, + Threshold: cfg.AbuseIPDBThreshold, + BlacklistRefresh: cfg.AbuseIPDBBlacklistRefresh, + Blacklisted: func(listed []reputation.BlacklistEntry) { + waf.BanAbuseIPDBBlacklist( + cfg, ledger, processLog, utcNow(), listed, + ) + }, + Now: utcNow, + ProcessLog: processLog, + Alerts: alertQueue, }) + + lc.Append(background(abuseIPDB.RunBlacklist)) + + return abuseIPDB } // newRouteWatch returns what asks routewatch about clients, or nil while diff --git a/internal/waf/abuseipdbblacklist.go b/internal/waf/abuseipdbblacklist.go new file mode 100644 index 0000000..c4dfb84 --- /dev/null +++ b/internal/waf/abuseipdbblacklist.go @@ -0,0 +1,46 @@ +package waf + +// The bans for AbuseIPDB's blacklist. They read SWW_WAF_ABUSEIPDB_BAN_DAYS and +// SWW_WAF_MODE; the blacklist is fetched by the reputation package. + +import ( + "log/slog" + "net/netip" + "time" + + "sneak.berlin/go/smallwebwaf/internal/bans" + "sneak.berlin/go/smallwebwaf/internal/config" + "sneak.berlin/go/smallwebwaf/internal/reputation" +) + +// BanAbuseIPDBBlacklist bans in ledger the netblock of each client on +// AbuseIPDB's blacklist, listed, for SWW_WAF_ABUSEIPDB_BAN_DAYS from now, as +// the ledger's BanForAbuseIPDB describes. It logs to processLog how many +// clients were listed and how many bans were made. Clients in one netblock +// make one ban, with the highest of their scores. In observe mode it makes +// no ban. +func BanAbuseIPDBBlacklist( + cfg *config.WAF, ledger *bans.Ledger, processLog *slog.Logger, + now time.Time, listed []reputation.BlacklistEntry, +) { + scores := make(map[netip.Prefix]int64, len(listed)) + + for _, client := range listed { + netblock := banNetblock(cfg, client.Addr) + scores[netblock] = max(scores[netblock], client.Score) + } + + made := 0 + + if !cfg.Observe { + made = ledger.BanForAbuseIPDB( + now, now.Add(cfg.AbuseIPDBBanDuration), scores, + ) + } + + processLog.Info( + "fetched AbuseIPDB's blacklist", + "clients", len(listed), + "bans_made", made, + ) +} diff --git a/internal/waf/abuseipdbblacklist_test.go b/internal/waf/abuseipdbblacklist_test.go new file mode 100644 index 0000000..3756699 --- /dev/null +++ b/internal/waf/abuseipdbblacklist_test.go @@ -0,0 +1,100 @@ +package waf_test + +import ( + "context" + "net/http" + "net/netip" + "testing" + "time" + + "sneak.berlin/go/smallwebwaf/internal/bans" + "sneak.berlin/go/smallwebwaf/internal/reputation" + "sneak.berlin/go/smallwebwaf/internal/requestlog" +) + +// abuseIPDBBanDays is the setting of how long a ban for AbuseIPDB's +// blacklist lasts, in days. +const abuseIPDBBanDays = "SWW_WAF_ABUSEIPDB_BAN_DAYS" + +func TestClientOnTheFetchedAbuseIPDBBlacklistIsRefused(t *testing.T) { + t.Parallel() + + s, clk, server := startWithClock(t, "", map[string]string{ + abuseIPDBKey: accountKey, + }) + + ctx, cancel := context.WithCancel(t.Context()) + stopped := make(chan struct{}) + + go func() { + server.AbuseIPDB.RunBlacklist(ctx) + close(stopped) + }() + + t.Cleanup(func() { + cancel() + <-stopped + }) + + waitUntil(func() bool { + active, _ := server.Ledger.Count(clk.Now()) + + return active == 1 + }) + + s.get(client, http.StatusForbidden, requestlog.ActionTemporarilyBanned) + s.get(otherClient, http.StatusOK, requestlog.ActionForward) +} + +func TestClientsOnTheAbuseIPDBBlacklistAreBannedForTheBanDays(t *testing.T) { + t.Parallel() + + s, clk, server := startWithClock(t, "", map[string]string{ + abuseIPDBBanDays: "2", banScopeV4Prefix: "24", + }) + + // Two clients in one netblock make one ban, with the higher score. + server.BanAbuseIPDBBlacklist([]reputation.BlacklistEntry{ + {Addr: netip.MustParseAddr(client), Score: 95}, + {Addr: netip.MustParseAddr(otherClient), Score: 100}, + {Addr: netip.MustParseAddr("2001:db8:5::1"), Score: 90}, + }) + + held := server.Ledger.Bans(netip.MustParsePrefix(clientsNet)) + if len(held) != 1 || held[0].Cause != bans.CauseAbuseIPDB || + *held[0].Notes.Reputation[0].Score != 100 { + t.Errorf("bans on %s %+v, want one for the blacklist, with 100", + clientsNet, held) + } + + // Every client of a banned netblock is refused, the IPv6 address's /64 + // included. + for _, from := range []string{"203.0.113.200", "2001:db8:5::ffff:1"} { + s.get(from, http.StatusForbidden, requestlog.ActionTemporarilyBanned) + } + + s.get("2001:db8:5:1::1", http.StatusOK, requestlog.ActionForward) + + clk.advance(2 * 24 * time.Hour) + s.get(client, http.StatusOK, requestlog.ActionForward) +} + +func TestAbuseIPDBBlacklistMakesNoBanInObserveMode(t *testing.T) { + t.Parallel() + + s, clk, server := startWithClock( + t, + "", + map[string]string{mode: "observe"}, + ) + + server.BanAbuseIPDBBlacklist([]reputation.BlacklistEntry{ + {Addr: netip.MustParseAddr(client), Score: 100}, + }) + + if active, _ := server.Ledger.Count(clk.Now()); active != 0 { + t.Errorf("%d bans active, want none", active) + } + + s.get(client, http.StatusOK, requestlog.ActionForward) +} diff --git a/internal/waf/export_test.go b/internal/waf/export_test.go index 24cb414..e87a2f2 100644 --- a/internal/waf/export_test.go +++ b/internal/waf/export_test.go @@ -1,4 +1,13 @@ package waf +import "sneak.berlin/go/smallwebwaf/internal/reputation" + // BesideLookupTimeLimit is besideLookupTimeLimit. const BesideLookupTimeLimit = besideLookupTimeLimit + +// BanAbuseIPDBBlacklist does on s what a fetch of AbuseIPDB's blacklist with +// the clients on listed does. +func (s *Server) BanAbuseIPDBBlacklist(listed []reputation.BlacklistEntry) { + h := s.Handler.(*handler) //nolint:forcetypeassert // New makes it one + BanAbuseIPDBBlacklist(h.config, h.ledger, h.processLog, h.now(), listed) +} diff --git a/internal/waf/proxy.go b/internal/waf/proxy.go index e1bd713..966fe8b 100644 --- a/internal/waf/proxy.go +++ b/internal/waf/proxy.go @@ -1,6 +1,7 @@ // Package waf is the server the waf command runs. It answers // rproxy's questions, takes rproxy's reports and answers its own endpoints, and -// writes a log line for each. +// writes a log line for each. It also bans the clients on AbuseIPDB's +// blacklist each time the reputation package fetches it. package waf import ( diff --git a/internal/waf/proxy_test.go b/internal/waf/proxy_test.go index 3951d33..9d0dfe3 100644 --- a/internal/waf/proxy_test.go +++ b/internal/waf/proxy_test.go @@ -431,7 +431,8 @@ func startRProxy( // With no geojsURL, there is no stand-in for GeoJS to look clients up at, and // SWW_WAF_LOOKUP_SOURCE is off unless env sets it. While it is file, the lookup // database SWW_WAF_LOOKUP_DB_PATH names is read. Clients are checked with AbuseIPDB -// at abuseIPDBURL while env sets SWW_WAF_ABUSEIPDB_KEY. +// 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. func newWAF( @@ -575,8 +576,9 @@ func addCounters(params *waf.Params) { } // addOutsideSources adds to params the lists fetched from URLs, the DNSBL -// zones' verdicts, AbuseIPDB's scores from abuseIPDBCheckURL, routewatch's -// answers while its setting is set, and GeoJS at geojsURL, as sww builds +// zones' verdicts, AbuseIPDB's scores from abuseIPDBCheckURL and its +// blacklist from abuseIPDBBlacklistURL, routewatch's answers while its +// setting is set, and GeoJS at geojsURL, as sww builds // them from params' settings and the parts addCounters added. The metrics // read the lists, the zones' verdicts, and AbuseIPDB's while its key is set. func addOutsideSources( @@ -605,15 +607,23 @@ func addOutsideSources( Alerts: alertQueue, }) params.AbuseIPDB = reputation.NewAbuseIPDB(reputation.AbuseIPDBParams{ - URL: abuseIPDBCheckURL, - Key: cfg.AbuseIPDBKey, - MinScore: cfg.AbuseIPDBMinScore, - DailyBudget: cfg.AbuseIPDBDailyBudget, - CacheTTL: cfg.IPReputationCacheTTL, - Timeout: cfg.DNSBLAbuseIPDBTimeout, - Now: params.Now, - ProcessLog: processLog, - Alerts: alertQueue, + URL: abuseIPDBCheckURL, + Key: cfg.AbuseIPDBKey, + MinScore: cfg.AbuseIPDBMinScore, + DailyBudget: cfg.AbuseIPDBDailyBudget, + CacheTTL: cfg.IPReputationCacheTTL, + Timeout: cfg.DNSBLAbuseIPDBTimeout, + BlacklistURL: abuseIPDBBlacklistURL, + Threshold: cfg.AbuseIPDBThreshold, + BlacklistRefresh: cfg.AbuseIPDBBlacklistRefresh, + Blacklisted: func(listed []reputation.BlacklistEntry) { + waf.BanAbuseIPDBBlacklist( + cfg, ledger, processLog, params.Now(), listed, + ) + }, + Now: params.Now, + ProcessLog: processLog, + Alerts: alertQueue, }) if cfg.RouteWatchURL != "" { diff --git a/internal/waf/reputation_test.go b/internal/waf/reputation_test.go index 7bb9335..ab4af72 100644 --- a/internal/waf/reputation_test.go +++ b/internal/waf/reputation_test.go @@ -822,22 +822,39 @@ const abuseipdb = reputation.AbuseIPDBSource // through which AbuseIPDB is asked. const abuseIPDBURL = "abuseipdb://stand-in/api/v2/check" +// abuseIPDBBlacklistURL is where newWAF has AbuseIPDB's blacklist fetched +// from: at abuseIPDBStandIn too. +const abuseIPDBBlacklistURL = "abuseipdb://stand-in/api/v2/blacklist" + // abuseIPDBStandIn is a stand-in for AbuseIPDB that gives every client the -// score 100, at once and without the network. +// score 100, at once and without the network. Its blacklist lists client +// alone, with the score 100, to a fetch with accountKey that asks for the +// clients scored 90 or more, the default threshold; it refuses any other +// fetch of it with 400. type abuseIPDBStandIn struct{} -// RoundTrip answers req with the score 100. +// RoundTrip answers req with the score 100, or with the blacklist. func (abuseIPDBStandIn) RoundTrip( req *http.Request, ) (*http.Response, error) { + status, body := http.StatusOK, `{"data":{"abuseConfidenceScore":100}}` + + if req.URL.Path == "/api/v2/blacklist" { + body = `{"data":[{"ipAddress":"` + client + + `","abuseConfidenceScore":100}]}` + + if req.Header.Get("Key") != accountKey || + req.URL.RawQuery != "confidenceMinimum=90" { + status, body = http.StatusBadRequest, `{"errors":[]}` + } + } + return &http.Response{ - StatusCode: http.StatusOK, - Status: "200 OK", + StatusCode: status, + Status: fmt.Sprintf("%d %s", status, http.StatusText(status)), Header: http.Header{}, - Body: io.NopCloser( - strings.NewReader(`{"data":{"abuseConfidenceScore":100}}`), - ), - Request: req, + Body: io.NopCloser(strings.NewReader(body)), + Request: req, }, nil } -- 2.54.0