aios/docs/security/trusted-builder-captrace.md

Trusted Candidate Builder — CAP_SYS_PTRACE security contract

Status: formal (V2R2C2) · Applies to: deploy/systemd/aios-trusted-candidate-builder.service (the live baseline unit)

0. Live baseline (rea truth, not nominal)

The authoritative deployed unit is the live systemd unit on the hw control plane host:

• User=root / Group=root (the builder runs as root)
• socket: aios-trusted-candidate-builder.socket ListenStream=/run/aios-trusted-candidate-builder.sock, SocketUser=root, SocketGroup=gitops, SocketMode=0660
• credentials: LoadCredentialEncrypted for signing_private_key / builder_hmac (under /etc/credstore.encrypted/aios-trusted-candidate-builder/) and source_admission_hmac (under /etc/credstore.encrypted/aios-release-source-admission/)
• hardening: NoNewPrivileges, PrivateTmp, PrivateNetwork, ProtectSystem=strict, ProtectHome, ProtectControlGroups, ProtectKernelTunables/Modules/Logs, RestrictAddressFamilies=AF_UNIX, LockPersonality, MemoryDenyWriteExecute, RestrictSUIDSGID, SystemCallArchitectures=native
• capability: AmbientCapabilities=CAP_SYS_PTRACE + CapabilityBoundingSet=CAP_SYS_PTRACE (live current state)

The tracked deploy/systemd/aios-trusted-candidate-builder.service is kept byte-identical (LF-normalized) to the live unit so sha256 drift is detectable: live sha256 = 9d194c23ec981528d29d55f601d1be858635ac6229c7e25c10736df4e44042d3.

This contract deliberately does NOT introduce a separate non-root -ptrace unit. §2 of the V2R2C2 instruction forbids inventing a distinct service uid/group, ProtectProc/ProcSubset, credential paths or socket ownership that diverge from the live baseline. The live baseline is root + the single minimal capability, and that is the only variant tracked.

1. Why a capability is declared at all

TrustedCandidateBuilder._verify_peer validates the connecting peer before signing any candidate. It reads three /proc/<pid> views of the peer:

view	function	failure → error
/proc/<pid>/cgroup	_resolve_cgroups	PEER_CGROUP_UNAVAILABLE
/proc/<pid>/exe	_resolve_process_identity	PEER_PROCESS_UNAVAILABLE
/proc/<pid>/cmdline	_resolve_process_identity	PEER_PROCESS_UNAVAILABLE

A cross-uid readlink("/proc/<pid>/exe") for a peer of a different uid is subject to the Yama ptrace_scope sysctl and returns EACCES for a process without the minimal CAP_SYS_PTRACE. Result: the builder fails closed (PEER_PROCESS_UNAVAILABLE), which is safe but loses availability for legitimate cross-uid peers.

The minimal CAP_SYS_PTRACE restores the ability to inspect the peer's /proc view across uids.

2. Capability sensitivity — MANDATORY reading

CAP_SYS_PTRACE is a high-sensitivity capability. It is not a read-only helper: it broadens the process's observation and debugging authority across uids, including ptrace, reading /proc/<pid>/mem, and inspecting another user's process state. It is therefore:

• limited to the single capability CAP_SYS_PTRACE (both AmbientCapabilities and CapabilityBoundingSet), and
• scoped to the dedicated builder service unit only.

It must never be used to imply "read-only" or "no control authority." It carries real inspection/debug power and is declared for one concrete purpose: restoring cross-uid /proc/<pid>/exe identity resolution for the builder's peer validation. Nothing more.

Three-state verification contract

• A. No CAP_SYS_PTRACE (fail-closed): cross-uid /proc/<pid>/exe raises PermissionError(EACCES) → resolvers fail closed → PEER_PROCESS_UNAVAILABLE (and PEER_CGROUP_UNAVAILABLE for cgroup). Never degrade to allow.
• B. Minimal CAP_SYS_PTRACE + legitimate peer: peer uid in allowed_peer_uid, cgroup in allowed_peer_cgroups, executable matches allowed_peer_executable_prefix, argv matches the runtime argument contract → readiness READY.
• C. CAP present but peer illegitimate: any identity check fails → PEER_IDENTITY_DENIED / PEER_CGROUP_DENIED / PEER_PROCESS_DENIED. The capability must never bypass the identity policy — it restores the ability to perform identity validation, not the authorization itself.

3. Operational rules

• Keep CapabilityBoundingSet and AmbientCapabilities pinned to exactly CAP_SYS_PTRACE. Never use capability wildcards (e.g. CAP_* applying to every capability).
• Keep NoNewPrivileges=true; ambient capabilities are the only inheritance path into the exec'd Python process.
• Do not re-introduce a separate non-root unit with a different uid/group/ProtectProc/ProcSubset/credential paths/socket ownership (see §0). The root + single-capability unit is the live baseline.
• Runtime verification (three-state) MUST be executed on the real Linux host that runs systemd; the adversarial states require real uids/cgroups/argv.

4. Testing

• Local (no /proc peer needed): the resolvers are exercised with monkeypatched PermissionError(EACCES) — mirroring the exact bytes a missing CAP_SYS_PTRACE / cross-uid read produces — covering cgroup → PEER_CGROUP_UNAVAILABLE, exe → PEER_PROCESS_UNAVAILABLE, cmdline → PEER_PROCESS_UNAVAILABLE (see tests/test_trusted_candidate_builder_captrace.py).
• Host (Linux, required for final acceptance): run systemd-analyze verify on the tracked unit; confirm the unit matches the live sha256; launch with/without the capability; confirm A → PEER_PROCESS_UNAVAILABLE, B → READY, C → *_DENIED.