From 33639efe0c3c8975fe7f906c43ce368c49af53e1 Mon Sep 17 00:00:00 2001
From: Thales Maciel <thales@thalesmaciel.com>
Date: Tue, 28 Apr 2026 17:30:58 -0300
Subject: [PATCH] docs: fix three security-sensitive doc/code mismatches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 README.md          |  5 +++--
 docs/privileges.md | 14 ++++++++------
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 69a43d4..c775866 100644
--- a/README.md
+++ b/README.md
@@ -75,8 +75,9 @@ The split matters:
   the owner home read-only.
 - `bangerd-root.service` is the only process that keeps elevated host
   capabilities, and that capability set is limited to the host-kernel
-  primitives banger actually uses (`CAP_CHOWN`, `CAP_SYS_ADMIN`,
-  `CAP_NET_ADMIN`).
+  primitives banger actually uses (`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`).
 
 To inspect or refresh the services:
 
diff --git a/docs/privileges.md b/docs/privileges.md
index a991da4..bef1411 100644
--- a/docs/privileges.md
+++ b/docs/privileges.md
@@ -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`.