# compliance-evidence attestor

Source: https://www.testifysec.com/docs/cilock/attestors/compliance-evidence/

The cilock compliance-evidence attestor embeds audit evidence (screenshots, API exports, documents) in a signed attestation, bound to the controls, audit and assets it supports.

Stores audit evidence inside the signed attestation, so the evidence itself is kept in Archivista, not only its digest. Each record names the controls it supports, the audit it belongs to, and the systems and changes it is about.

 

| Name | `compliance-evidence` |
| --- | --- |
| Predicate type | `https://testifysec.com/attestations/compliance-evidence/v0.1` |
| Lifecycle | `postproduct` |
| Default binary? | No |
| Category | compliance-scan (primary) |
| Recommended trace | off — no syscall tracing needed |
| Auto-attaches when | - preenv\_set: CILOCK\_COMPLIANCE\_EVIDENCE |

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

 

The command cilock wraps captures the evidence and writes a manifest, `compliance-evidence.json` by default, that lists each file. For every manifest entry the attestor:

 

1. refuses the entry if the file is not a product of the same run;
 2. re-hashes the file and refuses it if it changed after the run recorded its digest;
 3. embeds the exact bytes (base64 in JSON) with their sha256, media type and size.

 

Fields:

 

- `controls[]`: the controls the evidence supports, as `<framework>:<id>`, for example `soc2:CC8.1` or `secureframe:Code integration testing`.
 - `audit`: the audit engagement, for example `soc2-2026`.
 - `request`: the auditor's request, verbatim.
 - `assets[]`: `type` and `id` of each system or change the evidence is about.
 - `references[]`: gitoids of other attestations the evidence cites.
 - `collectedAt`: when the attestor read the evidence, RFC 3339 UTC.
 - `items[]`: `path`, `kind` (`screenshot`, `api-response`, `document`, `file`), `source` (the URL or the exact command), `title`, `description`, `capturedAt`, `mediaType`, `size`, `sha256`, `content`.

 

The attestor records evidence. It does not decide whether a control passes; write that rule in policy.

 

## When to use

 

When an auditor needs evidence that a tool or a web console cannot export in a signed form: console screenshots, admin-API responses, configuration exports. Run the capture command under `cilock run`, so the same signed record shows the command that captured the evidence and the bytes it produced.

 

## Flags

 

- `--attestor-compliance-evidence-control`: control the evidence supports. Repeatable; at least one is required.
 - `--attestor-compliance-evidence-audit`: audit engagement.
 - `--attestor-compliance-evidence-request`: the auditor's request.
 - `--attestor-compliance-evidence-asset`: `type=id`. Repeatable. Types: `commitsha`, `repo`, `pr` (`<owner>/<repo>#<number>`), `accountid` (AWS), `github-org`, `google-domain`, `cloudflare-account`, `saas-org` (`<vendor>:<org id>`). Other types are refused, because a misspelled type would bind to nothing.
 - `--attestor-compliance-evidence-reference`: gitoid of a cited attestation. Repeatable.
 - `--attestor-compliance-evidence-manifest`: manifest product path. Default `compliance-evidence.json`.
 - `--attestor-compliance-evidence-max-bytes`: most evidence bytes to embed. Default 2,949,120 bytes (2.8 MiB): base64 grows the bytes by a third, so this is the most raw evidence whose encoding fits under cilock's 4 MiB statement limit with 256 KiB left for item metadata and subjects. Above it the run fails; evidence is never truncated.

 

## Output shape

 

Subjects, each with a sha256 digest:

 

- `compliance-evidence:<path>`: digest of the file's bytes, to find the record that holds one exact file.
 - `compliance-control:<control>`, `audit:<audit>`, `attestation:<gitoid>`: digest of the value, to find every record for one control, audit or cited attestation.
 - `<type>:<id>` for each asset: digest of the id. `commitsha:`, `repo:` and `pr:` use the keys and digests of the `github-review` attestor (for `pr:` the digest is of the number alone), and `accountid:` matches `aws-iid`, so evidence joins those records.

 

## Gotchas

 

- Evidence is embedded, so envelopes grow with it. A full-page screenshot of a long page is 1 to 1.5 MB, so capture one or two pages per run.
 - A screenshot proves what the browser showed to the signed-in user at capture time. It does not prove the page was not altered in the browser before capture. Pair it with an `api-response` item for the same setting where an API exists.
 - `capturedAt` comes from the capture command. `collectedAt` and the signature timestamp come from cilock.

 

## CLI example

 

```sh
cilock run --step soc2-pr-9278 -d out -a compliance-evidence -a github-review \
  --attestor-github-review-pr 9278 \
  --attestor-compliance-evidence-control 'secureframe:Code integration testing' \
  --attestor-compliance-evidence-audit soc2-2026 \
  --attestor-compliance-evidence-asset pr=testifysec/judge#9278 \
  --attestor-compliance-evidence-asset repo=testifysec/judge \
  -- node compliance/scripts/capture-evidence.mjs --out out \
     --url https://github.com/testifysec/judge/pull/9278 \
     --exec 'pr.json=gh api repos/testifysec/judge/pulls/9278'
```

 

## See also

 

- [`github-review`](https://www.testifysec.com/docs/cilock/attestors/github-review): signed snapshot of a commit's pull request reviews.
 - [Catalog row](https://www.testifysec.com/docs/cilock/reference/attestor-catalog)

 

---

**This page is generated from the CI/lock tool catalog.** Don't edit it here — the source is [`attestation/detection/docs/compliance-evidence.doc.md`](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/compliance-evidence.doc.md) in [aflock-ai/rookery](https://github.com/aflock-ai/rookery). The same catalog powers `cilock tools show compliance-evidence` 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/compliance-evidence.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.