docs: fix three security-sensitive doc/code mismatches

A pre-release audit caught three places where the docs misrepresent
the trust model. Each is a claim users would read while auditing
banger and reach the wrong conclusion.

  * docs/privileges.md:140, 194 — bridge default was documented as
    "banger0" but the code default (model.DefaultBridgeName) is
    "br-fc". A user following the manual-removal recipe would `ip
    link del banger0` against a non-existent interface.
  * docs/privileges.md:192 — uninstall recipe said "stop your VMs
    first via `banger vm stop --all`". That flag doesn't exist; vm
    stop is a per-name action. Replaced with the actual options:
    `banger vm prune` (bulk) or per-VM `banger vm stop <name>`.
  * docs/privileges.md:255 and README.md:78-79 — helper unit's
    CapabilityBoundingSet was listed as 5 caps; the actual set in
    commands_system.go:370 is 11 (we added FOWNER/KILL/MKNOD/SETGID/
    SETUID/SYS_CHROOT during Phase B and never updated the docs).
    Updated both lists; the "what's NOT included" rationale stays
    accurate against the new positive list.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Thales Maciel 2026-04-28 17:30:58 -03:00
parent 4d8dca6b72
commit 33639efe0c
No known key found for this signature in database
GPG key ID: 33112E6833C34679
2 changed files with 11 additions and 8 deletions

View file

@ -75,8 +75,9 @@ The split matters:
the owner home read-only. the owner home read-only.
- `bangerd-root.service` is the only process that keeps elevated host - `bangerd-root.service` is the only process that keeps elevated host
capabilities, and that capability set is limited to the host-kernel capabilities, and that capability set is limited to the host-kernel
primitives banger actually uses (`CAP_CHOWN`, `CAP_SYS_ADMIN`, primitives banger actually uses (`CAP_CHOWN`, `CAP_DAC_OVERRIDE`,
`CAP_NET_ADMIN`). `CAP_FOWNER`, `CAP_KILL`, `CAP_MKNOD`, `CAP_NET_ADMIN`, `CAP_NET_RAW`,
`CAP_SETGID`, `CAP_SETUID`, `CAP_SYS_ADMIN`, `CAP_SYS_CHROOT`).
To inspect or refresh the services: To inspect or refresh the services:

View file

@ -137,7 +137,7 @@ the file-sync path, even if the owner edits config to try.
For each running VM banger creates: For each running VM banger creates:
- One bridge (default `banger0`, configurable). Created on first VM - One bridge (default `br-fc`, configurable). Created on first VM
start, never deleted automatically. start, never deleted automatically.
- One tap interface named `tap-fc-<vm_id>`. Created on VM start, - One tap interface named `tap-fc-<vm_id>`. Created on VM start,
deleted on VM stop or crash recovery. deleted on VM stop or crash recovery.
@ -189,9 +189,10 @@ What `uninstall` does, in order:
What `uninstall` does NOT do automatically: What `uninstall` does NOT do automatically:
- It does not delete the bridge or any iptables rules. Stop your VMs - It does not delete the bridge or any iptables rules. Stop your VMs
first (`banger vm stop --all`) so the per-VM teardown drops them. first (`banger vm prune` or `banger vm stop <name>` for each VM) so
The bridge itself is intentionally persistent — a future reinstall the per-VM teardown drops them. The bridge itself is intentionally
reuses it. To remove it manually: `sudo ip link del banger0`. persistent — a future reinstall reuses it. To remove it manually:
`sudo ip link del br-fc`.
- It does not undo `resolvectl` routing on a bridge that no longer - It does not undo `resolvectl` routing on a bridge that no longer
exists; the entries are harmless if the bridge is gone. exists; the entries are harmless if the bridge is gone.
- It does not remove the owner user, the owner's home, or anything - It does not remove the owner user, the owner's home, or anything
@ -252,9 +253,10 @@ Root helper (`bangerd-root.service`):
- Same hardening as above, plus `ProtectHome=yes` (no host-home - Same hardening as above, plus `ProtectHome=yes` (no host-home
visibility at all from the helper). visibility at all from the helper).
- `CapabilityBoundingSet=CAP_CHOWN CAP_DAC_OVERRIDE CAP_NET_ADMIN CAP_NET_RAW CAP_SYS_ADMIN`. - `CapabilityBoundingSet=CAP_CHOWN CAP_DAC_OVERRIDE CAP_FOWNER CAP_KILL CAP_MKNOD CAP_NET_ADMIN CAP_NET_RAW CAP_SETGID CAP_SETUID CAP_SYS_ADMIN CAP_SYS_CHROOT`.
Only the capabilities required for tap/bridge, iptables, dmsetup, Only the capabilities required for tap/bridge, iptables, dmsetup,
loop devices, and Firecracker. No `CAP_SYS_BOOT`, no `CAP_SYS_PTRACE`, loop devices, ownership fixups, device node creation, and Firecracker
process management. No `CAP_SYS_BOOT`, no `CAP_SYS_PTRACE`,
no `CAP_SYS_MODULE`, no `CAP_NET_BIND_SERVICE`. no `CAP_SYS_MODULE`, no `CAP_NET_BIND_SERVICE`.
- `ReadWritePaths=/var/lib/banger`. - `ReadWritePaths=/var/lib/banger`.