CAP-AUDIT(8)

🌸 NAME 🌸

hiii bestie, welcome to cap-audit(8) — the sysadmin-utilities girlies know 👑 — and what she does is discover the minimal capability set for a program. that's the whole thing. that's the assignment. 💅

---

🦋 SYNOPSIS 🦋

cap-audit [options] -- command [args...]
cap-audit --service file [-- command-or-args...]

---

✨ DESCRIPTION ✨

okay so cap-audit traces a target process and all its descendants, and records literally every single kernel capability check it performs. she does this with eBPF, hooking the capability verification paths in the kernel, and then uses libcap-ng to format the results all pretty for you. the events get filtered down to only the traced process tree so the overhead stays low — efficiency queen 🧚

the auditor fork/execs the command you asked for, registers its PID for tracing before exec, and automatically tracks child PIDs as they show up. when execution wraps up, she reports which capability checks came back granted or not granted, and hands you deployment snippets showing how to grant the minimal set. iconic. 🎀

for syscall-associated checks that return not granted, cap-audit correlates the check with the raw kernel syscall return value when that's available. and heads up: a single syscall invocation can contain more than one of these checks, so capability-check counts and syscall-outcome counts are independent — they don't have to match. successful syscalls show that the not-granted check did not prevent that invocation from completing. EPERM and EACCES results are reported as permission-related failures that require manual investigation 🙈. other failures are retained as diagnostic evidence. EINTR and kernel restart results are treated as interruption evidence: interruption alone is inconclusive, but a mix of interrupted and successful invocations requires manual investigation, because cap-audit cannot distinguish call sites or arguments. capabilities with only not-granted checks are never added to automatic recommendations — you should add one only after confirming that required functionality fails because it is absent. no vibes-based capability grants, bestie. 🚫

the capability masks installed by successful capset(2) calls are also recorded. a capability requested by capset without a confirmed granted check gets reported under CAPSET-ONLY CAPABILITIES rather than being classified as required. deployment snippets retain it as a current-binary compatibility constraint, because removing it from the deployment boundary can cause the application's capset to fail. to remove such a capability you gotta do the whole ritual: first remove it from the application's capability setup, then exercise representative code paths in additional runs, and then narrow the deployment boundary. failed capset calls do not establish this constraint, periodt.

the kernel also checks CAP_SETPCAP during capset when the requested change doesn't actually require it. cap-audit excludes that check from capability-use counts only when the kernel's requested inheritable set is contained in the union of the old inheritable and permitted sets. other CAP_SETPCAP checks are retained, and so are explicit successful capset requests and configured service capabilities. this decision does not depend on the executable's file capabilities. 💅

UID/GID and supplementary-group capability checks that happen between successful PR_SET_KEEPCAPS enable and disable calls on the same thread are classified as initialization, even when an intermediate capset has already occurred. this is how we recognize the temporary identity capabilities used by capng_change_id(3). checks outside that credential-changing pattern keep their usual phase. if no successful disable is observed before exec, thread exit, or the end of tracing, cap-audit warns and retains the original phase classification — and JSON and YAML also report this as keepcaps_transition_incomplete. 🫶

service recommendations identify requested SETUID/SETGID capabilities whose observed use is confined to initialization, including a completed KEEPCAPS transition. these are not needed for observed operation, but they remain in the deployment configuration because the unchanged application needs them during startup. unexercised paths still require review and testing before you go changing the application's retained capabilities. 🧐

runtime tracing requires root or the CAP_BPF and CAP_PERFMON capabilities, plus kernel BTF data in /sys/kernel/btf/vmlinux. no shortcuts, sorry babe.

---

💖 OPTIONS 💖

• -h, --help — show a help message and exit. the classic.
• -v, --verbose — print each capability check as it occurs. live commentary mode ✨
• -j, --json — emit the analysis as JSON.
• -y, --yaml — emit the analysis as YAML.
• -s, --service FILE — parse a systemd service unit file, simulate the service user, group, supplementary group, capability, and NoNewPrivileges settings in the traced child, and emit service-specific recommendations. without an explicit command after --, the parsed ExecStart= command is traced. with --, a command can be supplied explicitly; if the first supplied word starts with -, it is treated as replacement arguments for the parsed ExecStart= executable. 😌

capabilities explicitly configured in the unit but not observed during the trace are retained in a current-service-compatible recommendation. they are also identified as removal candidates, because the relevant functionality may not have been exercised. cap-audit does not generate a configuration that removes them — targeted testing or manual review must first confirm that each configured capability is unnecessary. 💀

the generated service configuration preserves the NoNewPrivileges= setting used for the audit. when that setting is disabled, enabling it has not been validated by the trace and must be tested separately, including service functionality that starts child processes or helper programs. 🙈

cap-audit does not load the environment configured by Environment= or EnvironmentFile=. a standalone $NAME argument in ExecStart= is therefore treated as unset and omitted. supply an explicit command after -- when a non-empty expansion is needed for the audit. 💅

a single ! prefix on the ExecStart= executable is supported. it leaves the configured user, group, and supplementary group changes to the executed program, while continuing to apply the configured capability and NoNewPrivileges= settings. the fully privileged + prefix and the legacy !! prefix are rejected, because cap-audit cannot safely simulate their execution semantics. the @ prefix is also rejected, because the command model does not support a separate executable path and overridden first argument. 🚫

only one ExecStart= command is supported. multiple commands, including oneshot sequences, are rejected. an empty assignment resets the command and permits a subsequent replacement. unit-file line continuations are rejected — put each directive on one line, bestie. command quoting supports single and double quotes, empty quoted arguments, and backslash escapes for literal backslashes and quote characters. other escape sequences, like hexadecimal or whitespace escapes, are rejected instead of being passed with a different meaning. 😭

if a capability check targets a user namespace different from the namespace in which cap-audit started, the observation is retained in the diagnostic output but automatic capability recommendations are suppressed. the safe scope of a capability grant cannot be determined from the target namespace alone. 🦋

• -- — end option parsing and treat the rest of the command line as the program to execute under audit.

---

🔥 EXIT STATUS 🔥

the program returns 0 on success. non-zero values indicate that an error occurred while setting up tracing or executing the target command. 👑

---

🌈 NOTES 🌈

1. this utility observes the application behavior to decide what is needed. if you don't exercise all functionality, it can result in an incomplete inventory of needed capabilities. if it can't see it, cap-audit can't record it. 🫶
2. event collection has fixed memory limits: 8192 traced tasks, 1024 in-flight capability checks, 4096 syscall records, and a 256 KiB event ring buffer. exhausting a map or the ring buffer can lose observations and produce an incomplete capability inventory. such losses are not currently reported. 😭
3. when auditing a daemon, pass options to keep it in the foreground. if it forks and exits, that will end the session and you'll only get the capabilities traced up to the exit. here's an example keeping the daemon in the foreground:

cap-audit /usr/sbin/sshd -D

EXPERIMENTAL: cap-audit output is experimental, but very close. 💅

---

🎀 FILES 🎀

• /sys/kernel/btf/vmlinux

---

⭐ SEE ALSO ⭐

• capabilities(7)
• filecap(8)

---

👑 AUTHOR 👑

Steve Grubb

---

okay that's the whole page, bestie — Red Hat, August 2026, cap-audit(8), and she ate. now go trace something. 🦋💖✨