# command-run attestor

Source: https://www.testifysec.com/docs/cilock/attestors/command-run/

The cilock command-run attestor records the executed argv, exit code, captured stdout/stderr, and an optional Linux ptrace forensic record, signed into in-toto evidence.

**Predicate version v0.3 (legacy)**

| Name | `command-run-v0.3` |
| --- | --- |
| Predicate type | `https://aflock.ai/attestations/command-run/v0.3` |
| Lifecycle | `execute` |
| Default binary? | No |
| Recommended trace | off — no syscall tracing needed |
| Auto-attaches when | *Not auto-detected — attach explicitly with `-a`.* |

The facts in this box are generated from the CI/lock binary's own catalog (`cilock tools list`). Do not hand-edit — run `npm run gen:catalog`.

**Predicate version v0.2 (latest)**

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.

| Name | `command-run` |
| --- | --- |
| Predicate type | `https://aflock.ai/attestations/command-run/v0.2` |
| Lifecycle | `execute` |
| Default binary? | Yes |
| Recommended trace | off — no syscall tracing needed |
| Auto-attaches when | *Not auto-detected — attach explicitly with `-a`.* |

The facts in this box are generated from the CI/lock binary's own catalog (`cilock tools list`). Do not hand-edit — run `npm run gen:catalog`.

## 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](https://www.testifysec.com/docs/cilock/attestors/command-run/#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[]`, `renames[]`, `deletes[]`, `permChanges[]` (mode bits + `setExec`). A write is named by the file behind the descriptor, not by the descriptor number's last open: the eBPF backend reads the file's identity when the write starts, and the ptrace backend pins the descriptor at entry and checks it at exit. `/proc/<pid>/fd/N` is used only when it still names that same file. A write to a socket, pipe or device is not a file write; a write to a regular file through stdout or stderr (a shell's `> out`) is. When a large trace moves to its companion, writes are stored one record per process and file; see [Large builds](https://www.testifysec.com/docs/cilock/guides/large-builds#the-trace-companion-format-command-run-tracev02).
 - `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

| Flag | Shorthand | Default | What it does |
| --- | --- | --- | --- |
| `--trace` | `-r` | `false` | Sets `SysProcAttr.Ptrace = true` on the child and enables the ptrace loop in `tracing_linux.go`. On macOS, enables the sandbox-report tracer. Unsupported platforms refuse tracing. |

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

| `--attestor-command-run-keep-arg` | — | none | Repeatable. An exact argv element the URL-userinfo scrub leaves as it is in the signed `cmd`, for an argument shaped like `user:password@host` that is not a credential, such as the Maven goal `codex:getLatestBuild@secret.store`, whose dotted execution id reads as a proxy host. Each value is one whole element, matched byte for byte; commas are part of the value. |

**Keeping an argv element.** The argv scrub redacts an element shaped like a proxy credential, because shape cannot tell which program reads it. A positional argument of `mvn`, `mvnw` or `mvnd` that is a Maven goal with a plain execution id (`codex:getLatestBuild@secretStoreBuild`, `docker:tag@tag`) is kept in `cmd` with no declaration. The same bytes given to any other program, as the value of a Maven option, in a traced `cmdline` or in output are still redacted, and so is a goal whose execution id has a dot, a port or token-like bytes: `mvn clean codex:getLatestBuild@secret.store` is signed as `mvn clean ******@secret.store`. An element `KEY=value` whose key names a secret (`-Dpassword=`, `--client-secret=`, `NPM_TOKEN=`) keeps its key and loses its value, and so does the element after a flag that names one (`--password <value>`). Declare the element to keep it:

```bash
cilock run --attestor-command-run-keep-arg 'codex:getLatestBuild@secret.store' -- mvn -B clean codex:getLatestBuild@secret.store install
```

Only an element equal to a declared string skips the scrub. A longer element that contains it (`-Dgoal=codex:...`) or a near-miss is redacted as before. Sensitive environment values are masked first, so a declaration cannot sign a secret from the environment. The traced `cmdlines[]` table and stdout/stderr keep their redaction. The record carries the declaration in `_meta.argvKept`: `declared` (sorted), `cmdIndexes` (the `cmd` indexes kept that would otherwise have been redacted) and `cmdlines: "redacted"`. It is absent when nothing was declared, and the predicate type stays `command-run/v0.2`. A policy can refuse any relaxation with `not input._meta.argvKept`. Do not declare a credential: it is already in your pipeline config, and declaring it signs it.

## Output shape

```json
{
  "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://a@evil.example@github.com/x`, `evil.example:8080/x@github.com` and `pip install git+https://github.com/org/repo@v1.2.3` 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`:
  
   
  
  ```text
<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]`.
 - **The ptrace backend kills what the command leaves running.** When the traced command exits, every process of its tree that is still running (a `nohup server &`, a database started for later steps, a Gradle or Kotlin daemon, a `setsid` child) is killed, and cilock prints `cilock-trace: killed N process(es) the traced command left running, so none acts after the trace (diagnostics.ptraceDescendantsKilled): pid 1234 sleep (sleep 300)`. Everything such a process did before the kill is in the trace. Before, it sat frozen in a ptrace stop until cilock exited and then ran on untraced. There is no opt-out: start a long-lived service outside the traced step, or run Gradle with `--no-daemon`.
 - **`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.

## Host context (`_meta.host`)

A traced run (`--trace`) records the machine it ran on in `_meta.host`, read once before the command starts. It is additive under v0.2 and absent from an untraced run. It exists so a reviewer can tell why two traces of the same build differ: a different kernel, a missing capability, a container, or the other tracer.

| Field | What it holds |
| --- | --- |
| `kernel` | `sysname`, `release`, `version`, `machine` from uname, plus `lockdown`, `lsm`, `btf` and `seccompActions`. `cmdline` keeps only allowlisted boot parameters (`mitigations`, `lockdown`, `lsm`, `preempt`, `isolcpus` and similar) with short values; `cmdlineOtherParams` counts the rest |
| `sysctl` | `kernel.unprivileged_bpf_disabled`, `kernel.perf_event_paranoid`, `kernel.kptr_restrict`, `kernel.bpf_stats_enabled`, `kernel.yama.ptrace_scope`, `net.core.bpf_jit_enable`, `net.core.bpf_jit_harden` |
| `cpu` | `onlineSet`, `affinity` (CPUs the build may use) and `model` |
| `cgroup` | `unified` (cgroup v2), `cpuMax`, `memoryMax` |
| `process` | `capEffective`, `capPermitted`, `seccompMode`, `noNewPrivs` of cilock itself |
| `virtualization` | `hypervisor`, `dmiVendor`, `dmiProduct`, and `container`: every indicator found (`/.dockerenv`, `/run/.containerenv`, `systemd:<manager>`, `kubernetes`), `[]` when none |
| `tracer` | `backend` (`ebpf` or `ptrace+seccomp`), `requested` (`CILOCK_TRACE_MODE`, `auto` when unset) and `reason`, such as `auto; eBPF probe passed` or `auto; eBPF unavailable: <why>`; and `privilege` when cilock ran from Linux file capabilities (see "Traced build privileges") |
| `tracee` | what the traced build was started with: `drop`, `uid`, `gid`, and for `root-capless`, `user` and `sudo` the `capBounding`, `capInheritable`, `capAmbient` and `noNewPrivs` read back from the thread the build was forked from. See "Traced build privileges" below |
| `cilock` | `version`, `revision` and `modified` of the cilock build that signed the trace |
| `unreadable` | a map from each dotted field name that could not be read to why |

Every value is read back from the host. A value cilock could not read is absent and named in `unreadable`, never recorded as zero or empty. Off Linux only `cilock` is filled and `unreadable.kernel` is `not linux`. The record names no host or user: uname's nodename is never read, the cgroup path is not recorded, and environment variables count only by presence. No policy reads `_meta.host` today; treat it as context for a reviewer, not as a check.

### Traced build privileges (`_meta.host.tracee`)

On Linux the tracer holds `CAP_BPF`, `CAP_PERFMON`, `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE`. A build that inherited them could unload or blind the eBPF programs, attach to cilock, or write its memory, so a traced build never starts with them unless the operator says so. `drop` records which rule applied:

| `drop` | When | The build |
| --- | --- | --- |
| `root-capless` | cilock runs as root with no sudo invoker: a container (`docker --privileged`, `--cap-add`), a Kubernetes pod | keeps uid 0, so it can still write its own tree, and execs with no capabilities, an empty bounding set and `no_new_privs`. A setuid or file-capability program cannot give them back |
| `user` | `CILOCK_TRACEE_USER=<uid>:<gid>`, cilock running as root | runs as that uid and gid with no supplementary groups, no capabilities and `no_new_privs` |
| `sudo` | root under sudo with a non-zero `SUDO_UID` | runs as `SUDO_UID:SUDO_GID`, under `setpriv --no-new-privs` when setpriv is on `PATH`, with the same empty bounding, inheritable and ambient sets and `no_new_privs` as the other drops |
| `inherited` | `CILOCK_TRACEE_USER=inherit` | keeps cilock's root and every capability in `process.capEffective` |
| `file-capabilities` | cilock is not root and runs from Linux file capabilities | keeps cilock's uid and starts with every set empty, an empty bounding set and `no_new_privs` |
| `none` | cilock is not root and holds no capabilities | has cilock's own uid |

If cilock cannot prove the drop (for example a container without `CAP_SETPCAP` cannot empty the bounding set), the run stops before the build starts and names the remedy. A uid-0 build without capabilities can still read and write files root owns and can signal cilock, so it can stop or kill it. Set `CILOCK_TRACEE_USER` to a build user to close that too. A trace with no `tracee` record comes from an older cilock, and a policy must read it as `inherited`.

For every drop but `none` and `inherited`, `tracee.exec` is the build's own `capPermitted`, `capEffective`, `capInheritable`, `capAmbient`, `capBounding` and `noNewPrivs`, read from `/proc/<pid>/status` after its exec. A build that exited before the read leaves it absent, with the reason in `unreadable["tracee.exec"]`.

When cilock runs from file capabilities (`setcap ...=p` on the binary), `tracer.privilege` records it: `source` (`file-capabilities`), `permitted` (the set at exec), `keptPastSetup` (what the drop before the build kept, only to leave the build's mount namespace), `threads` (how many threads the last drop read back) and `dropped`, true only when the final drop to no capabilities read back on every thread. cilock holds the capabilities effective only on the thread loading the tracer, drops them on every thread before it reads any path the caller named or starts the build, and refuses environment that changes what the tracer loads (`CILOCK_DEV_BPF_*`, `CILOCK_DIAGNOSE`, `CILOCK_OPEN_CAPTURE`, ...). Every other cilock command drops them at start.

## Trace overhead (`summary.diagnostics.overhead`)

Every traced run on Linux records what the tracer cost the build in `summary.diagnostics.overhead`. `total.seconds` is the wall time the tracer put on the build's critical path: attaching, the time some traced process was blocked on the tracer, and detaching. `total.parts` names what was summed, and `total.ratio` divides it by the untraced-equivalent wall time. The parts are `attach`, `fanotifyWait` (the fanotify permission wait, under both backends), `ptraceStop` (the ptrace tracer loop's busy time) and `detach`.

Each figure has a `status` of `measured` or `not_measured`, and a figure that was not measured carries a `reason` instead of a 0. `CILOCK_TRACE_OVERHEAD_STATS=1` adds the detail: per-event sums (`threadSeconds`), the hashing share of the fanotify wait (`fanotifyHash`), and the eBPF programs' run time (`bpf`). That last one turns on `BPF_ENABLE_STATS`, which is host-wide while held, so it stays opt-in, and it is CPU time across every CPU, never part of the headline. The field is informational; no policy reads it.

## CLI example

Builtin. cilock always runs this when it wraps a command. Naming `command-run` in `--attestations` is accepted: cilock logs a warning and records it once, the same as when it is left out. With `--trace`, captures ptrace-level syscall info per child process.

```bash
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](https://github.com/aflock-ai/attestor-compliance-examples/tree/main/01-command-run).

## See also

- [Catalog row](https://www.testifysec.com/docs/cilock/reference/attestor-catalog)
 - [Defending against supply-chain attacks](https://www.testifysec.com/docs/cilock/tutorials/defending-against-supply-chain-attacks)
 - Upstream: [witness/command-run.md](https://github.com/in-toto/witness/blob/main/docs/attestors/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.

**Predicate version v0.1 (legacy)**

| Name | `command-run-v0.1` |
| --- | --- |
| Predicate type | `https://aflock.ai/attestations/command-run/v0.1` |
| Lifecycle | `execute` |
| Default binary? | No |
| Recommended trace | off — no syscall tracing needed |
| Auto-attaches when | *Not auto-detected — attach explicitly with `-a`.* |

The facts in this box are generated from the CI/lock binary's own catalog (`cilock tools list`). Do not hand-edit — run `npm run gen:catalog`.

 

---

**This page is generated from the CI/lock tool catalog.** Don't edit it here — the source is [`attestation/detection/docs/command-run.doc.md`](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/command-run.doc.md) in [aflock-ai/rookery](https://github.com/aflock-ai/rookery). The same catalog powers `cilock tools show command-run` in the CLI, so a single edit keeps the terminal and the website in sync.

[Edit this page →](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/command-run.doc.md) ·  [Add a new tool →](https://github.com/aflock-ai/rookery/new/main/attestation/detection/docs)

When you open the pull request: if you are an **AI agent**, add the `ai-agent` label. If you are a **human**, add the `human` label.

Reference generated from the product documentation. Match commands and support details to your installed release.
