What is a chain of custody for test evidence?
A chain of custody for test evidence is a record that proves a test result and its files were not changed after the run. Nexus StudioQA, by Verdict System LLC, keeps it as an opt-in, append-only ledger: every file of an evidence folder is hashed with SHA-256 and chained to the record before it, so a check names the first record that changed.
Last updated:
By the Nexus StudioQA team, Verdict System LLC.
Why would a team need one?
A failed test turns into a bug report, a release decision or an item in an audit, and weeks later someone may ask whether the screenshot and the report are the ones the run produced. A folder on a disk proves nothing by itself: any file in it can be edited. A chain of custody lets anyone run one command and get a yes or a no, with the record that changed.
How does it work?
- A record is an evidence folder that holds a metadata.json, such as the folder a BREACHED run leaves with its report, screenshot and logs.
- Each file of the folder is hashed with SHA-256, and the record's hash also includes the hash of the record before it. Changing one byte of one file breaks that record and every record after it.
- The records live in one append-only ledger,
evidence/chain-of-custody/ledger.jsonl, next to the evidence and never trimmed. It uses only Node.js's built-in crypto and runs on your machine. - Sealing is opt-in. It starts with the first Real bug or False alarm call in the Studio, which joins the chain with its reason, or with
nexus verify --seal. - With no ledger, the check reports UNVERIFIED and fails. It never reports a silent OK, because missing proof is not proof.
What does it look like on a real run?
This is the output of the engine's own command on two evidence folders, a BREACHED run in Chromium and a TIMEOUT in Firefox, recorded on 2026-11-06. Between the third and the fourth command, one line of TC101's report.md was edited by hand.
> nexus verify
🔗 Nexus StudioQA — Evidence Chain of Custody (SHA-256, on-prem)
⚠️ UNVERIFIED — no ledger — run `nexus verify --seal` first (UNVERIFIED, not OK)
> nexus verify --seal
✅ SEALED 2 record(s) → evidence\chain-of-custody\ledger.jsonl
tip: bcc9f551e102aa6b0593bbab23e794d2da62934d58dcd27464fa322962338571
> nexus verify
✅ VERIFIED — verified 2 record(s), all artifacts intact
(report.md of TC101 edited by hand)
> nexus verify
❌ TAMPER DETECTED — evidence altered after sealing at record 0: TC101_chromium_2026-11-06_10-15-02 [BREACHED]
record: TC101 / chromium [BREACHED] — TC101_chromium_2026-11-06_10-15-02 [BREACHED]
The check exited 2 while unverified, 0 when verified and 1 when it found the edit, so a CI job can fail on tampering.
What are the four states?
| State | What it means | What to do |
|---|---|---|
| UNVERIFIED | No ledger yet, so nothing can be proven | Seal, or make the first Real bug or False alarm call |
| VERIFIED | Every sealed record and file matches its hash | Nothing |
| TAMPER DETECTED | A file or a ledger line changed after sealing; the first broken record is named | Compare that folder with a copy you trust |
| PURGED | A sealed folder was removed on purpose, and the ledger says who removed it and when | Nothing; the ledger still proves what it hashed to |
What happens when old evidence is cleaned up?
Before the disk budget, retention or Free disk removes a sealed folder, the engine appends a PURGE entry to the ledger that names who removed it and when. The check then reports the record as PURGED, not tampered. If the ledger cannot record the PURGE, the folder stays. Storage and self-maintenance explains the budget.
What are the limits?
- It proves the files did not change after sealing. It does not prove they were right before: a record sealed after an edit seals the edit.
- Only sealed records are covered. Evidence written before the first seal stays UNVERIFIED until you seal it.
- The ledger sits on the same disk as the evidence. Someone who can write to both could rebuild the whole chain, so keep the tip hash that sealing prints somewhere else, such as a ticket or a release note, and compare it later.
Where can I see it?
The Evidence page follows one failed test through every file it leaves, and the glossary defines UNVERIFIED and the Real bug or False alarm call. The free trial runs the same engine on your own tests.