SPEC: requirements and reasons only, reference material in docs/

docs/settings.md is now the one settings reference; the spec keeps the
conventions, the off list and each group's requirements and reasons, and
links to it for the per-setting entries. The endpoint list, the ban
notes, the state file contents, the rule file format and the alert
object likewise live in docs/ and are linked from the spec. The package
list from the README's Design section joins "Architecture". The nine
docs files are byte-identical to those on the README branch. Package
comments that named "Alert webhook schema", "Request log" and "Metrics
endpoint" for their field lists now name the docs files.

Model: fable-5-1

Dockerfile

@@ -140,10 +140,14 @@ RUN mkdir /etc/sysusers.d \
 # apt also fetches the live archive's InRelease files, which change daily
 # and which the install does not use. The snapshot service is HTTPS only
 # and this image has no CA certificates yet, so this step uses the Go
-# image's.
+# image's. The snapshot service answers 503 at times; apt retries a
+# failed download, waiting twice as long before each retry, and this
+# step gives it five retries, about half a minute in all, where its
+# default of three gives up after seven seconds.
 RUN --mount=type=bind,from=builder,source=/etc/ssl/certs/ca-certificates.crt,target=/tmp/go-image-ca.crt \
     apt-get update --snapshot 20261001T000000Z \
         -o Acquire::https::CaInfo=/tmp/go-image-ca.crt \
+        -o Acquire::Retries=5 \
     && printf '%s\n' \
         '45f95ce276cdba3e41870516a130e03c58b8b7a79e9546b0efe9e526d255740c  snapshot.ubuntu.com_ubuntu_20261001T000000Z_dists_resolute_InRelease' \
         '802e675dd9de4c7f3916434a95e7c1d8eec0e82886622d7805ab19a2c6fe0365  snapshot.ubuntu.com_ubuntu_20261001T000000Z_dists_resolute-updates_InRelease' \
@@ -153,6 +157,7 @@ RUN --mount=type=bind,from=builder,source=/etc/ssl/certs/ca-certificates.crt,tar
     && DEBIAN_FRONTEND=noninteractive apt-get install --yes --no-install-recommends \
         --snapshot 20261001T000000Z \
         -o Acquire::https::CaInfo=/tmp/go-image-ca.crt \
+        -o Acquire::Retries=5 \
         ca-certificates nix-bin runit \
     && rm -rf /var/lib/apt/lists/*
 

Makefile

@@ -1,11 +1,12 @@
 .PHONY: bootstrap setup test lint fmt fmt-check tidy check docker hooks build \
-	run example-app
+	run example-app gitea-requests
 
 # Makefile targets are thin shims; the implementations live in script/
 # per the scripts-to-rule-them-all pattern (see the Entrypoints section
 # of README.md). tidy writes go.mod and go.sum as `go mod tidy` does,
 # which test checks. build and run are for working on the code by hand;
-# example-app checks the image with an app built on it.
+# example-app checks the image with an app built on it; gitea-requests
+# reports the gitea requests the Core Rule Set refuses at the defaults.
 
 bootstrap:
 	@script/bootstrap
@@ -45,3 +46,6 @@ run:
 
 example-app:
 	@script/example-app
+
+gitea-requests:
+	@script/gitea-requests

README.md

@@ -96,11 +96,14 @@ in `bin/state` unless `SWWAF_STATE_DIR` is set, and the default rule file of
 ## What it does so far
 
 - Passes each request to the app and the app's answer back unchanged: method,
-  path, query, headers, body and status. Bodies stream through in both
-  directions and are never held whole in memory, but for the part of a request
-  body the Core Rule Set reads, at most `SWWAF_WAF_BODY_LIMIT` and one byte
-  more, which is held until the app is sent it. A WebSocket, or any other
-  upgraded connection, passes through, and the timeouts do not cut it.
+  path, query, headers, body and status. The one exception is a path starting
+  with `//` that holds a character Go escapes, such as `|`: Go cannot send it as
+  it is, and the app receives it decoded and escaped again, `%2F` as `/`. Bodies
+  stream through in both directions and are never held whole in memory, but for
+  the part of a request body the Core Rule Set reads, at most
+  `SWWAF_WAF_BODY_LIMIT` and one byte more, which is held until the app is sent
+  it. A WebSocket, or any other upgraded connection, passes through, and the
+  timeouts do not cut it.
 - Works out the client's address. A TCP peer outside `SWWAF_TRUSTED_PROXIES` is
   the client, and the forwarded headers it sends are replaced, not passed on.
   For a peer inside it, `X-Forwarded-For` is read from the right, and the first
@@ -110,16 +113,16 @@ in `bin/state` unless `SWWAF_STATE_DIR` is set, and the default rule file of
   `X-Forwarded-Proto`, and `X-Forwarded-For` with the peer added at the end. It
   also gets the request's id in `X-Request-ID`, the same id as in the request's
   log line (see `request_id` in "Request log" below).
-- Enforces the timeouts and the size limits below. A limit passed before the
-  response has started gets `smallwebwaf`'s own answer: `408` for a client too
-  slow to send its request, `413` for a request body that is too large, `504`
-  for an app too slow to answer, and `502` for a response that is too large or
-  an app that cannot be reached. A request that announces a body over the limit
-  is refused before anything reaches the app. While a request body is still on
-  its way, a request timeout that runs out answers `408` if `smallwebwaf` was
-  waiting for the client to send more, and `504` if it was waiting for the app
-  to take what it had. Once the response has started, a limit can only cut the
-  connection.
+- Enforces the timeouts and the size limits below. Once a request's line and
+  headers have been read, a limit passed before the response has started gets
+  `smallwebwaf`'s own answer: `408` for a client too slow to send its body,
+  `413` for a request body that is too large, `504` for an app too slow to
+  answer, and `502` for a response that is too large or an app that cannot be
+  reached. A request that announces a body over the limit is refused before
+  anything reaches the app. While a request body is still on its way, a request
+  timeout that runs out answers `408` if `smallwebwaf` was waiting for the
+  client to send more, and `504` if it was waiting for the app to take what it
+  had. Once the response has started, a limit can only cut the connection.
 - Counts each client's requests over a minute, an hour and a day. A request that
   takes the client over one of the rate limits below is refused with
   `SWWAF_BAN_RESPONSE`, `403` by default, before anything reaches the app, and
@@ -1042,9 +1045,11 @@ less severe than `SWWAF_LOG_LEVEL` are not written.
 Go's HTTP server, on which `smallwebwaf` is built, reads a request's line and
 headers before `smallwebwaf` sees the request, and some requests end there,
 without a line in the log: headers over `SWWAF_CLIENT_REQUEST_HEADER_MAX_BYTES`,
-which it answers `431`, headers slower than `SWWAF_CLIENT_REQUEST_TIMEOUT`,
-whose connection it closes without an answer, and requests it cannot read at
-all, which it answers itself, mostly with `400`.
+which it answers `431`, and requests it cannot read at all, which it answers
+itself, mostly with `400`. A client too slow to send its request line and
+headers within `SWWAF_CLIENT_REQUEST_TIMEOUT` gets either no answer or an error
+answer from the server, mostly `400 Bad Request`; either way the server closes
+its connection, nothing reaches the app, and no line is written in the log.
 
 ### Sending the log to a syslog server
 
@@ -1444,11 +1449,12 @@ whole service, its `asn`, for an AS number, its `name`, for a named netblock, or
 the `start` of a window in which it has requests or bytes; a list's `url`,
 `fetched` or `lines`, which is `[]` for an empty list; a verdict's `zone`,
 `client`, `listed`, which is `false` for a client the zone does not list, or
-`fetched`. So does a ban whose `cause` is not `limit`, `attack`, `admin` or
-`crowdsec`, alerts waiting for a destination that is not `webhook`, `slack` or
-`ntfy`, an anomaly counter whose `scope` is not `client`, `net`, `asn`, `total`
-or `watch`, and a copy of a list with a line that would make its fetch fail. An
-answer's `asn` or `as_name` left out reads as empty.
+`fetched`. So does a ban whose `expires` is not after its `start` or whose
+`cause` is not `limit`, `attack`, `admin` or `crowdsec`, alerts waiting for a
+destination that is not `webhook`, `slack` or `ntfy`, an anomaly counter whose
+`scope` is not `client`, `net`, `asn`, `total` or `watch`, and a copy of a list
+with a line that would make its fetch fail. An answer's `asn` or `as_name` left
+out reads as empty.
 
 While it runs, `smallwebwaf` watches `SWWAF_STATE_DIR` and takes in your edit of
 a state file as soon as you save it: what the file then holds replaces what
@@ -1458,14 +1464,15 @@ writes a file it takes in any edit made since, so your edit is not overwritten;
 a change `smallwebwaf` made after you opened the file, such as a new ban, is
 lost when you save over it. An edit that would stop the start, because it does
 not parse, has another `version`, leaves out a field an entry needs, gives a ban
-another `cause`, names another destination, gives an anomaly counter another
-`scope` or gives a list's copy a line that would make its fetch fail, does not
-stop the running `smallwebwaf`: it keeps what it holds, and at the file's next
-write renames your file to `<name>.bad`, such as `bans.json.bad`, writes the
-file again from memory, logs the file and where the error is, and raises a
-`file_error` alert for it. It waits for that write because an editor's file can
-be read before the editor has finished writing it. Mend the `.bad` file and move
-it back. A file you remove is written again at its next write.
+an `expires` not after its `start` or another `cause`, names another
+destination, gives an anomaly counter another `scope` or gives a list's copy a
+line that would make its fetch fail, does not stop the running `smallwebwaf`: it
+keeps what it holds, and at the file's next write renames your file to
+`<name>.bad`, such as `bans.json.bad`, writes the file again from memory, logs
+the file and where the error is, and raises a `file_error` alert for it. It
+waits for that write because an editor's file can be read before the editor has
+finished writing it. Mend the `.bad` file and move it back. A file you remove is
+written again at its next write.
 
 To ban a netblock, add an entry to `bans.json` with its `netblock`, its `start`
 and its `expires`, `null` for a ban that never ends; its `reason` and its
@@ -1954,8 +1961,14 @@ main "$@"
   without one, it still starts. At each start the `run` script of `smallwebwaf`
   gives that directory and every file in it to the `smallwebwaf` user, so a host
   directory mounted there needs no change of owner.
-- `docker stop` has runit stop both processes. `smallwebwaf` then stops taking
-  requests and gives those in progress five seconds to finish.
+- `docker stop` has runit stop both processes at once, each with SIGTERM.
+  `smallwebwaf` then stops taking requests and gives those in progress five
+  seconds to finish, which they can do only while the app still answers. An app
+  that exits at once on SIGTERM ends them: the client gets `502`, or a response
+  cut short if the app had already begun to answer. An app that should let them
+  finish keeps taking and answering requests, not only the ones it already has,
+  for the whole five seconds after SIGTERM, since `smallwebwaf` can still pass
+  it requests it took before then.
 
 A rule file is one rule per line: a name, what to match against, what to do, and
 a regex.
@@ -2147,13 +2160,14 @@ addresses sends, so that one client costs at most one check every
 `SWWAF_REPUTATION_CACHE_TTL`.
 
 Only a client whose history counts an offence is checked, so that the checks are
-spent on suspects: so far, one that has broken a rate limit or a byte limit,
-matched a ban rule, or had a request refused by a block rule or the Core Rule
-Set. A client dropped from the table of clients loses its history, and with it
-its offences. A client is checked in the background, at its first request after
-its offence that reaches the check: no request waits, a request refused under
-its ban is not checked, and the request that has it checked, and any other from
-it before the answer comes, goes on as from a client without a score.
+spent on suspects: so far, one that has broken a rate limit, a byte limit or the
+error burst, matched a ban rule, asked for a trap path, or had a request refused
+by a block rule, by the Core Rule Set or for a missing or wrong token. A client
+dropped from the table of clients loses its history, and with it its offences. A
+client is checked in the background, at its first request after its offence that
+reaches the check: no request waits, a request refused under its ban is not
+checked, and the request that has it checked, and any other from it before the
+answer comes, goes on as from a client without a score.
 
 A score at or over `SWWAF_ABUSEIPDB_MIN_SCORE`, 75 by default, is a hit, and
 `SWWAF_REPUTATION_ACTION` says what is done with its client, as for a DNSBL
@@ -2370,10 +2384,34 @@ so that they run in minimal containers.
   that the health check passes, that a request reaches the app through
   `smallwebwaf`, that a second request in a minute bans the client, that a probe
   for `/.env` bans another client, whose next request makes the ban permanent,
-  that `sv stop` and `docker stop` stop it in order, and that a new container on
-  the same volume still refuses the banned client; then removes the containers,
-  the volume and both images. It needs network access, for nixpkgs' binary
-  cache, and `script/check` does not run it; `make example-app` does.
+  that `sv stop` and `docker stop` stop it in order, that a new container on the
+  same volume still refuses the banned client, that a container with its state
+  files on a new volume mounted at the directory `SWWAF_STATE_DIR_FILE` names
+  becomes healthy, and that one whose `SWWAF_STATE_DIR` does not exist logs
+  `smallwebwaf`'s message about it; then removes the containers, the volumes and
+  both images. It needs network access, for nixpkgs' binary cache, and
+  `script/check` does not run it; `make example-app` does.
+- `script/gitea-requests`: builds the image and runs gitea 1.27.3 behind it,
+  with every setting of `smallwebwaf` at its default but `SWWAF_UPSTREAM_URL`,
+  which names gitea's container. Of the requests that three of the notes
+  specific to gitea in [`SPEC.md`](SPEC.md) say are refused, it sends through
+  it: for each file the note on a file name in a query parameter names, the
+  API's list of its commits; for `Runtime.java` alone, the commit graph of that
+  file, the hidden lines of its diff and the API's call for the contents of
+  files that names it; the sign-in page gitea sends a visitor to on the way to
+  the edit page of `document.write.js`; the pages of `java.lang.String.md`,
+  `META-INF/services/org.apache.commons.logging.LogFactory`, `process.env.d.ts`
+  and `.../notes.txt`; and one container image push that reuses a layer. It does
+  not send the raw file, history, blame or edit page of those four files, the
+  pages of the directories `META-INF/services` and `...`, or the push again. It
+  also sends a short sample of gitea's ordinary use: signing in, pages of files
+  and commits, a diff, the API, a push, clone and fetch over HTTP, and two
+  container image pushes. It prints a line for each request `smallwebwaf`
+  logged, with what it did with it and the ids of the Core Rule Set's rules that
+  matched it, then removes the containers, the network and the images it made,
+  but gitea's own image. It needs network access, and a docker daemon that
+  pushes to a registry on `localhost` over plain HTTP, as docker does by
+  default; `script/check` does not run it, and `make gitea-requests` does.
 
 ## TODO
 

docs/admin-endpoints.md

@@ -0,0 +1,35 @@
+# Admin endpoints
+
+`smallwebwaf` answers these requests itself, on the app's own address and
+through traefik like any other request. Apart from the health check, each needs
+a token, sent as `Authorization: Bearer <token>`, and goes through every check
+any other request goes through. It is answered where another request would be
+passed to the app: a banned client stays refused, and each request counts toward
+rate limiting. A missing or wrong token is answered `401`, in `observe` mode
+too. Such a refusal counts toward the error burst, so a client guessing tokens
+is soon banned. While a token is unset, its endpoints answer `404`.
+
+- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone, before any check and
+  without asking the app.
+- `GET /_smallwebwaf/metrics`: the metrics, for `SWWAF_METRICS_TOKEN` (see
+  [`metrics.md`](metrics.md)).
+- `GET /_smallwebwaf/bans`: every ban held, under `bans`, each as `bans.json`
+  lists it. Needs `SWWAF_ADMIN_TOKEN`, as do the three below.
+- `POST /_smallwebwaf/bans`: bans a netblock. The body is a JSON object of
+  `netblock`, `duration` and, if you like, `reason`. `netblock` is a netblock
+  such as `203.0.113.0/24`, or a client's address. A client's address bans its
+  IPv4 netblock (`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group. `duration` is a
+  duration such as `1h` or `7d`, or `permanent`. The ban starts at once, with
+  the cause `admin`. A bad body is answered `400`, saying what is wrong:
+    - one that is not such an object, or has another field;
+    - one longer than 4 KiB;
+    - one that names an IPv4-mapped netblock, or an address with a zone.
+- `DELETE /_smallwebwaf/bans/<client>`: lifts every active ban covering the
+  address `<client>`. It answers `404` when none is active.
+- `GET /_smallwebwaf/clients/<ip>`: what `smallwebwaf` knows of the client.
+  Under `client`, its counters and history as `clients.json` holds them, or
+  `null` when it has never been seen. Under `bans`, every ban covering the
+  address, with its notes.
+
+An admin whose own address is banned lifts that ban by editing `bans.json` (see
+[`bans.md`](bans.md)).

docs/alerts.md

@@ -0,0 +1,149 @@
+# Alerts
+
+Each alert goes to each destination you name. `SWWAF_ALERT_WEBHOOK_URL` gets it
+as one JSON object. `SWWAF_ALERT_SLACK_WEBHOOK_URL` and `SWWAF_ALERT_NTFY_URL`
+get a message made from it. The settings are under "Alert destinations" in
+[`settings.md`](settings.md). An alert is one of these events, and is sent when
+its event is in `SWWAF_ALERT_EVENTS`:
+
+- `ban`: a ban `smallwebwaf` made.
+- `permanent_ban`: a permanent ban it made, or an existing ban made permanent by
+  a request.
+- `waf_block`: the Core Rule Set scored a request at or over the threshold. In
+  `block` mode the request was refused. In `detect` mode it was not, and the
+  alert's `detail` gives `mode`.
+- `anomaly`: a count over an anomaly threshold.
+- `reputation_hit`: a request from a client on a blocklist, the CrowdSec
+  decision list or a DNS blocklist, or with an AbuseIPDB score that is a hit.
+  One alert per source.
+- `source_failure`: one of:
+    - GeoJS failing;
+    - a list that cannot be fetched;
+    - a DNS blocklist or AbuseIPDB failing or refusing a query;
+    - the day's AbuseIPDB checks used up.
+- `file_error`: one of:
+    - a rule file or state file edit with an error;
+    - a state file that cannot be written;
+    - a replacement lookup database that cannot be read.
+- `summary`: the hourly summary described under "Repeats and the hourly cap"
+  below.
+
+The bans you make 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`.
+
+## The JSON object
+
+This is the alert for a ban for a broken rate limit, shown indented; it is sent
+on one line:
+
+```json
+{
+    "instance": "fsn1app1/gitea",
+    "time": "2026-10-06T12:00:00.123461Z",
+    "event": "ban",
+    "client": "203.0.113.9",
+    "netblock": "203.0.113.9/32",
+    "asn": "",
+    "as_name": "",
+    "country": "",
+    "reason": "requests per minute over the limit of 1000",
+    "detail": {
+        "ban_expires": "2026-10-06T13:00:00.123Z",
+        "cause": "limit",
+        "notes": {
+            "asn": "",
+            "as_name": "",
+            "country": "",
+            "kind": "requests",
+            "limit": 1000,
+            "window": "minute",
+            "count": 1001,
+            "request": {
+                "time": "2026-10-06T12:00:00.123456789Z",
+                "method": "GET",
+                "host": "app.example",
+                "path": "/owner/repo/commits/branch/main?page=812",
+                "status": 403,
+                "user_agent": "scraper/1.0"
+            },
+            "requests": 5210,
+            "refused": 0,
+            "earlier_bans": {
+                "limit": 0,
+                "attack": 0,
+                "admin": 0,
+                "crowdsec": 0
+            }
+        }
+    },
+    "suppressed_repeats": 0
+}
+```
+
+- `instance` is `SWWAF_INSTANCE_NAME`. `time` is when the alert was raised.
+  `event` is one of the events above.
+- `client` is the address whose request raised the alert. `netblock` is the
+  ban's netblock, the netblock an anomaly counted, or the client's group. Both
+  are empty for `source_failure` and `file_error`. `asn`, `as_name` and
+  `country` are the client's as known when the alert was raised. They are empty
+  when GeoJS had not answered yet.
+- `reason` is a short sentence, such as
+  `requests per minute over the limit of 1000` or `listed by a blocklist`.
+- `detail` is what is particular to the event:
+    - for a ban, its `cause`, `ban_expires` and `notes` (see
+      [`bans.md`](bans.md) for the notes);
+    - for an anomaly, the `scope`, `window`, `kind`, `count` and `threshold`;
+    - for a reputation hit, the `source` and, for AbuseIPDB, the `score`;
+    - for a Core Rule Set match, the `rule_ids`, `score`, `method` and `path`;
+    - for a source failure, the `source` and `error`;
+    - for a file error, the `file` and `error`.
+- `suppressed_repeats` is how many repeats the cooldown held back before this
+  alert.
+
+## Slack and ntfy
+
+Slack and ntfy get a message with a title and a text. The title is the instance
+and the event, such as `fsn1app1/gitea: ban`. The text is the `reason`, then one
+line for each of these that the alert has:
+
+- the client, the netblock and the country;
+- the file, the source, the error and the mode from `detail`;
+- the suppressed repeats, if any.
+
+Slack gets the title in bold and the text below it, with `&`, `<` and `>`
+escaped. ntfy gets the text as the message, with these headers:
+
+- `Title`: the title;
+- `Authorization`: the token, as `Bearer <token>`, while
+  `SWWAF_ALERT_NTFY_TOKEN` is set;
+- `Priority` and `Tags`: by event, as listed below.
+
+The priority and tag by event:
+
+- `ban`: priority `default`, tag `no_entry`.
+- `permanent_ban`: priority `high`, tag `no_entry`.
+- `waf_block`: priority `default`, tag `shield`.
+- `anomaly`: priority `high`, tag `chart_with_upwards_trend`.
+- `reputation_hit`: priority `low`, tag `label`.
+- `source_failure` and `file_error`: priority `high`, tag `warning`.
+- `summary`: priority `default`, tag `bar_chart`.
+
+## Repeats and the hourly cap
+
+A repeat is an alert for the same event on the same netblock, source, file or
+thing counted, less than `SWWAF_ALERT_COOLDOWN` after the last. It is held back
+and counted, and the next alert sent gives the count. Past
+`SWWAF_ALERT_MAX_PER_HOUR` alerts in an hour, the rest are held back and counted
+by event. Once the hour ends, one alert with the event `summary` gives those
+counts. It also counts the repeats that a cooldown held back and that no later
+alert reported.
+
+## Sending
+
+Each destination has a queue of at most 1000 alerts, sent one at a time, so a
+slow destination holds up nothing. A `2xx` answer takes an alert. A `4xx` other
+than `408` and `429` refuses it, and it is dropped. Anything else is a failure:
+the alert is sent again a second later, and twice as long after each further
+failure, up to a minute. `alerts.json` keeps the queues and cooldowns across a
+restart (see [`state-files.md`](state-files.md)).

docs/bans.md

@@ -0,0 +1,84 @@
+# Bans
+
+How bans are made, what they cover and how long they last is under "Bans" in
+[`SPEC.md`](../SPEC.md); the settings are under "How long bans last and what
+they cover" in [`settings.md`](settings.md). This file says what a ban's notes
+hold, and how to make, keep or lift a ban.
+
+## The notes
+
+Each ban carries notes for deciding whether to lift it, drawn from what
+`smallwebwaf` already knows. Nothing is looked up to fill them:
+
+- the AS number, AS name and country, added when the lookup answers (empty when
+  lookups are off);
+- what was broken: the rule id and target that matched, or the trap path, or the
+  limit, its window and the count reached;
+- the client's percentage of the limit, with the setting that gave it;
+- the reputation sources the client is on;
+- the request that caused the ban: time, method, host, path with its query
+  string, status and user agent, each text cut to 256 bytes;
+- the netblock's requests since it was first seen, and how many this ban has
+  refused so far, kept up to date while the ban lasts;
+- how many earlier bans the netblock had, by cause.
+
+## Managing bans by editing `bans.json`
+
+`bans.json` in the state directory holds every ban, indented to be read. A
+permanent ban's `expires` is `null`. `smallwebwaf` watches the file and takes in
+an edit as soon as it is saved (see [`state-files.md`](state-files.md)).
+
+To ban a netblock, add an entry with its `netblock`, `start` and `expires`.
+`expires` is `null` for a ban that never ends. `reason`, `notes` and `cause` may
+be left out; the cause is then `admin`:
+
+```json
+{
+    "version": 1,
+    "bans": [
+        {
+            "netblock": "203.0.113.0/24",
+            "start": "2026-10-06T12:00:00Z",
+            "expires": null,
+            "reason": "probes for logins"
+        }
+    ]
+}
+```
+
+To keep a ban `smallwebwaf` made, so that it is never dropped, set its `cause`
+to `admin`. To lift a ban, add `"lifted"` with the time you lift it, such as
+`"lifted": "2026-10-06T13:00:00Z"`. The ban then refuses nothing and does not
+make the netblock's next ban longer. It is kept with its notes. To forget a ban,
+delete its entry. A ban whose cause is `attack` becomes permanent at the first
+request it refuses. One whose cause is `admin` or `crowdsec` does not.
+
+An edit that cannot be read does not stop the running `smallwebwaf`. It keeps
+what it holds. At the file's next write it renames your file to `bans.json.bad`,
+writes the file again from memory, and logs and alerts the error. Mend the
+`.bad` file and move it back.
+
+## Managing bans through the admin endpoints
+
+With `SWWAF_ADMIN_TOKEN` set, and the token in `$TOKEN`:
+
+```sh
+# Every ban.
+curl -H "Authorization: Bearer $TOKEN" https://app.example/_smallwebwaf/bans
+
+# Ban 203.0.113.0/24 for seven days.
+curl -H "Authorization: Bearer $TOKEN" \
+    --json '{"netblock": "203.0.113.0/24", "duration": "7d", "reason": "probes for logins"}' \
+    https://app.example/_smallwebwaf/bans
+
+# Lift the bans on 203.0.113.9.
+curl -H "Authorization: Bearer $TOKEN" -X DELETE \
+    https://app.example/_smallwebwaf/bans/203.0.113.9
+
+# What smallwebwaf knows of 203.0.113.9.
+curl -H "Authorization: Bearer $TOKEN" \
+    https://app.example/_smallwebwaf/clients/203.0.113.9
+```
+
+See [`admin-endpoints.md`](admin-endpoints.md) for what each answers. An admin
+whose own address is banned lifts that ban by editing `bans.json`.

docs/core-rule-set.md

@@ -0,0 +1,31 @@
+# The Core Rule Set
+
+The OWASP Core Rule Set 4.25.0 runs on each request after the rule files, unless
+`SWWAF_WAF_MODE` is `off`. It reads the method, the URL with its query, and the
+headers. Once `SWWAF_WAF_BODY_LIMIT` is set, it also reads a body that is form
+data, multipart, JSON or XML. No answer is inspected. The settings are under
+"Attack detection" in [`settings.md`](settings.md). The same section of
+[`SPEC.md`](../SPEC.md) says why bodies are not read by default, and gives the
+six changes `smallwebwaf` makes to the Core Rule Set, with the reason for each.
+
+Each rule that matches adds to the request's score. A score at or over
+`SWWAF_WAF_ANOMALY_THRESHOLD` is a match. A match is refused with `403` while
+`SWWAF_WAF_MODE` is `block`, and let through while it is `detect`. Either way
+the log line gives the rule ids and the score, and a `waf_block` alert is sent.
+A request with more than 1000 query parameters or body fields adds 5 to its
+score, since Coraza reads only the first 1000. The Core Rule Set inspects only a
+request that every earlier check let through. It skips a path under
+`SWWAF_WAF_EXEMPT_PATHS` and a client in `SWWAF_ALLOW_NETS`. An engine error on
+a request forwards the request, and is logged and counted.
+
+Body inspection suits apps whose forms carry no code. In front of a code forge
+it refuses issue and comment text, wiki pages and files saved in the web editor
+that hold shell commands or code. The log line names the rule ids, which
+`SWWAF_WAF_DISABLED_RULES` can switch off. A body the Core Rule Set cannot parse
+adds 5 to the score. So does a multipart body cut by the limit in the middle of
+a part's header. The client has until `SWWAF_CLIENT_REQUEST_TIMEOUT` runs out to
+send the part that is read. Any other body, such as a git push, reaches the app
+uninspected.
+
+[`gitea.md`](gitea.md) records what the Core Rule Set still refuses in front of
+gitea, with and without body inspection.

docs/gitea.md

@@ -0,0 +1,210 @@
+# smallwebwaf in front of gitea
+
+These notes record what `smallwebwaf` does in front of gitea at the default
+settings. They are observations, not requirements; the requirements are in
+[`SPEC.md`](../SPEC.md). `script/gitea-requests` runs gitea behind the image and
+sends through it a sample of gitea's ordinary use and the requests named below.
+It reports each request the Core Rule Set refuses, so that these notes can be
+checked again when gitea or the Core Rule Set changes version.
+
+## What the defaults cover
+
+- SSH access to gitea does not pass through `smallwebwaf` and is not protected
+  by it.
+- A clone is a response. It fits the defaults of 30 minutes and 5 GiB for all
+  but the largest repositories and slowest links.
+- A push is a request, and so is every other upload: a git push, an LFS object,
+  a container image layer, a package file or a release attachment. At the
+  defaults, an upload larger than 100 MiB or taking more than 60 seconds is cut
+  off. The client is answered `413` for a body that is too large, before
+  anything reaches gitea when the request announces its size. It is answered
+  `408` for a body it sends too slowly, or `504` if gitea is too slow to take
+  it. The upload fails, and no one is banned for it. A gitea that takes large
+  uploads needs `SWWAF_REQUEST_MAX_BYTES`, `SWWAF_CLIENT_REQUEST_TIMEOUT` and
+  `SWWAF_UPSTREAM_REQUEST_TIMEOUT` raised to fit. The Core Rule Set does not
+  read an upload's body, which streams through without being held in memory.
+- Archive download and blame or history pages are what scrapers hammer. The
+  request limits do most of the work there.
+- An Actions runner that reaches gitea through `smallwebwaf` sends requests all
+  day. One older than version 0.4 (April 2026) asks for work every 2 seconds,
+  43,200 requests a day, and reports a running job's log and state every second.
+  So it passes the day limit of 50,000 after about an hour and a quarter of
+  jobs. It is then banned, the job it is running fails, and each repeat within a
+  day makes the ban longer. Newer runners ask less often, but a busy one, or
+  several on one address, can still pass it. Put the runners' addresses in
+  `SWWAF_RATE_LIMIT_EXEMPT_NETS`. That takes them out of the request and byte
+  limits, while the error burst, attack detection and bans still apply.
+
+## What the Core Rule Set lets through
+
+At the defaults, the Core Rule Set lets gitea's ordinary use through, apart from
+the refusals in the next section:
+
+- browsing and views of files in a repository, with their history, blame and the
+  file tree;
+- diffs, including their hidden lines and large files, and pull request review;
+- git's clone, fetch and push over HTTP;
+- signing in, including the return to the page a visitor came from, and sign-in
+  with Git Credential Manager, git-credential-oauth or tea;
+- the API's calls for a file and its commits;
+- pushing and pulling container images and packages;
+- Actions runners, and artifacts uploaded with `actions/upload-artifact@v4`;
+- posting issues, pull requests, comments, wiki pages and files saved in the web
+  editor, code included, since no body is read;
+- the page gitea shows after a change, with its message naming what was done.
+
+## What the Core Rule Set still refuses
+
+Each refusal answers only that request, with `403`, and bans no one by itself.
+It counts toward the error burst, which a person does not reach this way. The
+request log names the rule in `waf_rule_ids`, which `SWWAF_WAF_DISABLED_RULES`
+can switch off.
+
+### A query string that reads as an attack
+
+Most often this is a search. Every query parameter is checked against the Core
+Rule Set's lists of system files and commands, except the ten named under
+"Attack detection" in `SPEC.md`. A release attachment uploaded through the API
+as `docker-compose.yml` is refused the same way. Examples:
+
+- a name on those lists, such as `package.json`, `.gitignore` or
+  `docker-compose.yml`;
+- text that starts with a command name, or whose first word has one right after
+  a `/`, such as `python3`, `ssh key` or `feat/docker-support`;
+- a shell command with its options or a system path (`ls -la`, `sed -i`,
+  `/bin/sh`), or a command in backticks;
+- script code (`fetch(`, `${VAR}`, `process.env`), HTML (`<img src=`) or an SQL
+  statement (`SELECT * FROM users WHERE`);
+- a URL naming an IP address or `localhost`.
+
+### A branch, tag or file name that starts with a command name
+
+The Core Rule Set's list of commands (932260) holds names such as `docker-`,
+`python3`, `ansible`, `base64` and `whoami`. A branch, tag or file name that
+starts with one is refused. So is one that has such a name right after a `/`,
+such as `feat/docker-support`, `fix/docker-build` or
+`renovate/docker-build-push-action-6.x`. gitea's own pages send the name in a
+query parameter that 930120, 932160 and 932260 still check:
+
+- `refSubUrl`, the branch or tag of a directory listing. It is sent when the
+  listing asks for its entries' last commits in a second request, which it does
+  whenever gitea takes more than a second to work them out;
+- `name`, when a branch is deleted or restored on the branches page;
+- `tag`, when a release is started from a tag;
+- `template`, the file of an issue template, when an issue is opened from it;
+- `rule_name`, when a branch protection rule is opened for editing in the
+  repository's settings or has just been saved.
+
+What a visitor sees, for a branch named `docker-build`:
+
+- A directory listing that makes that second request leaves those last commits
+  out and shows an error.
+- The branches page shows an error instead of deleting or restoring the branch.
+- A release started from such a tag gets the `403` answer of `smallwebwaf` in
+  place of its form. So does an issue opened from such a template, and such a
+  rule opened for editing.
+- Saving such a rule stores it. gitea then returns to the branch settings page,
+  which gets the `403` answer, so the save looks as if it failed.
+
+### A file name in a query parameter that trips the code rules
+
+The Core Rule Set's rules for Java, script, PowerShell and SQL find what they
+look for in some file names. This holds in the parameters `smallwebwaf` leaves
+out of 930120, 932160 and 932260 too (see the changes to the Core Rule Set under
+"Attack detection" in `SPEC.md`). Examples:
+
+- `runtime` in OpenJDK's `src/java.base/share/classes/java/lang/Runtime.java`
+  (944110);
+- a Java class, as in `java.lang.String.md` (944130);
+- `document.write.js` (941180);
+- `process.env.d.ts` (934100);
+- `__proto__` (934130);
+- the PowerShell command `Install-Script`, as in `install-script.sh` (932120);
+- a database's name, as in PostgreSQL's `information_schema.sql` (942140).
+
+For such a file, these requests are refused:
+
+- the API's list of its commits (`path`);
+- the API's call for the contents of files that names it in its query (`body`);
+- the commit graph of that file alone (`file`);
+- the hidden lines of its diff (`path`), which stay hidden;
+- the sign-in page gitea sends a visitor to on the way to a page of the file
+  that needs signing in, such as its edit page (`redirect_to`). The visitor can
+  still sign in by opening the sign-in page itself.
+
+### A path
+
+- A file name ending in `~`, or an `.xhtml` file whose path holds a space.
+- A path that holds what the Core Rule Set takes for a Java class (944130), as
+  `java.lang.String.md` and
+  `META-INF/services/org.apache.commons.logging.LogFactory` do.
+- A path that holds what it takes for Node.js code (934100), as
+  `process.env.d.ts` does.
+- A path with a directory named `...` (930100, 930110), such as `.../notes.txt`.
+
+For such a file, the page of the file, its raw file, its history, its blame and
+its edit page are refused. The directory that holds it lists it, and a clone
+carries it.
+
+### A container image push that reuses a layer
+
+A push can reuse a layer of an image docker has pushed to that gitea before.
+docker then asks gitea to take the layer from that image, naming it in the query
+parameter `from`, which 932260 checks. The request is refused when the image's
+owner, or its name after the owner, starts with an entry on the list of
+commands. Examples are `owner/python3-app`, `owner/docker-base`, and any image
+of an owner named `ansible` or `docker-team`.
+
+What happens next depends on docker's image store. A docker that keeps its
+images in containerd's image store fails the push, and fails each new try the
+same way. A new install of Docker Engine 29 does this. A docker that keeps them
+in its own older image store uploads the layer instead. The push then succeeds
+after one refusal for each layer it reuses, and each of those refusals counts
+toward the error burst.
+
+### Artifact uploads from `actions/upload-artifact@v3`
+
+This action sends the header `Content-Range`, which the Core Rule Set refuses
+(920450). The action sends two files at a time, does not retry a `403`, and
+sends no further file once one is refused. So an upload is refused once or
+twice, however many files it holds, and the step fails. One upload does not ban
+the runner. More than 30 such refusals from its address within a minute, as when
+many jobs upload at once, ban it through the error burst.
+`actions/upload-artifact@v4` does not send the header.
+
+## What body inspection refuses
+
+With `SWWAF_WAF_BODY_LIMIT` set, the Core Rule Set reads request bodies too. In
+front of gitea it then refuses these, until their rule ids, named in the request
+log, are added to `SWWAF_WAF_DISABLED_RULES`:
+
+- issue and comment text, wiki pages and files saved in the web editor that hold
+  shell commands or code (932125, 932235, 932250 and others);
+- package descriptions that show code;
+- PyPI uploads (922130);
+- attachments named like `debug.log` or `config.yml` (932180).
+
+## What `script/gitea-requests` sends
+
+Of the requests above, the script sends:
+
+- for each file named under "A file name in a query parameter that trips the
+  code rules", the API's list of its commits;
+- for `Runtime.java` alone, the commit graph of that file, the hidden lines of
+  its diff, and the API's call for the contents of files that names it;
+- the sign-in page gitea sends a visitor to on the way to the edit page of
+  `document.write.js`;
+- the pages of `java.lang.String.md`,
+  `META-INF/services/org.apache.commons.logging.LogFactory`, `process.env.d.ts`
+  and `.../notes.txt`;
+- one container image push that reuses a layer, which it does not try again.
+
+It does not send the raw file, history, blame or edit page of those four files,
+or the pages of the directories `META-INF/services` and `...`. It also sends a
+short sample of gitea's ordinary use:
+
+- signing in;
+- pages of files and commits, and a diff;
+- the API;
+- a push, and clone and fetch over HTTP;
+- two container image pushes.

docs/image.md

@@ -0,0 +1,56 @@
+# What the image holds
+
+The `smallwebwaf` image is the base of each app's own image. The requirements
+are under "Deployment" in [`SPEC.md`](../SPEC.md); this file lists what the
+image holds, how each part is pinned, and why.
+
+## Contents
+
+- Ubuntu 26.04 LTS, the newest long-term support release of Ubuntu, pinned by
+  digest. The image moves to the next LTS release when that ships.
+- `ca-certificates`, `nix-bin` and `runit` from Ubuntu, installed from a dated
+  snapshot of its archive and checked by hash. The Ubuntu image has no CA
+  certificates; without them Nix cannot download packages and `smallwebwaf`
+  cannot reach GeoJS.
+- Nix and nixpkgs, fixed at one release. Root uses Nix directly; no Nix daemon
+  runs. `nix-bin` creates no build users, so `build-users-group =` in
+  `/etc/nix/nix.conf` lets root build without them.
+- runit, and `runsvinit` as the entrypoint, as the owner's code style guide asks
+  for service containers. No package carries `runsvinit`, so the image builds it
+  from its archived source (`github.com/peterbourgon/runsvinit`, unchanged
+  since 2015) at a fixed commit hash, with a `go.mod` the build writes.
+  `runsvinit` starts runit's `runsvdir`, which runs the `run` script of each
+  directory under `/etc/service` and runs it again whenever it exits. Ubuntu's
+  `sv` looks for services there too.
+- The `smallwebwaf` binary, and a user of its own, `smallwebwaf` (uid and gid
+  65532).
+- The service directory `/etc/service/smallwebwaf`. Its `run` script waits one
+  second (`sleep 1`), makes `SWWAF_STATE_DIR` and every file in it belong to the
+  `smallwebwaf` user, and starts `smallwebwaf` as that user with runit's
+  `chpst`.
+- The directory `/var/lib/smallwebwaf` for the state files, and
+  `/etc/smallwebwaf/rules.d` with the default rule file.
+- Port 8080 declared (`EXPOSE 8080`), and the health check (`HEALTHCHECK`) that
+  "The health check" in `SPEC.md` describes.
+
+## Pinning
+
+- Ubuntu's packages come from Ubuntu's snapshot service, the archive as it was
+  at the moment the Dockerfile names (`--snapshot 20261001T000000Z`), never
+  earlier than the pinned Ubuntu image's date. The Dockerfile names the SHA-256
+  hash of each of the snapshot's `InRelease` files, which cover every package
+  list and so every package, and the build checks them before installing. The
+  hashes are the amd64 archive's, so the image is built for amd64 only. The
+  snapshot is fetched over HTTPS with the CA certificates of the Go image that
+  builds `smallwebwaf`, itself pinned by digest, since the Ubuntu image has
+  none.
+- nixpkgs comes from a release file on `releases.nixos.org` (`nixexprs.tar.xz`
+  of `nixos-26.05.11045.774debe7a0d1`), named with its SHA-256 hash, not from a
+  GitHub archive, whose bytes can change. It is set up for root as `nixpkgs`.
+  Root's Nix profile, `/nix/var/nix/profiles/default/bin`, is last on the
+  `PATH`, so that no package hides the image's own commands; busybox's `sv`, for
+  one, looks for services elsewhere. Unpacked, nixpkgs takes about 500 MiB.
+- An app built on the image gets the same packages each time it is built.
+  Security fixes from Ubuntu and nixpkgs come with a newer `smallwebwaf` image,
+  which an app takes by changing the digest in its `FROM` line. The image moves
+  to each new nixpkgs release, every six months.

docs/lookup.md

@@ -0,0 +1,79 @@
+# GeoJS and the lookup database
+
+`smallwebwaf` looks up each client's AS number and country, through GeoJS by
+default or in a database file on your own host. The settings are under "Looking
+up the AS number and country" in [`settings.md`](settings.md); the reasons for
+the defaults are under "Lookup of AS number and country" in
+[`SPEC.md`](../SPEC.md).
+
+## GeoJS
+
+By default `smallwebwaf` asks GeoJS, a free web service that needs no account,
+about every new visitor's address. It asks whether or not a setting uses the
+answer, since the log line, the history, the ban notes and the metrics carry the
+AS number and country. These addresses are never sent:
+
+- one in `SWWAF_ALLOW_NETS` or `SWWAF_DENY_NETS`;
+- one under a ban;
+- a private, loopback or link-local address, which no source can place.
+
+For an IPv6 visitor, GeoJS is asked about the first address of its group.
+Addresses are asked about together, up to 200 in one request
+(`https://get.geojs.io/v1/ip/geo.json?ip=a,b,c`), one request at a time. Each
+answer's `country_code`, `asn` and `organization_name` are read. An answer
+without a `country_code`, or with the `asn` `64512`, counts as unknown. Each
+answer is kept for seven days, in memory and in `lookups.json`, separately from
+the table of clients. Up to 100,000 answers are kept; past that, the answer used
+longest ago goes first.
+
+A request waits for its client's first answer only when a setting needs the
+answer before the request goes on. It waits up to `SWWAF_LOOKUP_TIMEOUT`. The
+settings that make it wait:
+
+- a country list;
+- `SWWAF_ADD_LOOKUP_HEADERS`;
+- any setting under "Lower limits by AS number and country" in
+  [`settings.md`](settings.md).
+
+Otherwise the request goes on at once, logged without the answer. The answer
+reaches the client's history and ban notes when it comes. A client whose answer
+has not come in time counts as from an unknown country until it comes, and its
+later requests do not wait. While GeoJS fails, new visitors count as from an
+unknown country, which `SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` refuses. GeoJS is
+then left alone for a second, and twice as long after each further failure, up
+to five minutes, and one `source_failure` alert is sent per cooldown.
+
+## The database file
+
+To keep your visitors' addresses on your own host, set
+`SWWAF_LOOKUP_SOURCE=off`, or set it to `file`. `file` looks every client up in
+the free IPinfo Lite database (`ipinfo_lite.mmdb`) at `SWWAF_LOOKUP_DB_PATH`,
+reading its `asn`, `as_name` and `country_code` fields. You download the
+database with an IPinfo account and mount it into the container; `smallwebwaf`
+never fetches it and holds no account or token for it. It answers at once, with
+nothing sent off the host. A client whose address it does not hold counts as
+from an unknown country.
+
+`smallwebwaf` reads the whole file at start. It reads the file again once it has
+gone 2 seconds without a change after you replace it. A replacement it cannot
+read is logged and alerted, and the file read before stays in use. Mount the
+directory that holds the file, not the file itself. Many editors and download
+tools save a file by replacing it, and a container keeps seeing the old file
+when only the file is mounted.
+
+IPinfo updates the database daily, and releases it under the Creative Commons
+Attribution-ShareAlike 4.0 licence. It asks for a link to IPinfo on the site
+that uses it, such as "IP address data is powered by IPinfo".
+
+## A client without a country
+
+A client the lookup cannot place has an unknown country and AS number. That is
+one of:
+
+- a client on a private address;
+- one GeoJS or the database does not know;
+- one whose GeoJS answer has not come in time.
+
+`SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` refuses such a client, and the lower
+limits give it `SWWAF_UNKNOWN_LIMIT_PERCENT`. Nothing else treats it
+differently.

docs/metrics.md

@@ -0,0 +1,83 @@
+# The metrics
+
+`GET /_smallwebwaf/metrics` answers in the Prometheus text format. The
+requirements are under "Metrics endpoint" in [`SPEC.md`](../SPEC.md); this file
+lists the metrics. Every metric carries the label `instance`, set to
+`SWWAF_INSTANCE_NAME`; Prometheus keeps it as `exported_instance` unless the
+scrape sets `honor_labels: true`. No metric carries a client's address.
+
+## Traffic
+
+- `smallwebwaf_requests_total`, `smallwebwaf_request_bytes_total` and
+  `smallwebwaf_response_bytes_total`, by `status_class` such as `2xx` and by
+  `action`;
+- `smallwebwaf_request_duration_seconds` and
+  `smallwebwaf_upstream_duration_seconds`, as histograms;
+- `smallwebwaf_requests_in_flight`.
+
+## Limits and bans
+
+- `smallwebwaf_rate_limit_hits_total`, by `window` and by `kind` (`requests`,
+  `bytes` or `refusals`);
+- `smallwebwaf_size_and_time_limit_hits_total`, by `limit`, the setting passed;
+- `smallwebwaf_offences_total`, by `kind`;
+- `smallwebwaf_bans_made_total`, by `cause`;
+- `smallwebwaf_active_bans` and `smallwebwaf_permanent_bans`.
+
+## Attack detection
+
+- `smallwebwaf_rule_matches_total`, by `rule_id` and `action`, and
+  `smallwebwaf_rules_loaded`;
+- `smallwebwaf_waf_matches_total`, by `mode` and `rule_id`, for the rules that
+  fired.
+
+## Countries and AS numbers
+
+For the `SWWAF_METRICS_TOP_N` busiest of each, the rest as `other`:
+
+- `smallwebwaf_country_requests_total`,
+  `smallwebwaf_country_request_bytes_total`,
+  `smallwebwaf_country_response_bytes_total` and
+  `smallwebwaf_country_list_refusals_total`, by `country`;
+- `smallwebwaf_asn_requests_total`, `smallwebwaf_asn_request_bytes_total` and
+  `smallwebwaf_asn_response_bytes_total`, by `asn`.
+
+## Lookups
+
+- `smallwebwaf_geojs_requests_total` and `smallwebwaf_geojs_failures_total`;
+- `smallwebwaf_geojs_unanswered_total`: the requests that needed an answer and
+  went on without it;
+- with the file source,
+  `smallwebwaf_lookup_database_last_read_timestamp_seconds` and
+  `smallwebwaf_lookup_database_read_failures_total`.
+
+## Reputation sources
+
+By `source`: each list's URL, each zone, and `abuseipdb`:
+
+- `smallwebwaf_reputation_hits_total`, `smallwebwaf_reputation_queries_total`
+  and `smallwebwaf_reputation_failures_total`;
+- `smallwebwaf_reputation_last_fetch_timestamp_seconds`, for a list;
+- `smallwebwaf_reputation_daily_budget_remaining`, for AbuseIPDB.
+
+## State files
+
+By `file`:
+
+- `smallwebwaf_state_file_writes_total`,
+  `smallwebwaf_state_file_write_failures_total`,
+  `smallwebwaf_state_file_last_write_timestamp_seconds` and
+  `smallwebwaf_state_file_size_bytes`;
+- `smallwebwaf_state_file_edits_taken_in_total` and
+  `smallwebwaf_state_file_edits_set_aside_total`;
+- `smallwebwaf_tracked_clients`: the clients in the table.
+
+## Remote log, alerts and the process
+
+- while a syslog server is set, `smallwebwaf_remote_log_lines_sent_total`,
+  `smallwebwaf_remote_log_lines_dropped_total` and
+  `smallwebwaf_remote_log_buffer_depth`;
+- by `destination`, `smallwebwaf_alerts_sent_total`,
+  `smallwebwaf_alerts_failed_total`, `smallwebwaf_alerts_suppressed_total` and
+  `smallwebwaf_alerts_dropped_total`;
+- Go's own `go_` metrics and the process's `process_` metrics.

docs/reputation.md

@@ -0,0 +1,113 @@
+# Reputation sources
+
+A reputation source judges a client by what others saw it do. None is on by
+default. The settings are under "Reputation sources" in
+[`settings.md`](settings.md); the reasons for the defaults are under
+"Reputation" in [`SPEC.md`](../SPEC.md). The sources are checked in this order,
+and a source the client is on refuses it, lowers its limits, or only notes it,
+as `SWWAF_BLOCKLIST_ACTION` and `SWWAF_REPUTATION_ACTION` say.
+
+## Blocklists
+
+`SWWAF_BLOCKLIST_URLS` lists text files of addresses and netblocks, one to a
+line, as the Spamhaus DROP list is written. Anything after a `;` or `#` is left
+out. An IPv4-mapped address such as `::ffff:192.0.2.0/120` is read as the IPv4
+netblock it stands for.
+
+Each list is fetched again `SWWAF_BLOCKLIST_REFRESH` after its last try, one
+list at a time. The file of `SWWAF_ASN_LIMIT_PERCENT_URL` is too.
+`reputation.json` keeps when each was last tried, so a restart does not fetch a
+list again before its time. A fetch fails when:
+
+- the server answers other than `200`;
+- the fetch does not finish within a minute;
+- the list is longer than 16 MiB;
+- a line is not an address or netblock, or, for the AS number file, not
+  `AS<number>:<percent>`.
+
+The copy fetched before stays in use, comment lines included. The failure is
+logged and raised as a `source_failure` alert. The log, the alerts, the ban
+notes and the metrics name each list by its URL, so keep a secret out of it.
+
+The Spamhaus DROP list is The Spamhaus Project's. Its terms, and what they mean
+for `SWWAF_BLOCKLIST_REFRESH` and for several instances on one host, are under
+"Reputation" in [`SPEC.md`](../SPEC.md). The copy in `reputation.json` keeps the
+list's date and copyright lines.
+
+## CrowdSec
+
+While `SWWAF_CROWDSEC_LAPI_URL` is set to the local API of a CrowdSec engine you
+run, `smallwebwaf` fetches its decision list every minute. It sends
+`SWWAF_CROWDSEC_LAPI_KEY` in the `X-Api-Key` header. The list is kept as a
+blocklist is kept. The decisions of the type `ban` on an address or a netblock
+are used. Any other, such as a captcha or a country, is left out. A decision
+lasts for the `duration` it had left when the engine answered.
+
+A request is refused when a decision still in force names its client. The
+client's netblock is banned until the decision ends, with the cause `crowdsec`.
+Only a client that sends a request is banned, so a long list does not fill
+`bans.json`. Such a ban is never made permanent, and does not lengthen the
+netblock's next ban for a broken limit. If you lift a ban while the decision is
+in force, the client's next request makes another. Delete the decision in
+CrowdSec first, such as with `cscli decisions delete --ip 203.0.113.9`, and lift
+the ban once the list has been fetched again. A fetch fails when:
+
+- the engine answers other than `200`, a redirect included;
+- the fetch does not finish within a minute;
+- the answer is longer than 16 MiB;
+- the answer is not a list of decisions.
+
+## DNS blocklists
+
+Each zone in `SWWAF_DNSBL_ZONES` is asked about a client's own address in the
+background, the first time the client is seen. The request goes on at once, and
+so does every request from the client until the zone has answered. The name
+asked about is the one RFC 5782 gives: the numbers of an IPv4 address reversed,
+or the 32 hex digits of an IPv6 address reversed. `192.0.2.99` is asked about as
+`99.2.0.192.dnsbl.dronebl.org`. An answer in `127.0.0.0/8` lists the client, but
+one in `127.255.255.0/24` is Spamhaus refusing the query. A name that does not
+exist does not list the client. These are failures:
+
+- an answer in `127.255.255.0/24`;
+- an answer outside `127.0.0.0/8`;
+- a resolver error;
+- no answer within `SWWAF_REPUTATION_TIMEOUT`.
+
+A failure is logged and alerted, and the zone is not asked again for a minute.
+Each verdict is kept for `SWWAF_REPUTATION_CACHE_TTL`, in memory and in
+`reputation.json`. Up to 100,000 verdicts are kept; past that, the one fetched
+longest ago goes first. At most 1,000 queries are under way at once.
+
+The key of a Spamhaus zone under `dq.spamhaus.net` is its first label.
+`smallwebwaf` shows `********` in its place wherever it names the zone. Only
+`reputation.json` keeps the zone with its key.
+
+## AbuseIPDB
+
+While `SWWAF_ABUSEIPDB_KEY` is set, `smallwebwaf` asks AbuseIPDB's check
+endpoint for the abuse confidence score of a client, from 0 to 100. Only a
+client that has committed an offence is checked. An offence is one of:
+
+- a broken limit;
+- a `ban` rule match or a trap path;
+- a refusal by a `block` rule, the Core Rule Set or a token check.
+
+The check runs in the background, at the client's first request after the
+offence that no ban refuses, so no request waits. The score applies to the
+client's later requests. For an IPv6 client, AbuseIPDB is asked about the
+address of the request that set off the check, and the score is used for the
+whole group. A score at or over `SWWAF_ABUSEIPDB_MIN_SCORE` is a hit, and
+`SWWAF_REPUTATION_ACTION` says what is done. Each score is kept for
+`SWWAF_REPUTATION_CACHE_TTL`, up to 100,000 scores.
+
+At most `SWWAF_ABUSEIPDB_DAILY_BUDGET` checks are made in a day, counted in UTC
+and kept in `reputation.json`. A restart does not make the budget whole again.
+The check that spends the last of the budget is logged and alerted. No client is
+checked until the day ends. A check fails when:
+
+- AbuseIPDB answers other than `200`;
+- the answer gives no score;
+- no answer comes within `SWWAF_REPUTATION_TIMEOUT`.
+
+A failure is logged and alerted, and no client is checked for a minute. The key
+is sent in the `Key` header and nowhere else, and is never logged.

docs/request-log.md

@@ -0,0 +1,128 @@
+# The request log's fields
+
+`smallwebwaf` writes one JSON object per line on stdout for every request. The
+requirements are under "Request log" in [`SPEC.md`](../SPEC.md); this file lists
+the fields. A field that does not apply to a request is left out.
+
+## Example
+
+```
+{"type":"request","time":"2026-10-03T12:00:00.123Z","instance":"fsn1app1/gitea","client_ip":"203.0.113.9","method":"GET","scheme":"https","host":"app.example","path":"/","query":"","protocol":"HTTP/1.1","status":200,"request_bytes":0,"response_bytes":5120,"referer":"","user_agent":"curl/8.9.1","request_id":"7Q2NHZ4KJ3VXW5YB6R3MEFTD2A","peer_ip":"172.18.0.2","forwarded_for":"203.0.113.9","client_group":"203.0.113.9/32","asn":"AS64496","as_name":"Example Net","country":"DE","request_headers":{"accept":"*/*"},"response_content_type":"text/html; charset=utf-8","upstream_status":200,"action":"forward","counts":{"minute":1,"hour":12,"day":40,"minute_bytes":5120,"hour_bytes":61440,"day_bytes":204800},"duration_total":3.217,"duration_checks":0.041,"duration_upstream_connect":0.052,"duration_upstream_first_byte":2.874,"duration_upstream_total":3.104}
+```
+
+## Standard web log fields
+
+- `time`: when the request arrived, RFC 3339 with milliseconds, in UTC;
+- `instance`: `SWWAF_INSTANCE_NAME`;
+- `client_ip`, `method`, `scheme`, `host`, `path`, `query`, `protocol`;
+- `status`: what the client was sent, `0` if nothing;
+- `request_bytes` and `response_bytes`: body bytes each way;
+- `referer` and `user_agent`.
+
+## Request detail
+
+- `request_id`: the `X-Request-ID` a trusted proxy sent, or a new random one of
+  26 letters and digits. It goes to the app in `X-Request-ID`.
+- `peer_ip`: the TCP peer, normally traefik.
+- `forwarded_for`: the `X-Forwarded-For` header as received.
+- `client_group`: the client as rate limiting counts it, an IPv4 address as a
+  /32 or an IPv6 group.
+- `asn`, `as_name` and `country`: the client's, as looked up. Each is empty
+  when:
+    - lookups are off;
+    - the client is not looked up;
+    - the source cannot place the client;
+    - GeoJS had not answered by the time the request went on.
+- `content_type` and `content_length`: the request's own.
+- `request_headers`: the headers listed in `SWWAF_LOG_REQUEST_HEADERS`, by name
+  in lower case.
+- `has_authorization` and `has_cookie`: true when the request had those headers.
+  Their values are never logged.
+- `websocket`: true when the app switched the connection to another protocol.
+
+## Response detail
+
+- `upstream_status`: what the app answered. It differs from `status` when
+  `smallwebwaf` answered itself.
+- `response_content_type`, `cache_control` and `location`: the answer's headers.
+- `aborted`: true when the client went away early.
+
+## Decision
+
+- `action`: what was done:
+    - `forward`: passed to the app;
+    - `denied`: refused for `SWWAF_DENY_NETS`, or for a reputation source with
+      the action `deny`;
+    - `banned`: refused under a ban, or for a `ban` rule, a trap path or a
+      CrowdSec decision, each of which bans the client;
+    - `country_denied`, `rate_limited`, `rule_blocked` and `waf_blocked`:
+      refused by that check;
+    - `too_large` and `timed_out`: a size or time limit was passed;
+    - `upstream_error`: the app could not be reached, or its answer broke off;
+    - `admin`: answered at one of `smallwebwaf`'s own endpoints.
+- `would_action`: in `observe` mode, what `enforce` mode would have done with a
+  request it would have refused. `action` then names what was done, normally
+  `forward`.
+- `limit_percent` and `limit_percent_setting`: the client's percentage of the
+  rate limits and the setting that lowered it, when one did. `bytes_percent` and
+  `bytes_percent_setting` do the same for the byte limits.
+- `counts`: the client's requests in the minute, hour and day as rate limiting
+  counts them, this request included, as `minute`, `hour` and `day`; its bytes
+  as `minute_bytes`, `hour_bytes` and `day_bytes`. A count can have a fraction,
+  since each window is counted in two buckets with the earlier one weighted.
+  `counts` is left out when rate limiting did not count the request.
+- `limit_hit`: the limit broken: `minute`, `hour` or `day` for a rate limit;
+  `minute_bytes`, `hour_bytes` or `day_bytes` for a byte limit; or
+  `error_burst`. A request whose bytes broke a limit was passed on whole, so its
+  `action` stays `forward`.
+- `rule_ids`: the rule file rules that matched, in order, up to the one that
+  refused.
+- `waf_score` and `waf_rule_ids`: the Core Rule Set's score and the rules that
+  matched, for a request it inspected.
+- `reputation`: the sources the client is on, in this order:
+    - blocklist URLs;
+    - the CrowdSec decision list's URL;
+    - DNS blocklist zones;
+    - `abuseipdb`.
+- `offence`: the kind of offence recorded, when one was.
+- `ban_expires`: when the client's ban ends, for a request that made one or was
+  refused under one: a time, or `permanent`.
+
+## Timings
+
+All in milliseconds:
+
+- `duration_total`: from the request's headers being read to its log line;
+- `duration_checks`: to the end of the checks, before forwarding;
+- `duration_waf`: the part of that the Core Rule Set took;
+- `duration_upstream_connect`: from the hand-over to the app until there was a
+  connection;
+- `duration_upstream_first_byte`: until the first byte of the answer;
+- `duration_upstream_total`: until the end of the answer.
+
+## Every line
+
+Every line has `type`, the standard web log fields, `request_id`, `peer_ip`,
+`client_group`, `asn`, `as_name`, `country`, `action` and `duration_total`. The
+process's own messages share the stream with `"type":"process"`; request lines
+carry `"type":"request"`.
+
+## Sending the log to a syslog server
+
+While `SWWAF_LOG_REMOTE_URL` is set, every line on stdout is also sent to that
+server, as the message of an RFC 5424 syslog record. Over UDP each record is one
+datagram. Over TCP and TLS each record follows its length in bytes and a space.
+stdout is unchanged. The record carries:
+
+- the facility from `SWWAF_LOG_REMOTE_FACILITY`;
+- the severity informational;
+- the time;
+- the host's name;
+- the app name from `SWWAF_LOG_REMOTE_APP_NAME`.
+
+Lines wait in a buffer of `SWWAF_LOG_REMOTE_BUFFER` lines, so a server that is
+slow or down never holds up a request. When the buffer is full, the oldest line
+is dropped. A failed connection is tried again a second later, and twice as long
+after each further failure, up to a minute. A line too long for one UDP datagram
+is dropped alone. As `smallwebwaf` stops, it spends at most two seconds sending
+the lines still waiting, and drops the rest. stdout has carried them.

docs/rules.md

@@ -0,0 +1,114 @@
+# Rule files
+
+`smallwebwaf` reads every `*.rules` file in `SWWAF_RULES_DIR`, in the order of
+their names, and checks each request against their rules in that order, unless
+the client is in `SWWAF_ALLOW_NETS`. The requirements the files meet are under
+"Rule files" in [`SPEC.md`](../SPEC.md). A file whose name starts with `.`, such
+as an editor's lock file, is not a rule file.
+
+## The format
+
+A rule is a line of four fields separated by spaces or tabs: an id, a target, an
+action and a regex. The regex runs to the end of the line. Blank lines and lines
+starting with `#` are ignored.
+
+```
+# id           target      action  regex
+env-file       path        ban     (?i)^/\.env(\.[a-z]+)?$
+scanner-agent  user_agent  ban     (?i)\b(sqlmap|nikto|nuclei|wpscan)\b
+```
+
+- The id is letters, digits, `-` and `_`. No two rules share one. The log line,
+  the metrics, the alerts and a ban's notes name the rule by it.
+- The target is what the regex is matched against:
+    - `path`: the path without the query;
+    - `uri`: the path and the query together;
+    - `query`: the query as sent;
+    - `method`, `host`, `user_agent` and `referer`;
+    - `header:<Name>`: any one request header but `Host` and
+      `Transfer-Encoding`, which Go's HTTP server takes out of every request.
+
+    `path` and `uri` are matched both as sent and once percent-decoded, so that
+    an encoded probe does not slip past. A header sent more than once is matched
+    with its values joined by `, `. A header not sent is empty text. No body is
+    read; reading bodies is the Core Rule Set's job, once `SWWAF_WAF_BODY_LIMIT`
+    switches it on.
+
+- The action is `log`, `block` or `ban`. `log` only notes the match in the log
+  line. `block` refuses the request with `403` and bans no one; the refusal
+  counts toward the error burst. `ban` refuses it and bans the client, as a
+  clear sign of attack. Matching stops at the first rule that refuses. Keep
+  `ban` for requests no real visitor sends. Anchor a path at the site root with
+  `^/`: a file of the same name deeper in a site can be ordinary content.
+- The regex is in Go's syntax, RE2. It has no backreferences or lookaround, and
+  takes time linear in the text it reads, so no rule can be made to stall the
+  proxy. It matches anywhere in the target unless anchored with `^` and `$`.
+  `(?i)` at its front makes it ignore case.
+
+## Errors
+
+These stop the start, with a message naming the file and line:
+
+- a line that is not a rule;
+- a bad `header:` name, or a rule for `Host` or `Transfer-Encoding`;
+- a regex that does not compile;
+- an id used twice.
+
+So does a `SWWAF_RULES_DIR` that does not exist. An empty directory is not an
+error: the log says that no rules were loaded.
+
+While it runs, `smallwebwaf` watches the directory. It reads the files again
+once the directory has had no change for 2 seconds, so that a file still being
+written is read whole. If the files then hold such an error, the rules stay as
+they were. The log and a `file_error` alert name the file and line. Once the
+file is fixed, it is read again.
+
+## The default file
+
+The image ships one file, `share/rules.d/00-default.rules`, installed as
+`/etc/smallwebwaf/rules.d/00-default.rules`:
+
+```
+# 00-default.rules: probes no real visitor sends, anchored at the site root
+
+# id             target      action  regex
+env-file         path        ban     (?i)^/\.env(\.[a-z]+)?$
+vcs-dir          path        ban     (?i)^/\.(git|svn|hg|bzr)(/|$)
+secrets-dir      path        ban     (?i)^/\.(aws|ssh|docker|kube)/
+secret-file      path        ban     (?i)^/\.(htpasswd|htaccess|npmrc|netrc|pgpass|git-credentials|bash_history|DS_Store)$
+editor-dir       path        ban     (?i)^/\.(vscode|idea)/
+backup-file      path        ban     (?i)^/[^/]+\.(php(\.[a-z0-9]+|~)|sql(\.[a-z0-9]+)?)$
+log-file         path        ban     (?i)^/(debug|error|access)\.log$
+compose-file     path        ban     (?i)^/(docker-)?compose\.ya?ml$
+php-shell        path        ban     (?i)^/(shell|c99|r57|wso|alfa)\.php$
+scanner-agent    user_agent  ban     (?i)\b(sqlmap|nikto|nuclei|masscan|zgrab|wpscan)\b
+path-traversal   uri         block   (\.\./){2,}
+empty-agent      user_agent  log     ^$
+```
+
+It is kept short and limited to patterns that are wrong for every app, with its
+path rules anchored at the site root. In front of gitea, `/.env` is a probe,
+while `/<owner>/<repo>/src/branch/main/.env.example` is a file in a repository
+that any visitor may open. Anything app-specific belongs in a file the app's
+`Dockerfile` adds or the deployer mounts. A request for `/wp-login.php`, for
+example, is a clear sign of attack in front of gitea and an ordinary login in
+front of WordPress. Such a rule goes in a file named to sort after the default:
+
+```
+# 50-gitea.rules: WordPress probes, which gitea never serves
+wp-probe         path        ban     (?i)^/(wp-login\.php|xmlrpc\.php|wp-admin/)
+```
+
+```dockerfile
+COPY 50-gitea.rules /etc/smallwebwaf/rules.d/50-gitea.rules
+```
+
+## Mounting rule files
+
+A directory mounted over `/etc/smallwebwaf/rules.d` replaces the default file;
+single files mounted into it add to it. Many editors save a file by replacing
+it, and a container keeps seeing the old one when the file alone is mounted. So
+rules to be edited while `smallwebwaf` runs belong in a mounted directory, with
+a copy of the default file if the defaults are to stay. The lookup database is
+mounted the same way, for the same reason. To run without rules, mount an empty
+directory or set `SWWAF_RULES_ENABLED=false`.

docs/settings.md

@@ -0,0 +1,483 @@
+# Settings
+
+Every setting is an environment variable whose name starts with `SWWAF_`. Every
+setting has a default, so none has to be set. Settings are read once, at start.
+To change one, restart the container.
+
+A setting that is set to a value it cannot take stops the start. The process
+writes one line, `"type":"process"` with `"msg":"invalid setting"`, naming the
+variable and what is wrong with the value. It exits with status 1, and runit
+starts it again every second until the value is fixed. The entries below say
+which values each setting takes. Any other value stops the start. At start, the
+settings in effect are logged on one line. Tokens, keys and the paths of
+webhooks are shown as `********`.
+
+The forms of values:
+
+- A duration is Go's syntax, with `d` for days: `90s`, `15m`, `24h`, `7d`. Zero
+  and negative durations are refused.
+- A size is a number of bytes with an optional `K`, `M` or `G`, which are powers
+  of 1024: `1K` is 1024 bytes, `512K`, `100M`, `5G`.
+- A count is a whole number of requests, such as `1000`.
+- `off` switches a setting off, where its entry below says it takes `off`.
+- A list is comma separated, with spaces around items ignored. An empty item is
+  refused. A list set but empty is an empty list, and replaces the default.
+- A netblock is an address and a prefix length, such as `10.0.0.0/8`. A bare
+  address stands for itself alone.
+- A country is a two-letter code of ISO 3166-1, in either case: `de` and `DE`
+  are the same. `xk` stands for Kosovo. A code that is not a country is refused,
+  such as `nk` (North Korea is `kp`) or the withdrawn `su`.
+- An AS number is `AS` and the number, in either case, such as `AS64496`.
+- A percentage is a whole number from 0 to 100.
+- A path prefix starts with `/`, such as `/assets/`.
+
+## Where it listens and what it protects
+
+- `SWWAF_LISTEN_ADDR` (default `:8080`): where `smallwebwaf` listens, an
+  optional host and a port. Keep the host empty: `:9000`, never
+  `127.0.0.1:9000`. The app must not listen on that port. The health check
+  follows the setting, and traefik's label must name the port.
+- `SWWAF_UPSTREAM_URL` (default `http://127.0.0.1:8081`): the app. An `http` or
+  `https` URL with a host and an optional port, and nothing more: no path, user
+  or query.
+- `SWWAF_INSTANCE_NAME` (default: the container's host name, the first 12
+  characters of the container's id): the `instance` name in every log line,
+  alert and metric. Set it to a name that survives deploys and tells instances
+  apart, such as `fsn1app1/gitea`. It must be valid UTF-8. While
+  `SWWAF_ALERT_NTFY_URL` is set, it may hold no control character. While
+  `SWWAF_LOG_REMOTE_URL` is set and `SWWAF_LOG_REMOTE_APP_NAME` is not, it must
+  be 1 to 48 printable ASCII characters without a space.
+- `SWWAF_MODE` (default `enforce`): `enforce`, or `observe` to ban no one and
+  log what `enforce` would have done. Observe mode still refuses a request over
+  a size or time limit, and one without the right token.
+- `SWWAF_TRUSTED_PROXIES` (default `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`,
+  the private address ranges): the netblocks whose `X-Forwarded-For` is
+  believed, normally where traefik comes from. Set but empty, it trusts nothing:
+  every TCP peer is then the client.
+- `SWWAF_IPV6_GROUP_PREFIX` (default `64`): the length of the netblock that is
+  one IPv6 client, from 32 to 128. After a change, each IPv6 client starts
+  afresh. Existing bans keep refusing their netblocks until they end.
+- `SWWAF_MAX_TRACKED_CLIENTS` (default `20000`): the most clients kept in memory
+  and in `clients.json`, a whole number above zero. Past it, the least recently
+  seen client is dropped first.
+
+## Time and size limits
+
+Each request has limits on both sides: between the client and `smallwebwaf`, and
+between `smallwebwaf` and the app. Bodies stream through in both directions,
+except the part the Core Rule Set reads while `SWWAF_WAF_BODY_LIMIT` is set.
+
+- `SWWAF_CLIENT_REQUEST_TIMEOUT` (default `60s`): how long a client may take to
+  send its request line and headers, and then, from the end of the headers, its
+  body. A duration or `off`.
+- `SWWAF_CLIENT_REQUEST_HEADER_MAX_BYTES` (default `32K`): the largest request
+  line and headers. A size over `4K`. It cannot be `off`: Go's HTTP server
+  always has such a limit.
+- `SWWAF_CLIENT_IDLE_TIMEOUT` (default `120s`): how long a kept-open connection
+  may wait for its next request before it is closed. A duration or `off`. The
+  default is longer than the 90 seconds after which traefik closes an unused
+  connection, so traefik closes first.
+- `SWWAF_CLIENT_RESPONSE_TIMEOUT` (default `30m`): how long the answer may take
+  to reach the client, from the end of the request to the last byte. A duration
+  or `off`.
+- `SWWAF_UPSTREAM_REQUEST_TIMEOUT` (default `60s`): how long connecting to the
+  app and sending it the whole request may take. A duration or `off`.
+- `SWWAF_UPSTREAM_RESPONSE_TIMEOUT` (default `30m`): how long the app may take
+  to send its whole answer. A duration or `off`.
+- `SWWAF_REQUEST_MAX_BYTES` (default `100M`): the largest request body. A size
+  or `off`. A request that announces a larger body is refused before anything
+  reaches the app.
+- `SWWAF_RESPONSE_MAX_BYTES` (default `5G`): the largest response body. A size
+  or `off`.
+
+In front of a code forge, a clone is a response and a push is a request. At the
+defaults, an upload over 100 MiB or slower than 60 seconds is cut off. A forge
+that takes large uploads needs `SWWAF_REQUEST_MAX_BYTES`,
+`SWWAF_CLIENT_REQUEST_TIMEOUT` and `SWWAF_UPSTREAM_REQUEST_TIMEOUT` raised to
+fit.
+
+What the client gets when a limit is passed is under "Size and time limits" in
+[`SPEC.md`](../SPEC.md).
+
+## Netblock lists
+
+- `SWWAF_ALLOW_NETS` (default empty): netblocks whose clients skip every check,
+  such as your monitoring or your own network. The size and time limits still
+  apply to them. They are not looked up. They still need a token for the admin
+  endpoints.
+- `SWWAF_RATE_LIMIT_EXEMPT_NETS` (default empty): netblocks whose clients are
+  exempt from rate limiting and the byte limits, such as a machine that talks to
+  the app all day. Everything else still applies to them.
+- `SWWAF_DENY_NETS` (default empty): netblocks whose clients are always refused.
+  A client in both lists is let through.
+
+## Rate limiting and byte limits
+
+- `SWWAF_RATE_LIMIT_PER_MINUTE` (default `1000`), `SWWAF_RATE_LIMIT_PER_HOUR`
+  (default `10000`) and `SWWAF_RATE_LIMIT_PER_DAY` (default `50000`): the most
+  requests a client may make in each window. A count or `off`. The defaults are
+  several times what one busy person produces. A browser loading a heavy page
+  makes a few hundred requests, and several people often share one address.
+- `SWWAF_RATE_LIMIT_EXEMPT_PATHS` (default empty): path prefixes exempt from
+  rate limiting, such as `/assets/`. Their bytes are not counted either. The
+  path is matched exactly as sent, without the query, and is not
+  percent-decoded. `/assets/` matches `/assets/app.js`. It does not match
+  `/Assets/app.js`, `/%61ssets/app.js` or `/static/assets/app.js`. There are no
+  wildcards. A path holding `..`, a backslash or an encoded slash (`%2F`) is
+  never exempt, since the app may read it as a path outside the prefix.
+- `SWWAF_BYTES_LIMIT_PER_MINUTE` (default `10G`), `SWWAF_BYTES_LIMIT_PER_HOUR`
+  (default `20G`) and `SWWAF_BYTES_LIMIT_PER_DAY` (default `50G`): the most
+  bytes a client may have counted in each window. A size or `off`. Bytes are
+  counted once the answer has ended, so a byte limit never cuts an answer short.
+  The client's next request is refused instead. Each default is above the
+  largest request and answer together, so at the defaults no single download
+  breaks a limit.
+- `SWWAF_BYTES_COUNT` (default `both`): which body bytes the byte limits count:
+  `response`, `request` or `both`. For a WebSocket, what it carried each way
+  counts once it closes.
+
+## Looking up the AS number and country
+
+- `SWWAF_LOOKUP_SOURCE` (default `geojs`): `geojs`, `file` or `off`. `geojs`
+  asks the GeoJS web service, which is then told the address of every new
+  visitor. `file` looks clients up in the IPinfo Lite database file at
+  `SWWAF_LOOKUP_DB_PATH`, and sends nothing off the host. `off` looks up no
+  client. With `off`, a setting that needs lookups stops the start:
+    - a country list;
+    - `SWWAF_ADD_LOOKUP_HEADERS`;
+    - an entry in `SWWAF_ASN_LIMIT_PERCENT`, `SWWAF_COUNTRY_LIMIT_PERCENT`,
+      `SWWAF_ASN_BYTES_PERCENT` or `SWWAF_COUNTRY_BYTES_PERCENT`;
+    - `SWWAF_UNKNOWN_LIMIT_PERCENT` below 100;
+    - `SWWAF_ASN_LIMIT_PERCENT_URL`;
+    - an anomaly threshold per AS number.
+- `SWWAF_LOOKUP_DB_PATH` (default empty): the IPinfo Lite database file, in its
+  `.mmdb` form, for `SWWAF_LOOKUP_SOURCE=file`. `file` without it stops the
+  start, and so does setting it with any other source. A file that is missing or
+  cannot be read stops the start too.
+- `SWWAF_LOOKUP_TIMEOUT` (default `1s`): how long a request waits for its
+  client's first answer from GeoJS when a setting needs it, and how long a
+  request to GeoJS may take. A duration; it cannot be `off`.
+- `SWWAF_ADD_LOOKUP_HEADERS` (default `false`): `true` passes the app the
+  client's AS number in `X-Client-ASN` and its country in `X-Client-Country`. A
+  header whose value is unknown is left out. Whatever this setting says, any
+  such header the client sent is removed.
+
+See [`lookup.md`](lookup.md) for what each source sends where, and how long
+answers are kept.
+
+## Country lists
+
+- `SWWAF_DENIED_COUNTRIES` (default empty): countries whose clients are refused,
+  such as `cn,ru,kp`.
+- `SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES` (default empty): when set, the only
+  countries whose clients get through, such as `us,de`. A client whose country
+  cannot be found is refused too. Otherwise every new client would be let in
+  whenever GeoJS stops answering. A client on a private address has no country,
+  so it is refused unless it is in `SWWAF_ALLOW_NETS`.
+
+A country on both lists stops the start. What a refused request gets, and why
+the lists are empty by default, is under "Country lists" in
+[`SPEC.md`](../SPEC.md).
+
+## Lower limits by AS number and country
+
+Clients of the AS numbers and countries listed here get a percentage of every
+rate limit and byte limit. A lowered limit is rounded down. "Biased thresholds"
+in [`SPEC.md`](../SPEC.md) says why the lists are empty by default and why no
+budget is shared by a whole AS number or country.
+
+- `SWWAF_ASN_LIMIT_PERCENT` (default empty): a list of AS numbers, each with `:`
+  and a percentage, such as `AS14061:50,AS16276:50,AS45102:25`. An AS number
+  listed twice is refused.
+- `SWWAF_COUNTRY_LIMIT_PERCENT` (default empty): the same by country, such as
+  `cn:25,ru:50`.
+- `SWWAF_ASN_BYTES_PERCENT` and `SWWAF_COUNTRY_BYTES_PERCENT` (default empty):
+  the same for the byte limits alone. For the AS numbers and countries they
+  list, they take the place of the two settings above.
+- `SWWAF_UNKNOWN_LIMIT_PERCENT` (default `100`): the percentage of every limit
+  for a client without a country:
+    - one the lookup cannot place;
+    - one on a private address;
+    - one whose answer from GeoJS has not come in time.
+- `SWWAF_ASN_LIMIT_PERCENT_URL` (default unset): the `http` or `https` URL of a
+  text file of such entries, one to a line, such as `AS14061:50`. One list can
+  then serve several instances. It is fetched and kept as a blocklist is. Where
+  it and `SWWAF_ASN_LIMIT_PERCENT` both give a percentage, the lower applies. A
+  URL that is also in `SWWAF_BLOCKLIST_URLS` stops the start.
+
+A client to which several percentages apply gets the lowest. The log line of
+each counted request, and the notes of each ban, say which setting lowered the
+limit.
+
+## Reputation sources
+
+None is on by default. A reputation source judges a client by what others saw it
+do. The defaults judge it by what it does to your service.
+
+- `SWWAF_BLOCKLIST_URLS` (default empty): blocklists to fetch, such as
+  `https://www.spamhaus.org/drop/drop.txt`. Each is an `http` or `https` URL
+  without a user or a fragment. A URL listed twice is refused.
+- `SWWAF_BLOCKLIST_REFRESH` (default `24h`): how long a list waits after its
+  last fetch, or failed try, before it is fetched again. A duration of `1h` or
+  more; it cannot be `off`. The Spamhaus lists may be fetched no more than once
+  an hour.
+- `SWWAF_BLOCKLIST_ACTION` (default `deny`): what is done with a client on a
+  blocklist. `deny` refuses its requests. `limit:<percent>`, such as `limit:25`,
+  gives it that percentage of every limit. `log` only notes the list in the log
+  line and raises an alert.
+- `SWWAF_DNSBL_ZONES` (default empty): the DNS blocklists to ask about each
+  client, such as `dnsbl.dronebl.org`. A DNS blocklist answers a DNS query for a
+  name made from an address, and so says whether the address is on it. A zone is
+  a DNS name of at most 189 characters. A Spamhaus zone carries its key, as in
+  `<key>.xbl.dq.spamhaus.net`, and is shown with the key masked. A zone listed
+  twice is refused, whatever its case or key. Do not name a zone meant for mail:
+  such a zone holds the residential addresses ordinary visitors come from.
+- `SWWAF_DNSBL_RESOLVER` (default unset): the resolver to ask the zones through,
+  such as `192.0.2.53` or `[2001:db8::53]:5353`. An IP address with an optional
+  port, 53 when none is given. Unset, the host's resolver is used. Several zones
+  refuse queries that come through a public resolver.
+- `SWWAF_ABUSEIPDB_KEY` (default unset): the key of your AbuseIPDB account.
+  While it is set, a client that has committed an offence is checked. A control
+  character in it is refused.
+- `SWWAF_ABUSEIPDB_MIN_SCORE` (default `75`): the least abuse confidence score,
+  from 0 to 100, that is a hit.
+- `SWWAF_ABUSEIPDB_DAILY_BUDGET` (default `900`): the most checks made in a day,
+  in UTC, a whole number above zero. AbuseIPDB's free accounts may make 1,000.
+- `SWWAF_CROWDSEC_LAPI_URL` (default unset): the local API of a CrowdSec engine
+  you run, such as `http://172.17.0.1:8080`. An `http` or `https` URL without a
+  user or a fragment. Its decision list is at `v1/decisions` under that URL, and
+  is fetched every minute. Set without the key, it stops the start. So does a
+  decision list URL that is also in `SWWAF_BLOCKLIST_URLS`, or that is
+  `SWWAF_ASN_LIMIT_PERCENT_URL`.
+- `SWWAF_CROWDSEC_LAPI_KEY` (default unset): the key the engine gave for
+  `smallwebwaf`, as `cscli bouncers add smallwebwaf` prints it. Set without the
+  URL, it stops the start.
+- `SWWAF_REPUTATION_ACTION` (default `limit:25`): what is done with a client on
+  a DNS blocklist, or one whose AbuseIPDB score is a hit. `deny`,
+  `limit:<percent>` or `log`, as for `SWWAF_BLOCKLIST_ACTION`. Such a verdict is
+  less certain than the Spamhaus DROP list, so by default the client gets a
+  quarter of every limit.
+- `SWWAF_REPUTATION_CACHE_TTL` (default `24h`): how long a zone's verdict or
+  AbuseIPDB's score is used. A duration; it cannot be `off`.
+- `SWWAF_REPUTATION_TIMEOUT` (default `2s`): how long a query to a zone or a
+  check with AbuseIPDB may take. A duration; it cannot be `off`.
+
+See [`reputation.md`](reputation.md) for how each source is asked and what it
+does with the answer.
+
+## Attack detection
+
+- `SWWAF_RULES_DIR` (default `/etc/smallwebwaf/rules.d`): the directory of the
+  rule files (see [`rules.md`](rules.md)). A directory that cannot be read stops
+  the start. An empty one is no error.
+- `SWWAF_RULES_ENABLED` (default `true`): `false` reads no rule file.
+- `SWWAF_TRAP_PATHS` (default empty): paths the app never serves and only
+  scanners ask for, such as `/wp-login.php,/xmlrpc.php` in front of a code
+  forge. A request for one bans the client, as a `ban` rule does. Each starts
+  with `/` and holds no `?`. A trap path is matched whole, without the query,
+  against the path as sent and once percent-decoded. `/wp-login.php` matches
+  `/wp-login.php?x=1` and `/%77p-login.php`. It does not match `/wp-login.php/`
+  or `/blog/wp-login.php`.
+- `SWWAF_WAF_MODE` (default `block`): what the Core Rule Set does with a request
+  it takes for an attack. `block` refuses it with `403`. `detect` lets it
+  through, logged and alerted. `off` inspects no request.
+- `SWWAF_WAF_PARANOIA_LEVEL` (default `1`): the Core Rule Set's paranoia level,
+  from 1 to 4. Each level up runs more rules. Those find more attacks, and take
+  more ordinary requests for attacks.
+- `SWWAF_WAF_ANOMALY_THRESHOLD` (default `5`): the score at which a request is a
+  match. Each rule that matches adds to the request's score, and a rule rated
+  critical adds 5. So by default one such rule is enough. A whole number above
+  zero, or `off`. With `off` no request is a match, and scores are still logged.
+- `SWWAF_WAF_DISABLED_RULES` (default
+  `920340,920420,920440,920640,930130,930140`): the ids of Core Rule Set rules
+  to switch off. The log line names the rules a request matched, so a rule that
+  refuses your app's ordinary requests can be found there. "Attack detection" in
+  [`SPEC.md`](../SPEC.md) says what the six default ids refuse and why they are
+  off. A list you give replaces the default, so name these six ids in it to keep
+  them off. An id must be a whole number above zero. An id from 900000 to 900999
+  is refused: those are the rules that set the Core Rule Set up, and
+  `smallwebwaf`'s own.
+- `SWWAF_WAF_EXEMPT_PATHS` (default empty): path prefixes the Core Rule Set does
+  not inspect, matched as `SWWAF_RATE_LIMIT_EXEMPT_PATHS` is.
+- `SWWAF_WAF_BODY_LIMIT` (default `off`): `off` reads no request body. A size,
+  at most `1G`, switches body inspection on. The Core Rule Set then reads a form
+  data or multipart body up to that size, and the rest streams on to the app. It
+  reads a JSON or XML body no larger than that size, since those cannot be read
+  in part. Any other body, such as a git push, reaches the app uninspected. See
+  [`core-rule-set.md`](core-rule-set.md).
+- `SWWAF_ERROR_BURST_THRESHOLD` (default `30`): the most refusals of one client
+  in a minute for a rule match, a trap path, a Core Rule Set match or a failed
+  token check. One more bans the client, as a broken rate limit does. A count or
+  `off`. The app's own `401` and `404` answers are not counted.
+
+## How long bans last and what they cover
+
+- `SWWAF_BAN_RESPONSE` (default `403`): how a refused client is answered: `403`,
+  `429`, or `close` to close the connection without an answer. A `block` rule
+  and the Core Rule Set always answer `403`.
+- `SWWAF_LIMIT_BAN_DURATION` (default `1h`): the ban for a first broken rate
+  limit, byte limit or error burst. A duration; it cannot be `off`.
+- `SWWAF_LIMIT_BAN_REPEAT_WINDOW` (default `24h`): a client that breaks a limit
+  again within this time after its ban ended is banned three times as long. A
+  duration; it cannot be `off`.
+- `SWWAF_MAX_BAN_DURATION` (default `7d`): a ban for a broken limit that would
+  be longer is permanent instead. A duration; it cannot be `off`.
+- `SWWAF_ATTACK_BAN_DURATION` (default `7d`): the ban for a first clear sign of
+  attack. A duration; it cannot be `off`.
+- `SWWAF_MAX_BANS` (default `5000`): the most bans `smallwebwaf` made that are
+  kept, whether past, active or permanent. A whole number above zero. Bans whose
+  cause is `admin` are kept besides and never dropped (see
+  [`bans.md`](bans.md)).
+- `SWWAF_BAN_SCOPE_V4_PREFIX` (default `32`): the length of the netblock around
+  an IPv4 client that a ban covers, from 0 to 32. `24` bans the surrounding /24.
+  An IPv6 ban covers the client's group.
+
+## Where and how often the state files are written
+
+- `SWWAF_STATE_DIR` (default `/var/lib/smallwebwaf`): the directory of the state
+  files, an absolute path. A directory that does not exist or cannot be written
+  stops the start.
+- `SWWAF_STATE_WRITE_DELAY` (default `10s`): how long `bans.json` waits to be
+  written after a ban is made, lifted or made permanent. Every change in between
+  goes into the same write. A duration; it cannot be `off`.
+- `SWWAF_STATE_COUNTER_INTERVAL` (default `15m`): how often every state file is
+  written. A duration; it cannot be `off`.
+
+## Logging
+
+- `SWWAF_LOG_REQUEST_HEADERS` (default
+  `accept,accept-language,accept-encoding,content-type,origin,range`): the
+  request headers to record in the log line, in either case. `Authorization`,
+  `Cookie` and `Set-Cookie` are never logged, even if listed. `Host` and
+  `Transfer-Encoding` are refused: Go's HTTP server takes them out of the
+  request. The host is the field `host`.
+- `SWWAF_LOG_LEVEL` (default `info`): the least severe of `smallwebwaf`'s own
+  messages that are written: `debug`, `info`, `warn` or `error`. No message is
+  at `debug`. It holds back no request log line. `warn` and `error` hold back
+  the line of settings at start.
+- `SWWAF_LOG_REMOTE_URL` (default unset): a syslog server every line on stdout
+  is also sent to, such as `syslog+tls://logs.example:6514`. The forms are
+  `syslog+udp://`, `syslog+tcp://` and `syslog+tls://`, each with a host and a
+  port and nothing more.
+- `SWWAF_LOG_REMOTE_TLS_CA_FILE` (default unset): a file of PEM certificates
+  that a `syslog+tls` server's certificate must chain to, instead of the host's
+  own. A file that cannot be read, or holds no certificate, stops the start.
+- `SWWAF_LOG_REMOTE_BUFFER` (default `10000`): the most lines held while they
+  wait to be sent, a whole number above zero.
+- `SWWAF_LOG_REMOTE_FACILITY` (default `local0`): the syslog facility: `kern`,
+  `user`, `mail`, `daemon`, `auth`, `syslog`, `lpr`, `news`, `uucp`, `cron`,
+  `authpriv`, `ftp`, or `local0` to `local7`.
+- `SWWAF_LOG_REMOTE_APP_NAME` (default: `SWWAF_INSTANCE_NAME`): the app name in
+  each syslog record, 1 to 48 printable ASCII characters without a space.
+
+## Tokens and metrics
+
+- `SWWAF_ADMIN_TOKEN` (default unset): the token for the ban endpoints and
+  `/_smallwebwaf/clients/<ip>`. A long random value of at least 32 characters.
+  Unset, those endpoints are off. Give it as a file to keep it from the app (see
+  "Settings given as files" below).
+- `SWWAF_METRICS_TOKEN` (default unset): the token a scraper sends for
+  `/_smallwebwaf/metrics`, at least 32 characters. Unset, the metrics are off.
+  It is separate from the admin token, so a scraper cannot manage bans.
+- `SWWAF_METRICS_TOP_N` (default `50`): how many AS numbers and how many
+  countries get series of their own in the metrics. The rest count as `other`. A
+  whole number above zero.
+
+## Alert destinations
+
+- `SWWAF_ALERT_WEBHOOK_URL` (default unset): the webhook that receives each
+  alert as a JSON object. An `http` or `https` URL without a user or a fragment.
+  The settings logged at start show its path and query as `********`, since many
+  webhooks carry their secret there.
+- `SWWAF_ALERT_WEBHOOK_HEADERS` (default empty): headers sent with each post,
+  such as `Authorization:Bearer 0123456789abcdef`. A list of name, `:` and
+  value. A value cannot hold a comma.
+- `SWWAF_ALERT_SLACK_WEBHOOK_URL` (default unset): the Slack incoming webhook
+  that receives each alert as a message. It is checked and masked as the webhook
+  URL is.
+- `SWWAF_ALERT_NTFY_URL` (default unset): the ntfy topic that receives each
+  alert, as the topic's full URL, such as `https://ntfy.sh/my-alerts`. It is
+  checked and masked as the webhook URL is.
+- `SWWAF_ALERT_NTFY_TOKEN` (default unset): an ntfy access token, sent as
+  `Authorization: Bearer <token>`. A control character in it is refused.
+- `SWWAF_ALERT_EVENTS` (default
+  `ban,permanent_ban,waf_block,anomaly,reputation_hit,source_failure,file_error`):
+  the events alerts are sent for. Any other name is refused.
+- `SWWAF_ALERT_COOLDOWN` (default `15m`): how long a repeat of an alert is held
+  back. A duration or `off`.
+- `SWWAF_ALERT_MAX_PER_HOUR` (default `60`): the most alerts sent in an hour.
+  The rest are rolled into one summary. A whole number above zero, or `off`.
+
+See [`alerts.md`](alerts.md) for the events and what each destination gets.
+
+## Anomaly thresholds
+
+These only alert. They refuse and ban nothing. Each scope has four thresholds:
+the most requests and the most bytes counted in a minute and in an hour.
+Requests are counts, bytes are sizes. Each is `off` by default. What is unusual
+depends on each service's normal traffic, which the metrics show. The four
+thresholds per client are:
+
+- `SWWAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE`;
+- `SWWAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR`;
+- `SWWAF_ANOMALY_CLIENT_BYTES_PER_MINUTE`;
+- `SWWAF_ANOMALY_CLIENT_BYTES_PER_HOUR`.
+
+The other scopes' names have another prefix before the same four endings, such
+as `REQUESTS_PER_MINUTE`:
+
+- `SWWAF_ANOMALY_NET_...`: per netblock around a client. Two settings give the
+  netblock's length:
+    - `SWWAF_ANOMALY_NET_V4_PREFIX` (default `24`, from 0 to 32) for an IPv4
+      client;
+    - `SWWAF_ANOMALY_NET_V6_PREFIX` (default `48`, from 0 to 128) for an IPv6
+      client.
+- `SWWAF_ANOMALY_ASN_...`: per AS number. Needs lookups on.
+- `SWWAF_ANOMALY_TOTAL_...`: the whole service.
+- `SWWAF_WATCH_...`: each netblock in `SWWAF_WATCH_NETS`, as a whole.
+  `SWWAF_WATCH_NETS` (default empty) is a list of name, `=` and netblock, such
+  as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. An item without `=` or a
+  name, or with a bad netblock, is refused. So is a name used twice.
+
+Every request but the health check is counted, whatever was done with it,
+clients in `SWWAF_ALLOW_NETS` included. At most 20,000 counters are kept.
+`alerts.json` keeps them across a restart.
+
+## Settings given as files
+
+Any setting may be given as a file holding its value. Add `_FILE` to the
+setting's name: `SWWAF_METRICS_TOKEN_FILE` names the file that holds
+`SWWAF_METRICS_TOKEN`. The file's contents are the value, less one newline at
+the end. They are checked as the value itself would be. Setting both forms stops
+the start, and so does naming a file that cannot be read.
+`SWWAF_LOG_REMOTE_TLS_CA_FILE` already holds a file name, so it has no `_FILE`
+form.
+
+A token given as a file is out of the app's reach only while the `smallwebwaf`
+user alone can read the file. Make it on the host, owned by uid 65532 with mode
+`0400`:
+
+```sh
+mkdir -p /srv/app/tokens
+openssl rand -hex 32 > /srv/app/tokens/metrics
+chown 65532:65532 /srv/app/tokens/metrics
+chmod 0400 /srv/app/tokens/metrics
+```
+
+Mount its directory into the container read-only, and name the file:
+
+```sh
+docker run \
+    -v /srv/app/tokens:/etc/smallwebwaf/tokens:ro \
+    -e SWWAF_METRICS_TOKEN_FILE=/etc/smallwebwaf/tokens/metrics \
+    ...
+```
+
+## Fixed limits
+
+A few limits are fixed rather than settings:
+
+- at most 100,000 GeoJS answers are kept, for 7 days each;
+- at most 100,000 DNS blocklist verdicts and 100,000 AbuseIPDB scores are kept;
+- at most 1,000 DNS blocklist queries are under way at once;
+- the CrowdSec decision list is fetched again a minute after the last fetch.

docs/state-files.md

@@ -0,0 +1,102 @@
+# State files
+
+`smallwebwaf` keeps its state in memory, and a copy of it in five JSON files in
+`SWWAF_STATE_DIR`. The files are meant for people as well: you can read or edit
+them at any time, and the running `smallwebwaf` takes the edit in. The
+requirements they meet are under "Persistent state" in [`SPEC.md`](../SPEC.md).
+
+## The files
+
+Each has a top-level `version` of 1.
+
+- `bans.json`: active and past bans, up to `SWWAF_MAX_BANS` that `smallwebwaf`
+  made and every ban you made, indented to be read. Per entry:
+    - the netblock, start and expiry (`null` for permanent);
+    - the cause: `attack`, `limit`, `admin` or `crowdsec`;
+    - a short reason;
+    - when it was lifted, if you lifted it;
+    - the notes (see [`bans.md`](bans.md)).
+- `clients.json`: per client, its minute, hour and day counters and its history
+  since it was first seen, one client per line, so `grep` shows everything about
+  one. The history holds:
+    - the first and last time seen;
+    - the AS number, AS name and country last looked up, and when;
+    - total requests, and how many were forwarded and how many refused;
+    - bytes in each direction;
+    - responses by status class;
+    - offences by kind: `limit`, `attack`, `rule_blocked`, `waf_blocked` and
+      `token_refused`.
+
+    Clients that were never banned are kept too, so every client's history
+    survives a restart.
+
+- `lookups.json`: GeoJS answers, one per line: the AS number, AS name and
+  country, when GeoJS was asked and when the answer was last used.
+- `reputation.json`:
+    - the last good copy of each list fetched from a URL, with when it was last
+      tried;
+    - each DNS blocklist verdict still in use;
+    - AbuseIPDB's scores, and the checks spent today.
+- `alerts.json`:
+    - the anomaly counters;
+    - the alert cooldowns: for each event and netblock, source, file or thing
+      counted, when it was last sent and the count of repeats held back since;
+    - the alerts sent and held back in the current hour;
+    - the alerts waiting for each destination.
+
+Times are RFC 3339 UTC. Durations and sizes are plain numbers, with the unit in
+the field name. `bans.json`, `reputation.json` and `alerts.json` are indented;
+`clients.json` and `lookups.json` put each entry on one line.
+
+## Sizes
+
+`clients.json` takes about 1 KiB per client, about 20 MiB at the default
+`SWWAF_MAX_TRACKED_CLIENTS`. Written every 15 minutes, that is under 2 GiB of
+disk writes a day. `bans.json` takes about 1.2 KiB per ban, at most about 2.5
+KiB, so about 6 MiB at the default `SWWAF_MAX_BANS`. With a full file, a hundred
+new bans a day come to about 600 MiB of writes. `lookups.json` takes about 150
+bytes per answer, under 1.5 GiB of writes a day when full. The other two files
+are usually a few MiB or less.
+
+## Writing
+
+`bans.json` is written `SWWAF_STATE_WRITE_DELAY` after a ban is made, lifted or
+made permanent. Every file is written every `SWWAF_STATE_COUNTER_INTERVAL`, and
+when `smallwebwaf` stops. Each write goes to a temporary file that then replaces
+the file, so a crash leaves the old file or the new one, whole. Before writing a
+file, `smallwebwaf` takes in any edit you made to it, so your edit is not
+overwritten. A write that fails is logged, raised as a `file_error` alert, and
+tried again at the next write. A hard kill loses what changed since the last
+write:
+
+- ban changes from the last `SWWAF_STATE_WRITE_DELAY` (10 seconds);
+- everything else from the last `SWWAF_STATE_COUNTER_INTERVAL` (15 minutes):
+    - counts and history, and the counts in ban notes;
+    - GeoJS answers;
+    - reputation verdicts and the AbuseIPDB count;
+    - anomaly counters and alert cooldowns.
+
+## Reading at start
+
+The files are read back. Each client keeps its counts, so a restart gives no one
+a fresh allowance. Each ban keeps refusing until it ends. Counter buckets and
+cache entries whose time has passed are discarded. A missing file is empty
+state. These stop the start, with a message naming the file and the place:
+
+- a file that does not parse, or has another `version`;
+- an entry without a field it needs;
+- a ban whose `cause` is not `limit`, `attack`, `admin` or `crowdsec`;
+- a ban whose `expires` is not after its `start`.
+
+## Editing while it runs
+
+`smallwebwaf` watches the directory and takes in your edit of a file as soon as
+you save it. What the file then holds replaces what `smallwebwaf` held for it.
+It tells its own writes from yours by comparing the file with what it last read
+or wrote. A change it made after you opened the file, such as a new ban, is lost
+when you save over it; most editors warn when a file changed on disk while it
+was open. An edit with an error that would stop the start does not stop the
+running `smallwebwaf`. It keeps what it holds. At the file's next write it
+renames your file to `<name>.bad`, writes the file again from memory, and logs
+and alerts the file and the place of the error. Mend the `.bad` file and move it
+back. A file you remove is written again at its next write.

internal/alerts/alerts.go

@@ -1,8 +1,8 @@
 // Package alerts sends alerts on bans, on traffic over an anomaly
 // threshold, on a source that fails and on a file with an error to each
 // destination set: to the webhook
-// SWWAF_ALERT_WEBHOOK_URL names, each as one JSON object, as the "Alert
-// webhook schema" section of SPEC.md describes, to the Slack incoming
+// SWWAF_ALERT_WEBHOOK_URL names, each as one JSON object, as "The JSON
+// object" in docs/alerts.md describes, to the Slack incoming
 // webhook SWWAF_ALERT_SLACK_WEBHOOK_URL names, as a message, and to the
 // ntfy topic SWWAF_ALERT_NTFY_URL names. A repeat within
 // SWWAF_ALERT_COOLDOWN is held back, and so is an alert past
@@ -149,11 +149,10 @@ type Params struct {
 }
 
 // Alert is one alert, as the webhook is sent it and alerts.json holds it,
-// with the fields of the "Alert webhook schema" section of SPEC.md. ASN,
-// ASName and Country are, for a ban, the client's as the ban's notes give
-// them.
+// with the fields of "The JSON object" in docs/alerts.md. ASN, ASName and
+// Country are, for a ban, the client's as the ban's notes give them.
 //
-//nolint:tagliatelle // SPEC.md's alert webhook schema names its fields in snake_case
+//nolint:tagliatelle // docs/alerts.md names the alert's fields in snake_case
 type Alert struct {
 	Instance string       `json:"instance"`
 	Time     time.Time    `json:"time"`

internal/anomaly/anomaly.go

@@ -1,8 +1,8 @@
 // Package anomaly counts requests and bytes over a minute and an hour, per
 // client, per surrounding netblock, per AS number, for the whole service
 // and per named netblock, and raises an anomaly alert for a count over its
-// threshold, as "Anomaly thresholds" under "Configuration surface" in
-// SPEC.md describes. It refuses and bans nothing. At most 20,000 counters
+// threshold, as "Anomaly thresholds" under "Settings" in SPEC.md
+// describes. It refuses and bans nothing. At most 20,000 counters
 // are kept, in memory, and written to alerts.json and read from it by the
 // state package.
 package anomaly

internal/bans/admin_test.go

@@ -61,6 +61,59 @@ func TestAdminsBansAreNeverDroppedAndDoNotCountTowardMaxBans(t *testing.T) {
 	wantBans(t, ledger, map[netip.Prefix]int{adminsOnly: 2, both: 1, second: 0, third: 1})
 }
 
+func TestEarlierBansCountABanDroppedAfterAnAdminsBan(t *testing.T) {
+	t.Parallel()
+
+	rules := defaultRules()
+	rules.MaxBans = 2
+	ledger := bans.New(rules)
+	netblock := netip.MustParsePrefix("203.0.113.1/32")
+	other := netip.MustParsePrefix("203.0.113.2/32")
+
+	// An admin bans the netblock for a minute, and it then breaks a limit
+	// twice, each time after its last ban has ended.
+	ledger.BanForAdmin(netblock, midnight(), midnight().Add(time.Minute),
+		"probes for logins")
+	first, _ := ledger.BanForLimit(netblock, midnight().Add(time.Minute), bans.Notes{})
+	second, _ := ledger.BanForLimit(netblock, first.Expires, bans.Notes{})
+
+	// A ban on another netblock fills the ledger, and the netblock's first
+	// ban for a limit, its earliest that is not an admin's, goes.
+	ledger.BanForLimit(other, second.Start, bans.Notes{})
+	wantBans(t, ledger, map[netip.Prefix]int{netblock: 2, other: 1})
+
+	// The netblock's next ban still counts it.
+	third, _ := ledger.BanForLimit(netblock, second.Expires, bans.Notes{})
+	if third.Notes.EarlierBans != (bans.EarlierBans{Limit: 2, Admin: 1}) {
+		t.Errorf("the third ban for a limit has earlier bans %+v, "+
+			"want 2 for a limit and 1 an admin's", third.Notes.EarlierBans)
+	}
+}
+
+func TestEarlierBansCountABanAnAdminKeepsOnce(t *testing.T) {
+	t.Parallel()
+
+	ledger := bans.New(defaultRules())
+	netblock := netip.MustParsePrefix("203.0.113.1/32")
+
+	// The netblock breaks a limit twice, the second time after its first
+	// ban has ended, and the second ban's notes count the first. An admin
+	// then keeps the first ban.
+	first, _ := ledger.BanForLimit(netblock, midnight(), bans.Notes{})
+	second, _ := ledger.BanForLimit(netblock, first.Expires, bans.Notes{})
+
+	kept := first
+	kept.Cause = bans.CauseAdmin
+	ledger.LoadEdit([]bans.Ban{kept, second})
+
+	// The netblock's next ban counts the kept ban once, as an admin's.
+	third, _ := ledger.BanForLimit(netblock, second.Expires, bans.Notes{})
+	if third.Notes.EarlierBans != (bans.EarlierBans{Limit: 1, Admin: 1}) {
+		t.Errorf("the third ban for a limit has earlier bans %+v, "+
+			"want 1 for a limit and 1 an admin's", third.Notes.EarlierBans)
+	}
+}
+
 func TestReasonOfTheBansSmallwebwafMakes(t *testing.T) {
 	t.Parallel()
 

internal/bans/bans.go

@@ -687,26 +687,51 @@ func (l *Ledger) ban(
 }
 
 // earlierBans returns how many bans a netblock with the bans held, oldest
-// first, has had, by cause: the first ban held counts the bans the
-// netblock had before that one, since dropped to make room, and each ban
-// held adds one.
+// first, has had, by cause. Each ban held gives a count: the bans its
+// notes count before it, and one for it and each ban held after it. A
+// ban's count misses a ban dropped after it to make room, and that of an
+// admin's ban added to bans.json without notes misses the bans before it,
+// so the count that names the most bans is taken, whole: a ban an admin
+// keeps by giving it CauseAdmin is still counted under its old cause in
+// later bans' notes, and taking each cause from another count would count
+// it twice.
 func earlierBans(held []Ban) EarlierBans {
-	earlier := held[0].Notes.EarlierBans
+	// fromHere counts ban and the bans held after it.
+	var most, fromHere EarlierBans
 
-	for _, ban := range held {
+	for _, ban := range slices.Backward(held) {
 		switch ban.Cause {
 		case CauseLimit:
-			earlier.Limit++
+			fromHere.Limit++
 		case CauseAttack:
-			earlier.Attack++
+			fromHere.Attack++
 		case CauseAdmin:
-			earlier.Admin++
+			fromHere.Admin++
 		case CauseCrowdSec:
-			earlier.CrowdSec++
+			fromHere.CrowdSec++
+		}
+
+		notes := ban.Notes.EarlierBans
+		count := EarlierBans{
+			Limit:    notes.Limit + fromHere.Limit,
+			Attack:   notes.Attack + fromHere.Attack,
+			Admin:    notes.Admin + fromHere.Admin,
+			CrowdSec: notes.CrowdSec + fromHere.CrowdSec,
+		}
+
+		// Of counts that name as many bans, the earlier ban's is taken: it
+		// counts more of the bans held by the cause they have now.
+		if count.total() >= most.total() {
+			most = count
 		}
 	}
 
-	return earlier
+	return most
+}
+
+// total returns how many bans e counts, of all causes.
+func (e EarlierBans) total() int {
+	return e.Limit + e.Attack + e.Admin + e.CrowdSec
 }
 
 // markChanged has Changed receive a value, unless one is waiting already.

internal/metrics/metrics.go

@@ -1,6 +1,7 @@
-// Package metrics keeps smallwebwaf's Prometheus metrics, as the "Metrics
-// endpoint" section of SPEC.md lists them, and serves them in the
-// Prometheus text format. No metric carries a client's address.
+// Package metrics keeps smallwebwaf's Prometheus metrics, as
+// docs/metrics.md lists them, and serves them in the Prometheus text
+// format, as the "Metrics endpoint" section of SPEC.md requires. No
+// metric carries a client's address.
 package metrics
 
 import (

internal/proxy/bodies.go

@@ -1,8 +1,10 @@
 package proxy
 
 import (
+	"bufio"
 	"errors"
 	"io"
+	"net"
 	"net/http"
 	"sync/atomic"
 
@@ -211,9 +213,20 @@ func (w *responseWriter) FlushError() error {
 	return err
 }
 
+// Hijack takes over the connection to the client, which ReverseProxy does
+// only to pass on the app's 101 Switching Protocols: that is then the
+// status sent.
+func (w *responseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
+	conn, buffered, err := http.NewResponseController(w.ResponseWriter).Hijack()
+	if err == nil {
+		w.status = http.StatusSwitchingProtocols
+	}
+
+	return conn, buffered, err
+}
+
 // Unwrap lets http.ResponseController reach net/http's own
-// ResponseWriter, which is how ReverseProxy takes over the connection of
-// an upgraded request.
+// ResponseWriter for what responseWriter does not do itself.
 func (w *responseWriter) Unwrap() http.ResponseWriter {
 	return w.ResponseWriter
 }

internal/proxy/coreruleset.go

@@ -23,7 +23,7 @@ import (
 // limit while the Core Rule Set reads it, which it notes nothing of.
 func (rq *request) checkCoreRuleSet() string {
 	cfg := rq.h.config
-	if cfg.WAFMode == config.WAFModeOff || pathExempt(rq.in.URL, cfg.WAFExemptPaths) {
+	if cfg.WAFMode == config.WAFModeOff || pathExempt(rq.in, cfg.WAFExemptPaths) {
 		return ""
 	}
 

internal/proxy/passthrough_test.go

@@ -74,6 +74,47 @@ func TestPassesRequestAndAnswerUnchanged(t *testing.T) {
 	wantRequestFields(t, line, addr, len(requestBody), len(answerBody))
 }
 
+func TestPassesThePathAsSent(t *testing.T) {
+	t.Parallel()
+
+	for _, path := range []string{
+		// An encoded slash and a character Go escapes: |, ^, and é sent
+		// as its UTF-8 bytes.
+		"/a%2Fb|c", "/feat%2Fx/file^1", "/x%2Fy/café",
+		// A path starting with //, which Go would send as a scheme and
+		// host if it were put in URL.Opaque.
+		"//a%2Fb",
+	} {
+		t.Run(path, func(t *testing.T) {
+			t.Parallel()
+
+			saw := make(chan string, 1)
+			app := startApp(t, func(_ http.ResponseWriter, r *http.Request) {
+				saw <- r.RequestURI
+			})
+			addr, out := startProxy(t, app.URL, nil)
+
+			conn := dial(t, addr)
+			send(t, conn, "GET "+path+"?q=1 HTTP/1.1\r\nHost: "+appHost+"\r\n\r\n")
+
+			got := readResponse(t, conn)
+			if got.status != http.StatusOK {
+				t.Fatalf("status %d, want %d", got.status, http.StatusOK)
+			}
+
+			target := <-saw
+			if target != path+"?q=1" {
+				t.Errorf("app saw %s, want %s", target, path+"?q=1")
+			}
+
+			line := out.requestLine(t)
+			if line.Path != path {
+				t.Errorf("log line has path %s, want %s", line.Path, path)
+			}
+		})
+	}
+}
+
 // wantAppSaw checks that the app received the test's request unchanged.
 func wantAppSaw(t *testing.T, saw appSaw, body []byte) {
 	t.Helper()
@@ -151,6 +192,36 @@ func wantRequestFields(t *testing.T, line logLine, host string, sent, received i
 	}
 }
 
+func TestAddsNoContentTypeTheAppDidNotSend(t *testing.T) {
+	t.Parallel()
+
+	const typed = "text/plain"
+
+	app := startApp(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/typed" {
+			w.Header().Set("Content-Type", typed)
+		} else {
+			// The key with no value keeps Go's server from adding one.
+			w.Header()["Content-Type"] = nil
+		}
+
+		_, _ = io.WriteString(w, "<!doctype html><title>page</title>")
+	})
+	addr, _ := startProxy(t, app.URL, nil)
+
+	got := get(t, addr, "/")
+	if got.header.Values("Content-Type") != nil {
+		t.Errorf("client got Content-Type %q, want none",
+			got.header.Get("Content-Type"))
+	}
+
+	got = get(t, addr, "/typed")
+	if got.header.Get("Content-Type") != typed {
+		t.Errorf("client got Content-Type %q, want %q",
+			got.header.Get("Content-Type"), typed)
+	}
+}
+
 func TestStreamsTheRequestBody(t *testing.T) {
 	t.Parallel()
 
@@ -309,6 +380,23 @@ func echoAfterUpgrade(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+func TestAnswers502WhenTheAppSwitchesToAnotherProtocol(t *testing.T) {
+	t.Parallel()
+
+	// answerAfterUpgrade switches to websocket whatever the client asked
+	// for, and ReverseProxy passes on a switch only to the protocol the
+	// client asked for, here "websocket, foo".
+	app := startApp(t, answerAfterUpgrade)
+	addr, out := startProxy(t, app.URL, nil)
+
+	conn := dial(t, addr)
+	send(t, conn, "GET /ws HTTP/1.1\r\nHost: app\r\n"+
+		"Connection: Upgrade\r\nUpgrade: websocket, foo\r\n\r\n")
+
+	wantStatus(t, readResponse(t, conn), http.StatusBadGateway)
+	wantLine(t, out.requestLine(t), http.StatusBadGateway, requestlog.ActionUpstreamError)
+}
+
 func TestServerHasTheDefaultLimits(t *testing.T) {
 	t.Parallel()
 

internal/proxy/ratelimits_test.go

@@ -185,6 +185,9 @@ func TestRateLimitCountsPathsThatAreNotExempt(t *testing.T) {
 		"/assets/x%2Fy",
 		"/assets/x%2fy",
 		`/assets/x\y`,
+		// The same with a character Go escapes, |, for which Go's
+		// URL.EscapedPath gives /assets/x/y%7Cz, with no encoded slash.
+		"/assets/x%2Fy|z",
 	} {
 		t.Run(sent, func(t *testing.T) {
 			t.Parallel()

internal/proxy/request.go

@@ -8,7 +8,6 @@ import (
 	"net/http/httptrace"
 	"net/http/httputil"
 	"net/netip"
-	"net/url"
 	"os"
 	"slices"
 	"strings"
@@ -22,6 +21,7 @@ import (
 	"sneak.berlin/go/smallwebwaf/internal/lookup"
 	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
 	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+	"sneak.berlin/go/smallwebwaf/internal/rules"
 )
 
 // flushAfterEachWrite has ReverseProxy pass on each part of the app's
@@ -137,7 +137,7 @@ func (h *handler) newRequest(w http.ResponseWriter, r *http.Request) *request {
 			Method:           r.Method,
 			Scheme:           scheme(r, peerTrusted),
 			Host:             r.Host,
-			Path:             r.URL.EscapedPath(),
+			Path:             rules.Path(r),
 			Query:            r.URL.RawQuery,
 			Protocol:         r.Proto,
 			Referer:          r.Referer(),
@@ -284,7 +284,7 @@ func (rq *request) checkClient(ctx context.Context) string {
 	}
 
 	rq.counted = !isInside(rq.client, cfg.RateLimitExemptNets) &&
-		!pathExempt(rq.in.URL, cfg.RateLimitExemptPaths)
+		!pathExempt(rq.in, cfg.RateLimitExemptPaths)
 	if rq.counted {
 		rq.limitPercent, rq.bytesPercent = rq.limitPercentages()
 		rq.line.LimitPercent, rq.line.LimitPercentSetting = rq.limitPercent.logged()
@@ -307,7 +307,7 @@ func (rq *request) checkClient(ctx context.Context) string {
 	return rq.checkCoreRuleSet()
 }
 
-// pathExempt reports whether a request for u is exempt under prefixes,
+// pathExempt reports whether r is exempt under prefixes,
 // SWWAF_RATE_LIMIT_EXEMPT_PATHS or SWWAF_WAF_EXEMPT_PATHS: whether its
 // path as sent, the path the app receives, not percent-decoded, starts
 // with one of prefixes, so that /%61ssets/x is not under /assets/ for an
@@ -316,10 +316,9 @@ func (rq *request) checkClient(ctx context.Context) string {
 // encoded slash (%2F or %2f), never is, since an app may act on it as a
 // path outside every prefix: /assets/..%2Flogin as /login, or /assets%2Fx
 // as one path segment, as Go's router does.
-func pathExempt(u *url.URL, prefixes []string) bool {
-	decoded := u.Path
-	// EscapedPath is the path as the app receives it, not decoded.
-	sent := u.EscapedPath()
+func pathExempt(r *http.Request, prefixes []string) bool {
+	decoded := r.URL.Path
+	sent := rules.Path(r)
 
 	if strings.Contains(decoded, "..") || strings.Contains(decoded, `\`) ||
 		strings.Contains(strings.ToLower(sent), "%2f") {
@@ -375,6 +374,17 @@ func (rq *request) rewrite(pr *httputil.ProxyRequest) {
 	// ReverseProxy drops query parameters it cannot parse; the app gets
 	// the query as the client sent it.
 	pr.Out.URL.RawQuery = pr.In.URL.RawQuery
+	// ReverseProxy sends the path URL.EscapedPath gives, which, for a path
+	// holding a character Go escapes, such as |, is the whole path decoded
+	// and escaped again, %2F turned into /. Opaque is sent as it is, so the
+	// app gets the path as the client sent it. Left out are a target that
+	// is no path, such as *, and a path starting with //, which Go would
+	// send in Opaque as a scheme and host.
+	path := rules.Path(pr.In)
+	if strings.HasPrefix(path, "/") && !strings.HasPrefix(path, "//") {
+		pr.Out.URL.Opaque = path
+	}
+
 	setForwardedHeaders(pr.In, pr.Out, rq.peer, rq.peerTrusted)
 	pr.Out.Header.Set(requestIDHeader, rq.line.RequestID)
 	pr.Out.Header.Del(asnHeader)
@@ -395,8 +405,10 @@ func (rq *request) modifyResponse(res *http.Response) error {
 		// timeouts. ReverseProxy writes this answer straight to the
 		// connection it takes over, not through rq.out, and then copies
 		// what passes each way through res.Body, the connection to the app.
+		// It may still refuse the switch, as when the app's Upgrade is not
+		// the client's, so the status is noted only once it has taken over
+		// the connection, by rq.out's Hijack.
 		rq.stopTimers()
-		rq.out.status = res.StatusCode
 		rq.line.Websocket = true
 
 		conn, ok := res.Body.(io.ReadWriteCloser)
@@ -419,6 +431,13 @@ func (rq *request) modifyResponse(res *http.Response) error {
 		return errResponseTooLarge
 	}
 
+	// Go's server adds a Content-Type it guesses from the body to a
+	// response whose headers have no Content-Type key. The key with no
+	// value sends none, as the app sent none.
+	if res.Header.Get("Content-Type") == "" {
+		rq.out.Header()["Content-Type"] = nil
+	}
+
 	res.Body = &responseBody{body: limitBody(res.Body, maxBytes), rq: rq}
 	rq.startClientResponseTimeout()
 
@@ -428,6 +447,13 @@ func (rq *request) modifyResponse(res *http.Response) error {
 // answerError is ReverseProxy's ErrorHandler: the request could not be
 // passed to the app, or the app's answer cannot be passed on.
 func (rq *request) answerError(_ http.ResponseWriter, _ *http.Request, err error) {
+	if rq.upgraded != nil {
+		// The app switched protocols, but the switch was not passed on,
+		// and ReverseProxy leaves the app's connection open when it
+		// refuses it.
+		_ = rq.upgraded.Close()
+	}
+
 	refused := rq.refused.Load()
 	if refused == nil {
 		if rq.in.Context().Err() != nil {
@@ -710,6 +736,16 @@ func (rq *request) requestTimedOut(limit string) {
 	}
 
 	if rq.body == nil || !rq.body.waiting.Load() {
+		// Once the app has answered, the transport, ReverseProxy and Go's
+		// server each close the client's body, and closing it reads what
+		// is left of a body under 256 KiB without requestBody.Read, so
+		// waiting is false while that read waits for the client. That
+		// read ends now, before refuse: should smallwebwaf still answer
+		// itself, answer then sets the deadline it gives its own answers.
+		if !rq.answerStarted.IsZero() {
+			rq.stopReadingBody(time.Now())
+		}
+
 		rq.refuse(refusal{
 			status: http.StatusGatewayTimeout,
 			action: requestlog.ActionTimedOut,
@@ -795,9 +831,19 @@ func (rq *request) responseTimedOut() {
 	}
 }
 
-// responseReceived is called once the app has sent its whole answer.
+// responseReceived is called once the app has sent its whole answer. An
+// app may answer before the client has sent its whole body, as with a 404
+// it sends without reading it. The timeouts then run on: until the
+// transport's read of the body returns, Go's server cannot send the
+// answer, and SWWAF_CLIENT_REQUEST_TIMEOUT is what ends that read for a
+// client that stops sending.
 func (rq *request) responseReceived() {
 	rq.complete = true
+
+	if rq.body != nil && !rq.body.received.Load() {
+		return
+	}
+
 	rq.stopTimers()
 }
 

internal/proxy/request_internal_test.go

@@ -0,0 +1,55 @@
+package proxy
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"sneak.berlin/go/smallwebwaf/internal/config"
+)
+
+func TestAnAnswerWithoutAContentTypeGetsNone(t *testing.T) {
+	t.Parallel()
+
+	srv := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			rq := &request{
+				h:   &handler{config: &config.Config{}},
+				out: &responseWriter{ResponseWriter: w},
+			}
+			app := &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{},
+				Body:       http.NoBody,
+			}
+
+			err := rq.modifyResponse(app)
+			if err != nil {
+				t.Errorf("modifyResponse: %v", err)
+			}
+
+			// The headers go out with this, the first part of the body,
+			// which Go's server would guess a Content-Type from.
+			_, _ = io.WriteString(w, "<!doctype html><title>page</title>")
+		}))
+	t.Cleanup(srv.Close)
+
+	req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, srv.URL,
+		http.NoBody)
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+
+	res, err := srv.Client().Do(req)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+
+	_ = res.Body.Close()
+
+	if res.Header.Values("Content-Type") != nil {
+		t.Errorf("client got Content-Type %q, want none",
+			res.Header.Get("Content-Type"))
+	}
+}

internal/proxy/timeouts_test.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strconv"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -194,6 +195,151 @@ func sendLargeBody(t *testing.T, addr string) net.Conn {
 	return conn
 }
 
+func TestClientStopsSendingAfterTheAppHasAnswered(t *testing.T) {
+	t.Parallel()
+
+	// answeredAt is when the app answered, or nil if the bytes the client
+	// sent never reached it.
+	var answeredAt atomic.Pointer[time.Time]
+
+	// The app answers without reading the whole body, as an app does for
+	// a path it does not serve, and only once smallwebwaf waits for the
+	// rest of it: the app takes the bytes the client sent, and then waits
+	// half the timeout, far longer than smallwebwaf takes to go on to
+	// wait.
+	app := startApp(t, func(w http.ResponseWriter, r *http.Request) {
+		_, err := io.ReadFull(r.Body, make([]byte, len("the first bytes")))
+		if err != nil {
+			return
+		}
+
+		time.Sleep(shortTimeout / 2)
+		answeredAt.Store(new(time.Now()))
+		http.NotFound(w, r)
+	})
+	addr, out := startProxy(t, app.URL, map[string]string{
+		clientRequestTimeout: shortTimeoutSetting,
+		metricsToken:         token,
+	})
+
+	start := time.Now()
+	got := readResponse(t, sendPartOfBody(t, addr))
+	wantTimedOut(t, start)
+
+	// Close returns once the app has finished with the request.
+	app.Close()
+
+	// The app's answer came before the time ran out, so the client is
+	// sent that answer, not smallwebwaf's 408. Only a hold-up of the test
+	// process can make it come later, and SPEC.md then asks for 408, as
+	// smallwebwaf was waiting for the client, or for 504 if the bytes the
+	// client sent had not reached the app.
+	at := answeredAt.Load()
+	want := http.StatusNotFound
+
+	switch {
+	case at == nil:
+		want = http.StatusGatewayTimeout
+	case at.Sub(start) >= shortTimeout:
+		want = http.StatusRequestTimeout
+	}
+
+	wantStatus(t, got, want)
+	wantLine(t, out.requestLine(t), want, requestlog.ActionTimedOut)
+	wantLimitHits(t, addr, clientRequestTimeout, 1)
+}
+
+func TestClientStopsSendingWithLittleOfItsBodyLeft(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		// limit is the setting set to shortTimeout, which runs out, and
+		// clientTimeout what SWWAF_CLIENT_REQUEST_TIMEOUT is set to when it
+		// is not limit.
+		limit, clientTimeout string
+	}{
+		{
+			name:  "client request timeout",
+			limit: clientRequestTimeout,
+		},
+		{
+			name:          "upstream request timeout, client request timeout off",
+			limit:         upstreamRequestTimeout,
+			clientTimeout: off,
+		},
+		{
+			name:          "upstream request timeout, client request timeout longer",
+			limit:         upstreamRequestTimeout,
+			clientTimeout: longTimeoutSetting,
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			// appClosed is closed once smallwebwaf has closed its
+			// connection to the app, which it does once it has the app's
+			// answer.
+			appClosed := make(chan struct{})
+
+			// The app answers without reading the rest of the body, and
+			// says it closes the connection, only once smallwebwaf waits
+			// for the client to send more: it takes the bytes the client
+			// sent, and then waits half the timeout, far longer than
+			// smallwebwaf takes to go on to wait.
+			app := startApp(t, func(w http.ResponseWriter, _ *http.Request) {
+				conn, buf, err := http.NewResponseController(w).Hijack()
+				if err != nil {
+					return
+				}
+
+				_, _ = io.ReadFull(buf.Reader, make([]byte, len("the first bytes")))
+
+				time.Sleep(shortTimeout / 2)
+
+				_, _ = buf.WriteString("HTTP/1.1 404 Not Found\r\n" +
+					"Content-Length: 0\r\nConnection: close\r\n\r\n")
+				_ = buf.Flush()
+				_, _ = io.Copy(io.Discard, buf.Reader)
+				_ = conn.Close()
+
+				close(appClosed)
+			})
+
+			env := map[string]string{tc.limit: shortTimeoutSetting, metricsToken: token}
+			if tc.clientTimeout != "" {
+				env[clientRequestTimeout] = tc.clientTimeout
+			}
+
+			addr, out := startProxy(t, app.URL, env)
+
+			// Less than 256 KiB of the body is left after the first bytes,
+			// little enough for Go's server in smallwebwaf to read the rest
+			// itself before it sends the app's answer.
+			start := time.Now()
+			conn := dial(t, addr)
+			send(t, conn, "POST /upload HTTP/1.1\r\nHost: app\r\nContent-Length: 200000\r\n\r\n"+
+				"the first bytes")
+
+			select {
+			case <-appClosed:
+			case <-time.After(waitLimit):
+				t.Fatal("smallwebwaf did not close its connection to the app")
+			}
+
+			// More of the body, which can no longer go to the app, and then
+			// nothing.
+			send(t, conn, strings.Repeat("x", 8<<10))
+
+			got := readResponse(t, conn)
+			wantTimedOut(t, start)
+			wantStatus(t, got, http.StatusNotFound)
+			wantLine(t, out.requestLine(t), http.StatusNotFound, requestlog.ActionTimedOut)
+			wantLimitHits(t, addr, tc.limit, 1)
+		})
+	}
+}
+
 func TestAppTooSlowToAnswer(t *testing.T) {
 	t.Parallel()
 

internal/ratelimit/ratelimit.go

@@ -206,7 +206,7 @@ type Hit struct {
 // Counts are a client's requests and bytes in the minute, the hour and
 // the day that end at a request, that request's included.
 //
-//nolint:tagliatelle // SPEC.md's request log names its fields in snake_case
+//nolint:tagliatelle // docs/request-log.md names the fields in snake_case
 type Counts struct {
 	Minute      float64 `json:"minute"`
 	Hour        float64 `json:"hour"`

internal/remotelog/remotelog.go

@@ -1,8 +1,9 @@
 // Package remotelog sends the lines smallwebwaf writes on stdout to the
 // remote log endpoint, SWWAF_LOG_REMOTE_URL, as the "Request log" section
-// of SPEC.md describes: each line as the message of an RFC 5424 syslog
-// record, over UDP, TCP or TLS. Lines wait in a bounded buffer, so a slow
-// or unreachable endpoint never holds up a request or stdout.
+// of SPEC.md requires and "Sending the log to a syslog server" in
+// docs/request-log.md describes: each line as the message of an RFC 5424
+// syslog record, over UDP, TCP or TLS. Lines wait in a bounded buffer, so
+// a slow or unreachable endpoint never holds up a request or stdout.
 package remotelog
 
 import (

internal/requestlog/requestlog.go

@@ -64,11 +64,10 @@ const LimitHitErrorBurst = "error_burst"
 const timeLayout = "2006-01-02T15:04:05.000Z07:00"
 
 // Line is one request's line in the request log. The field names, and
-// their order, are those of the "Request log" section of SPEC.md. A field
-// that may not apply to a request is left out of its line when it does
-// not.
+// their order, are those of docs/request-log.md. A field that may not
+// apply to a request is left out of its line when it does not.
 //
-//nolint:tagliatelle // SPEC.md's request log names its fields in snake_case
+//nolint:tagliatelle // docs/request-log.md names the fields in snake_case
 type Line struct {
 	Type string `json:"type"`
 

internal/state/state.go

@@ -61,6 +61,7 @@ var (
 	// errMissing is for an entry without a field it needs.
 	errMissing     = errors.New("has no")
 	errCause       = errors.New("is not limit, attack, admin or crowdsec")
+	errExpires     = errors.New("is not after its start")
 	errDestination = errors.New("is not webhook, slack or ntfy")
 	errScope       = errors.New("is not client, net, asn, total or watch")
 	errWaitingList = errors.New(`waiting is a list, but now lists the alerts by ` +
@@ -646,8 +647,10 @@ func (e BanEntry) ban() bans.Ban {
 // client, a start, from which the length of the netblock's next ban is
 // worked out, or an expires, which would make it permanent. A permanent
 // ban's expires is null, which Bans cannot tell from a missing one, so
-// each expires is read again as written. A cause other than limit,
-// attack, admin or crowdsec, most likely misspelt, is refused too.
+// 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, admin or crowdsec, most likely misspelt.
 func (f *bansFile) check(data []byte) error {
 	var written struct {
 		Bans []struct {
@@ -668,6 +671,8 @@ func (f *bansFile) check(data []byte) error {
 			return missing(i, "start")
 		case written.Bans[i].Expires == nil:
 			return missing(i, "expires")
+		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.CauseCrowdSec:

internal/state/state_test.go

@@ -865,6 +865,21 @@ func TestBanWithAnotherCauseStopsTheStart(t *testing.T) {
 		`: entry 4's cause "atack" is not limit, attack, admin or crowdsec`)
 }
 
+func TestBanThatDoesNotEndAfterItsStartStopsTheStart(t *testing.T) {
+	t.Parallel()
+
+	// The first ban ends a second after its start; the second ends as it
+	// starts, or an hour before.
+	for _, expires := range []string{`"2026-10-06T00:00:00Z"`, `"2026-10-05T23:00:00Z"`} {
+		wantRefused(t, bansJSON, `{"version": 1, "bans": [`+
+			`{"netblock": "203.0.113.9/32", "start": "2026-10-06T00:00:00Z", `+
+			`"expires": "2026-10-06T00:00:01Z"}, `+
+			`{"netblock": "203.0.113.10/32", "start": "2026-10-06T00:00:00Z", `+
+			`"expires": `+expires+`}]}`,
+			`: entry 2's expires is not after its start`)
+	}
+}
+
 func TestUnknownVersionStopsTheStart(t *testing.T) {
 	t.Parallel()
 

internal/waf/waf.go

@@ -1,8 +1,8 @@
 // Package waf runs the OWASP Core Rule Set 4.25.0, through Coraza, on the
 // method, the URL with its query and the headers of a request, and on its
 // body while SWWAF_WAF_BODY_LIMIT is set, with the six changes smallwebwaf
-// makes to it, as "Attack detection" under "Configuration surface" in
-// SPEC.md describes them. It reads no response.
+// makes to it, as "Attack detection" under "Settings" in SPEC.md describes
+// them. It reads no response.
 //
 // smallwebwaf writes only to its state directory, so Coraza is built with
 // its no_fs_access tag, as the Dockerfile and script/build build it: of a

script/example-app

@@ -5,12 +5,15 @@
 # served through smallwebwaf, that a second one in a minute bans the
 # client, that a probe for /.env bans another client, which its next
 # request bans for good, that `sv stop` stops smallwebwaf in order, that
-# `docker stop` stops the container without having to kill it, and that
-# a new container on the same volume still refuses the banned client. The
+# `docker stop` stops the container without having to kill it, that a
+# new container on the same volume still refuses the banned client, that
+# a container with its state files on a new volume mounted at the
+# directory SWWAF_STATE_DIR_FILE names becomes healthy, and that one whose
+# SWWAF_STATE_DIR does not exist logs smallwebwaf's message about it. The
 # containers run with SWWAF_LOOKUP_SOURCE=off, so that no address is sent
-# to GeoJS. The containers, the volume and both images are removed however
-# the script ends. Building the app needs network access, for nixpkgs'
-# binary cache. script/check does not run this.
+# to GeoJS. The containers, the volumes and both images are removed
+# however the script ends. Building the app needs network access, for
+# nixpkgs' binary cache. script/check does not run this.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -23,10 +26,15 @@ IMAGE="$NAME-base"
 APP_IMAGE="$NAME-app"
 CONTAINER="$NAME"
 VOLUME="$NAME-state"
+# The volumes of the container whose state directory SWWAF_STATE_DIR_FILE
+# names: its state files, and the file that names their directory.
+MOVED_VOLUME="$NAME-moved-state"
+SETTINGS_VOLUME="$NAME-settings"
 
 cleanup() {
     docker rm --force "$CONTAINER" >/dev/null 2>&1 || true
-    docker volume rm --force "$VOLUME" >/dev/null 2>&1 || true
+    docker volume rm --force "$VOLUME" "$MOVED_VOLUME" "$SETTINGS_VOLUME" \
+        >/dev/null 2>&1 || true
     docker rmi --force "$APP_IMAGE" "$IMAGE" >/dev/null 2>&1 || true
 }
 
@@ -76,6 +84,27 @@ start_container() {
     address="$(docker port "$CONTAINER" 8080/tcp)"
 }
 
+# start_moved_container: run the app's container with the state files on
+# a new volume at /srv/state, which SWWAF_STATE_DIR_FILE names in a file
+# only the smallwebwaf user can read, as under "Settings given as files"
+# in README.md, and wait until it is healthy. smallwebwaf can write the
+# new volume only once the run script has given it to that user.
+start_moved_container() {
+    docker volume create "$MOVED_VOLUME" >/dev/null
+    docker volume create "$SETTINGS_VOLUME" >/dev/null
+    docker run --rm --volume "$SETTINGS_VOLUME:/settings" \
+        --entrypoint bash "$IMAGE" -c 'echo /srv/state > /settings/state-dir &&
+            chown smallwebwaf:smallwebwaf /settings/state-dir &&
+            chmod 0400 /settings/state-dir'
+    docker run --detach --name "$CONTAINER" \
+        --volume "$MOVED_VOLUME:/srv/state" \
+        --volume "$SETTINGS_VOLUME:/etc/smallwebwaf/settings:ro" \
+        --env SWWAF_STATE_DIR_FILE=/etc/smallwebwaf/settings/state-dir \
+        --env SWWAF_LOOKUP_SOURCE=off \
+        "$APP_IMAGE" >/dev/null
+    wait_for "the health check did not pass" healthy
+}
+
 # refused: a request to the container gets 403, SWWAF_BAN_RESPONSE's
 # default.
 refused() {
@@ -140,6 +169,20 @@ main() {
     wait_for "smallwebwaf logged no request refused under the ban" \
         logged '"action":"banned"'
     echo "example-app: a new container on the same volume keeps the ban"
+
+    docker rm --force "$CONTAINER" >/dev/null
+    start_moved_container
+    echo "example-app: the run script gives the state files' directory named" \
+        "by SWWAF_STATE_DIR_FILE to the smallwebwaf user"
+
+    docker rm --force "$CONTAINER" >/dev/null
+    docker run --detach --name "$CONTAINER" \
+        --env SWWAF_STATE_DIR=/srv/missing \
+        --env SWWAF_LOOKUP_SOURCE=off \
+        "$APP_IMAGE" >/dev/null
+    wait_for "smallwebwaf did not report the missing state directory" \
+        logged "SWWAF_STATE_DIR cannot be written"
+    echo "example-app: smallwebwaf reports a state directory that does not exist"
 }
 
 main "$@"

script/gitea-requests

@@ -0,0 +1,336 @@
+#!/bin/sh
+# script/gitea-requests: build the image and run gitea 1.27.3 behind it,
+# with every setting of smallwebwaf at its default but SWWAF_UPSTREAM_URL,
+# which names gitea's container. Then send through it the gitea requests
+# that reading gitea's source found the Core Rule Set refuses, which
+# docs/gitea.md records, and a short sample of gitea's ordinary use:
+# signing in, pages of files and commits, a diff, the API, a push, clone
+# and fetch over HTTP, and two container image pushes. Last, print each
+# request smallwebwaf logged, with what it did with it and the ids of the
+# Core Rule Set's rules that matched it.
+# Every request comes from one client, docker's gateway, so more than
+# SWWAF_ERROR_BURST_THRESHOLD, 30, refusals in a minute would ban it, and
+# the requests after would show as banned. The containers, the network,
+# the images and the files the script makes are removed however it ends;
+# gitea's own image stays, as the base images of a build do. It needs
+# network access, and a docker daemon that pushes to a registry on
+# localhost over plain HTTP, as docker does by default. script/check does
+# not run this.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+# gitea 1.27.3, 2026-08-29
+GITEA_IMAGE="gitea/gitea@sha256:87a67ee09d3ae0d1df5fda5dcda3e2a1f9236a45b0a59025d6e00e46adc43bef"
+
+# Named after this run, so that runs in other clones on the same host
+# never touch each other's.
+NAME="$("$SCRIPT_DIR/projectname")-gitea-$$"
+IMAGE="$NAME-image"
+NETWORK="$NAME"
+SMALLWEBWAF="$NAME-smallwebwaf"
+GITEA="$NAME-gitea"
+
+# gitea's one user, who owns the repository and the container images.
+PASSWORD="owner-password"
+
+BROWSER="Mozilla/5.0 (X11; Linux x86_64; rv:131.0) Gecko/20100101 Firefox/131.0"
+
+# The files the script makes, and smallwebwaf's address once it runs,
+# localhost and the port docker publishes it on: a host name, since the
+# Core Rule Set takes a Host that is an IP address for a warning (920350).
+WORK=""
+address=""
+
+cleanup() {
+    # So that a signal cannot stop it partway through.
+    trap '' HUP INT TERM
+    docker rm --force --volumes "$SMALLWEBWAF" "$GITEA" >/dev/null 2>&1 || true
+    docker network rm "$NETWORK" >/dev/null 2>&1 || true
+    docker rmi --force "$IMAGE" >/dev/null 2>&1 || true
+    if [ -n "$address" ]; then
+        docker rmi --force "$address/owner/python3-app:1" "$address/owner/app:1" \
+            >/dev/null 2>&1 || true
+    fi
+    rm -rf "$WORK"
+}
+
+fail() {
+    echo "gitea-requests: $*" >&2
+    report
+    exit 1
+}
+
+# wait_for <what fails> <command>...: run the command every second until
+# it succeeds, for at most a minute.
+wait_for() {
+    failure="$1"
+    shift
+    tries=0
+    until "$@"; do
+        tries=$((tries + 1))
+        [ "$tries" -lt 60 ] || fail "$failure"
+        sleep 1
+    done
+}
+
+healthy() {
+    status="$(docker inspect --format '{{.State.Health.Status}}' "$SMALLWEBWAF")"
+    [ "$status" = healthy ]
+}
+
+# logged <text>...: a line of smallwebwaf's output holds every text, in
+# any order.
+logged() {
+    lines="$(docker logs "$SMALLWEBWAF" 2>&1)"
+    for text in "$@"; do
+        lines="$(printf '%s\n' "$lines" | grep -F "$text")" || return 1
+    done
+}
+
+# send <label> <path> <curl option>...: send a request for path to
+# smallwebwaf, with label as its X-Request-ID, which the report gives,
+# and keep the body of the answer in $WORK/answer. The Core Rule Set
+# reads that header too, so a label names no file the cases name.
+send() {
+    label="$1"
+    path="$2"
+    shift 2
+    curl --silent --show-error --max-time 30 --output "$WORK/answer" \
+        --header "X-Request-ID: $label" "$@" "http://$address$path"
+}
+
+# page <label> <path> <curl option>...: send the request as a browser
+# does, with the cookies gitea has set. Its Referer is the repository's
+# page, which links to the others, and never a page the Core Rule Set
+# refused: its address would have the next request refused too.
+page() {
+    label="$1"
+    path="$2"
+    shift 2
+    send "$label" "$path" --compressed --user-agent "$BROWSER" \
+        --header "Accept: text/html,application/xhtml+xml,*/*;q=0.8" \
+        --header "Accept-Language: en-US,en;q=0.5" \
+        --cookie "$WORK/cookies" --cookie-jar "$WORK/cookies" \
+        --referer "http://$address/owner/repo" "$@"
+}
+
+# api <label> <path> <curl option>...: send the request as a client of
+# gitea's API does, as the owner.
+api() {
+    label="$1"
+    path="$2"
+    shift 2
+    send "$label" "$path" --user "owner:$PASSWORD" \
+        --header "Accept: application/json" "$@"
+}
+
+# repo_git <git argument>...: run git as the owner, without the host's
+# own git settings, so that nothing it does is kept outside $WORK.
+repo_git() {
+    GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 git \
+        -c user.name=owner -c user.email=owner@example.invalid "$@"
+}
+
+# lines: forty lines of text, enough for a diff to hide some of them.
+lines() {
+    i=1
+    while [ "$i" -le 40 ]; do
+        echo "line $i"
+        i=$((i + 1))
+    done
+}
+
+# make_repository: create the repository owner/repo, holding a file of
+# each name the cases name, and push it, which is the push over HTTP of
+# the sample. The second commit adds a line at the end of Runtime.java,
+# so that its diff hides the lines above.
+make_repository() {
+    status="$(api create-repository /api/v1/user/repos \
+        --header "Content-Type: application/json" --data '{"name":"repo"}' \
+        --write-out '%{http_code}')"
+    [ "$status" = 201 ] || fail "creating the repository was answered $status"
+
+    dir="$WORK/repo"
+    repo_git init --quiet --initial-branch=main "$dir"
+    for file in \
+        src/java.base/share/classes/java/lang/Runtime.java \
+        java.lang.String.md \
+        META-INF/services/org.apache.commons.logging.LogFactory \
+        document.write.js \
+        process.env.d.ts \
+        test/fixtures/__proto__.json \
+        install-script.sh \
+        src/backend/catalog/information_schema.sql \
+        .../notes.txt \
+        README.md; do
+        mkdir -p "$dir/$(dirname "$file")"
+        lines >"$dir/$file"
+        repo_git -C "$dir" add "$file"
+    done
+    repo_git -C "$dir" commit --quiet --message "Add the files"
+    echo "line 41" >>"$dir/src/java.base/share/classes/java/lang/Runtime.java"
+    repo_git -C "$dir" commit --quiet --all --message "Add a line"
+
+    repo_git -C "$dir" -c "http.extraHeader=X-Request-ID: git-push" push --quiet \
+        "http://owner:$PASSWORD@$address/owner/repo.git" main ||
+        fail "the push of the repository failed"
+}
+
+# browse: sign in, then open pages as a person does. The cases are those
+# of https://git.eeqj.de/sneak/smallwebwaf/issues/30.
+browse() {
+    # Case: gitea sends a visitor who is not signed in to the sign-in
+    # page, with the page asked for in redirect_to, when that page needs
+    # signing in, as a file's edit page does.
+    page issue-30-case /owner/repo/_edit/main/document.write.js --location
+
+    page sign-in /user/login
+    status="$(page sign-in /user/login --header "Origin: http://$address" \
+        --data-urlencode user_name=owner --data-urlencode "password=$PASSWORD" \
+        --write-out '%{http_code}')"
+    [ "$status" = 303 ] || fail "signing in was answered $status"
+
+    page browse /
+    page browse /owner/repo
+    page browse /owner/repo/src/branch/main/README.md
+    page browse /owner/repo/commits/branch/main
+    page browse "/owner/repo/commit/$(repo_git -C "$WORK/repo" rev-parse HEAD)"
+
+    # Case: expanding the lines the diff hides, by the link the diff's
+    # page gives for it.
+    excerpt="$(sed -n 's/.*data-fetch-url="\([^"]*blob_excerpt[^"]*\)".*/\1/p' \
+        "$WORK/answer" | head -n 1 | sed 's/&amp;/\&/g')"
+    [ -n "$excerpt" ] || fail "the diff's page has no link to its hidden lines"
+    page issue-30-case "$excerpt"
+
+    # Cases: the commit graph of one file, and the pages of files whose
+    # path the Core Rule Set takes for an attack.
+    page issue-30-case "/owner/repo/graph?file=src/java.base/share/classes/java/lang/Runtime.java"
+    page issue-30-case /owner/repo/src/branch/main/META-INF/services/org.apache.commons.logging.LogFactory
+    page issue-30-case /owner/repo/src/branch/main/java.lang.String.md
+    page issue-30-case /owner/repo/src/branch/main/process.env.d.ts
+    page issue-30-case /owner/repo/src/branch/main/.../notes.txt
+}
+
+# call_api: the API's calls the cases name: the commits of a file, for a
+# file of each name the Core Rule Set takes for an attack in the query
+# parameter path, and the file-contents call, which takes its list of
+# files as JSON in the query parameter body.
+call_api() {
+    for file in \
+        src/java.base/share/classes/java/lang/Runtime.java \
+        java.lang.String.md \
+        document.write.js \
+        process.env.d.ts \
+        test/fixtures/__proto__.json \
+        install-script.sh \
+        src/backend/catalog/information_schema.sql; do
+        api issue-30-case /api/v1/repos/owner/repo/commits --get --data-urlencode "path=$file"
+    done
+    api issue-30-case /api/v1/repos/owner/repo/file-contents --get \
+        --data-urlencode 'body={"files":["src/java.base/share/classes/java/lang/Runtime.java"]}'
+}
+
+# push_images: push a container image to owner/python3-app, then the same
+# image to owner/app. For the second, the case, docker asks gitea to take
+# its layer from owner/python3-app, naming it in the query parameter
+# from. docker sends no X-Request-ID, so its requests have the ids
+# smallwebwaf gives them. The image is one small file, imported rather
+# than built.
+push_images() {
+    echo "$NAME" >"$WORK/layer.txt"
+    tar -cf - -C "$WORK" layer.txt |
+        docker import - "$address/owner/python3-app:1" >/dev/null
+    docker tag "$address/owner/python3-app:1" "$address/owner/app:1"
+
+    # The login is written here rather than made with docker login, which
+    # would keep it in the host's credential helper when it has one.
+    mkdir "$WORK/docker"
+    printf '{"auths":{"%s":{"auth":"%s"}}}\n' "$address" \
+        "$(printf 'owner:%s' "$PASSWORD" | base64)" >"$WORK/docker/config.json"
+    for image in "$address/owner/python3-app:1" "$address/owner/app:1"; do
+        DOCKER_CONFIG="$WORK/docker" docker push --quiet "$image" >/dev/null ||
+            echo "gitea-requests: the push of $image failed" >&2
+    done
+}
+
+# clone_and_fetch: the clone and fetch over HTTP of the sample.
+clone_and_fetch() {
+    repo_git -c "http.extraHeader=X-Request-ID: git-clone" clone --quiet \
+        "http://owner:$PASSWORD@$address/owner/repo.git" "$WORK/clone" ||
+        fail "the clone failed"
+    repo_git -C "$WORK/clone" -c "http.extraHeader=X-Request-ID: git-fetch" fetch --quiet ||
+        fail "the fetch failed"
+}
+
+# field <name> <line>: the text of the field name in line, a line of the
+# request log, or nothing when it has none.
+field() {
+    printf '%s\n' "$2" | sed -n "s/.*\"$1\":\"\([^\"]*\)\".*/\1/p"
+}
+
+# report: print a line for each request smallwebwaf logged, but its
+# health checks: what it did with the request, the ids of the Core Rule
+# Set's rules that matched it, its X-Request-ID, and the request.
+# waf_blocked is a refusal by the Core Rule Set, and forward a request
+# passed on to gitea, whatever gitea answered.
+report() {
+    docker logs "$SMALLWEBWAF" 2>/dev/null | grep '"type":"request"' |
+        grep -v '"action":"admin"' | sed 's/\\u0026/\&/g' >"$WORK/requests"
+    while IFS= read -r line; do
+        ids="$(printf '%s\n' "$line" | sed -n 's/.*"waf_rule_ids":\[\([0-9,]*\)\].*/\1/p')"
+        query="$(field query "$line")"
+        printf '%-11s %-13s %-17s %s %s%s\n' "$(field action "$line")" "${ids:--}" \
+            "$(field request_id "$line")" "$(field method "$line")" \
+            "$(field path "$line")" "${query:+?$query}"
+    done <"$WORK/requests"
+    echo "gitea-requests: $(grep -c . "$WORK/requests") requests," \
+        "$(grep -c '"action":"waf_blocked"' "$WORK/requests") refused by the Core Rule Set"
+}
+
+main() {
+    cd "$ROOT"
+    trap cleanup EXIT
+    trap 'exit 1' HUP INT TERM
+    WORK="$(mktemp -d)"
+
+    docker build --no-cache -t "$IMAGE" .
+
+    # smallwebwaf first, so that gitea can be given the address it is
+    # reached at, and gitea's image pulled before, so that gitea starts
+    # within the minute smallwebwaf's health check waits for it.
+    docker pull --quiet "$GITEA_IMAGE" >/dev/null
+    docker network create "$NETWORK" >/dev/null
+    docker run --detach --name "$SMALLWEBWAF" --network "$NETWORK" \
+        --publish 127.0.0.1::8080 \
+        --env SWWAF_UPSTREAM_URL="http://$GITEA:3000" \
+        "$IMAGE" >/dev/null
+    published="$(docker port "$SMALLWEBWAF" 8080/tcp)"
+    address="localhost:${published##*:}"
+
+    docker run --detach --name "$GITEA" --network "$NETWORK" \
+        --env GITEA__security__INSTALL_LOCK=true \
+        --env GITEA__server__ROOT_URL="http://$address/" \
+        "$GITEA_IMAGE" >/dev/null
+    # smallwebwaf's health check passes once gitea takes connections.
+    wait_for "the health check did not pass" healthy
+    docker exec --user git "$GITEA" gitea admin user create --admin \
+        --username owner --password "$PASSWORD" --email owner@example.invalid \
+        --must-change-password=false >/dev/null
+
+    make_repository
+    browse
+    call_api
+    push_images
+    clone_and_fetch
+
+    # The fetch's last request is the last of all; once it is logged, so
+    # is every other.
+    wait_for "smallwebwaf logged no line for the fetch" \
+        logged '"request_id":"git-fetch"' '"method":"POST"'
+    report
+}
+
+main "$@"

share/smallwebwaf.run

@@ -5,12 +5,32 @@ set -euo pipefail
 # exits; the wait spaces out the restarts. The state directory and every
 # file in it are given to the smallwebwaf user, so that a volume mounted
 # there needs no change of owner; chown -R changes a symbolic link itself,
-# never what it points to. exec, so that the signal `sv stop` sends
-# reaches smallwebwaf itself.
+# never what it points to. When SWWAF_STATE_DIR, in either form, cannot be
+# read or is not the absolute path of a directory, no owner is changed,
+# and smallwebwaf starts and stops with a message naming the setting. A
+# change of owner that fails, as on a volume mounted read-only, does not
+# end the script either: smallwebwaf reports a directory it cannot write.
+# exec, so that the signal `sv stop` sends reaches smallwebwaf itself.
 main() {
     sleep 1
-    chown -R smallwebwaf:smallwebwaf "${SWWAF_STATE_DIR:-/var/lib/smallwebwaf}"
+    local dir
+    if dir="$(state_dir)" && [[ "$dir" == /* && -d "$dir" ]]; then
+        chown -R smallwebwaf:smallwebwaf "$dir" || true
+    fi
     exec chpst -u smallwebwaf:smallwebwaf /usr/local/bin/smallwebwaf
 }
 
+# state_dir prints SWWAF_STATE_DIR, /var/lib/smallwebwaf when it is unset,
+# or what is in the file SWWAF_STATE_DIR_FILE names, less every newline at
+# its end. It fails when both are set or the file cannot be read.
+state_dir() {
+    if [[ ! -v SWWAF_STATE_DIR_FILE ]]; then
+        printf '%s\n' "${SWWAF_STATE_DIR-/var/lib/smallwebwaf}"
+    elif [[ ! -v SWWAF_STATE_DIR ]]; then
+        cat -- "$SWWAF_STATE_DIR_FILE" 2>/dev/null
+    else
+        return 1
+    fi
+}
+
 main "$@"