|
|
|
@@ -284,6 +284,10 @@ account, a key, a token or an alert destination stays off until you give one.
|
|
|
|
|
`SWW_WAF_BYTES_COUNTED` says. Headers are never counted. What the visitor sent
|
|
|
|
|
over a WebSocket counts as request bytes, and what the app sent as response
|
|
|
|
|
bytes.
|
|
|
|
|
- An anomaly is more requests or bytes than an `SWW_WAF_ANOMALY_` threshold
|
|
|
|
|
allows. Crossing a threshold sends one `anomaly` alert to the alert
|
|
|
|
|
destinations, and does nothing else: no client is banned, rate limited or
|
|
|
|
|
blocked.
|
|
|
|
|
- An invalid setting stops the process at start with one log line naming the
|
|
|
|
|
variable and what is wrong with the value. The settings in effect are logged
|
|
|
|
|
on one line at start, with tokens, keys and webhook paths shown as `********`.
|
|
|
|
@@ -384,29 +388,29 @@ Every setting the code reads, with its default:
|
|
|
|
|
| `SWW_WAF_ALERT_EVENTS` | `ban,permanent_ban,core_rule_set_match,anomaly,reputation_hit,source_failure,file_error` | The events alerts are sent for; the hourly `summary` is sent whatever it says. |
|
|
|
|
|
| `SWW_WAF_ALERT_COOLDOWN` | `15m` | How long after an alert its repeats are held back and counted, a duration or `off`. |
|
|
|
|
|
| `SWW_WAF_ALERT_MAX_PER_HOUR` | `60` | The most alerts sent in an hour, a number or `off`; the rest are counted in the hour's `summary`. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE` | `off` | Alert when one client makes more requests than this in a minute, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR` | `off` | Alert when one client makes more requests than this in an hour, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one client in a minute, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one client in an hour, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_MINUTE` | `off` | Alert when the netblock around a client makes more requests than this in a minute, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_HOUR` | `off` | Alert when the netblock around a client makes more requests than this in an hour, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the netblock around a client in a minute, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the netblock around a client in an hour, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_V4_PREFIX` | `24` | The prefix length of the netblock around an IPv4 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 32. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_V6_PREFIX` | `48` | The prefix length of the netblock around an IPv6 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 128. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_MINUTE` | `off` | Alert when one AS number makes more requests than this in a minute, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_HOUR` | `off` | Alert when one AS number makes more requests than this in an hour, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one AS number in a minute, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for one AS number in an hour, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_MINUTE` | `off` | Alert when the whole service gets more requests than this in a minute, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_HOUR` | `off` | Alert when the whole service gets more requests than this in an hour, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the whole service in a minute, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for the whole service in an hour, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NETS` | empty | Named netblocks the `SWW_WAF_ANOMALY_WATCHED_NET_` thresholds count each as a whole, such as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_MINUTE` | `off` | Alert when a watched netblock makes more requests than this in a minute, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_HOUR` | `off` | Alert when a watched netblock makes more requests than this in an hour, a count. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_MINUTE` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for a watched netblock in a minute, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_HOUR` | `off` | Alert when more than this many bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted for a watched netblock in an hour, a size. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when one client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when one client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_V4_PREFIX` | `24` | The prefix length of the netblock around an IPv4 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 32. Those thresholds only send alerts. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_NET_V6_PREFIX` | `48` | The prefix length of the netblock around an IPv6 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 128. Those thresholds only send alerts. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when the whole service gets more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when the whole service gets more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the whole service in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the whole service in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NETS` | empty | Named netblocks the `SWW_WAF_ANOMALY_WATCHED_NET_` thresholds count each as a whole, such as `office=203.0.113.0/24,scraper-x=198.51.100.0/22`. Those thresholds only send alerts. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when a watched netblock makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
| `SWW_WAF_ANOMALY_WATCHED_NET_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for a watched netblock in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
|
|
|
|
|
|
|
|
|
|
[`docs/settings.md`](docs/settings.md) gives the values each setting takes in
|
|
|
|
|
full, and the limits that are fixed rather than settings.
|
|
|
|
@@ -416,8 +420,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 but "On the
|
|
|
|
|
open internet" publishes `rproxy`'s port on the host, for trying it out.
|
|
|
|
|
own, where each reaches the others by service name. Each example publishes
|
|
|
|
|
`rproxy`'s port on the host, for trying it out.
|
|
|
|
|
|
|
|
|
|
### Smallest setup
|
|
|
|
|
|
|
|
|
@@ -449,142 +453,6 @@ 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:
|
|
|
|
|
# traefik v3.7.19, 2026-11-13
|
|
|
|
|
image: traefik@sha256:a6c0194dda77bcb804824580f36fa7edc56e315b1acfe933366c8b52844a78a4
|
|
|
|
|
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
|
|
|
|
|
# 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"
|
|
|
|
|
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, sent in
|
|
|
|
|
# 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:
|
|
|
|
|
- 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 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
|
|
|
|
|
# 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
|
|
|
|
|
# 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
|
|
|
|
|
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 ntfy topic's URL;
|
|
|
|
|
- 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:
|
|
|
|
|