Capability matrix

Every operation CSM performs that needs privilege beyond reading its own files, or that writes outside its own directories, with the privilege it needs and the setting that stops it.

Print it on any host, before or after install:

csm privileges              # table
csm privileges --json       # machine-readable

The command prints a static inventory. It does not load CSM configuration or probe host privileges, so it can be used before installing the service. Output failures produce a nonzero exit status in text, JSON and Markdown formats.

How to read it

Needs is what the operation requires from the kernel. root means uid 0 rather than one capability: the operation reads or writes files owned by many different accounts, or drives a panel tool that assumes root. Today the daemon runs as a single root process; splitting it into a small privileged helper plus a reduced-privilege main process is planned, and this inventory is its first stage. Capability names describe the privileged kernel interfaces as well as the root filesystem access. For BPF, tracing and LSM programs need CAP_BPF plus CAP_PERFMON; cgroup socket programs need CAP_BPF plus CAP_NET_ADMIN. CAP_SYS_ADMIN is the broader fallback on older kernels. These requirements follow the kernel program-load checks.

Trigger is automatic when the daemon may start the operation on its own, and operator when it runs only in response to a command or a button. Not running the command is how an operator operation is turned off.

Writes lists what the operation writes while it runs, including writes made by a tool it invokes. Paths starting with / are filesystem paths; everything else is a resource named <kind>:<name>. “nothing (read-only)” means the operation only reads. Paths describe default locations; configured account roots, state, rule, log, spool and policy paths replace those defaults and may require service drop-ins. Shared CSM state and audit-log writes are grouped in the state rows. This is not a list of every possible path written by an external panel tool.

Turn it off is the config key and YAML value that stops the named operation. Dotted keys describe nested YAML mappings; they are not literal top-level keys. Apply changes before restarting the daemon: several controls are read only at startup. A row saying “not configurable” has no single config switch that stops all its callers. disabled_checks takes a list and only affects scheduled checks. Stopping new work does not undo installed rules, hooks, quarantines or blocks; use the subsystem removal commands for that. Disabling the forward guard removes its existing Exim configuration, which is itself a host write.

Action record says whether the operation writes to the action log. “no” does not mean the operation is silent; it means it is not on that stream yet and the daemon log is where it appears.

Without the privilege is what an operator loses by withholding it, so the row reads as a decision rather than a demand.

Relationship to the systemd sandbox

The daemon runs under ProtectSystem=strict with an explicit writable-path allow-list; see service confinement. The two lists are compared by tests: every declared in-daemon filesystem write must fit a packaged grant, and every grant must have an in-daemon writer. Empty inventories and grant lists fail. Paths are compared on directory boundaries, and an operation outside the sandbox cannot justify a daemon grant. The unit parser rejects invalid paths and unsupported syntax, including continuations, specifiers and directory flags, instead of guessing which locations are writable. Tests cannot discover omitted operations or prove the privilege and disable claims; those require tracing the runtime code.

Operations marked “outside the systemd sandbox” run as standalone operator commands or transient services forked by PID 1. The latter use direct execution on hosts without a reachable systemd service manager. Mixed operations have separate rows for their in-daemon writes, such as the AF_ALG marker repair and forward-guard lookup refresh. The service sandbox does not bound external tools.

Turning most of it off at once

mode: observe stops automatic remediation and integration deployment, and refuses configurations that enable those subsystems. It still maintains CSM state, loads temporary BPF capability probes in BPF builds, and invokes the KernelCare probe, which can update its own cache. It is not a guarantee of zero host writes. See observe mode.

The matrix

The risk tier says what can go wrong if an operation acts on the wrong target: 0 changes nothing outside CSM’s own directories, 1 records a recommendation or dry-run decision, 2 is a low-risk change such as a probe, challenge gate or mail hold, 3 quarantines, blocks or denies a target, and 4 signals processes, reloads services, or rewrites content or configuration. Rows describe maximum live effect, so preview-only tier 1 has no separate row today. A tier does not promise automatic rollback; see recovery gaps below and the current contracts in the JSON inventory. The TIER column of csm privileges and the JSON inventory use the same 0 to 4 numbers.

Regenerate the table with go run ./cmd/csm privileges --markdown. A gate in internal/ci fails when the page and the inventory disagree.

Risk tiers and recovery coverage

csm privileges --json reports each operation’s risk tier as a number from 0 to 4. A row with no tier would report -1; the test suite refuses such an inventory, so a release never ships one. The tier is the operation’s maximum live effect on a wrong target. It is not the severity of the finding that triggered the operation.

Seven operations carry a safety contract in the JSON inventory: respond.block_ip, operate.manual_firewall, integrate.firewall_ruleset, integrate.challenge_port_gate, integrate.challenge_snippet, respond.quarantine_file and respond.clean_file. Each states the authority it needs, how the target is revalidated before the change, how the change is reversed, and the limit that bounds it. The contracts describe current behaviour, including what it does not cover. Every other operation that changes the host states the recovery this inventory does not yet cover: