thaloco/banger
1
Fork 0
Code Pull requests Releases Packages Activity Actions

docs: fix three security-sensitive doc/code mismatches

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

14
docs/privileges.md
View file

@ -137,7 +137,7 @@ the file-sync path, even if the owner edits config to try.
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.
- One tap interface named `tap-fc-<vm_id>`. Created on VM start,
deleted on VM stop or crash recovery.
@ -189,9 +189,10 @@ What `uninstall` does, in order:
What `uninstall` does NOT do automatically:
- 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.
The bridge itself is intentionally persistent — a future reinstall
reuses it. To remove it manually: `sudo ip link del banger0`.
first (`banger vm prune` or `banger vm stop <name>` for each VM) so
the per-VM teardown drops them. The bridge itself is intentionally
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
exists; the entries are harmless if the bridge is gone.
- 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
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,
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`.
- `ReadWritePaths=/var/lib/banger`.