Most organisations now receive signed provenance, SBOMs and scan results for the software they run, but very few verify them against a policy, so the evidence changes nothing. in-toto is the CNCF project whose Attestation Framework defines the common format behind SLSA provenance, GitHub artifact attestations and PyPI's PEP 740 attestations: a signed envelope, a statement binding claims to artifact digests, and a typed predicate carrying the claim itself. Understanding that structure is what lets you write verification policy that actually rejects a tampered or mis-built artifact. This guide explains the framework's layers, the vetted predicate types, how verification works, how in-toto layouts differ from standalone attestations, how to roll out generation and enforcement, and what to monitor. It is written for build and platform engineers, supply chain security leads and anyone writing admission or deployment policy. For control objectives around artifact integrity, see the OWASP CI/CD Top 10 CICD-SEC-9 Improper Artifact Integrity Validation Guide.
Key takeaways
- Three layers, three jobs. The Envelope (normally DSSE) authenticates, the Statement binds to subjects by digest, and the Predicate carries the claim. Verification has to check all three.
- Subjects match by digest only. The specification states that subjects are matched purely by digest regardless of content type, so the artifact you hash must be exactly the artifact you deploy.
- Trust the signer, not the file. A valid signature from an unrecognised identity is worthless; policy must name which builder or workload identity may attest which predicate type.
- Provenance proves origin, not safety. GitHub's documentation warns that attestations are not a guarantee an artifact is secure; the Ultralytics compromise shipped malicious versions from the project's own release workflow.
- Bundles are not authenticated as a whole. Attestations in a
.intoto.jsonlbundle can be deleted, replayed or injected without detection, so policy must require the attestations it needs rather than trusting what is present.
What in-toto is: layouts and the Attestation Framework
in-toto has two related parts that are easy to confuse.
| Part | What it defines | Status | Typical use |
|---|---|---|---|
| in-toto specification (layouts and links) | A project owner signs a layout listing the supply chain steps, the functionaries (identified by public key) allowed to perform each, artifact rules, and inspections the client runs. Each step produces signed link metadata. | Stable version 1.0, with a living current version maintained by the in-toto Steering Committee | End-to-end verification of a whole defined pipeline, for example by a package manager before install |
| in-toto Attestation Framework | A general format for signed claims about software artifacts: Envelope, Statement, Predicate, plus Bundle and ResourceDescriptor types. Language bindings for Go, Python, Rust and Java. | Statement v1; the project describes the framework as still under development | SLSA provenance, SBOM and scan results, PyPI and GitHub artifact attestations, policy engines |
The specification describes three roles: the project owner defines the layout, functionaries perform steps and record link metadata, and clients verify the final product against the layout. Link metadata is itself carried as an attestation predicate type (Link) for migration from in-toto 0.9. Most adopters today start with standalone attestations and policy, and use layouts where they need to prove that a fixed sequence of steps all happened with the right actors.
Anatomy of an attestation
Envelope
The Envelope handles serialisation and signatures. The recommended format is the Dead Simple Signing Envelope (DSSE) v1.0, whose JSON form has payload (base64 of the serialised Statement), payloadType and a signatures array of keyid and sig. The in-toto Envelope rules require payloadType to be application/vnd.in-toto+json or a predicate-specific form application/vnd.in-toto.<predicate>+json, and the payload type is signed together with the payload. The specification is explicit that consumers should rely on the Statement's predicateType, not the media type, and must parse and verify the payload to get authenticated predicate information.
Alternative envelopes must meet ITE-5 (multiple signatures, authenticated payload type, no reliance on canonicalisation). The in-toto documentation notes that the Sigstore bundle supports DSSE but requires a single signature, and that COSE_Sign is compliant while single-signer COSE_Sign1 is not.
Statement
The Statement binds the claim to artifacts. Its fields are _type (always https://in-toto.io/Statement/v1 for this version), subject (one or more ResourceDescriptors, each of which must have a digest), predicateType (a URI) and predicate. Subjects are assumed immutable. A ResourceDescriptor can also carry name, uri, mediaType and small inline content; the specification says name should be stable, such as a filename, if policy uses it.
Predicate
The Predicate is the claim. Its meaning comes entirely from predicateType, so policy must pin the exact type URIs it accepts.
Predicate types you will meet
The in-toto project maintains a list of vetted predicates. The ones most often seen in practice:
| Predicate | What it claims | Example producer | Policy question it answers |
|---|---|---|---|
SLSA Provenance (https://slsa.dev/provenance/v1) | How an artifact was built: buildDefinition (buildType, externalParameters, internalParameters, resolvedDependencies) and runDetails (builder.id, metadata, byproducts) | CI builders, GitHub artifact attestations, PyPI uploads | Was this built by our trusted builder, from our repository, with expected parameters? |
| SLSA Verification Summary (VSA) | A verifier's decision that an artifact met a SLSA level and policy | Central verification service | Has someone we trust already verified this? |
| SPDX 2, SPDX 3, CycloneDX | Software bill of materials | SBOM generators in the build | What components does this contain? See the SBOM Guide. |
| Vulns | Vulnerability scan results | Scanners | Was it scanned, by what, and with what result? |
| Test Result | Results of any test run | CI test stages | Did required tests pass? |
| Simple Verification Result, SCAI Report | Policy evaluation results; evidence-based assertions about attributes or behaviour | Policy engines, auditors | Was a specific control evaluated? |
| Release, Reference | Artifact belongs to a named release; pointers to related documents | Release tooling | Is this the official release artifact? |
| Link, Runtime Traces | in-toto step evidence; runtime traces of supply chain operations | in-toto tooling, build observers | Did each defined step run, and what did it touch? |
SLSA's provenance documentation says externalParameters are untrusted, must be included and must be verified downstream, and that verifiers should reject unrecognised or unexpected fields in them; builder.id determines which build platform, and therefore which SLSA Build level, the claim rests on. SLSA v1.2 is the current approved version and keeps the same provenance predicate type. For how provenance maps to SLSA levels, see the SLSA and Build Provenance Guide.
How verification works
The in-toto validation model takes the artifact, the envelope, a list of recognised attesters (name and public key, or in keyless systems an identity), and acceptable digest algorithms (usually SHA-256), then:
- Envelope: decode it and check each signature against the recognised attesters; reject if no recognised attester signed.
- Payload type: reject unless
payloadTypeis an in-toto media type. - Statement: decode the payload and reject unless
_typeishttps://in-toto.io/Statement/v1. - Subject match: hash the artifact with an acceptable algorithm and reject unless at least one subject digest matches.
- Policy: pass
predicateType,predicate, matched subjects and attester names to a policy engine.
Steps 1 to 4 are mechanical and handled by libraries and CLIs. Step 5 is where security is won or lost. A useful policy for SLSA provenance checks at minimum:
- Signer identity: the attester is the expected builder identity (for keyless Sigstore signing, the certificate's issuer and subject such as a specific workflow path on a specific ref).
- Builder:
runDetails.builder.idis on an allowlist. - Source: the source repository and ref in
externalParametersorresolvedDependenciesmatch the expected repository and a protected branch or tag. - Build type:
buildTypeis one you know how to interpret; unknown types fail closed. - Completeness: every required predicate type is present for the subject (for example provenance plus SBOM plus a vulnerability scan within the last N days).
The Bundle specification uses JSON Lines with the .intoto.jsonl suffix and media type application/vnd.in-toto.bundle. Because a bundle is not authenticated as a whole, consumers must ignore unrecognised lines and must not depend on order, and policy should demand specific attestations rather than infer approval from whatever is present.
Where in-toto attestations appear today
- GitHub artifact attestations: generated with Sigstore; public repositories use the Sigstore Public Good Instance and private repositories use GitHub's own Sigstore instance, which has no transparency log. GitHub states that artifact attestations alone provide SLSA v1.0 Build Level 2, and recommends reusable workflows to go further. Verify with
gh attestation verify. - PyPI (PEP 740, status Final): PyPI accepts in-toto attestations with SLSA Provenance and PyPI Publish predicates, at most one of each per uploaded file, signed by Trusted Publisher identities (GitHub Actions, GitLab CI/CD, Google Cloud and ActiveState).
- Container registries and Kubernetes: attestations stored alongside images and checked at admission. See the Kubernetes Admission Control Guide.
- npm provenance: see the npm Trusted Publishing and Provenance Guide.
Where identity fits: attesters are non-human identities
Every attestation is signed by a machine identity: a CI workflow's OIDC token exchanged for a short-lived Sigstore certificate, a builder's signing key, or a scanner's service account. That identity is the trust anchor, so it needs the same governance as any privileged workload credential.
- Prefer keyless, workflow-bound identities: short-lived certificates tied to a specific repository, workflow file and ref leave no long-lived signing key to steal. See the Sigstore Guide.
- Separate attesters by predicate: the build identity signs provenance; the scanner identity signs vulnerability results. Policy then checks the right identity for each type, so a compromised scanner cannot forge provenance.
- Protect the signing workflow: restrict who can change the release workflow and run it on protected refs; an attacker who controls the workflow gets valid provenance. See the GitHub Actions OIDC Federation Hardening Guide.
- Retire parallel credentials: a leftover publishing token lets an attacker bypass attested publishing entirely.
Rolling out attestations and enforcement
- Inventory release artifacts: list what you ship and deploy (images, packages, binaries). Following GitHub's guidance, attest releases and things people run, not every test build or individual source file.
- Generate provenance in the build: use the build platform's native provenance where it exists, signed by the builder identity, with subjects set to the exact artifact digests.
- Add SBOM and scan predicates: attach SPDX or CycloneDX and vulnerability results as separate attestations from separate identities.
- Store attestations with artifacts: in the registry next to the image or package, plus a copy in your own store so verification does not depend on one service.
- Verify in audit mode: at deployment or admission, evaluate policy and log the result without blocking for two to four weeks; fix producers that fail.
- Enforce for one environment: block unverified artifacts in production for one cluster or service, with a documented break-glass path that is itself logged and time-limited.
- Extend to third-party software: verify upstream attestations where suppliers publish them, and record which suppliers do not.
Rollback: switch the policy from enforce to audit for the affected scope, not off; keep logging so the gap is visible. Small versus large organisations: a small team can rely on platform-native attestations and a single CLI verification step in deployment. A large estate needs a central policy repository, per-predicate attester allowlists, a verification service that can issue VSAs so every cluster does not re-verify, and reporting on coverage.
Detection and measurement
- Log: every verification decision (artifact digest, predicate types found, attester identity, policy result), every break-glass use, and every change to attester allowlists or policy.
- Alert: artifacts published with no attestation where one is expected; attestations signed by an identity outside the allowlist; provenance pointing at an unexpected repository, ref or builder.
- Metric: percentage of production deployments with verified provenance (target 100% for first-party artifacts).
- Metric: percentage of release artifacts carrying provenance, SBOM and scan attestations.
- Metric: policy failures per week by reason, and time to fix the producer.
- Metric: break-glass deployments per month (target near zero, each reviewed).
Framework mapping
| Framework | Reference | How in-toto attestations support it |
|---|---|---|
| NIST SP 800-53 Rev. 5 | SR-4 Provenance; SR-11 Component Authenticity; SI-7 and SI-7(15) Code Authentication; CM-14 Signed Components | Signed provenance and verification before installation |
| NIST CSF 2.0 | GV.SC-07, PR.PS-06 | Supplier risk understood and monitored; secure development practices with evidence |
| NIST SP 800-218 SSDF | PS.2, PS.3 | Mechanisms to verify release integrity; archive provenance data |
| SLSA v1.x | Build track provenance | Provenance predicate is the evidence each Build level requires |
| MITRE ATT&CK | T1195.002 Compromise Software Supply Chain | Verification detects artifacts not produced by the expected builder and source |
| OWASP CI/CD Top 10 | CICD-SEC-9 Improper Artifact Integrity Validation | Attestations plus enforced policy are the validation mechanism |
Lessons from incidents
In the Ultralytics PyPI compromise in December 2024, versions 8.3.41 and 8.3.42 were published through the project's own Trusted Publishing release workflow after an injected branch name is believed to have poisoned the Actions cache; Sigstore records and provenance showed they came from the workflow, not a token. Versions 8.3.45 and 8.3.46 were then uploaded with a leftover API token and carried no attestations. Two lessons follow. First, provenance correctly identified the build path, but a policy that only checks "built by our workflow" would have accepted the malicious release; policy must also constrain the triggering event and ref, and the workflow itself must be hardened. Second, the token-published versions were detectable precisely because they lacked attestations: consumers that required provenance would have rejected them. For build tampering at larger scale, the SolarWinds SUNBURST compromise shows why provenance must come from an isolated, hardened builder: SUNBURST was injected into Orion builds, not the source repository, and shipped as legitimately signed updates, so a signature alone proved nothing about how the build ran.
Common failure patterns
- Signature checked, identity not: verification accepts any valid Sigstore signature, so anyone with a GitHub account can produce a "valid" attestation.
- Digest of the wrong thing: provenance subject is the tarball, deployment uses the image built from it, so nothing matches and teams disable the check.
- Trusting the media type: reading the predicate type from
payloadTypeor a bundle file name instead of the authenticated Statement. - Presence equals approval: treating "an attestation exists" as a pass, which a bundle injection or replay can satisfy.
- Unknown build types accepted: policy does not fail closed on unrecognised
buildTypeor unexpectedexternalParameters. - Attest everything, verify nothing: every CI run signs every file, the log is noise, and no deployment gate reads it.
Practitioner checklist
- Release artifacts carry SLSA provenance signed by a workflow-bound builder identity, with subjects equal to deployed digests.
- SBOM and vulnerability results are attached as separate attestations from separate identities.
- Policy pins accepted
predicateTypeURIs, attester identities per type,builder.id, source repository and protected refs. - Policy fails closed on unknown build types and unexpected
externalParameters. - Required attestations are demanded explicitly; bundle contents are never treated as approval by presence.
- Verification runs at deployment or admission, first in audit mode, then enforced with logged break-glass.
- Release workflows are protected (limited editors, protected refs, no untrusted cache restore) and legacy publishing tokens are revoked.
- Verification decisions and policy changes are logged and reviewed.
Standards and references
- in-toto: Attestation Framework specification v1
- in-toto: Attestation validation model
- in-toto: Vetted attestation predicates
- in-toto: Specification (layouts and link metadata)
- Secure Systems Lab: DSSE Envelope
- SLSA: Build Provenance
- Python: PEP 740 Index support for digital attestations
- GitHub Docs: Artifact attestations
Related NHI Mgmt Group resources: SLSA and Build Provenance Guide · Sigstore Guide · SBOM Guide · OWASP CI/CD Top 10 CICD-SEC-9 Improper Artifact Integrity Validation Guide