Skip to content

Provenance Chain-of-Custody Record

Provenance register — instantiates Substrate Lineage Risk Audit

Reconstructs and records the origin-to-here custody chain of an inherited substrate, so every handoff — and every gap in the trail — is on the record before the substrate is trusted.

A Provenance Chain-of-Custody Record is the ledger that answers a question most reviews never ask of their foundations: where did this substrate come from, through whose hands did it pass, and how sure are we of each step? Borrowing the forensic idea of chain of custody, it traces a borrowed library, image, dataset, or template back from the artifact in hand to its origin, logging each handoff with whatever evidence exists — a signature, a commit, an invoice, a maintainer's email. Its defining move is that it treats gaps in the trail as findings: an unverifiable hop doesn't prove tampering, but it means you can no longer vouch for what you are holding, and the record says so out loud. It is about the trail and its breaks — not the substrate's contents, and not whether its assumptions still fit.

Example

A fintech acquires a small startup and, with it, a cryptographic-signing library now sitting in the payments path. Nobody wrote it in-house, so nobody can immediately say what it is. The chain-of-custody record reconstructs the trail: an original author (a contractor who left two years ago), a fork taken from an open-source project at some unrecorded commit, two local patches applied without review, then a re-vendoring into the acquired codebase. Two of those hops have no evidence at all.

The record doesn't declare the library unsafe — it declares that the chain is broken in two places, grades provenance confidence low, and assigns a named steward to own the follow-up. That single artifact turns "we inherited some crypto code" into "we are running signing code whose origin we cannot verify, and here is who is now accountable for it" — which is exactly the input a release decision needs before it leans on the thing.

How it works

The record is built by tracing backward from the artifact to its origin, not forward from a plan:

  • Walk the custody hops. Enumerate each point where the substrate changed hands or was transformed — authored, forked, patched, packaged, vendored, acquired — as an ordered chain.
  • Attach evidence to each hop. Record what proves it: a cryptographic signature, a version-control history, a supplier attestation, a purchase record. Mark every hop that has none.
  • Grade the chain, not the code. Compute a provenance-confidence level from how many hops are verified and how strong that evidence is — a chain is only as trustworthy as its weakest verified link.
  • Name a steward. Assign the accountable custodian going forward, so the substrate stops being ownerless background.

Tuning parameters

  • Trace depth — how far back to reconstruct (last handoff only, or all the way to first authorship). Deeper trailing catches laundered origins but costs investigation time.
  • Evidence bar — what counts as a "verified" hop (a signed attestation vs. someone's recollection). A higher bar makes confidence scores honest but marks more of the chain as broken.
  • Confidence granularity — a coarse high/medium/low band or a finer graded score; finer scores discriminate better but invite false precision.
  • Broken-chain policy — whether an unverifiable hop blocks use, permits use under stewardship, or merely annotates. This sets how much the record actually bites.
  • Refresh trigger — re-open the record on every re-vendoring or version bump, or only at audit time.

When it helps, and when it misleads

Its strength is that it makes "we don't actually know where this came from" an explicit, owned fact rather than a shrug — and it puts a name against each inherited substrate so provenance stops being nobody's job.

Its central trap is confusing a complete-looking record with a safe substrate. Chain of custody establishes where something came from and how confidently — not that the origin was trustworthy or that the artifact is uncompromised.[1] A pristine, fully-verified chain leading back to a poisoned upstream is still poisoned; provenance is not integrity. The record is also easily run backwards — assembled after adoption to rubber-stamp a substrate already in production. The discipline that keeps it honest is to treat a low confidence score as a finding that must be actioned, verify hops independently rather than taking each party's word for the previous one, and never let a filled-in ledger substitute for actually inspecting what the substrate does.

How it implements the components

This register fills the provenance-trail side of the archetype's machinery — the components that establish where from and how sure, not what's inside:

  • substrate_lineage_map — the record's spine is the ordered origin-to-here graph of custody hops; the map is the reconstructed chain.
  • provenance_confidence_score — it grades trust from the number and quality of verified versus unverifiable hops, so downstream decisions know how much the lineage can bear.
  • substrate_stewardship_owner — it names the accountable custodian for each inherited substrate, converting ownerless background into an owned dependency.

It does NOT enumerate the substrate's internal parts — that's Software Bill of Materials with Lineage — nor test those parts for known flaws — that's Transitive Vulnerability Scan. This record establishes the trail; its siblings inspect the contents.

Notes

Provenance confidence is not a safety score. A high-confidence chain tells you the substrate is what it claims to be and came from where it claims — it says nothing about whether that origin was itself sound. Keeping this distinction sharp is what stops a well-documented lineage from being mistaken for a clean bill of health; the safety question belongs to Transitive Vulnerability Scan and the Substrate Risk Release Gate.

References

[1] Chain of custody is the forensic and legal discipline of documenting every person who handled evidence and every transfer between them; an unbroken chain is what lets the evidence be trusted in court. The concept is used here for its structure — a single undocumented handoff undermines confidence in everything downstream — not as a guarantee of the artifact's integrity. ↩