clawbot
17c5dd2438
check / check (push) Successful in 7m25s
`smallwebwaf rproxy` reads the first 64 KiB of each body, asks servewaf over HTTP/1.1, and passes what servewaf allows to the app within its limits. Any other answer goes to the visitor as servewaf gave it. SWRP_DEFAULT_DISPOSITION decides only when servewaf cannot be connected to, does not answer at all, or does not answer within SWRP_TIMEOUT_MS. A method SPEC.md does not list gets 405. Duplication: internal/rproxy copies passing-on code from internal/proxy until #172 removes the originals. Rule suppressed: gosec G704 and G705; gosec at internal/smallwebwaf/rproxy_test.go:431; tagliatelle at internal/requestlog/requestlog.go:203; paralleltest on one test. Judgement call: an answer over 1 MiB, or with a status below 200, gets 502. Judgement call: every target not starting with one / gets 400. Model: opus-5-5
60 lines
2.4 KiB
Markdown
60 lines
2.4 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.
|
|
|
|
- `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
|
|
```
|
|
|
|
## `servewaf`
|
|
|
|
`smallwebwaf servewaf` answers these endpoints at its own address. No check runs
|
|
on those requests (see "`servewaf`" in [`SPEC.md`](../SPEC.md)).
|
|
|
|
## `rproxy`
|
|
|
|
`smallwebwaf rproxy` answers only the health check, at its own address. It asks
|
|
`servewaf` about any other request under `/_smallwebwaf/` (see "`rproxy`" in
|
|
[`SPEC.md`](../SPEC.md)).
|