import { appendFileSync, readFileSync } from "node:fs"; import path from "node:path"; /** * Opt-in record of every process the provider launch chain starts. * * The cgroup system test has to prove which processes ran, with which argv, * and in which cgroup. Sampling `/proc` from outside could not: `systemd-run * --scope` execs into the scope wrapper on the same PID, a fresh child shows * its parent's argv until it execs, and a 5 ms sampler kept recording the * wrong phase. Each stage therefore writes its own line here, at the moment it * knows the answer: a process records itself from the kernel's view * (`/proc/self`), and a spawner records a child with the exact argv vector it * handed to `spawn`. * * Off unless `PROVIDER_PROCESS_TRACE_PATH` is set, and nothing in CI sets it. * The trace is a second place argv lands. Persisting it in production would * turn a future argv regression — a credential or the provider command put on * a command line — into a durable file instead of a transient `/proc` value, * and as audit evidence it would need the same publish-path, size and schema * controls as the sealed reports. Neither is part of this fix. * * A line carries only role, PID, parent PID, argv and (for self records) the * cgroup. Never the environment: that is where credentials and the provider * command travel. Every spawn in the launch chain must call * {@link traceSpawnedProviderProcess}; a spawn that does not is invisible to * the test. */ export const PROVIDER_PROCESS_TRACE_VARIABLE = "PROVIDER_PROCESS_TRACE_PATH"; export type ProviderProcessRole = | "supervisor" | "guardian" | "systemd-run" | "scope-wrapper" | "bwrap"; export type ProviderProcessTraceEntry = Readonly<{ role: ProviderProcessRole; pid: number; ppid: number; argv: readonly string[]; cgroup?: string; }>; /** Records the calling process as `role`, as the kernel sees it. */ export function traceOwnProviderProcess(role: ProviderProcessRole): void { if (!process.env[PROVIDER_PROCESS_TRACE_VARIABLE]) return; writeTrace(() => ({ role, pid: process.pid, ppid: process.ppid, argv: readFileSync("/proc/self/cmdline", "utf8").split("\0").slice(0, -1), cgroup: readFileSync("/proc/self/cgroup", "utf8").trim(), })); } /** * Records a child this process just spawned with exactly `argv`. * * The argv is the vector passed to `spawn`, not a later `/proc` read: by the * time anyone looks, `systemd-run` may already have exec'd into the wrapper. * No cgroup either, for the same reason — the wrapper records its own. */ export function traceSpawnedProviderProcess( role: ProviderProcessRole, pid: number | undefined, argv: readonly string[], ): void { if (!process.env[PROVIDER_PROCESS_TRACE_VARIABLE] || !pid) return; writeTrace(() => ({ role, pid, ppid: process.pid, argv: [...argv] })); } /** * The trace setting for a child whose environment is otherwise rebuilt from * an allow-list (`systemd-run` hands its own environment to the wrapper). */ export function providerProcessTraceEnvironment(): Readonly> { const target = process.env[PROVIDER_PROCESS_TRACE_VARIABLE]; return target ? { [PROVIDER_PROCESS_TRACE_VARIABLE]: target } : {}; } /** * A diagnostic must not decide whether a provider run passes, so a failed * write is reported and dropped. Whoever reads the trace sees the line missing. */ function writeTrace(entry: () => ProviderProcessTraceEntry): void { const target = process.env[PROVIDER_PROCESS_TRACE_VARIABLE]!; try { // Relative would resolve against a different cwd in each process. if (!path.isAbsolute(target)) throw new TypeError(`${PROVIDER_PROCESS_TRACE_VARIABLE} must be absolute`); appendFileSync(target, `${JSON.stringify(entry())}\n`, { mode: 0o600 }); } catch (error) { process.stderr.write(`provider process trace was not written: ${ error instanceof Error ? error.message : String(error) }\n`); } }