README: blocks misbehaving scrapers, not normal ones (closes #387)

The opening now says a scraper within the default limits is left alone
whatever its user agent, and lists what bans a client: the rate and byte
limits, a probe for a secret path, and the refusal limit.

Model: opus-5-5

Dockerfile

@@ -161,20 +161,6 @@ RUN git checkout --quiet --detach b4b2c785308b1ce785b6155c7fe5f16879080193 \
 # ubuntu 26.04, 2026-09-27
 FROM ubuntu@sha256:f144425ff09be612d6d9ad965196e9cdc23dae1f42110a8a11a3e9a8198759f7
 
-# The image's own labels, in place of the ones it would inherit from
-# Ubuntu's. script/docker and script/cibuild pass the build arguments;
-# a build that passes none labels the image unknown rather than leave
-# Ubuntu's values.
-ARG VERSION=unknown
-ARG CREATED=unknown
-ARG REVISION=unknown
-LABEL org.opencontainers.image.title="smallwebwaf" \
-    org.opencontainers.image.description="A web application firewall for self-hosted web apps: sww rproxy in front of an app, and sww waf, which decides." \
-    org.opencontainers.image.version="${VERSION}" \
-    org.opencontainers.image.created="${CREATED}" \
-    org.opencontainers.image.revision="${REVISION}" \
-    org.opencontainers.image.source="https://git.eeqj.de/sneak/smallwebwaf"
-
 # runit's install creates its _runit-log user with minsysusers, which
 # reads this file in place of runit's /usr/lib/sysusers.d/runit.conf.
 # runit's line leaves out the shell, and minsysusers prints a Perl

README.md

@@ -5,17 +5,20 @@
 requests of misbehaving scrapers, scanners and other abusers before they reach
 an app.
 
-With the default settings, a client is banned when it does any of these:
+It does not block scrapers as such. A scraper that stays within the limits below
+is left alone, whatever its user agent. With the default settings, a client is
+banned when it does any of these:
 
 - makes more than 120 requests in a minute, 1500 in an hour or 6000 in a day;
 - moves more than `50G` of request and response bodies in an hour, or `100G` in
   a day;
-- asks for a secret or backup file, such as `/.env` or `/.git/config`;
+- asks for a path no real visitor asks for, such as `/.env` or `/.git/config`;
-- sends a user agent that names a security scanner, such as `sqlmap` or `nikto`;
 - has more than 30 requests in a minute refused as probes or attacks.
 
-A scraper that does none of these is left alone. A scraper that waits 15 seconds
+A scraper that waits 15 seconds between requests stays under every one of these
-between requests stays under the rate limits.
+limits. The user agent alone gets a client refused only when it names a security
+scanner, such as `sqlmap` or `nikto`. Settings you add, such as a refused
+country or a blocklist, can refuse any client.
 
 ## What it does
 
@@ -23,10 +26,10 @@ A web application firewall reads each request on its way to a web app and
 refuses the ones that look like abuse. `smallwebwaf` is one program, `sww`,
 shipped in one image, with two commands that do this together:
 
-- `sww rproxy` is a small reverse proxy in front of one app. It sits behind a
+- `sww rproxy` is a small reverse proxy in front of one app. traefik routes to
-  TLS-terminating proxy, such as traefik, nginx or Caddy. It asks `waf` about
+  it. It asks `waf` about each request, passes the allowed ones to the app, and
-  each request, passes the allowed ones to the app, and passes the app's answers
+  passes the app's answers back. It keeps nothing between requests and writes
-  back. It keeps nothing between requests and writes nothing to disk.
+  nothing to disk.
 - `sww waf` decides. It runs the checks and keeps the bans, the counters and
   each client's history. One `waf` serves many sites: a client banned through
   one site is refused on all of them, and its requests on all of them count
@@ -70,7 +73,8 @@ For the operator, it:
 
 Not built, and not planned:
 
-- TLS and routing by host name. Both stay with the TLS-terminating proxy.
+- TLS and routing by host name. Both stay with traefik, the reverse proxy in
+  front of `rproxy`.
 - Browser challenges such as captchas.
 - A web console, or a configuration file.
 - Defence against floods large enough to fill the host's network link.
@@ -102,61 +106,20 @@ accepts connections, whether or not `waf` answers; in `waf`'s container, once
 The usual setup is three containers on one private network:
 
 - the app;
-- `rproxy`, in front of the app, which the TLS-terminating proxy forwards to:
+- `rproxy`, in front of the app, which traefik routes to:
   `SWW_RPROXY_WAF_BACKEND` names `waf` and `SWW_RPROXY_UPSTREAM_URL` names the
   app;
 - `waf`, with `SWW_COMMAND=waf` and a volume at `/var/lib/sww` for its state
   files.
 
-Publish no port of the app or of `waf`. Anything on that network can reach the
+Point traefik's labels at port 8080 of `rproxy`
-app around `rproxy`, and can ask `waf` questions, so the network holds only what
+(`traefik.http.services.<name>.loadbalancer.server.port=8080`). Publish no port
-you trust. Each further app adds its own container and its own `rproxy`, whose
+of the app or of `waf`. Anything on that network can reach the app around
+`rproxy`, and can ask `waf` questions, so the network holds only what you trust.
+Each further app adds its own container and its own `rproxy`, whose
 `SWW_RPROXY_WAF_BACKEND` names the same `waf`. The "Smallest setup" example
 below shows this shape.
 
-### The TLS-terminating proxy
-
-`rproxy` serves plain HTTP. It runs behind any TLS-terminating proxy, such as
-traefik, nginx or Caddy. The TLS-terminating proxy must:
-
-- forward each request to port 8080 of `rproxy` over plain HTTP;
-- keep the visitor's `Host` header;
-- add the visitor's address to `X-Forwarded-For`;
-- set `X-Forwarded-Proto` to the scheme the visitor used;
-- close an unused connection to `rproxy` in under 120 seconds;
-- connect to `rproxy` from an address in `SWW_RPROXY_TRUSTED_PROXIES`, by
-  default `10.0.0.0/8`, `172.16.0.0/12` or `192.168.0.0/16`.
-
-From any other address, `rproxy` ignores the forwarded headers and takes the
-TLS-terminating proxy for the visitor. Every visitor then shares one address,
-and one ban.
-
-traefik and Caddy keep the `Host` header and set both forwarded headers by
-default. traefik's Docker label
-`traefik.http.services.<name>.loadbalancer.server.port=8080` names the port.
-Caddy keeps an unused connection for 120 seconds by default, so its site
-shortens that to 90 seconds:
-
-```caddyfile
-reverse_proxy rproxy:8080 {
-    transport http {
-        keepalive 90s
-    }
-}
-```
-
-By default nginx sends the host in `proxy_pass` as `Host` and sets neither
-forwarded header, so its site sets all three:
-
-```nginx
-location / {
-    proxy_pass http://rproxy:8080;
-    proxy_set_header Host $host;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-}
-```
-
 ### `rproxy` in the app's container
 
 An app's image can instead be built on the `smallwebwaf` image, so that `rproxy`
@@ -207,13 +170,13 @@ entrypoint starts `rproxy` and the app side by side, each as its own user. Run
 the app's image with `SWW_RPROXY_WAF_BACKEND` set. `deploy/example-app` is such
 an app, and the "`rproxy` beside the app" example below runs one.
 
-The app's TCP peer is `rproxy`. The app sees the headers the TLS-terminating
+The app sees the headers traefik sent, with traefik's address added to
-proxy sent, with that proxy's address added to `X-Forwarded-For`. So the app
+`X-Forwarded-For`, from a TCP peer that is `rproxy`. So the app must trust
-must trust `rproxy`'s address for forwarded headers. In a container of its own,
+`rproxy`'s address for forwarded headers. In a container of its own, `rproxy` is
-`rproxy` is on the private network, which the usual default of a trusted-proxy
+on the private network, which the usual default of a trusted-proxy setting
-setting covers. Beside the app, its address is `127.0.0.1` or `::1`, which the
+covers. Beside the app, its address is `127.0.0.1` or `::1`, which the private
-private ranges leave out, so the app's own setting must name them too, as
+ranges leave out, so the app's own setting must name them too, as `app.run`
-`app.run` does.
+does.
 
 ### Checking that it works
 
@@ -221,7 +184,7 @@ private ranges leave out, so the app's own setting must name them too, as
   `healthy` for each container of `smallwebwaf`.
 - A log line with `"msg":"starting"` gives the version, the address and every
   setting in effect, with secrets masked.
-- A request to the site through the TLS-terminating proxy gets the app's answer.
+- A request to the site through traefik gets the app's answer.
   `https://<site>/_sww/healthz` answers `ok`. `waf`'s log lines about the
   request have `"action":"forward"`.
 - To see a refusal without banning yourself, run `waf` with

SPEC.md

@@ -3,7 +3,7 @@
 `smallwebwaf` is a web application firewall for self-hosted apps. It is one
 binary, `sww`, and two of its commands do the work:
 
-- `sww rproxy` is a reverse proxy between a TLS-terminating proxy and one app.
+- `sww rproxy` is a reverse proxy between traefik and one app.
 - `sww waf` decides what happens to each request, for many sites.
 
 This document says what it must do and why, each requirement once. Everything in
@@ -45,8 +45,7 @@ never as a time.
 
 ## Non-goals
 
-- TLS, certificates and routing by host name. Those are the job of the
+- TLS, certificates and routing by host name. Those are traefik's job.
-  TLS-terminating proxy, such as traefik, nginx or Caddy.
 - More than one app behind one `rproxy`. Each app has its own.
 - Browser challenges such as captchas or proof of work. If wanted, chain Anubis
   between `rproxy` and the app.
@@ -1944,10 +1943,10 @@ leave out a cookie only when its name matches exactly, case included.
 ### Ban lengths, response and scope
 
 `SWW_WAF_BAN_RESPONSE` is `403` by default, which makes a ban easy to recognise
-when debugging; `429` and `close` are the alternatives. `close` does not leave
+when debugging; `429` and `close` are the alternatives. Behind traefik, `close`
-the client unanswered: the TLS-terminating proxy answers `502`, as it does
+does not leave the client unanswered: traefik answers `502`, as it does whenever
-whenever its backend drops a connection. `SWW_WAF_BAN_SCOPE_V4_PREFIX` widens an
+its backend drops a connection. `SWW_WAF_BAN_SCOPE_V4_PREFIX` widens an IPv4 ban
-IPv4 ban to the surrounding netblock. The four ban lengths are under "Bans".
+to the surrounding netblock. The four ban lengths are under "Bans".
 
 ### Reputation
 
@@ -2772,9 +2771,9 @@ its whole body. The visitor gets that answer at once, and the connection closes
 after it.
 
 The largest request line and headers is 32 KiB. A kept-open connection is closed
-after 120 seconds idle. Neither has a setting. The TLS-terminating proxy should
+after 120 seconds idle. Neither has a setting. traefik, by default, closes an
-close an unused connection sooner, so that it never sends a request on a
+unused connection after 90 seconds. So traefik closes first, and never sends a
-connection `rproxy` is closing. traefik closes one after 90 seconds by default.
+request on a connection `rproxy` is closing.
 
 What the visitor gets when a limit is passed:
 
@@ -2825,16 +2824,14 @@ chooses: `waf` runs `waf`, and with it unset the image runs `rproxy`.
 The usual setup is three containers on one private network:
 
 - the app;
-- `rproxy`, which the TLS-terminating proxy forwards to, with
+- `rproxy`, which traefik routes to, with `SWW_RPROXY_UPSTREAM_URL` naming the
-  `SWW_RPROXY_UPSTREAM_URL` naming the app and `SWW_RPROXY_WAF_BACKEND` naming
+  app and `SWW_RPROXY_WAF_BACKEND` naming `waf`;
-  `waf`;
 - `waf`, with `SWW_COMMAND=waf` and a volume for its state files.
 
 Each further app adds its own container and its own `rproxy`, whose
 `SWW_RPROXY_WAF_BACKEND` names the same `waf` (see "Sites"). Anything on that
 network can reach an app around `rproxy`, and can ask `waf` questions or send it
-reports. So the network holds only what you trust. `README.md` lists what the
+reports. So the network holds only what you trust.
-TLS-terminating proxy must do.
 
 ### `rproxy` in the app's container
 
@@ -2906,10 +2903,10 @@ process that stops at start is started again every second, not in a tight loop.
   container's output, which `docker logs` shows.
 - When a service exits, runit runs its `run` script again, and the container
   does not stop. Beside an app, the other process keeps running.
-- While `rproxy` is down, the TLS-terminating proxy answers `502`. While the app
+- While `rproxy` is down, traefik answers `502`. While the app is down, `rproxy`
-  is down, `rproxy` answers `502`, which is not a client offence. While `waf` is
+  answers `502`, which is not a client offence. While `waf` is down,
-  down, `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides (see "Without an
+  `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides (see "Without an answer
-  answer from `waf`").
+  from `waf`").
 - Only faults found at start stop `waf`:
     - invalid configuration;
     - a lookup database that is missing or unreadable;
@@ -2942,26 +2939,23 @@ checks:
 - With `SWW_COMMAND` unset, empty or `rproxy`, it passes while `rproxy` answers
   that request on `127.0.0.1`, at the port in `SWW_RPROXY_LISTEN_ADDR`, and the
   app accepts connections at `SWW_RPROXY_UPSTREAM_URL`. It does not ask `waf`,
-  so that the site stays in the TLS-terminating proxy's routes while `waf` is
+  so that the site stays in traefik's routes while `waf` is down.
-  down.
 - With any other value, it fails with a message naming `SWW_COMMAND` and its
   value.
 
-A TLS-terminating proxy that reads Docker's health status, as traefik does,
+traefik sends a container no requests until it shows as healthy. So the check
-sends a container no requests until it shows as healthy. So the check runs every
+runs every second from the container's start until it first passes, for up to a
-second from the container's start until it first passes, for up to a minute, and
+minute, and every 30 seconds after that. An app with a health check of its own
-every 30 seconds after that. An app with a health check of its own can replace
+can replace the image's `HEALTHCHECK` with one that checks both.
-the image's `HEALTHCHECK` with one that checks both.
 
 ### Ports
 
 `rproxy` listens on no port but the one in `SWW_RPROXY_LISTEN_ADDR`, 8080 by
-default, which the TLS-terminating proxy forwards to. It passes requests to the
+default, which traefik routes to. It passes requests to the app at
-app at `SWW_RPROXY_UPSTREAM_URL`, `http://127.0.0.1:8081` by default. Another
+`SWW_RPROXY_UPSTREAM_URL`, `http://127.0.0.1:8081` by default. Another port may
-port may be set: the health check follows the setting, and the TLS-terminating
+be set: the health check follows the setting, and traefik's port label
-proxy must name it, as traefik's port label
+(`traefik.http.services.<name>.loadbalancer.server.port`) must name it. An app
-(`traefik.http.services.<name>.loadbalancer.server.port`) does. An app beside
+beside `rproxy` must leave that port free.
-`rproxy` must leave that port free.
 
 `waf` listens on no port but the one in `SWW_WAF_LISTEN_ADDR`, 8080 by default.
 The questions, the reports and its own endpoints all come there.
@@ -3002,9 +2996,9 @@ in `docs/settings.md` shows the commands.
 ### Forwarded headers
 
 The app's TCP peer is `rproxy`, and the `X-Forwarded-For` the app receives ends
-with the TLS-terminating proxy's address, which `rproxy` adds after the
+with traefik's address, which `rproxy` adds after the visitor's. So the app must
-visitor's. So the app must trust `rproxy`'s address for forwarded headers,
+trust `rproxy`'s address for forwarded headers, besides the private address
-besides the private address ranges the TLS-terminating proxy is on.
+ranges traefik is on.
 
 - In a container of its own, `rproxy`'s address is on the private network. The
   usual default for a trusted-proxy setting, the private ranges, covers it.

deploy/example-app/Dockerfile

@@ -9,10 +9,6 @@
 ARG SWW_IMAGE=smallwebwaf
 FROM ${SWW_IMAGE}
 
-# Its own title and description, in place of the smallwebwaf image's.
-LABEL org.opencontainers.image.title="smallwebwaf-example-app" \
-    org.opencontainers.image.description="An example app built on the smallwebwaf image."
-
 # Packages the app needs, from the nixpkgs in the image.
 RUN nix-env -iA nixpkgs.busybox
 

docs/request-log.md

@@ -68,8 +68,7 @@ Every one of these lines has:
 ### Request detail
 
 - `request_id`: the id `rproxy` made for the request when it arrived.
-- `peer_ip`: the address of `rproxy`'s TCP peer, normally the TLS-terminating
+- `peer_ip`: the address of `rproxy`'s TCP peer, normally traefik.
-  proxy.
 - `forwarded_for`: the `X-Forwarded-For` header the visitor's request came with.
 - `client_group`: the client as rate limiting counts it, an IPv4 address as a
   /32 or an IPv6 group.

docs/settings.md

@@ -478,9 +478,9 @@ start, and an invalid value stops the start. Any can be given as a file, as a
   `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16`): the netblocks whose
   `X-Forwarded-For` is believed. Set but empty, it trusts nothing. A client
   outside these netblocks cannot claim another address. Where other containers
-  reach `rproxy` directly, or visitors on a private network reach the
+  reach `rproxy` directly, or visitors on a private network reach traefik, they
-  TLS-terminating proxy, they can name another address in the header. Narrowing
+  can name another address in the header. Narrowing the setting to traefik's own
-  the setting to the TLS-terminating proxy's own network closes that gap.
+  network closes that gap.
 
 ## The image's command
 

script/cibuild

@@ -20,13 +20,8 @@ main() {
     # the version a build stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    revision="$(git rev-parse HEAD 2>/dev/null || true)"
-    [ -n "$revision" ] || revision="unknown"
-    created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
     docker build --no-cache \
         --build-arg VERSION="$version" \
-        --build-arg REVISION="$revision" \
-        --build-arg CREATED="$created" \
         -t "$("$SCRIPT_DIR/projectname")" .
 }
 

script/docker

@@ -16,13 +16,8 @@ main() {
     # the version a build stage derives from the .git in the context.
     version="$(git describe --tags --always --dirty 2>/dev/null || true)"
     [ -n "$version" ] || version="unknown"
-    revision="$(git rev-parse HEAD 2>/dev/null || true)"
-    [ -n "$revision" ] || revision="unknown"
-    created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
     docker build --no-cache \
         --build-arg VERSION="$version" \
-        --build-arg REVISION="$revision" \
-        --build-arg CREATED="$created" \
         -t "$("$SCRIPT_DIR/projectname")" .
 }