README: what rproxy gives an app without waf (closes #386)

Adds a paragraph to "What it does" listing what rproxy enforces with
default settings whether or not waf answers: malformed requests, methods,
header size, request and response times, body sizes, idle connections.
After the list, it says which header limits are waf's.

Removes the "Slow and oversized requests" bullet, which the new list
states with figures.

Model: opus-5-5

README.md

@@ -10,10 +10,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
@@ -22,7 +22,26 @@ shipped in one image, with two commands that do this together:
 The site keeps answering while `waf` is down, slow or restarting: without an
 answer in time, `rproxy` passes the request to the app.
 
-It protects against:
+`rproxy` also protects the app on its own, whether or not `waf` answers. With
+the default settings, `rproxy`:
+
+- answers `400` to a malformed request, such as a broken header line or a
+  missing `Host`;
+- answers `405` to a method it does not pass on, such as `TRACE`;
+- answers `431` to a request line and headers over 32 KiB together;
+- gives the visitor 60 seconds to send the request line and headers, and then 60
+  seconds more for the whole request to reach the app;
+- answers `413` to a request body over 100 MiB;
+- gives the app's answer 30 minutes to reach the visitor, counted from the end
+  of the request;
+- answers `502` in place of an app's answer whose body is over 1 GiB, or cuts it
+  off if it has started;
+- closes a kept-open connection after 120 seconds idle.
+
+`rproxy` does not limit the number of headers. `waf` limits the number of
+headers and cookies, and the length of the request line and of each header line.
+
+Together, `rproxy` and `waf` protect against:
 
 - Scrapers that fetch every page of a site, all day. Each client gets a limit on
   requests and on body bytes per minute, per hour and per day. The defaults
@@ -44,8 +63,6 @@ It protects against:
       limit, so that they are banned sooner;
     - refuse or limit clients on a blocklist, a DNS blocklist, or with a high
       AbuseIPDB score.
-- Slow and oversized requests. Every request and every answer has a time limit
-  and a size limit.
 
 For the operator, it:
 
@@ -57,7 +74,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.
@@ -89,61 +107,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`
@@ -194,13 +171,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
 
@@ -208,7 +185,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.

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