Join our Newsletter — 33% off our NHI Course
Home› Guides› in-toto Attestations Guide: Sign, Verify and Enforce Software…
Guide Software & AI Supply Chain

in-toto Attestations Guide: Sign, Verify and Enforce Software Supply Chain Claims

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

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.jsonl bundle 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.

PartWhat it definesStatusTypical 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 CommitteeEnd-to-end verification of a whole defined pipeline, for example by a package manager before install
in-toto Attestation FrameworkA 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 developmentSLSA 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:

PredicateWhat it claimsExample producerPolicy 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 uploadsWas 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 policyCentral verification serviceHas someone we trust already verified this?
SPDX 2, SPDX 3, CycloneDXSoftware bill of materialsSBOM generators in the buildWhat components does this contain? See the SBOM Guide.
VulnsVulnerability scan resultsScannersWas it scanned, by what, and with what result?
Test ResultResults of any test runCI test stagesDid required tests pass?
Simple Verification Result, SCAI ReportPolicy evaluation results; evidence-based assertions about attributes or behaviourPolicy engines, auditorsWas a specific control evaluated?
Release, ReferenceArtifact belongs to a named release; pointers to related documentsRelease toolingIs this the official release artifact?
Link, Runtime Tracesin-toto step evidence; runtime traces of supply chain operationsin-toto tooling, build observersDid 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:

  1. Envelope: decode it and check each signature against the recognised attesters; reject if no recognised attester signed.
  2. Payload type: reject unless payloadType is an in-toto media type.
  3. Statement: decode the payload and reject unless _type is https://in-toto.io/Statement/v1.
  4. Subject match: hash the artifact with an acceptable algorithm and reject unless at least one subject digest matches.
  5. 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.id is on an allowlist.
  • Source: the source repository and ref in externalParameters or resolvedDependencies match the expected repository and a protected branch or tag.
  • Build type: buildType is 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

  1. 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.
  2. 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.
  3. Add SBOM and scan predicates: attach SPDX or CycloneDX and vulnerability results as separate attestations from separate identities.
  4. 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.
  5. 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.
  6. 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.
  7. 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

FrameworkReferenceHow in-toto attestations support it
NIST SP 800-53 Rev. 5SR-4 Provenance; SR-11 Component Authenticity; SI-7 and SI-7(15) Code Authentication; CM-14 Signed ComponentsSigned provenance and verification before installation
NIST CSF 2.0GV.SC-07, PR.PS-06Supplier risk understood and monitored; secure development practices with evidence
NIST SP 800-218 SSDFPS.2, PS.3Mechanisms to verify release integrity; archive provenance data
SLSA v1.xBuild track provenanceProvenance predicate is the evidence each Build level requires
MITRE ATT&CKT1195.002 Compromise Software Supply ChainVerification detects artifacts not produced by the expected builder and source
OWASP CI/CD Top 10CICD-SEC-9 Improper Artifact Integrity ValidationAttestations 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 payloadType or 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 buildType or unexpected externalParameters.
  • 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 predicateType URIs, 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.