sneak
dfb44c5546
check / check (push) Waiting to run
The old README opened with project history and one list of a hundred settings. The new one leads with what smallwebwaf is, what it protects against, how to build and deploy it, how it sits in front of the app, what happens to a request, the settings most deployments touch, how to check it works and how to develop it. The reference material, every setting, bans, rule files, the Core Rule Set, the admin endpoints, the request log, alerts, metrics, state files, lookups, reputation sources, the image and gitea, moves to files under docs/, each linked from the README. Every statement was checked against the code on next. Model: fable-5-1
36 lines
2.1 KiB
Markdown
36 lines
2.1 KiB
Markdown
# Admin endpoints
|
|
|
|
`smallwebwaf` answers these requests itself, on the app's own address and
|
|
through traefik like any other request. Apart from the health check, each needs
|
|
a token, sent as `Authorization: Bearer <token>`, and goes through every check
|
|
any other request goes through. It is answered where another request would be
|
|
passed to the app: a banned client stays refused, and each request counts toward
|
|
rate limiting. A missing or wrong token is answered `401`, in `observe` mode
|
|
too. Such a refusal counts toward the error burst, so a client guessing tokens
|
|
is soon banned. While a token is unset, its endpoints answer `404`.
|
|
|
|
- `GET /_smallwebwaf/healthz`: `200` and `ok`, to anyone, before any check and
|
|
without asking the app.
|
|
- `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. A client's address bans its
|
|
IPv4 netblock (`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group. `duration` is a
|
|
duration such as `1h` or `7d`, or `permanent`. The ban starts at once, with
|
|
the cause `admin`. 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 it has never been seen. Under `bans`, every ban covering the
|
|
address, with its notes.
|
|
|
|
An admin whose own address is banned lifts that ban by editing `bans.json` (see
|
|
[`bans.md`](bans.md)).
|