command-run attestor

Records the command cilock run executed — argv, exit code, captured stdout/stderr, and (when --trace is enabled on Linux) a per-process ptrace record of opened files, network activity, file mutations, and security-sensitive syscalls.

What it captures

Top-level CommandRun fields (json tags from the struct):

• cmd — the argv slice that was executed.
• stdout — the verbatim stdout the process wrote (captured into a bytes.Buffer and stored as a string).
• stderr — the verbatim stderr, same mechanism.
• exitcode — the child's exit status.
• processes — populated only when --trace is on; one ProcessInfo entry per traced PID.
• program: the program argv[0] started, recorded on every run, traced or not, on every platform. There is no flag to turn it off. See The program record.

Each ProcessInfo carries: program, processid, parentpid, programdigest, comm, cmdline, exedigest, exedigestSource (what exedigest measures: mapped-image is SHA-256 of /proc/<pid>/exe read through a single descriptor, claimed only when the backend can PROVE both that the measured file is the image this exec mapped and that the image stayed write-protected across the whole measurement - today only the ptrace backend, which holds the tracee stopped at the execve return; path-hash means the value is a copy of programdigest, the bytes at the caller-named path when the tracer opened it, which is not proof of what executed; empty means unlabelled, never "mapped image"; a policy comparing exedigest against an image allowlist must require mapped-image), exedigestDowngradeReason (why a backend that would otherwise report the mapped image reported a path hash: not-kernel-bound - the exec event carries no kernel identity to bind the measurement to, which is the case for the eBPF backend because its execve event comes from a syscall-entry kprobe fired before the kernel resolves or maps anything, so that backend always downgrades; unprotected-measurement - write protection could not be GUARANTEED for the whole measurement, so the bytes hashed need never have executed. This covers the process no longer mapping the image (ETXTBSY lapses once the last executing reference goes away), running on Linux 6.11 or 6.12 where an in-place write to a mapped image is not ETXTBSY-denied, and being unable to determine the kernel version at all - an unknown answer downgrades exactly as a negative one does, because a producer that cannot tell whether writes were possible is in the position of one that knows they were. Empty means no downgrade. It exists so a verifier can tell "the producer declined to claim what it could not prove" from "this producer never populated the field"), environ, specbypassisvuln, exitcode (per-process exit status; for signal-terminated processes uses the shell convention 128 + signal_number; absent/zero means "still running when trace ended"), openedfiles (a map[path]DigestSet populated from openat syscalls and re-resolved at trace end), plus three nested structures:

• network (NetworkActivity): sockets[], connections[] (each with syscall, family, address, port, fd, timestamp, and hostname for TLS SNI from ClientHello on port 443), dnsLookups[].
• fileOps (FileActivity): writes[] (path resolved via /proc/pid/fd/N), renames[], deletes[], permChanges[] (mode bits + setExec).
• syscallEvents[] — notable syscalls: memfd_create, ptrace, mount, clone (with namespace flags), dup2 (socket→stdio = reverse-shell pattern), mprotect (PROT_EXEC), prctl (PR_SET_NAME / PR_SET_DUMPABLE / PR_SET_NO_NEW_PRIVS), setsid, setns, init_module/finit_module.

The program record

cmd is the text the caller typed, and terraform names whatever PATH found. program names the file:

• lookup: path-search (a bare name searched on PATH), workdir-relative (a name with a separator, resolved against the working directory) or absolute.
• path: the absolute path the exec's own lookup produced, not lexically cleaned (./t run in /w is /w/./t). On Windows it carries the PATHEXT extension Start would add (.\tool records ...\.\tool.exe), and cilock hands Start that same resolved name, so the file hashed and the file started are one string. With no working directory cilock can name, a relative path stays relative, opened against the directory the exec uses.
• realPath, realPathSource: the real path after every symlink, read back from the descriptor that was hashed (proc-self-fd on Linux, f-getpath on macOS), never from a second walk of the name. When the descriptor cannot answer, the name is resolved and kept only if it is the same file (evalsymlinks-confirmed); otherwise realPath is empty, realPathSource is unresolved, realPathReason says why, and the digest is kept. An unreadable program reports name, or on Linux proc-self-fd through an O_PATH descriptor.
• digest, sizeBytes: sha256 (plus any --hashes algorithm) of the whole file, with no size limit, taken through the same settle-and-bracket read the tracers use.
• file: device, inode, link count, setId (setuid, setgid, or a Linux file capability) and fsType of the same descriptor. setId is always emitted: true or false only when established, null with setIdReason when it is not. On Linux the capability is read through the hashed descriptor, and only "no such attribute" or "this file system carries none" establishes false; any other error leaves null. A rule that requires setId == false refuses null.
• format: elf, mach-o, mach-o-universal, pe, script or other, from the first bytes the hash read; absent when those bytes could not be read.
• host (GOOS/GOARCH) and workdir, the directory the child started in.
• checkout.relation: always emitted, and unknown in this release with the reason "containment is not computed by this CI/lock build". A rule that requires outside refuses it.
• wrapper: present when cilock itself started another program first: sandbox-exec under --trace on macOS, with its own path and digest.
• unresolved: why there is no digest. The only expected cause is a program cilock cannot read (permission denied: the program is executable but not readable, for an execute-only file). The command still runs.
• executionBinding: always emitted, in the scripts[] vocabulary. It is always unverified in this release: the digest is of the file the lookup named, read before the command started, and nothing proves those bytes are the ones the kernel then executed. bindingReason says so, or says "the exec target changed after the program was recorded" when anything other than a wrapper cilock names rewrote the exec target before it started. On Linux under sudo that includes the setpriv privilege drop, which searches PATH again as the invoking user.

A pin on program.digest.sha256 is a pin on argv[0] only. env A=1 tool, sh -c "...", timeout 600 tool and npx tool record the launcher, and a shim (pyenv, rustup, the macOS xcrun /usr/bin/git) records the shim, not the tool it starts.

Absolute paths, including home directories. path, realPath and workdir are absolute, so on a laptop they carry the login name (/Users/<login>/.nvm/...) into every signed attestation and to every place the attestation goes: Archivista, a platform that stores evidence, and the provider of any AI policy, which receives the whole command-run attestor as its input.

Older verifiers ignore the field: it is additive, and the predicate type stays command-run/v0.2. A verifier built before it shows Rego no program, whatever the signed bytes carry.

When to use

Always — it's the spine of every cilock run. --trace turns the attestor from "I ran this command and here is its stdio" into a forensic record of what the process did at the syscall level.

Flags

| --trace-file-content | — | false | With tracing on macOS, records bounded workspace text snapshots from file-access reports. Requires explicit opt-in. |

There are no --attestor-commandrun-* flags — commandrun.init() registers with no registry.Configurer options.

Output shape

{
  "cmd": ["go", "build", "./..."],
  "stdout": "...verbatim bytes the child wrote to stdout...",
  "stderr": "...verbatim bytes the child wrote to stderr...",
  "exitcode": 0,
  "program": {
    "lookup": "path-search",
    "path": "/usr/local/go/bin/go",
    "realPath": "/usr/local/go/bin/go",
    "realPathSource": "proc-self-fd",
    "digest": {"sha256": "..."},
    "sizeBytes": 16100000,
    "file": {"device": 2049, "inode": 1311234, "links": 1, "setId": false, "fsType": "ext4"},
    "format": "elf",
    "host": "linux/amd64",
    "workdir": "/home/runner/work/app/app",
    "checkout": {"relation": "unknown", "reason": "containment is not computed by this CI/lock build"},
    "executionBinding": "unverified",
    "bindingReason": "this CI/lock build does not bind the program to the exec: the digest is of the file the lookup named, read before the command started"
  },
  "processes": [
    {
      "program": "/usr/local/go/bin/go",
      "processid": 12345,
      "parentpid": 12344,
      "programdigest": {"sha256": "..."},
      "comm": "go",
      "cmdline": "go build ./...",
      "exedigest": {"sha256": "..."},
      "exedigestSource": "mapped-image",
      "openedfiles": {"/path/to/go.mod": {"sha256": "..."}},
      "environ": "GOFLAGS=... GOPATH=...",
      "specbypassisvuln": false,
      "network": {
        "sockets": [{"family": "AF_INET", "type": "SOCK_STREAM", "protocol": 0, "fd": -1}],
        "connections": [{"syscall": "connect", "family": "AF_INET", "address": "140.82.112.3", "port": 443, "fd": 7, "timestamp": "2026-05-21T12:00:00Z", "hostname": "proxy.golang.org"}],
        "dnsLookups": [{"serverAddress": "1.1.1.1", "serverPort": 53}]
      },
      "fileOps": {
        "writes": [{"path": "/tmp/go-build/main", "bytes": 4096, "timestamp": "..."}]
      },
      "syscallEvents": [{"syscall": "memfd_create", "detail": "...", "timestamp": "..."}]
    }
  ]
}

Gotchas

• stdout / stderr are raw bytes, not digests. The attestor stores stdoutBuffer.String() and stderrBuffer.String() into the predicate byte for byte, with two redactions that also apply to cmd and every traced cmdline: the value of an environment variable whose name marks it as a secret (TOKEN, SECRET, PASSWORD, ...) becomes [REDACTED], and the userinfo of a URL (http://user:pass@proxy:3128, user:pass@proxy:3128) becomes ******, the rule the environment attestor applies to its values, read word by word. A URL is never recorded with a host the command did not use: where Go, Python, WHATWG and curl do not read one userinfo and one host, the URL keeps only its scheme and ******@/, so https://[email protected]@github.com/x, evil.example:8080/[email protected] and pip install git+https://github.com/org/[email protected] all lose their host and path. An argv element that is a URL, or a flag whose value is one, is read whole, so --proxy=http://u:my pw@proxy:3128 is redacted. So is one that is a URL once its tabs and newlines are removed, as WHATWG removes them (http:/<TAB>/u:pass@proxy:3128). A KEY= prefix on a word or an element is not taken on trust, because = is also base64 padding: the positional proxy value dG9rZW4=@proxy:3128 is a token and a proxy, not a key and an empty userinfo. Such a word is read whole as well as after its key, and where the whole reading finds a credential the key goes with it, so HTTPS_PROXY=user:pass@proxy:3128 in output becomes ******@proxy:3128. The name-based redaction runs first, because it finds a value byte for byte and the URL redaction rewrites the bytes: a secret variable whose value holds a URL (API_TOKEN=https://u:p@host/?token=...) becomes [REDACTED] whole, query token included. In a traced cmdline it runs before the elements are read apart, with the NULs between them read as spaces, so a value the shell split into two elements is masked too; in cmd each element is matched on its own. Nothing else is changed. Large output goes into the signed envelope as-is, and so does a secret that is neither: a password with a space in it inside a line of output, a token on its own, or a credential glued to more text (u:p@proxy:3128,localhost).

• Trace capabilities differ by backend. Linux supports eBPF/ptrace; macOS uses sandbox reports with the limitations below. Unsupported platforms refuse tracing.

• macOS tracing needs log stream, which macOS runs only for the admin group. A user outside admin (a CI account, say) either joins it (dseditgroup -o edit -a <user> -t user admin) or gets a sudoers rule for exactly the command cilock runs, and cilock then starts the collector as sudo -n without ever prompting. Install it with visudo -f /etc/sudoers.d/cilock-logstream:

  <user> ALL=(root) NOPASSWD: /usr/bin/log stream --style ndjson --predicate senderImagePath CONTAINS\[c\] "sandbox"

  The escaped \[c\] is required: unescaped, sudoers reads [c] as a glob class and the rule stops matching. The rule lets the user read, as root, the Sandbox kext's reports for every process on the machine, which an admin can already do, and nothing else. Without either fix, --trace refuses before running the command and prints both. The attestation is the same whichever way the collector started.

• Tracing needs ptrace(2). Default Docker drops it; you need --cap-add=SYS_PTRACE (and to not be under a restrictive seccomp profile). Kubernetes pods need an equivalent securityContext.capabilities.add: [SYS_PTRACE].

• openedfiles is populated from openat — and digested at open time, with a retry pass at trace end (retryOpenedFiles) for files that didn't exist yet. Files opened-but-never-read still appear.

• TLS SNI extraction is best-effort. The tracer peeks the first write on any fd that connected to port 443 and parses the ClientHello for the server_name extension. Only one peek per fd; non-printable hostnames are discarded.

• DNS detection is a heuristic — any connect() to port 53 is recorded as a DNS lookup. Non-DNS traffic to port 53 will be misclassified.

CLI example

Builtin. cilock always runs this — there's no --attestations command-run toggle. With --trace, captures ptrace-level syscall info per child process.

cilock run --step my-step \
  --signer-file-key-path key.pem --outfile attestation.json \
  --trace \
  -- make build 

Validated. Always part of every cilock run. See the full real-data example at https://github.com/aflock-ai/attestor-compliance-examples/tree/main/01-command-run.

See also

• Catalog row
• Defending against supply-chain attacks
• Upstream: witness/command-run.md

macOS traced file content (opt-in)

cilock run --trace --trace-file-content extends the sandbox-exec+oslog backend with kernel file-read-data reports scoped to the working directory using a sandbox subpath filter. System and toolchain reads outside that scope are not requested; they are not collected and then discarded in Go. A startup canary must demonstrate that this channel delivers file-access reports; otherwise requested capture refuses before the workload starts. Ordinary tracing and --script-capture retain their existing defaults. The flag currently requires macOS.

The scope is deliberately incomplete for reads outside the workspace, including external dependencies and symlink targets outside it. The startup probe uses a separate literal-path reporting rule for its private temporary file; that rule is not applied to the workload.

This captures observed access to workspace files including scripts, Makefiles, includes, and files read by child processes. Each attributed event appears in processes[].syscalls[] in v0.2 (syscallEvents[] in the expanded representation), with syscall: "file-read-data", a path, timestamp, and outcome: "permitted-not-confirmed". The sandbox reports permission to access, not a successful read or its returned bytes.

fileAtCollectorOpen holds a snapshot with status, optional content, digest, and sizeBytes. captured-at-collector-open means the collector read those bytes after delivery of the report. It is not execution binding or proof of what the process consumed. Generated files deleted before delivery may be unavailable; a replacement before collector access can yield different bytes. Nothing is promoted into openedfiles or verified scripts from these observations. Absence of an event does not establish absence of access.

Content is opt-in separately from script operand capture. Only regular UTF-8 text without NUL bytes under the run's working directory is eligible. Scoped opens refuse symlink escapes; FIFOs/devices are not read. Limits are 64 KiB per file, 4 MiB read per run, and 256 attempted workspace snapshots. Repeated reads consume the same budget because the contents may have changed. No partial body is emitted when a size/budget limit is reached. Status records distinguish outside-workspace, unavailable, binary, non-regular, oversize, changed-during- capture, and exhausted-budget cases. Policies requiring full coverage must refuse these omissions rather than treat them as negative findings.

summary.diagnostics.darwin.fileReadsObserved records the capability probe, fileContentScope names the workspace, fileReadReports counts attributed reports, and unprovenFileReadReports counts reports whose process ownership was not established. No content is opened for a process lacking capture-time attribution. These are observations, not a completeness guarantee.

Captured content can contain credentials. Review the capture scope and secret handling before publishing the signed evidence; this flag does not redact source bytes or authorize uploading them. For Jev, use these snapshots as context, not proof that an adversarial build consumed the pictured bytes.