Ban lists: where Guard and fail2ban ban addresses

A program bans an address (every port, or a protocol's ports) for a
time; the ban list says what it is kept from: the firewall, some hosts
behind it, or everything. Bans drop ahead of every rule, close the
address's connections, group IPv6 by /64, are kept in the database
across restarts and audited. Never banned: the inside, the firewall's
own addresses, the caller, the list's never. bans grant (bans:write:LIST),
hc banlist/bans/ban/unban, Traffic -> Bans, a fail2ban action in contrib/,
and failed logins and refused tokens logged for Guard and fail2ban.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/api.md

@@ -108,15 +108,15 @@ Lists replace the old ones. `probation_seconds` 0 is the default (120).
 
 ### Objects
 
-Zones, sets, services, rules, port forwards, source NAT and redirects
-share one pattern, `/{kind}` with kind `zones`, `sets`, `services`,
-`rules`, `forwards`, `snats` or `redirects`:
+Zones, sets, services, rules, port forwards, source NAT, redirects and
+ban lists share one pattern, `/{kind}` with kind `zones`, `sets`,
+`services`, `rules`, `forwards`, `snats`, `redirects` or `banlists`:
 
 | | |
 |---|---|
 | `GET /{kind}` | all of them, in order; `GET /rules?chain=input` for one chain; `GET /services` includes the built-in ones |
 | `POST /{kind}[?before=ID\|after=ID\|first=1]` | create; rules, forwards and NAT rules go last unless given a `position`, or placed before or after another of their chain, or first, in the same change (one history entry; staged in a changeset, the place goes with it) |
-| `GET /{kind}/{ref}` | by ID, or name for zones, sets, services and forwards |
+| `GET /{kind}/{ref}` | by ID, or name for zones, sets, services, forwards and ban lists |
 | `PATCH /{kind}/{ref}` | change the fields given (a JSON merge: `null` clears) |
 | `DELETE /{kind}/{ref}` | refused while something uses it |
 | `POST /rules/{ref}/reset-quota` | start a rule's quota again now (`config:write`; audited, not staged). Optional body: `{"address": "192.168.1.23"}` starts only that address's again (a per-address quota; an IPv6 address counts for its /64; 404 if it hasn't used the quota); `{"give": 5368709120}` takes that many bytes off what was used instead (the address's, or every address's), until the next reset |
@@ -145,7 +145,18 @@ The objects:
 
 A source NAT rule is a match (as a rule's, without the rule's other
 fields) with `"to"` (empty: masquerade), a redirect a match with
-`"to_port"`. Times are seconds (`timeout`).
+`"to_port"`. A ban list ([bans.md](bans.md)):
+
+```json
+{"name": "web", "scope": "hosts", "hosts": ["10.0.10.57"], "never": ["trusted"],
+ "default_time": 3600, "max_time": 604800, "max_entries": 10000, "group_v6": 64, "comment": "", "disabled": false}
+```
+
+`scope` is `firewall`, `hosts` or `everything`; 0 is the default for the
+numbers, and `max_time` -1 is no limit. A ban list can't be renamed.
+Someone with a `bans` grant but no `config:read` may read the ban lists
+the grant covers (`GET /banlists`, `GET /banlists/{ref}`). Times are
+seconds (`timeout`).
 
 ### Statistics
 
@@ -196,6 +207,22 @@ These need `sets:read` or `sets:write`, for that set
 ([permissions.md](permissions.md)); they aren't on probation or in the
 history, but are audited.
 
+### Bans
+
+| | |
+|---|---|
+| `GET /bans` | the active bans of every ban list you may read: `id`, `list_id`, `list`, `address` (an address, or an IPv6 prefix), `protocol` and `port` (none: every port), `expires` and `timeout` (seconds left; none: no end), `created`, `who`, `source`, `reason` |
+| `GET /banlists/{ref}/bans` | one list's |
+| `POST /banlists/{ref}/bans` | ban: `{"address": "203.0.113.9", "protocol": "tcp", "ports": "ssh", "time": 3600, "source": "guard/ssh", "reason": "…"}`. `ports` is a number, a string (`"22"`, `"http,https"`, `"0:65535"` or `"all"` for every port) or a list; without a protocol a number is TCP and UDP, a service its own protocols. `time` 0 is the list's default, -1 its longest; longer is cut down. 201 with `{"bans": [ban…, "existing": true for a renewed one], "closed": N}` (connections closed) |
+| `DELETE /banlists/{ref}/bans/{id}` | lift one ban |
+| `DELETE /banlists/{ref}/bans?address=A` | lift all of an address's bans (404 if it has none) |
+
+These need `bans:read` or `bans:write` for the list
+([permissions.md](permissions.md)); bans aren't on probation or in the
+history, but are audited (`ban.add`, `ban.remove`). Refusals: `422
+never_ban` (inside, the firewall's own, the caller's own, or in the
+list's `never`), `422 list_full`, `409` for a disabled list.
+
 ### Probation
 
 | | |