smallwebwaf/docs/admin-endpoints.md

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).
• 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).