sneak
ed6ba53747
check / check (push) Successful in 4m27s
`smallwebwaf servewaf` runs today's checks on the visitor's request a question carries and answers allow, deny or close, instead of passing it to an app. rproxy's report then counts the bytes toward the byte limits and adds the request to the client's history. SPEC.md gives the exact question, answer and report, which rproxy follows. `smallwebwaf` with no command is unchanged. Judgement call: a third disposition, close, since closing the question's connection would read as servewaf down and let the request through. Judgement call: allow can answer a new request id, since a visitor behind a trusted proxy can choose its own. Model: opus-5-5
50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# Admin endpoints
|
|
|
|
The endpoints under `/_smallwebwaf/`, what each takes and what each answers.
|
|
"Admin endpoints" in [`SPEC.md`](../SPEC.md) says which checks they go through
|
|
and how their tokens work. `smallwebwaf servewaf` answers them at its own
|
|
address, without those checks (see "`servewaf`" in [`SPEC.md`](../SPEC.md)).
|
|
|
|
- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone.
|
|
- `GET /_smallwebwaf/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
|
|
(`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 `smallwebwaf` 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.
|
|
|
|
## Examples
|
|
|
|
With `SWWAF_ADMIN_TOKEN` set, and the token in `$TOKEN`:
|
|
|
|
```sh
|
|
# Every ban.
|
|
curl -H "Authorization: Bearer $TOKEN" https://app.example/_smallwebwaf/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"}' \
|
|
https://app.example/_smallwebwaf/bans
|
|
|
|
# Lift the bans on 203.0.113.9.
|
|
curl -H "Authorization: Bearer $TOKEN" -X DELETE \
|
|
https://app.example/_smallwebwaf/bans/203.0.113.9
|
|
|
|
# What smallwebwaf knows of 203.0.113.9.
|
|
curl -H "Authorization: Bearer $TOKEN" \
|
|
https://app.example/_smallwebwaf/clients/203.0.113.9
|
|
```
|