sneak
fbb5158377
check / check (push) Failing after 14m17s
`smallwebwaf rproxy` reads the first 64 KiB of each body, asks servewaf, and passes what servewaf allows to the app within its own size and time limits. It reports each request servewaf answered. SWRP_DEFAULT_DISPOSITION decides when servewaf gives no answer. Duplication: internal/rproxy copies passing-on code from internal/proxy until #172 removes the originals. Rule suppressed: gosec G704 on servewaf's URL, a setting. Rule suppressed: gosec G705 on the answer written to the visitor. Judgement call: the SWRP_ size and time limits take off; SWRP_TIMEOUT_MS does not. 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)).
|