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,11 +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 the
+- `sww rproxy` is a small reverse proxy in front of one app. traefik routes to
-  reverse proxy that terminates TLS, such as traefik, nginx or Caddy. It asks
+  it. It asks `waf` about each request, passes the allowed ones to the app, and
-  `waf` about each request, passes the allowed ones to the app, and passes the
+  passes the app's answers back. It keeps nothing between requests and writes
-  app's answers back. It keeps nothing between requests and writes nothing to
+  nothing to disk.
-  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
@@ -23,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
@@ -45,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:
 
@@ -58,8 +74,8 @@ For the operator, it:
 
 Not built, and not planned:
 
-- TLS and routing by host name. Both stay with the reverse proxy in front of
+- TLS and routing by host name. Both stay with traefik, the reverse proxy in
-  `rproxy`.
+  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.
@@ -91,48 +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 reverse proxy that terminates TLS
+- `rproxy`, in front of the app, which traefik routes to:
-  forwards to: `SWW_RPROXY_WAF_BACKEND` names `waf` and
+  `SWW_RPROXY_WAF_BACKEND` names `waf` and `SWW_RPROXY_UPSTREAM_URL` names the
-  `SWW_RPROXY_UPSTREAM_URL` names the app;
+  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 reverse proxy in front
-
-`rproxy` serves plain HTTP. It runs behind any reverse proxy that terminates
-TLS, such as traefik, nginx or Caddy. That 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;
-- 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
-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, and
-Caddy's `reverse_proxy rproxy:8080` needs nothing more. nginx sets none of the
-headers by default, so its site names them:
-
-```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`
@@ -183,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 sees the headers the reverse proxy in front sent, with that proxy's
+The app sees the headers traefik sent, with traefik's address added to
-address added to `X-Forwarded-For`, from a TCP peer that is `rproxy`. 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
 
@@ -197,9 +185,9 @@ 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 reverse proxy in front gets the app's
+- A request to the site through traefik gets the app's answer.
-  answer. `https://<site>/_sww/healthz` answers `ok`. `waf`'s log lines about
+  `https://<site>/_sww/healthz` answers `ok`. `waf`'s log lines about the
-  the request have `"action":"forward"`.
+  request have `"action":"forward"`.
 - To see a refusal without banning yourself, run `waf` with
   `SWW_WAF_MODE=observe` and ask for `/.env`. The request reaches the app.
   `waf`'s log lines have `"would_action":"temporarily_banned"` and

SPEC.md

@@ -3,8 +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 one app and the reverse proxy that
+- `sww rproxy` is a reverse proxy between traefik and one app.
-  terminates TLS.
 - `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
@@ -46,8 +45,7 @@ never as a time.
 
 ## Non-goals
 
-- TLS, certificates and routing by host name. Those are the job of the reverse
+- TLS, certificates and routing by host name. Those are traefik's job.
-  proxy in front of `rproxy`, 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.
@@ -1945,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 reverse proxy in front 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
 
@@ -2773,10 +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 reverse proxy in front 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.
-nginx, by default, opens a new connection for each request.
 
 What the visitor gets when a limit is passed:
 
@@ -2827,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 reverse proxy that terminates TLS 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. "The reverse proxy in front"
+reports. So the network holds only what you trust.
-in `README.md` lists what that proxy must do.
 
 ### `rproxy` in the app's container
 
@@ -2908,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 reverse proxy in front answers `502`. While the
+- While `rproxy` is down, traefik answers `502`. While the app is down, `rproxy`
-  app is down, `rproxy` answers `502`, which is not a client offence. While
+  answers `502`, which is not a client offence. While `waf` is down,
-  `waf` is down, `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides (see
+  `SWW_RPROXY_WAF_BACKEND_NO_ANSWER_DISPOSITION` decides (see "Without an answer
-  "Without an answer from `waf`").
+  from `waf`").
 - Only faults found at start stop `waf`:
     - invalid configuration;
     - a lookup database that is missing or unreadable;
@@ -2944,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 routes of the reverse proxy in front while `waf`
+  so that the site stays in traefik's routes while `waf` is down.
-  is down.
 - With any other value, it fails with a message naming `SWW_COMMAND` and its
   value.
 
-A reverse proxy that reads Docker's health status, as traefik does, sends a
+traefik sends a container no requests until it shows as healthy. So the check
-container no requests until it shows as healthy. So the check runs every second
+runs every second from the container's start until it first passes, for up to a
-from the container's start until it first passes, for up to a minute, and every
+minute, and every 30 seconds after that. An app with a health check of its own
-30 seconds after that. An app with a health check of its own can replace the
+can replace the image's `HEALTHCHECK` with one that checks both.
-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 reverse proxy in front 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 reverse proxy in
+be set: the health check follows the setting, and traefik's port label
-front 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.
@@ -3004,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 address of the reverse proxy in front, 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 that 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 reverse proxy in
+- `peer_ip`: the address of `rproxy`'s TCP peer, normally traefik.
-  front of it.
 - `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 reverse
+  reach `rproxy` directly, or visitors on a private network reach traefik, they
-  proxy in front, they can name another address in the header. Narrowing the
+  can name another address in the header. Narrowing the setting to traefik's own
-  setting to that proxy's own network closes that gap.
+  network closes that gap.
 
 ## The image's command