Evidence (build / verify)
belay evidence produces and checks a tamper-evident evidence pack: a SHA-256
manifest computed over your findings and SARIF output. It gives you a portable, verifiable
artifact you can hand to an auditor, attach to a ticket, or archive — and later prove has
not been altered.
When to use
- To snapshot your recent audit-log decisions into a portable, verifiable bundle.
- Before archiving or sharing results, so a recipient can confirm integrity.
- In compliance or incident workflows that need a tamper-evident record.
How it relates to the audit log
Belay maintains two complementary integrity mechanisms:
| Mechanism | What it protects | How |
|---|---|---|
Hash-chained audit log (~/.belay/audit.ndjson) | The live stream of every decision | Each row carries the previous row's hash plus a SHA-256 over its own canonical (recursively key-sorted, whitespace-free) JSON, so any edit or deletion breaks the chain. |
Evidence pack (evidence build / verify) | A point-in-time bundle of findings + SARIF | A manifest.json of per-file SHA-256 hashes; verify recomputes and compares. |
The audit log continuously chains every runtime decision; the evidence pack snapshots a set of findings into a self-contained, re-verifiable package. They reinforce each other: the log proves the timeline was not tampered with, the pack proves a specific set of results was not tampered with.
Steps
1. Build an evidence pack
belay evidence build --out <pack-dir>
--out is optional — omit it and Belay writes to a fresh temp directory instead. build
sources its findings from your last 500 audit-log rows (--dir is not a build
option; it only applies to verify, below). It writes the findings, a SARIF file, and a
manifest.json containing a SHA-256 hash of each file in the pack.
The SARIF file build writes is currently a fixed, empty {"version":"2.1.0","runs":[]}
stub — it is not yet populated from a real scanner run. Rely on the findings + manifest
for the tamper-evident record; do not treat the SARIF file as scan output today.
2. Verify an evidence pack
belay evidence verify --dir <pack-dir>
verify recomputes the SHA-256 of every file in the pack and compares it against the
recorded manifest. Any mismatch — a modified, added, or removed file — is reported.
verify is deterministic and offline: it recomputes hashes locally and needs no network
and no keys.
What integrity gives you
- Detect tampering. A changed byte anywhere in a covered file changes its SHA-256 and fails verification.
- Portable proof. The pack is self-contained; a recipient can run
verifywithout access to your machine. - Chain of custody. Combined with the hash-chained audit log, you can show both what happened (the chained timeline) and what was found (the verified pack).
Verifying an evidence pack tells you the files match their recorded hashes. It does not, by itself, prove when they were created — pair it with the hash-chained audit log for a temporal record of the decisions that produced them.