Supply chain
Connect dependency review and artifact provenance to the exact binaries, helpers, policies, and manifests admitted by the execution boundary.
On this page
An operator can name the source, dependencies, toolchain, and build behind every binary the kernel and the cage admit, and trace each one to the process its launch contract started.
Each link in that chain has its own owner and its own observation. A matching commit cannot identify an arbitrary rebuild, and a valid archive signature cannot show which bytes an admitted process executed, so the candidate record keeps source identity, release provenance, and launch evidence side by side through upgrades and recovery.
The lockfile fixes the graph the gates read
cargo metadata --locked records the resolved package graph for the selected features and target. The dependency gate reads transitive runtime edges from that graph, and the provenance gate checks each recorded adaptation. Build from source.
Authority is held by a composition, so the composition is what gets reviewed
The kernel is one part of the software that performs an agent's work. The cage helper establishes confinement, adapters construct provider requests, manifests describe tools, and policy selects trusted identities. A change to any of them can alter the running system's authority while the kernel source stays the same.
The security boundary therefore depends on the kernel, its cryptography, the SQLite integration, the cage helper, the Linux enforcement libraries, the broker, and each tool executable. Review status and execution evidence are separate facts about them: a dependency can carry an accepted audit while the candidate still needs a confinement run on a Linux kernel, and a binary can pass portable tests in a deployment with the wrong socket identity.
Rollback is a composition change too. Reinstalling a previous binary meets retained state written by its successor, and replacing a helper changes the launch contract, so software and state compatibility are reviewed together.
A candidate record fixes source, toolchain, and graph before any check runs
Start the record from the release itself. Every Chio release passes the security-dependencies and security-provenance gates before it is tagged, and the release workflow signs a qualification summary that names each gate with its result. Check it for the release you are about to roll out:
chio release verify --evidence qualificationbinary /usr/local/bin/chio chio 0.2.0 x86_64-unknown-linux-gnu checksum matches SHA256SUMS for v0.2.0 signed by release.yml on backbay-labs/chio, issuer token.actions.githubusercontent.com provenance SLSA v1, 5 subjects, tag v0.2.0 qualification summary bound to v0.2.0 security-dependencies pass security-provenance pass verified
You should see both gates pass under a summary bound to the tag you selected. The dependency gate audits the resolved graph and its scoped exceptions; the provenance gate ties the security implementation to the reviewed source. Running those gates yourself against a source tree is contributor work, and its result for a release is the line above.
The finished record answers six questions about the candidate:
- Source and dependencies. Source identity, lockfile, resolved metadata, feature selection.
- Review. Audit records, policy results, and the rationale for each scoped exception.
- Build. Toolchain, target, build invocation, and the output digests of the kernel, services, helper, and tools.
- Admission. Signed manifests, the registry snapshot, and helper and target identities.
- Configuration. Policy, authority pins, and store and deployment digests.
- Behavior. Portable tests, supported-host gates, recovery cases, and protected-resource observations.
Record a working tree that is not clean
umask 077
mkdir -p evidence
rustc --version --verbose > evidence/rustc.txt
cargo --version --verbose > evidence/cargo.txt
cargo metadata --locked --format-version 1 > evidence/cargo-metadata.json
git rev-parse HEAD > evidence/source-revision.txt
git diff --binary HEAD > evidence/source-working-tree.patchThese commands record the toolchain and resolved metadata without installing a toolchain or updating dependencies. Review the working-tree patch before exporting it, because local configuration can hold sensitive values. An empty patch plus the recorded revision identifies tracked source; untracked build inputs need their own inventory. Cargo metadata records the graph under the invoked features and target, so record any nondefault build flags separately.
After building, record the output digests and compare them with the helper, target, registry, and deployment bindings used at runtime. That comparison connects the candidate you reviewed with the process the security boundary admits.
Dependency review reads the resolved graph, forks included
Portable security types and pure label operations need different dependencies from Unix daemons and durable stores. The dependency gate reads transitive runtime edges from Cargo metadata, excluding development-only edges, and enforces the separation between pure engines, security types, kernel and guards, and platform adapters, across the security, kernel, platform, trust, and guard components. A portable label component that picks up a runtime dependency indirectly fails it even when its direct manifest still looks small.
The provenance gate checks each documented adaptation and its marked destination, and needs ripgrep (rg) on PATH. It keeps attribution and license notices intact when source moves into an example or reviewed upstream code is integrated; it is neither a vulnerability audit nor evidence that an executable is confined. Audits and exemptions apply to the resolved graph, and an exemption is a scoped review decision with a recorded reason.
The local aws-lc-rs fork is a resolved artifact with its own review. Cargo Vet's policy.aws-lc-rs entry sets audit-as-crates-io, so Cargo Vet treats the path-dependency fork as the published aws-lc-rs 1.18.1 it patches, and cargo vet --locked accepts the fork only when that published base meets the audit criteria. The Chio patch (third_party/aws-lc-rs-chio/CHIO-PATCH.patch) and its restored-fixture manifest are reviewed separately, because Cargo Vet cannot authenticate the fork's own bytes. The same reading applies to cryptographic libraries, TLS validation, syscall-filter compilation, filesystem enforcement, and persistence: review the selected implementation with its vendored patches.
Publishing a downloadable example
A downloadable example carries its lockfile, required toolchain, license, attribution, and source-copy manifest; the security-research project ships unmodified Chio modules, a source manifest, and the Apache license. Distinguish a vendored production module from the smaller wrapper that exposes it, compare copied-module hashes with the reviewed implementation, and rerun the example's public-API assertions after an update. Adapt the surrounding demonstration, and document any adaptation of the copied code with its scope.
Inspect the archive before publishing. Exclude local receipt databases, credentials, build directories, and caches, and keep the source and fixtures the documented behavior needs, so a reader's run depends only on what the archive contains.
Launch binds the reviewed bytes to the running process
The cage retains executable descriptors and checks the running helper and the post-exec target against them. A file replaced at the same path after preparation changes nothing that runs: the retained executable runs, or the launch is refused. The signed manifest names what may run, and the live verified registry supplies the server, tool, snapshot, and authenticated topology authority beside it; protocol discovery cannot promote an executable into that trusted set.
| Artifact | Retain | Runtime connection |
|---|---|---|
| Kernel and authority services | Build identity, dependency review, signing configuration | Trusted host and service pins |
| Cage helper and enforcement stack | Reviewed binaries, library versions, host prerequisites | Retained helper descriptor and observed restrictions |
| Tool executable | Exact digest and signed manifest relationship | Retained target and post-exec identity |
| Policy and registry | Signed content and registered verification keys | Admission and launch authorization |
| Broker and response snapshot | Configuration and logical store digests | Authenticated IPC and immutable artifact selection |
For the published chio archive, the archive review script confirms that the tag peels to the commit you selected independently, compares the archive with its checksum sidecar and the checksum index, refuses a modified copy, and requires the signature, certificate, and source-named provenance bundle before it reports signed-release acceptance. It exits 4 when any of those is missing.
python3 review_public_archive.py \
--tag "$VERSION" --target "$TARGET" \
--source-sha "$REVIEWED_COMMIT" \
--output ./release-reviewHash equality, builder identity, and measured launch are three observations with three owners. Run confinement gates on the supported kernel and architecture, because cross-compilation shows that code builds for a target, while only a run on the host shows that Landlock and seccomp restrictions are installed. Native hosts covers the Linux resource qualification.
Read more in Verified tool launch, which gives the complete host integration.
An upgrade is reviewed against the work it must still honor
A rebuild is a new authority-bearing composition. Retain its build invocation, target, and features beside the output digests, keep the audit, deny, and vet decisions with their scoped exemptions, and select checks for the behavior the change touches: wire encoding, signatures, TLS, transactions, or confinement. Each identity in the candidate moves on its own terms:
- Public source. Review source and dependency differences from the reviewed commit, clean tree, lockfile, and features, then rerun the applicable gates.
- Archive and builder. Verify the new release identity from its original bytes, checksum siblings, pinned workflow and issuer, and full provenance subjects.
- Helper and target. Compare the new digests with the signed launch contract; a rebuilt or replaced binary needs a reviewed contract.
- Tools and transport. The signed manifest, live registry snapshot, and authenticated topology decide which executables are trusted.
- Runtime authority and state. Verify retained envelopes under the pins they were signed against, and recover previously authorized work under its original bindings.
Recovery is rehearsed on the state the previous version wrote
Rehearse recovery with the state already written and the effects already authorized: pending operations and unfinished response contributions from the previous version, run against the new runtime. A fresh empty database misses migration defects.
Reverting a binary is safe only when the resulting composition can honor the retained history. Keep original signed envelopes and superseded verification keys; old records are never re-signed to hide an incompatible migration.
Read more in rollout evidence and key history, which carry the candidate's identities into deployment.