From f2fd9cd734bd560b33fecc917c14d1d321e0bc15 Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 19 Nov 2026 07:45:32 +0000 Subject: [PATCH 1/7] README: compose example for the open internet, with common waf settings (closes #381) A new example puts one gitea behind traefik, rproxy and waf. waf sets nine settings most sites use, then eight more commented out, each with what it does and when to set it. Model: opus-5-5 --- README.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c947ac5..2bf15cf 100644 --- a/README.md +++ b/README.md @@ -416,8 +416,8 @@ full, and the limits that are fixed rather than settings. Each example is a complete `compose.yaml`. `smallwebwaf` is the tag `make docker` gives the image; on another host, use the name you pushed it under, by digest. Docker Compose puts the services on a private network of its -own, where each reaches the others by service name. Each example publishes -`rproxy`'s port on the host, for trying it out. +own, where each reaches the others by service name. Each example but "On the +open internet" publishes `rproxy`'s port on the host, for trying it out. ### Smallest setup @@ -449,6 +449,132 @@ volumes: waf-state: ``` +### On the open internet + +One gitea at `git.example.com`, with traefik in front of `rproxy`. traefik gets +the certificate from Let's Encrypt and is the only service with published ports. +`waf` sets what most sites set. More `waf` settings follow, commented out, each +with what it does and when to set it. + +```yaml +services: + traefik: + image: traefik:v3.7.19 + restart: unless-stopped + command: + - --providers.docker=true + - --providers.docker.exposedByDefault=false + - --entryPoints.web.address=:80 + - --entryPoints.websecure.address=:443 + # Redirect plain HTTP to HTTPS. + - --entryPoints.web.http.redirections.entryPoint.to=websecure + - --entryPoints.web.http.redirections.entryPoint.scheme=https + # A Let's Encrypt certificate for each site, by the TLS-ALPN + # challenge on port 443. + - --entryPoints.websecure.http.tls.certResolver=le + - --certificatesResolvers.le.acme.email=hostmaster@example.com + - --certificatesResolvers.le.acme.storage=/letsencrypt/acme.json + - --certificatesResolvers.le.acme.tlsChallenge=true + ports: + - "80:80" + - "443:443" + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - acme:/letsencrypt + + app: + # Your app: here a gitea, which listens on port 3000. + image: registry.example/app@sha256:0000000000000000000000000000000000000000000000000000000000000000 + restart: unless-stopped + + rproxy: + image: smallwebwaf + restart: unless-stopped + environment: + SWW_RPROXY_WAF_BACKEND: http://waf:8080 + SWW_RPROXY_UPSTREAM_URL: http://app:3000 + # Accept git pushes up to 1 GiB, rather than 100 MiB. + # SWW_RPROXY_MAX_REQUEST_SIZE: 1G + labels: + - traefik.enable=true + - traefik.http.routers.git.rule=Host(`git.example.com`) + - traefik.http.routers.git.entryPoints=websecure + - traefik.http.services.git.loadBalancer.server.port=8080 + + waf: + image: smallwebwaf + restart: unless-stopped + environment: + SWW_COMMAND: waf + # The name in every log line, alert and metric. The default, + # the container's host name, is a random id under Compose. + SWW_WAF_INSTANCE_NAME: host1/waf + # The app each hostname serves. Only that app's fixes to the + # Core Rule Set apply there. + SWW_WAF_APPS: git.example.com:gitea + # Monitoring skips every check. + SWW_WAF_ALLOW_NETS: 192.0.2.10 + # The office and the CI runner, which would pass the rate + # limits, are never rate limited. + SWW_WAF_RATE_LIMIT_EXEMPT_NETS: 203.0.113.0/24,198.51.100.7 + # WordPress paths, which only scanners ask a gitea for. One + # request for one bans the client. + SWW_WAF_TRAP_PATHS: /wp-login.php,/xmlrpc.php + # Spamhaus's list of netblocks hijacked or leased by + # criminals. Their clients are refused. + SWW_WAF_BLOCKLIST_URLS: https://www.spamhaus.org/drop/drop.txt + # The token for the ban endpoints, to lift a ban without + # editing bans.json. + SWW_WAF_ADMIN_TOKEN_FILE: /etc/sww/tokens/admin + # Alerts, such as one for each ban, to an ntfy topic. + SWW_WAF_ALERT_NTFY_URL: https://ntfy.example.com/smallwebwaf + + # Refuse nothing and ban no one, for the first days. Each log + # line says what enforce mode would have done. + # SWW_WAF_MODE: observe + # The access token for an ntfy topic that is not public. + # SWW_WAF_ALERT_NTFY_TOKEN_FILE: /etc/sww/tokens/ntfy + # The token for /_sww/metrics, for Prometheus. Unset, the + # metrics are off. + # SWW_WAF_METRICS_TOKEN_FILE: /etc/sww/tokens/metrics + # 600 requests an hour rather than 1500, to ban slower + # scrapers. A fast human reader can reach it too. + # SWW_WAF_RATE_LIMIT_PER_HOUR: "600" + # A quarter of every limit for clients in two hosting + # networks, where scrapers run rather than people. + # SWW_WAF_TAG_LIMIT_PERCENT: asn=14061:25,asn=16276:25 + # For a site only for people in a few countries. Clients + # elsewhere are refused, and so are any the lookup cannot place. + # SWW_WAF_EXCLUSIVELY_ALLOWED_COUNTRIES: de,at,ch + # Drop a refused client's connection rather than answer 403. + # SWW_WAF_BAN_RESPONSE: close + # A copy of every log line to a syslog server. + # SWW_WAF_LOG_REMOTE_URL: syslog+tls://logs.example.com:6514 + volumes: + - waf-state:/var/lib/sww + - /srv/sww/tokens:/etc/sww/tokens:ro + +volumes: + acme: + waf-state: +``` + +Change these before the first start: + +- `git.example.com`, in the router rule and in `SWW_WAF_APPS`; +- the email address for Let's Encrypt; +- the app's image and port; +- the netblocks, which are documentation addresses. + +Make the admin token file first, as for any token file: + +```sh +mkdir -p /srv/sww/tokens +openssl rand -hex 32 > /srv/sww/tokens/admin +chown 65532:65532 /srv/sww/tokens/admin +chmod 0400 /srv/sww/tokens/admin +``` + ### Custom per-address limits For a site with no API: -- 2.54.0 From aa19f8b85469224246e282a2db050e151058d3d7 Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 19 Nov 2026 08:12:41 +0000 Subject: [PATCH 2/7] README: pin the open-internet example's traefik image by digest The example pulled traefik:v3.7.19 by its tag, which the registry can move; the repository's policy and every other image reference in the repository name an image by its digest. Model: opus-5-5 --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2bf15cf..a54959c 100644 --- a/README.md +++ b/README.md @@ -459,7 +459,8 @@ with what it does and when to set it. ```yaml services: traefik: - image: traefik:v3.7.19 + # traefik v3.7.19, 2026-11-13 + image: traefik@sha256:a6c0194dda77bcb804824580f36fa7edc56e315b1acfe933366c8b52844a78a4 restart: unless-stopped command: - --providers.docker=true -- 2.54.0 From a320407ea5c9b73eb67281c2a42f663ab4cf66ca Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 19 Nov 2026 08:12:46 +0000 Subject: [PATCH 3/7] README: raise the request time with the size for large git pushes The commented rproxy line said it accepts git pushes up to 1 GiB, but raised only SWW_RPROXY_MAX_REQUEST_SIZE. SWW_RPROXY_MAX_REQUEST_TIME_MS still gave the body 60 seconds to arrive, so most such pushes were answered 408. Model: opus-5-5 --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a54959c..a4d8398 100644 --- a/README.md +++ b/README.md @@ -494,8 +494,10 @@ services: environment: SWW_RPROXY_WAF_BACKEND: http://waf:8080 SWW_RPROXY_UPSTREAM_URL: http://app:3000 - # Accept git pushes up to 1 GiB, rather than 100 MiB. + # Accept git pushes up to 1 GiB, rather than 100 MiB, sent in + # up to 10 minutes, rather than 1. # SWW_RPROXY_MAX_REQUEST_SIZE: 1G + # SWW_RPROXY_MAX_REQUEST_TIME_MS: "600000" labels: - traefik.enable=true - traefik.http.routers.git.rule=Host(`git.example.com`) -- 2.54.0 From 580fa8f26ae78a8580490c6b6d6c0c71462b37f2 Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 19 Nov 2026 08:12:49 +0000 Subject: [PATCH 4/7] README: say the exempt office and CI runner would exceed the limits "Which would pass the rate limits" reads as either getting through the limits or going over them, the opposite reasons for the exemption. Model: opus-5-5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a4d8398..8403475 100644 --- a/README.md +++ b/README.md @@ -517,7 +517,7 @@ services: SWW_WAF_APPS: git.example.com:gitea # Monitoring skips every check. SWW_WAF_ALLOW_NETS: 192.0.2.10 - # The office and the CI runner, which would pass the rate + # The office and the CI runner, which would exceed the rate # limits, are never rate limited. SWW_WAF_RATE_LIMIT_EXEMPT_NETS: 203.0.113.0/24,198.51.100.7 # WordPress paths, which only scanners ask a gitea for. One -- 2.54.0 From 3222c55009c77ecafd8fa91c2f654d1543f422e7 Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 19 Nov 2026 08:12:54 +0000 Subject: [PATCH 5/7] README: list the ntfy URL among the values to change first SWW_WAF_ALERT_NTFY_URL is set to a placeholder on example.com, but the list of what to change before the first start left it out, so a copied example sent every alert nowhere. Model: opus-5-5 --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 8403475..68ebfe5 100644 --- a/README.md +++ b/README.md @@ -566,6 +566,7 @@ Change these before the first start: - `git.example.com`, in the router rule and in `SWW_WAF_APPS`; - the email address for Let's Encrypt; +- the ntfy topic's URL; - the app's image and port; - the netblocks, which are documentation addresses. -- 2.54.0 From 5b5a12e57c086971cd02042f98f68153279cd77b Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 19 Nov 2026 08:51:32 +0000 Subject: [PATCH 6/7] README: raise traefik's read timeout with rproxy's for large git pushes The commented rproxy lines said a git push may take up to 10 minutes to send, but traefik v3 gives a whole request, body included, 60 seconds by default, and answers 502 to a slower one. A commented traefik line now raises its readTimeout to match. Model: opus-5-5 --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 68ebfe5..8e25d77 100644 --- a/README.md +++ b/README.md @@ -476,6 +476,9 @@ services: - --certificatesResolvers.le.acme.email=hostmaster@example.com - --certificatesResolvers.le.acme.storage=/letsencrypt/acme.json - --certificatesResolvers.le.acme.tlsChallenge=true + # Give a request 10 minutes to arrive, rather than 1, for the + # large git pushes the rproxy lines below accept. + # - --entryPoints.websecure.transport.respondingTimeouts.readTimeout=600s ports: - "80:80" - "443:443" @@ -495,7 +498,8 @@ services: SWW_RPROXY_WAF_BACKEND: http://waf:8080 SWW_RPROXY_UPSTREAM_URL: http://app:3000 # Accept git pushes up to 1 GiB, rather than 100 MiB, sent in - # up to 10 minutes, rather than 1. + # up to 10 minutes, rather than 1, with traefik's readTimeout + # line above. # SWW_RPROXY_MAX_REQUEST_SIZE: 1G # SWW_RPROXY_MAX_REQUEST_TIME_MS: "600000" labels: -- 2.54.0 From 330501484756e30ecd14c22c99ee9add76969f50 Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 19 Nov 2026 09:16:16 +0000 Subject: [PATCH 7/7] README: say what close gives a refused client behind traefik The commented SWW_WAF_BAN_RESPONSE line said close drops a refused client's connection, but in this example traefik is in front and answers the client 502 when rproxy closes the connection. The comment now says so, and why someone would set it. Model: opus-5-5 --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8e25d77..f5ef002 100644 --- a/README.md +++ b/README.md @@ -553,7 +553,9 @@ services: # For a site only for people in a few countries. Clients # elsewhere are refused, and so are any the lookup cannot place. # SWW_WAF_EXCLUSIVELY_ALLOWED_COUNTRIES: de,at,ch - # Drop a refused client's connection rather than answer 403. + # Close a refused request's connection rather than answer + # 403. traefik then answers 502, so a scraper cannot tell a + # ban from a broken site. # SWW_WAF_BAN_RESPONSE: close # A copy of every log line to a syslog server. # SWW_WAF_LOG_REMOTE_URL: syslog+tls://logs.example.com:6514 -- 2.54.0