# Attestors

Source: https://www.testifysec.com/docs/cilock/attestors/

Each CI/lock attestor captures one slice of build/run state and emits it as an in-toto predicate inside the DSSE envelope. A single cilock run invocation can chain many attestors together, so the resulting collection is the union of every signal you asked for.

Each CI/lock attestor captures one slice of build/run state and emits it as an in-toto predicate inside the DSSE envelope. A single `cilock run` invocation can chain many attestors together, so the resulting collection is the union of every signal you asked for.

 

This section has **one page per attestor** — what it captures, when to use it, available flags, output shape, and common gotchas.

 

For a comparative overview (predicate type, lifecycle phase, which ones ship by default), see the [Attestor catalog](https://www.testifysec.com/docs/cilock/reference/attestor-catalog).

 

## Lifecycle phases (when an attestor fires)

 

| Phase | Fires | Examples |
| --- | --- | --- |
| `prematerial` | Before materials are recorded | `git`, `environment`, `github`, `aws` |
| `material` | Snapshot of inputs before the wrapped command runs | `material` (always run) |
| `execute` | The wrapped command itself | `command-run` (always run), `github-action` |
| `product` | Snapshot of outputs after the command runs | `product` (always run) |
| `postproduct` | After products are recorded | `sbom`, `sarif`, `secretscan`, `slsa`, `vex`, `oci` |
| `verify` | Only inside `cilock verify` | `policyverify` |

 

The `material → execute → product` core fires on every `cilock run`. Everything else comes from the default set, from auto-detection, or from `--attestations`.

 

## Always run

 

Three attestors fire on every `cilock run` that wraps a command. They're the spine of the in-toto link statement CI/lock emits:

 

- **[material](https://www.testifysec.com/docs/cilock/attestors/material)** — digests of the working directory before the command
 - **[command-run](https://www.testifysec.com/docs/cilock/attestors/command-run)** — the wrapped command, exit code, optional ptrace
 - **[product](https://www.testifysec.com/docs/cilock/attestors/product)** — digests of files changed or created after the command

 

`--no-default-attestor material` or `--no-default-attestor product` drops one of the two snapshot attestors. Dropping both is refused, because the collection would carry no material or product evidence.

 

## Default-on

 

When `--attestations` (`-a`) is not specified, CI/lock additionally enables:

 

- **[environment](https://www.testifysec.com/docs/cilock/attestors/environment)** — OS, hostname, username, environment variables (sensitive ones masked)
 - **[git](https://www.testifysec.com/docs/cilock/attestors/git)** — commit, branch, dirty status, parents, refs, remotes
 - **platform**: binds the run to your logged-in TestifySec platform tenant. It is dropped from the default set when there is no platform session (`--offline`, or not logged in) and when the binary does not include it. It has no page in this section yet.

 

To override, pass `--attestations "<comma-separated names>"`. An explicit list is used exactly as given: the defaults above are replaced, not extended.

 

## Auto-detection

 

When you do not pass `-a`, `cilock run` also inspects the wrapped command, its environment and the working directory, and attaches every attestor whose detection rule matches. The rules live in each attestor's `detector.yaml` (`argv_prefix`, `file_exists`, `env_set`): a `.git/HEAD` attaches `git`, a `go build` or `go.mod` attaches `go-build`, and a scanner attestor attaches only when that scanner is the wrapped command.

 

- Pass `-a` and detection is off: your list is the exact set.
 - `--workload auto` forces detection even alongside `-a`; `--workload manual` turns it off.
 - `cilock run --validate-only ...` prints the planned attestor set without running the command.
 - An attestor that auto-detection attached and that then fails does not fail the run. Name it with `-a` to make a failure fatal.

 

## Default vs. builder opt-in

 

Every attestor below ships in the default `cilock` binary unless its page says "**builder opt-in only**" — those exist in rookery but aren't blank-imported in the default. To add one, [build a custom CI/lock](https://www.testifysec.com/docs/cilock/guides/build-a-custom-cilock).

 

## Naming gotcha

 

The directory name in `plugins/attestors/` is not always the attestor name you pass to `--attestations`. Use the canonical name (see each attestor's page, or the [catalog](https://www.testifysec.com/docs/cilock/reference/attestor-catalog)).

 

| Directory | Name to use |
| --- | --- |
| `commandrun/` | `command-run` |
| `githubaction/` | `github-action` |
| `aws-iid/` | `aws` |

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