sneak/smallwebwaf
1
0 Fork 0
Code Issues 25 Pull Requests 7 Actions 89 Packages Projects Releases Wiki Activity

Rename discriminator to waf everywhere (closes #312)
check / check (push) In progress
Details

Browse Source 
The command is now `sww waf`, and the package is `internal/waf`. Types,
functions, files, tests, comments, docs, the Dockerfile, the runit
script, `script/`, compose examples, the log field `waf_line` and the
`X-From-Waf` test header follow. No behaviour changes, and no setting
changes name: rproxy already finds the waf through `SWRP_WAF_BACKEND`.

Done with one `sed -i` (Discriminator and DISCRIMINATOR to WAF,
discriminator to waf) over the files `git grep -i discriminator`
listed, as sneak allowed for this rename, then `git mv` for the
package and files. By hand afterwards: the header's spelling, which
the linter requires, and the padding after `waf` in `sww`'s usage
text.

Model: opus-5-5
This commit was merged in pull request #319.
This commit is contained in:
clawbot committed 2026-11-11 02:43:16 +01:00
1 parent ad36dd1775
commit f7e3190654
89 files changed
+1454 -1489
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/settings.md
+37 -40
View File
@@ -4,9 +4,9 @@ Every setting, its default and the values it takes, in the groups of "Settings"
in [`SPEC.md`](../SPEC.md). That section gives the conventions, the settings
that take `off`, the `_FILE` form, and what each group does and why.
The settings that start with `SWW_` are `discriminator`'s. Those that start with
`SWRP_` are `rproxy`'s, and are under "`rproxy`" below. `SWW_COMMAND` chooses
between the two (see "The image's command" below).
The settings that start with `SWW_` are `waf`'s. Those that start with `SWRP_`
are `rproxy`'s, and are under "`rproxy`" below. `SWW_COMMAND` chooses between
the two (see "The image's command" below).
## Forms of values
@@ -28,21 +28,20 @@ between the two (see "The image's command" below).
## Core
- `SWW_LISTEN_ADDR` (default `:8080`): where `discriminator` listens: `:` and a
port, such as `:9000`. Leave the host out (see "Ports" in
[`SPEC.md`](../SPEC.md)).
- `SWW_LISTEN_ADDR` (default `:8080`): where `waf` listens: `:` and a port, such
as `:9000`. Leave the host out (see "Ports" in [`SPEC.md`](../SPEC.md)).
- `SWW_INSTANCE_NAME` (default: the container's host name): the `instance` name
in each line `discriminator` logs, and in each alert and metric, such as
`fsn1/discriminator`. Valid UTF-8. No control character while
`SWW_ALERT_NTFY_URL` is set. 1 to 48 printable ASCII characters without a
space while `SWW_LOG_REMOTE_URL` is set and `SWW_LOG_REMOTE_APP_NAME` is not.
in each line `waf` logs, and in each alert and metric, such as `fsn1/waf`.
Valid UTF-8. No control character while `SWW_ALERT_NTFY_URL` is set. 1 to 48
printable ASCII characters without a space while `SWW_LOG_REMOTE_URL` is set
and `SWW_LOG_REMOTE_APP_NAME` is not.
- `SWW_MODE` (default `enforce`): `enforce` or `observe`.
- `SWW_IPV6_GROUP_PREFIX` (default `64`): the prefix length of an IPv6 client's
group, from 32 to 128.
- `SWW_MAX_TRACKED_CLIENTS` (default `20000`): the most clients kept, a whole
number above zero.
- `SWW_MAX_BANS` (default `5000`): how many of its own bans `discriminator`
keeps, a whole number above zero.
- `SWW_MAX_BANS` (default `5000`): how many of its own bans `waf` keeps, a whole
number above zero.
## Tokens
@@ -62,8 +61,8 @@ between the two (see "The image's command" below).
## Logging
- `SWW_LOG_LEVEL` (default `info`): the least severe of `discriminator`'s own
messages that are written: `debug`, `info`, `warn` or `error`.
- `SWW_LOG_LEVEL` (default `info`): the least severe of `waf`'s own messages
that are written: `debug`, `info`, `warn` or `error`.
- `SWW_LOG_REQUEST_HEADERS` (default
`accept,accept-language,accept-encoding,content-type,origin,range`): the
request headers recorded in the log line, in either case. `Host` and
@@ -167,8 +166,8 @@ cut off; the client is banned.
## Request tags
Every request gets tags from what `discriminator` knows of its client. See
"Request tags" in [`SPEC.md`](../SPEC.md).
Every request gets tags from what `waf` knows of its client. See "Request tags"
in [`SPEC.md`](../SPEC.md).
- `SWW_TAG_LISTS` (default empty): address lists that each add a tag, as
`name=URL` pairs, such as `torexit=https://example.com/tor.txt`. A name is the
@@ -188,10 +187,10 @@ Every request gets tags from what `discriminator` knows of its client. See
- `SWW_ROUTEWATCH_URL` (default unset): the `http` or `https` URL of a
routewatch instance. [routewatch](https://git.eeqj.de/sneak/routewatch) is a
service that gives an address's announced netblock and origin AS.
`discriminator` asks it about each client, in the background, and adds the
tags `asn=<number>` and `prefix=<netblock>` from its answer. While it is
unset, nothing asks routewatch and no request gets a `prefix=` tag.
service that gives an address's announced netblock and origin AS. `waf` asks
it about each client, in the background, and adds the tags `asn=<number>` and
`prefix=<netblock>` from its answer. While it is unset, nothing asks
routewatch and no request gets a `prefix=` tag.
`SWW_TAG_DENY` and `SWW_TAG_LIMIT_PERCENT` accept tags in either case. A tag
that no request can get stops the start. A request can get only these:
@@ -377,7 +376,7 @@ Then mount its directory into the container read-only, and name the file:
```sh
docker run \
-v /srv/app/tokens:/etc/sww/tokens:ro \
-e SWW_COMMAND=discriminator \
-e SWW_COMMAND=waf \
-e SWW_METRICS_TOKEN_FILE=/etc/sww/tokens/metrics \
...
```
@@ -391,21 +390,20 @@ A few limits are fixed rather than settings:
- at most 1,000 DNS blocklist queries are under way at once;
- at most 20,000 anomaly counters are kept;
- each alert destination's queue holds at most 1,000 alerts;
- `discriminator` holds at most 10,000 answered requests awaiting their reports;
- `discriminator` refuses a request with more than 50 cookies or more than 100
header fields (see "Answering in time" under "`discriminator`" in
[`SPEC.md`](../SPEC.md));
- `waf` holds at most 10,000 answered requests awaiting their reports;
- `waf` refuses a request with more than 50 cookies or more than 100 header
fields (see "Answering in time" under "`waf`" in [`SPEC.md`](../SPEC.md));
- `rproxy` takes a request line and headers of at most 32 KiB, and closes a
kept-open connection idle for 120 seconds;
- `rproxy` reads at most 1 MiB of the body of `discriminator`'s answer, and
answers `502` to a longer one.
- `rproxy` reads at most 1 MiB of the body of `waf`'s answer, and answers `502`
to a longer one.
## `discriminator`'s answer and `rproxy`'s wait
## `waf`'s answer and `rproxy`'s wait
`SWW_LOOKUP_TIMEOUT` is the longest a question waits on an outside source. Keep
it well under `rproxy`'s `SWRP_TIMEOUT_MS`, as the default is. No question waits
for `SWW_REPUTATION_TIMEOUT`, since the DNS blocklists and AbuseIPDB are asked
in the background (see "Answering in time" under "`discriminator`" in
in the background (see "Answering in time" under "`waf`" in
[`SPEC.md`](../SPEC.md)).
## `rproxy`
@@ -417,16 +415,15 @@ they do.
A time here is a whole number of milliseconds above zero, such as `2000`.
- `SWRP_WAF_BACKEND` (required, no default): `discriminator`'s URL. An `http` or
`https` URL with a host and an optional port, and nothing more. `rproxy`
speaks HTTP/1.1 to it.
- `SWRP_TIMEOUT_MS` (default `2000`): how long `rproxy` waits for
`discriminator`'s answer, to a question and to a report. A time; never `off`.
- `SWRP_WAF_BACKEND` (required, no default): `waf`'s URL. An `http` or `https`
URL with a host and an optional port, and nothing more. `rproxy` speaks
HTTP/1.1 to it.
- `SWRP_TIMEOUT_MS` (default `2000`): how long `rproxy` waits for `waf`'s
answer, to a question and to a report. A time; never `off`.
- `SWRP_DEFAULT_DISPOSITION` (default `allow`): what is done with a request when
`discriminator` cannot be connected to, does not answer at all, or does not
answer within `SWRP_TIMEOUT_MS`. `allow` passes it to the app, and `deny`
answers `503`. It does not apply to an answer `discriminator` gives, such as
an error.
`waf` cannot be connected to, does not answer at all, or does not answer
within `SWRP_TIMEOUT_MS`. `allow` passes it to the app, and `deny` answers
`503`. It does not apply to an answer `waf` gives, such as an error.
- `SWRP_MAX_REQUEST_SIZE` (default `100M`): the largest request body. A size or
`off`.
- `SWRP_MAX_RESPONSE_SIZE` (default `1G`): the largest response body. A size or
@@ -452,8 +449,8 @@ A time here is a whole number of milliseconds above zero, such as `2000`.
## The image's command
`SWW_COMMAND` (default `rproxy`) chooses what the image runs and what its health
check checks: `rproxy` or `discriminator` (see "Deployment" in
[`SPEC.md`](../SPEC.md)). It cannot be given as a file.
check checks: `rproxy` or `waf` (see "Deployment" in [`SPEC.md`](../SPEC.md)).
It cannot be given as a file.
## Where earlier settings went