abrown38andClaude Opus 5.5
500bfc7bdd
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>
93 lines
3.9 KiB
Markdown
93 lines
3.9 KiB
Markdown
# Users, permissions and tokens
|
||
|
||
## Users
|
||
|
||
**Administrators** may do everything, including managing users. Everyone
|
||
else gets **grants**, `resource:access`:
|
||
|
||
| Resource | read | write |
|
||
|---|---|---|
|
||
| `config` | settings, zones, sets, services, rules, NAT, the ruleset, history, interfaces, probation, changesets (the web UI shows the forms locked) | change them, stage and apply changesets (your own, or anyone's for administrators), undo, import, confirm and roll back; close connections; start and stop traces |
|
||
| `sets` | dynamic sets' entries | add and remove entries |
|
||
| `bans` | ban lists' bans, and the lists the grant names | ban and unban ([bans.md](bans.md)) |
|
||
| `log` | hit counters, the log, connections, traces | – |
|
||
| `audit` | the audit log | – |
|
||
| `*` | all of the above | |
|
||
|
||
A `sets` grant can name the sets it covers: `sets:write:guests` may
|
||
change the entries of the set `guests` and no other;
|
||
`sets:read:guests,blocked` may read two. That is the grant for another
|
||
program, such as Steward's captive portal, which should be able to let a
|
||
client in and nothing more. A dynamic set's entries need a `sets` grant
|
||
even for those with `config:write`.
|
||
|
||
A `bans` grant names ban lists the same way: `bans:write:web` may ban
|
||
into the list `web` (and read it) and nothing else, the grant for Guard
|
||
or fail2ban on the web server.
|
||
|
||
Only administrators may delete other tables (`hc takeover`), and manage
|
||
users and the certificate (`hc cert`, Server → Certificate).
|
||
|
||
**Roles** are ready-made sets of grants:
|
||
|
||
| Role | Grants |
|
||
|---|---|
|
||
| `viewer` | `config:read sets:read bans:read log:read` |
|
||
| `operator` | `config:write sets:write bans:write log:read audit:read` |
|
||
| `log` | `log:read`, e.g. for a monitoring script |
|
||
|
||
```sh
|
||
hc user add sam --role operator
|
||
hc user add portal --no-password --grant sets:write:guests # tokens only
|
||
hc user update sam --grant config:read --grant log:read
|
||
```
|
||
|
||
The last administrator can't be removed, demoted or disabled.
|
||
|
||
## API tokens
|
||
|
||
A token has its user's permissions, or fewer. A token made with `--role`
|
||
or `--grant` can do only that, even if its user can do more:
|
||
|
||
```sh
|
||
hc token create portal --user portal --grant sets:write:guests --expires 365d
|
||
```
|
||
|
||
The secret is shown once; only its hash is stored. A restricted token can
|
||
only create tokens with a subset of its own grants. The web UI only offers
|
||
roles within what your account may do; a token with more would get no
|
||
more than its user anyway.
|
||
|
||
**Rotating** gives a token a new secret, keeping its ID, name and
|
||
permissions, so only the programs that use it need updating:
|
||
|
||
```sh
|
||
hc token rotate 7 --grace 1h # the old secret works for another hour
|
||
hc token rotate --current --save # this CLI's own token
|
||
```
|
||
|
||
A token that expires gets its lifetime again, from now (`--expires 90d`
|
||
or `never` to change it). Without `--grace` the old secret stops at once:
|
||
use that when it may have leaked. Using an old secret during its grace
|
||
period is logged, naming the token and the address, so you can find the
|
||
programs still to update. A restricted token may rotate itself and tokens
|
||
no wider than itself. `hc token list` shows when each token was last
|
||
used, and from where. `hc token revoke ID` stops one at once.
|
||
|
||
## The local socket
|
||
|
||
On the firewall, `/run/housecarl/housecarl.sock` lets root and the
|
||
`housecarl` user act as administrator without a token, and their changes
|
||
aren't on probation. The audit log shows them by their system user name.
|
||
Both can already change the machine's firewall, so this adds convenience,
|
||
not power. Anyone else on the socket needs a token, and their changes are
|
||
on probation like any other.
|
||
|
||
## The audit log
|
||
|
||
Logins (and failed ones), users, tokens, every configuration change (with
|
||
its history entry), changesets created, applied and discarded,
|
||
confirmations and rollbacks, imports, takeovers,
|
||
dynamic set entries and bans are recorded with who, from where and how: `session`,
|
||
`token` or `socket`.
|