Rename the program to sww and its deciding daemon to discriminator
check / check (push) Successful in 5m33s

The program is now sww, built from cmd/sww, with two modes: sww rproxy and
sww discriminator. servewaf becomes discriminator everywhere it names that
daemon: the package (internal/discriminator), its types, functions, files, the
discriminator_line log field, and its docs and tests.

smallwebwaf is left only where sneak's directive allows it: the documents'
product name, the git.eeqj.de/sneak/smallwebwaf URLs, and the Go module path
sneak.berlin/go/smallwebwaf. Everywhere else a name containing it takes the sww
form: the package (internal/sww), metric names (sww_*), the X-Sww-* headers,
the /_sww/ admin endpoints, the SWW_COMMAND setting, the OS user, and the state
and rules directories.

No logic changes. make check passes.

Model: deepseek-v4-pro
This commit is contained in:
sneak committed 2026-11-07 04:19:17 +00:00
1 parent 7fed6b6d36
commit d8f417b00b
97 files changed
+1945 -1912

No files matched your search

+25 -25
View File
@@ -1,60 +1,60 @@
# Admin endpoints
The endpoints under `/_smallwebwaf/`, what each takes and what each answers.
`smallwebwaf servewaf` answers them at its own address, on the private network.
The endpoints under `/_sww/`, what each takes and what each answers.
`sww discriminator` answers them at its own address, on the private network.
"Admin endpoints" in [`SPEC.md`](../SPEC.md) says how their tokens work.
- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone.
- `GET /_smallwebwaf/metrics`: the metrics, for `SWWAF_METRICS_TOKEN` (see
- `GET /_sww/healthz`: `200` and `ok`, to anyone.
- `GET /_sww/metrics`: the metrics, for `SWWAF_METRICS_TOKEN` (see
[`metrics.md`](metrics.md)).
- `GET /_smallwebwaf/bans`: every ban held, under `bans`, each as `bans.json`
lists it. Needs `SWWAF_ADMIN_TOKEN`, as do the three below.
- `POST /_smallwebwaf/bans`: bans a netblock. The body is a JSON object of
`netblock`, `duration` and, if you like, `reason`. `netblock` is a netblock
such as `203.0.113.0/24`, or a client's address, which bans its IPv4 netblock
- `GET /_sww/bans`: every ban held, under `bans`, each as `bans.json` lists it.
Needs `SWWAF_ADMIN_TOKEN`, as do the three below.
- `POST /_sww/bans`: bans a netblock. The body is a JSON object of `netblock`,
`duration` and, if you like, `reason`. `netblock` is a netblock such as
`203.0.113.0/24`, or a client's address, which bans its IPv4 netblock
(`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group. `duration` is a duration such
as `1h` or `7d`, or `permanent`. A bad body is answered `400`, saying what is
wrong:
- one that is not such an object, or has another field;
- one longer than 4 KiB;
- one that names an IPv4-mapped netblock, or an address with a zone.
- `DELETE /_smallwebwaf/bans/<client>`: lifts every active ban covering the
address `<client>`. It answers `404` when none is active.
- `GET /_smallwebwaf/clients/<ip>`: what `servewaf` knows of the client. Under
- `DELETE /_sww/bans/<client>`: lifts every active ban covering the address
`<client>`. It answers `404` when none is active.
- `GET /_sww/clients/<ip>`: what `discriminator` knows of the client. Under
`client`, its counters and history as `clients.json` holds them, or `null`
when `clients.json` does not hold it. Under `bans`, every ban covering the
address, with its notes.
- `POST /_smallwebwaf/report`: takes `rproxy`'s report, without a token. It
answers `204`, or `400` to a body that is no report (see "The report" in
- `POST /_sww/report`: takes `rproxy`'s report, without a token. It answers
`204`, or `400` to a body that is no report (see "The report" in
[`SPEC.md`](../SPEC.md)).
No check runs on these requests. A missing or wrong token is answered `401`. An
endpoint whose token is unset answers `404`, as does any other path.
`smallwebwaf rproxy` answers only the health check of these, at its own address.
It asks `servewaf` about any other request under `/_smallwebwaf/`. One that
passes the checks is answered `404`, so that the app never sees that prefix (see
"`rproxy`" in [`SPEC.md`](../SPEC.md)).
`sww rproxy` answers only the health check of these, at its own address. It asks
`discriminator` about any other request under `/_sww/`. One that passes the
checks is answered `404`, so that the app never sees that prefix (see "`rproxy`"
in [`SPEC.md`](../SPEC.md)).
## Examples
With `SWWAF_ADMIN_TOKEN` set, the token in `$TOKEN`, and `servewaf` reached as
`servewaf:8080` on its network:
With `SWWAF_ADMIN_TOKEN` set, the token in `$TOKEN`, and `discriminator` reached
as `discriminator:8080` on its network:
```sh
# Every ban.
curl -H "Authorization: Bearer $TOKEN" http://servewaf:8080/_smallwebwaf/bans
curl -H "Authorization: Bearer $TOKEN" http://discriminator:8080/_sww/bans
# Ban 203.0.113.0/24 for seven days.
curl -H "Authorization: Bearer $TOKEN" \
--json '{"netblock": "203.0.113.0/24", "duration": "7d", "reason": "probes for logins"}' \
http://servewaf:8080/_smallwebwaf/bans
http://discriminator:8080/_sww/bans
# Lift the bans on 203.0.113.9.
curl -H "Authorization: Bearer $TOKEN" -X DELETE \
http://servewaf:8080/_smallwebwaf/bans/203.0.113.9
http://discriminator:8080/_sww/bans/203.0.113.9
# What servewaf knows of 203.0.113.9.
# What discriminator knows of 203.0.113.9.
curl -H "Authorization: Bearer $TOKEN" \
http://servewaf:8080/_smallwebwaf/clients/203.0.113.9
http://discriminator:8080/_sww/clients/203.0.113.9
```
+7 -7
View File
@@ -6,7 +6,7 @@ back or dropped.
## Events
- `ban`: a ban `servewaf` made.
- `ban`: a ban `discriminator` made.
- `permanent_ban`: a permanent ban it made, or an existing ban made permanent by
a request.
- `waf_block`: the Core Rule Set scored a request at or over the threshold. The
@@ -34,7 +34,7 @@ on one line:
```json
{
"instance": "fsn1/servewaf",
"instance": "fsn1/discriminator",
"time": "2026-10-06T12:00:50.123461Z",
"event": "ban",
"host": "app.example",
@@ -79,9 +79,9 @@ on one line:
- `instance`: `SWWAF_INSTANCE_NAME`. `time`: when the alert was raised. `event`:
one of the events above.
- `host`: the site of the request that raised the alert, since one `servewaf`
serves many sites. It is left out of `source_failure`, `file_error` and
`summary`.
- `host`: the site of the request that raised the alert, since one
`discriminator` serves many sites. It is left out of `source_failure`,
`file_error` and `summary`.
- `client`: the address whose request raised the alert. Empty for
`source_failure`, `file_error` and `summary`.
- `netblock`: empty for `source_failure`, `file_error` and `summary`; otherwise
@@ -111,8 +111,8 @@ on one line:
## Slack and ntfy
Slack and ntfy get a message with a title and a text. The title is the instance
and the event, such as `fsn1/servewaf: ban`. The text is the `reason`, then one
line for each of these that the alert has:
and the event, such as `fsn1/discriminator: ban`. The text is the `reason`, then
one line for each of these that the alert has:
- the host, the client, the netblock and the country;
- the file, the source, the error and the mode from `detail`;
+8 -9
View File
@@ -1,7 +1,7 @@
# What the image holds
The contents of the `smallwebwaf` image, and how each part is pinned. The image
runs `rproxy` by default, or `servewaf` with `SMALLWEBWAF_COMMAND=servewaf`.
runs `rproxy` by default, or `discriminator` with `SWW_COMMAND=discriminator`.
"Deployment" in [`SPEC.md`](../SPEC.md) says why each part is there and why it
is pinned that way.
@@ -15,13 +15,12 @@ is pinned that way.
Unpacked, nixpkgs takes about 500 MiB.
- `runsvinit` as the entrypoint, built from `github.com/peterbourgon/runsvinit`
at a fixed commit hash.
- The `smallwebwaf` binary, and the user `smallwebwaf` (uid and gid 65532).
- The service directory `/etc/service/smallwebwaf`, with the `run` script
`share/smallwebwaf.run`.
- `/var/lib/smallwebwaf` for `servewaf`'s state files, and
`/etc/smallwebwaf/rules.d` with the default rule file
`share/rules.d/00-default.rules`.
- `EXPOSE 8080`, and the `HEALTHCHECK` that runs `smallwebwaf healthcheck`.
- The `sww` binary, and the user `sww` (uid and gid 65532).
- The service directory `/etc/service/sww`, with the `run` script
`share/sww.run`.
- `/var/lib/sww` for `discriminator`'s state files, and `/etc/sww/rules.d` with
the default rule file `share/rules.d/00-default.rules`.
- `EXPOSE 8080`, and the `HEALTHCHECK` that runs `sww healthcheck`.
## Pins
@@ -33,4 +32,4 @@ is pinned that way.
- `runsvinit`: the archived repository, unchanged since 2015, at its last commit
(`b4b2c78`, eight commits after `v2.0.0`), by commit hash, with a `go.mod` the
build writes.
- The Go image that builds `smallwebwaf`: by digest.
- The Go image that builds `sww`: by digest.
+39 -48
View File
@@ -1,90 +1,81 @@
# The metrics
What `GET /_smallwebwaf/metrics` answers with, at `servewaf`'s own address.
What `GET /_sww/metrics` answers with, at `discriminator`'s own address.
"Metrics endpoint" in [`SPEC.md`](../SPEC.md) describes the endpoint. Prometheus
keeps the `instance` label as `exported_instance` unless the scrape sets
`honor_labels: true`. `rproxy` has no metrics.
## Traffic
- `smallwebwaf_requests_total`, `smallwebwaf_request_bytes_total` and
`smallwebwaf_response_bytes_total`, by `status_class` such as `2xx` and by
`action`;
- `smallwebwaf_request_duration_seconds` and
`smallwebwaf_upstream_duration_seconds`, as histograms;
- `smallwebwaf_requests_in_flight`: the questions and requests to its own
endpoints that `servewaf` is handling.
- `sww_requests_total`, `sww_request_bytes_total` and
`sww_response_bytes_total`, by `status_class` such as `2xx` and by `action`;
- `sww_request_duration_seconds` and `sww_upstream_duration_seconds`, as
histograms;
- `sww_requests_in_flight`: the questions and requests to its own endpoints that
`discriminator` is handling.
## Limits and bans
- `smallwebwaf_rate_limit_hits_total`, by `window` and by `kind` (`requests`,
`bytes` or `refusals`);
- `smallwebwaf_offences_total`, by `kind`;
- `smallwebwaf_bans_made_total`, by `cause`;
- `smallwebwaf_active_bans` and `smallwebwaf_permanent_bans`.
- `sww_rate_limit_hits_total`, by `window` and by `kind` (`requests`, `bytes` or
`refusals`);
- `sww_offences_total`, by `kind`;
- `sww_bans_made_total`, by `cause`;
- `sww_active_bans` and `sww_permanent_bans`.
## Attack detection
- `smallwebwaf_rule_matches_total`, by `rule_id` and `action`, and
`smallwebwaf_rules_loaded`;
- `smallwebwaf_waf_matches_total`, by `mode` and `rule_id`, for the rules that
fired.
- `sww_rule_matches_total`, by `rule_id` and `action`, and `sww_rules_loaded`;
- `sww_waf_matches_total`, by `mode` and `rule_id`, for the rules that fired.
## Countries and AS numbers
For the `SWWAF_METRICS_TOP_N` busiest of each, the rest as `other`:
- `smallwebwaf_country_requests_total`,
`smallwebwaf_country_request_bytes_total`,
`smallwebwaf_country_response_bytes_total` and
`smallwebwaf_country_list_refusals_total`, by `country`;
- `smallwebwaf_asn_requests_total`, `smallwebwaf_asn_request_bytes_total` and
`smallwebwaf_asn_response_bytes_total`, by `asn`.
- `sww_country_requests_total`, `sww_country_request_bytes_total`,
`sww_country_response_bytes_total` and `sww_country_list_refusals_total`, by
`country`;
- `sww_asn_requests_total`, `sww_asn_request_bytes_total` and
`sww_asn_response_bytes_total`, by `asn`.
## Lookups
- `smallwebwaf_geojs_requests_total` and `smallwebwaf_geojs_failures_total`;
- `smallwebwaf_geojs_unanswered_total`: the requests that needed an answer and
went on without it;
- with the file source,
`smallwebwaf_lookup_database_last_read_timestamp_seconds` and
`smallwebwaf_lookup_database_read_failures_total`.
- `sww_geojs_requests_total` and `sww_geojs_failures_total`;
- `sww_geojs_unanswered_total`: the requests that needed an answer and went on
without it;
- with the file source, `sww_lookup_database_last_read_timestamp_seconds` and
`sww_lookup_database_read_failures_total`.
## Reputation sources
By `source`: each list's URL, each zone, and `abuseipdb`:
- `smallwebwaf_reputation_hits_total`, `smallwebwaf_reputation_queries_total`
and `smallwebwaf_reputation_failures_total`;
- `smallwebwaf_reputation_last_fetch_timestamp_seconds`, for a list;
- `smallwebwaf_reputation_daily_budget_remaining`, for AbuseIPDB.
- `sww_reputation_hits_total`, `sww_reputation_queries_total` and
`sww_reputation_failures_total`;
- `sww_reputation_last_fetch_timestamp_seconds`, for a list;
- `sww_reputation_daily_budget_remaining`, for AbuseIPDB.
## State files
By `file`:
- `smallwebwaf_state_file_writes_total`,
`smallwebwaf_state_file_write_failures_total`,
`smallwebwaf_state_file_last_write_timestamp_seconds` and
`smallwebwaf_state_file_size_bytes`;
- `smallwebwaf_state_file_edits_taken_in_total` and
`smallwebwaf_state_file_edits_set_aside_total`;
- `smallwebwaf_tracked_clients`: the clients in the table.
- `sww_state_file_writes_total`, `sww_state_file_write_failures_total`,
`sww_state_file_last_write_timestamp_seconds` and `sww_state_file_size_bytes`;
- `sww_state_file_edits_taken_in_total` and
`sww_state_file_edits_set_aside_total`;
- `sww_tracked_clients`: the clients in the table.
## Remote log, alerts and the process
- while a syslog server is set, `smallwebwaf_remote_log_lines_sent_total`,
`smallwebwaf_remote_log_lines_dropped_total` and
`smallwebwaf_remote_log_buffer_depth`;
- by `destination`, `smallwebwaf_alerts_sent_total`,
`smallwebwaf_alerts_failed_total`, `smallwebwaf_alerts_suppressed_total` and
`smallwebwaf_alerts_dropped_total`;
- while a syslog server is set, `sww_remote_log_lines_sent_total`,
`sww_remote_log_lines_dropped_total` and `sww_remote_log_buffer_depth`;
- by `destination`, `sww_alerts_sent_total`, `sww_alerts_failed_total`,
`sww_alerts_suppressed_total` and `sww_alerts_dropped_total`;
- Go's own `go_` metrics and the process's `process_` metrics.
## When a request is counted
`servewaf` counts a denied request at its decision, and a request to its own
endpoints when it is answered. It counts an allowed request when its report
`discriminator` counts a denied request at its decision, and a request to its
own endpoints when it is answered. It counts an allowed request when its report
comes, with the status, bytes and times the report gives. These are not counted:
- a report itself;
+32 -31
View File
@@ -1,32 +1,32 @@
# The request log's fields
The fields of the JSON objects `rproxy` and `servewaf` write about each request.
"Request log" and "The log" in [`SPEC.md`](../SPEC.md) say when a line is
written and how the log is sent to a syslog server. A field that does not apply
to a request is left out.
The fields of the JSON objects `rproxy` and `discriminator` write about each
request. "Request log" and "The log" in [`SPEC.md`](../SPEC.md) say when a line
is written and how the log is sent to a syslog server. A field that does not
apply to a request is left out.
## `servewaf`'s lines
## `discriminator`'s lines
`smallwebwaf servewaf` writes two lines for each question it answers, joined by
`request_id`. The field `servewaf_line` says which of the two a line is:
`sww discriminator` writes two lines for each question it answers, joined by
`request_id`. The field `discriminator_line` says which of the two a line is:
- `decision`: the line it writes once it has answered the question;
- `report`: the line it writes when `rproxy`'s report comes, with everything
known. The repetition is intended.
A request to its own endpoints writes one line, without `servewaf_line`. A
A request to its own endpoints writes one line, without `discriminator_line`. A
report writes no line but the `report` line of the request it names.
These questions write no line:
- a question refused with `400` (see "The question" under "`servewaf`" in
- a question refused with `400` (see "The question" under "`discriminator`" in
[`SPEC.md`](../SPEC.md));
- a question whose body stopped arriving, which gets no answer.
A `report` line:
```
{"type":"request","servewaf_line":"report","time":"2026-10-03T12:00:00.123Z","instance":"fsn1/servewaf","client_ip":"203.0.113.9","method":"GET","scheme":"https","host":"app.example","path":"/","query":"","protocol":"HTTP/1.1","status":200,"request_bytes":0,"response_bytes":5120,"referer":"","user_agent":"curl/8.9.1","request_id":"7Q2NHZ4KJ3VXW5YB6R3MEFTD2A","peer_ip":"172.18.0.2","forwarded_for":"203.0.113.9","client_group":"203.0.113.9/32","asn":"AS64496","as_name":"Example Net","country":"DE","request_headers":{"accept":"*/*"},"action":"forward","counts":{"minute":1,"hour":12,"day":40,"minute_bytes":5120,"hour_bytes":61440,"day_bytes":204800},"waf_score":0,"duration_total":3.217,"duration_checks":0.041,"duration_waf":0.029,"duration_upstream_total":3.104}
{"type":"request","discriminator_line":"report","time":"2026-10-03T12:00:00.123Z","instance":"fsn1/discriminator","client_ip":"203.0.113.9","method":"GET","scheme":"https","host":"app.example","path":"/","query":"","protocol":"HTTP/1.1","status":200,"request_bytes":0,"response_bytes":5120,"referer":"","user_agent":"curl/8.9.1","request_id":"7Q2NHZ4KJ3VXW5YB6R3MEFTD2A","peer_ip":"172.18.0.2","forwarded_for":"203.0.113.9","client_group":"203.0.113.9/32","asn":"AS64496","as_name":"Example Net","country":"DE","request_headers":{"accept":"*/*"},"action":"forward","counts":{"minute":1,"hour":12,"day":40,"minute_bytes":5120,"hour_bytes":61440,"day_bytes":204800},"waf_score":0,"duration_total":3.217,"duration_checks":0.041,"duration_waf":0.029,"duration_upstream_total":3.104}
```
### Every line
@@ -41,7 +41,7 @@ Every one of these lines has:
### Standard web log fields
- `time`: when `servewaf` had read the question's body, RFC 3339 with
- `time`: when `discriminator` had read the question's body, RFC 3339 with
milliseconds, in UTC. The `report` line gives the same time as the `decision`
line.
- `instance`: `SWWAF_INSTANCE_NAME`.
@@ -52,8 +52,9 @@ Every one of these lines has:
- `host`: the site the visitor asked for.
- `protocol`: the question's own, `HTTP/1.1`.
- `status`:
- on the `decision` line, what `servewaf` answered: `200` for `allow`, the
status of `deny`, or `0` for `close`, as the visitor is then sent nothing;
- on the `decision` line, what `discriminator` answered: `200` for `allow`,
the status of `deny`, or `0` for `close`, as the visitor is then sent
nothing;
- on the `report` line, what the visitor got, `0` if nothing.
- `request_bytes`:
- on the `decision` line, how much of the question's body the Core Rule Set
@@ -61,7 +62,7 @@ Every one of these lines has:
- on the `report` line, the bytes of the visitor's body that `rproxy` read,
with what a WebSocket carried from the visitor.
- `response_bytes`:
- on the `decision` line, the body of `servewaf`'s answer;
- on the `decision` line, the body of `discriminator`'s answer;
- on the `report` line, the bytes of the answer's body, with what a
WebSocket carried from the app.
- `referer` and `user_agent`.
@@ -78,7 +79,7 @@ Every one of these lines has:
- lookups are off;
- the client is not looked up;
- the source cannot place the client;
- GeoJS had not answered by the time `servewaf` answered.
- GeoJS had not answered by the time `discriminator` answered.
- `content_type`: the visitor's `Content-Type`.
- `content_length`: the body length the visitor announced.
- `request_headers`: the headers listed in `SWWAF_LOG_REQUEST_HEADERS`, by name
@@ -88,7 +89,7 @@ Every one of these lines has:
### Response detail
- `response_content_type`: the type of `servewaf`'s own answer.
- `response_content_type`: the type of `discriminator`'s own answer.
- `aborted`: true when `rproxy` went away before the answer.
### Decision
@@ -102,8 +103,8 @@ Every one of these lines has:
- `country_denied`, `rate_limited`, `rule_blocked` and `waf_blocked`:
refused by that check;
- `too_large`: over a header limit;
- `admin`: answered at one of `servewaf`'s own endpoints, or `404` for a
path under `/_smallwebwaf/`.
- `admin`: answered at one of `discriminator`'s own endpoints, or `404` for
a path under `/_sww/`.
- `would_action`: in `observe` mode, what `enforce` mode would have done with a
request it would have refused. `action` then names what was done, normally
`forward`.
@@ -147,8 +148,8 @@ Every one of these lines has:
All in milliseconds:
- `duration_total`:
- on the `decision` line, from `servewaf` having read the question's body to
the line;
- on the `decision` line, from `discriminator` having read the question's
body to the line;
- on the `report` line, from `rproxy` having read the request's headers to
the end of the answer.
- `duration_checks`: to the end of the checks;
@@ -158,8 +159,8 @@ All in milliseconds:
### Requests to its own endpoints
The line of a request to `servewaf`'s own endpoints has these fields, with these
meanings where they differ:
The line of a request to `discriminator`'s own endpoints has these fields, with
these meanings where they differ:
- `client_ip` and `peer_ip`: the request's TCP peer.
- `request_id`: a new random one of 26 letters and digits.
@@ -171,8 +172,8 @@ meanings where they differ:
## `rproxy`'s line
`smallwebwaf rproxy` writes one short line for each request. `request_id` joins
it to `servewaf`'s two. It has these fields and no others:
`sww rproxy` writes one short line for each request. `request_id` joins it to
`discriminator`'s two. It has these fields and no others:
- `type`: `request`.
- `time`: when the request arrived, RFC 3339 with milliseconds, in UTC.
@@ -187,15 +188,15 @@ it to `servewaf`'s two. It has these fields and no others:
carried from the app.
- `duration_request`: milliseconds from the request's headers being read until
the app had been sent the whole request, or the answer started if that was
sooner. It includes the wait for `servewaf`.
sooner. It includes the wait for `discriminator`.
- `duration_response`: milliseconds from then until the end of the answer.
- `disposition`: what was done with the request: `allow`, `deny` or `close`. It
is `servewaf`'s answer, or the value of `SWRP_DEFAULT_DISPOSITION`. It is left
out when:
- `servewaf` was not asked, as for the health check;
- the visitor went away while `servewaf` was being asked;
- `servewaf`'s answer had no valid `X-Smallwebwaf-Disposition`;
- `rproxy` could not pass on `servewaf`'s answer, and answered `502`.
is `discriminator`'s answer, or the value of `SWRP_DEFAULT_DISPOSITION`. It is
left out when:
- `discriminator` was not asked, as for the health check;
- the visitor went away while `discriminator` was being asked;
- `discriminator`'s answer had no valid `X-Sww-Disposition`;
- `rproxy` could not pass on `discriminator`'s answer, and answered `502`.
- `default_disposition`: `true` when `SWRP_DEFAULT_DISPOSITION` gave
`disposition`, and otherwise left out.
+8 -7
View File
@@ -32,7 +32,7 @@ scanner-agent user_agent ban (?i)\b(sqlmap|nikto|nuclei|wpscan)\b
## The default file
The image ships one file, `share/rules.d/00-default.rules`, installed as
`/etc/smallwebwaf/rules.d/00-default.rules`:
`/etc/sww/rules.d/00-default.rules`:
```
# 00-default.rules: probes no real visitor sends, anchored at the site root
@@ -54,19 +54,20 @@ empty-agent user_agent log ^$
## A file of your own
`servewaf` reads the rule files in its own container. Rules of your own go in a
file named to sort after the default, such as `50-site.rules`:
`discriminator` reads the rule files in its own container. Rules of your own go
in a file named to sort after the default, such as `50-site.rules`:
```
# 50-site.rules: WordPress probes, which this site never serves
wp-probe path ban (?i)^/(wp-login\.php|xmlrpc\.php|wp-admin/)
```
A `Dockerfile` built on the `smallwebwaf` image, for `servewaf` to run from,
adds it:
A `Dockerfile` built on the `smallwebwaf` image, for `discriminator` to run
from, adds it:
```dockerfile
COPY 50-site.rules /etc/smallwebwaf/rules.d/50-site.rules
COPY 50-site.rules /etc/sww/rules.d/50-site.rules
```
Or mount it there. A `path` rule applies on every site behind that `servewaf`.
Or mount it there. A `path` rule applies on every site behind that
`discriminator`.
+39 -38
View File
@@ -4,8 +4,8 @@ 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 `SWWAF_` are `servewaf`'s. Those that start with
`SWRP_` are `rproxy`'s, and are under "`rproxy`" below. `SMALLWEBWAF_COMMAND`
The settings that start with `SWWAF_` 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).
## Forms of values
@@ -28,12 +28,12 @@ chooses between the two (see "The image's command" below).
## Core
- `SWWAF_LISTEN_ADDR` (default `:8080`): where `servewaf` listens: `:` and a
port, such as `:9000`. Leave the host out (see "Ports" in
- `SWWAF_LISTEN_ADDR` (default `:8080`): where `discriminator` listens: `:` and
a port, such as `:9000`. Leave the host out (see "Ports" in
[`SPEC.md`](../SPEC.md)).
- `SWWAF_INSTANCE_NAME` (default: the container's host name): the `instance`
name in each line `servewaf` logs, and in each alert and metric, such as
`fsn1/servewaf`. Valid UTF-8. No control character while
name in each line `discriminator` logs, and in each alert and metric, such as
`fsn1/discriminator`. Valid UTF-8. No control character while
`SWWAF_ALERT_NTFY_URL` is set. 1 to 48 printable ASCII characters without a
space while `SWWAF_LOG_REMOTE_URL` is set and `SWWAF_LOG_REMOTE_APP_NAME` is
not.
@@ -42,20 +42,20 @@ chooses between the two (see "The image's command" below).
client's group, from 32 to 128.
- `SWWAF_MAX_TRACKED_CLIENTS` (default `20000`): the most clients kept, a whole
number above zero.
- `SWWAF_MAX_BANS` (default `5000`): how many of its own bans `servewaf` keeps,
a whole number above zero.
- `SWWAF_MAX_BANS` (default `5000`): how many of its own bans `discriminator`
keeps, a whole number above zero.
## Tokens
- `SWWAF_ADMIN_TOKEN` (default unset): the token for the ban endpoints and
`/_smallwebwaf/clients/<ip>`. At least 32 characters.
- `SWWAF_METRICS_TOKEN` (default unset): the token for `/_smallwebwaf/metrics`.
At least 32 characters.
`/_sww/clients/<ip>`. At least 32 characters.
- `SWWAF_METRICS_TOKEN` (default unset): the token for `/_sww/metrics`. At least
32 characters.
## State files
- `SWWAF_STATE_DIR` (default `/var/lib/smallwebwaf`): the directory of the state
files, an absolute path that exists and can be written.
- `SWWAF_STATE_DIR` (default `/var/lib/sww`): the directory of the state files,
an absolute path that exists and can be written.
- `SWWAF_STATE_WRITE_DELAY` (default `10s`): how long `bans.json` waits to be
written after a ban is made, lifted or made permanent. A duration.
- `SWWAF_STATE_COUNTER_INTERVAL` (default `15m`): how often every state file is
@@ -63,7 +63,7 @@ chooses between the two (see "The image's command" below).
## Logging
- `SWWAF_LOG_LEVEL` (default `info`): the least severe of `servewaf`'s own
- `SWWAF_LOG_LEVEL` (default `info`): the least severe of `discriminator`'s own
messages that are written: `debug`, `info`, `warn` or `error`.
- `SWWAF_LOG_REQUEST_HEADERS` (default
`accept,accept-language,accept-encoding,content-type,origin,range`): the
@@ -170,8 +170,8 @@ chooses between the two (see "The image's command" below).
## Attack detection
- `SWWAF_RULES_DIR` (default `/etc/smallwebwaf/rules.d`): the directory of the
rule files.
- `SWWAF_RULES_DIR` (default `/etc/sww/rules.d`): the directory of the rule
files.
- `SWWAF_RULES_ENABLED` (default `true`): `false` reads no rule file.
- `SWWAF_TRAP_PATHS` (default empty): paths only scanners ask for, such as
`/wp-login.php,/xmlrpc.php`. Each starts with `/` and holds no `?`.
@@ -310,9 +310,9 @@ Then mount its directory into the container read-only, and name the file:
```sh
docker run \
-v /srv/app/tokens:/etc/smallwebwaf/tokens:ro \
-e SMALLWEBWAF_COMMAND=servewaf \
-e SWWAF_METRICS_TOKEN_FILE=/etc/smallwebwaf/tokens/metrics \
-v /srv/app/tokens:/etc/sww/tokens:ro \
-e SWW_COMMAND=discriminator \
-e SWWAF_METRICS_TOKEN_FILE=/etc/sww/tokens/metrics \
...
```
@@ -325,41 +325,42 @@ 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;
- `servewaf` holds at most 10,000 answered requests awaiting their reports;
- `servewaf` refuses a request with more than 50 cookies or more than 100 header
fields (see "Answering in time" under "`servewaf`" in
- `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));
- `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 `servewaf`'s answer, and answers
`502` to a longer one.
- `rproxy` reads at most 1 MiB of the body of `discriminator`'s answer, and
answers `502` to a longer one.
## `servewaf`'s answer and `rproxy`'s wait
## `discriminator`'s answer and `rproxy`'s wait
`SWWAF_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 `SWWAF_REPUTATION_TIMEOUT`, since the DNS blocklists and AbuseIPDB are
asked in the background (see "Answering in time" under "`servewaf`" in
asked in the background (see "Answering in time" under "`discriminator`" in
[`SPEC.md`](../SPEC.md)).
## `rproxy`
`smallwebwaf rproxy` reads the settings below and no others. They are read once
at start, and an invalid value stops the start. None can be given as a file,
since `rproxy` never touches disk. "`rproxy`" in [`SPEC.md`](../SPEC.md) says
what they do.
`sww rproxy` reads the settings below and no others. They are read once at
start, and an invalid value stops the start. None can be given as a file, since
`rproxy` never touches disk. "`rproxy`" in [`SPEC.md`](../SPEC.md) says what
they do.
A time here is a whole number of milliseconds above zero, such as `2000`.
- `SWRP_WAF_BACKEND` (required, no default): `servewaf`'s URL. An `http` or
- `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 `servewaf`'s
answer, to a question and to a report. A time; never `off`.
- `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_DEFAULT_DISPOSITION` (default `allow`): what is done with a request when
`servewaf` 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 `servewaf` gives, such as an error.
`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.
- `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
@@ -383,8 +384,8 @@ A time here is a whole number of milliseconds above zero, such as `2000`.
## The image's command
`SMALLWEBWAF_COMMAND` (default `rproxy`) chooses what the image runs and what
its health check checks: `rproxy` or `servewaf` (see "Deployment" in
`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.
## Where earlier settings went
+1 -1
View File
@@ -7,7 +7,7 @@ Each has a top-level `version` of 1.
## `bans.json`
Active and past bans: every ban an admin made, and up to `SWWAF_MAX_BANS` of
those `servewaf` made. Per entry:
those `discriminator` made. Per entry:
- `netblock`, `start` and `expires` (`null` for a permanent ban);
- `cause`: `attack`, `limit`, `admin` or `crowdsec`;