abrown38andClaude Opus 5.5
a45c893830
- Connections: the kernel's tracked connections, read and closed over ctnetlink (internal/conntrack, raw netlink like the drop log), with their NAT and TCP state; closing one makes the rules check its next packet again (GET /connections, POST /connections/close; hc connections; Traffic → Connections). - Rules can check every packet (every_packet, --every-packet): before established connections are accepted, so a drop or reject also stops connections already open. They can't accept. - A packet tracer (internal/trace): a table of its own, inet housecarl-trace, marks the packets a filter picks, `nft monitor trace` reports every rule and policy they meet in every table, and the tracer names what accepted or dropped them, Housecarl's rules by name (POST, GET, DELETE /trace; hc trace; Traffic → Trace). One trace at a time, at most 200 packets and 20 a second; the table goes when it ends. e2e: 157 checks, among them an upload a normal block doesn't stop and an every-packet one does, and a trace naming the blocking rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
88 lines
3.6 KiB
Markdown
88 lines
3.6 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 |
|
||
| `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`.
|
||
|
||
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 log:read` |
|
||
| `operator` | `config:write sets: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 and
|
||
dynamic set entries are recorded with who, from where and how: `session`,
|
||
`token` or `socket`.
|