Engineers with a laptop at automation test rigs in a bright production hall

SBOM

in-toto, explained: supply chain layouts, links and attestations

Last updated:

in-toto is a framework for securing the integrity of a software supply chain, now run as a CNCF graduated project, built around layout and link metadata and, more recently, the in-toto Attestation Framework's Statement/Predicate model — the same Statement layer SLSA itself recommends for packaging provenance. Its own site states the goal is "to ensure the integrity of a software product from initiation to end-user installation," by making transparent "what steps were performed, by whom and in what order" — rather than asking a consumer to trust a final binary or package on faith, in-toto gives them a way to check the recorded history of how it was built. The project traces back to academic research: it "is led by Prof. Santiago Torres-Arias at Purdue University," with contributors from "the Secure Systems Lab at NYU and the NJIT Cybersecurity Research Center," and was formally published as "in-toto: Providing farm-to-table guarantees for bits and bytes" by Santiago Torres-Arias, Hammad Afzali, Trishank Karthik Kuppusamy, Reza Curtmola and Justin Cappos at the 28th USENIX Security Symposium (USENIX Security '19), August 2019. Development was supported by the US National Science Foundation, DARPA, and the Air Force Research Laboratory.

Key takeaways

  • The project moved through the CNCF maturity levels in stages: accepted on 14 August 2019, incubating from 10 March 2022, and graduated on 10 February 2025.
  • Minor releases keep the Statement type at https://in-toto.io/Statement/v1; only a major version would change it.
  • Synthetic example: the file name and digests are invented and shortened.
  • The project encourages reusing an existing predicate where one fits; new ones go through its predicate guidelines.

in-toto's original specification (version 1.0.0) is built on two metadata types:

Metadata type Produced by What it records
Layout The project owner, signed in advance Expiration date; authorized public keys per functionary (a person or automated script allowed to perform a step); the ordered list of steps, each with expected materials/products and a threshold of required signoffs; client-side inspections to run at verification time
Link Each functionary, signed after performing their step The step name and command executed; materials (input artifacts) and products (output artifacts) as cryptographic hashes; byproducts (stdout, stderr, return value); environment details (variables, working directory)

Verification checks the chain as a whole: the layout's own signature and expiration are checked first, then each required step must have a corresponding, correctly signed link from an authorized functionary, and the artifact-rule chain must hold: a step's recorded products must match the next step's recorded materials, so nothing was substituted in between. The specification is explicit that superficial fields like the suggested command in a layout step should only raise a warning on mismatch, since "this field can easily be forged" and cannot itself be trusted as a security control; the cryptographic material/product chain is what carries the actual guarantee.

The project moved through the CNCF maturity levels in stages: accepted on 14 August 2019, incubating from 10 March 2022, and graduated on 10 February 2025.

What is the in-toto Attestation Framework?

Alongside the original layout/link model, the project maintains the in-toto Attestation Framework, a more general specification for "generating verifiable claims about any aspect of how a piece of software is produced." Its spec README gives the latest version as v1.2 and defines four layers that are "independent but designed to work together":

Layer What it does Who reads it
Predicate Arbitrary metadata about the subject, with a type-specific schema (for example, SLSA build provenance or an SBOM) Policy that understands that predicate type
Statement Binds the attestation to a particular subject and identifies the predicate type Every verifier
Envelope Handles authentication and serialization: the signature Every verifier, first
Bundle Groups multiple attestations in one file Tools that collect evidence for one artifact

Minor releases keep the Statement type at https://in-toto.io/Statement/v1; only a major version would change it. This framework is what most supply-chain tooling now produces and consumes, rather than raw layout and link files. The original link format survives as a predicate "for migration from in-toto 0.9."

What does an in-toto Statement for a firmware image look like?

Synthetic example: the file name and digests are invented and shortened. A Statement that attaches a CycloneDX SBOM to a gateway update package:

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    { "name": "gw-4.2.0.swu", "digest": { "sha256": "5d2e…a91c" } },
    { "name": "gw-image-prod-gw-imx8.rootfs.wic", "digest": { "sha256": "07b4…e6d2" } }
  ],
  "predicateType": "https://cyclonedx.org/bom",
  "predicate": {
    "bomFormat": "CycloneDX",
    "specVersion": "1.6",
    "components": [
      { "type": "application", "name": "busybox", "version": "1.36.1", "purl": "pkg:generic/[email protected]" }
    ]
  }
}

Three fields carry the weight, per the Statement specification:

  • subject is a list of ResourceDescriptors, and every element "MUST have digest set." Subjects are assumed immutable. For firmware, name the files a device or customer actually receives.
  • predicateType is a URI that tells the verifier how to parse predicate. The CycloneDX predicate uses https://cyclonedx.org/bom, and its predicate "contains a JSON-encoded CycloneDX BOM."
  • predicate is the claim itself. The Statement adds no meaning to it; that comes from the predicate's own specification.

The same subject can carry several Statements: one for SLSA provenance, one for the SBOM, one for test results.

Which predicate types can a device maker use?

The vetted predicates list covers the evidence a firmware release usually needs:

Predicate Describes, per the project Firmware use
SLSA Provenance "How an artifact or set of artifacts was produced" Build provenance for the image
SLSA Verification Summary A SLSA verification decision about an artifact Release gate's pass result, for customers
CycloneDX CycloneDX BOM for software artifacts Image SBOM (see CycloneDX vs SPDX)
SPDX2 and SPDX3 SPDX-formatted BOM Yocto's create-spdx output
Test Result Results of any type of tests Fuzzing or hardware-in-the-loop runs
VULNS Results of vulnerability scanning Scanner output at release time
Release An artifact that is part of a given release version Mapping files to release 4.2.0
Link Migration from in-toto 0.9 Existing layout/link pipelines

The project encourages reusing an existing predicate where one fits; new ones go through its predicate guidelines. A vulnerability-scan predicate records what a scanner found at one moment; whether each finding applies to the product belongs in VEX, such as OpenVEX.

How is a Statement signed and shipped?

The Envelope specification recommends DSSE v1.0. In a DSSE envelope, payload is the base64-encoded Statement, payloadType must be application/vnd.in-toto+json (or a predicate-specific variant), and signatures is an array, so several parties can sign the same Statement. Consumers should rely on predicateType inside the verified payload, not on the media type.

Two compatibility notes matter for tool choice. The specification says the Sigstore bundle supports DSSE but is not fully compliant with its envelope rules, because it allows only one signature; likewise COSE_Sign qualifies and single-signer COSE_Sign1 does not. In practice, a single-signer Sigstore flow is common and works; it just cannot carry a second signature.

For storage, the Bundle layer uses JSON Lines, one envelope per line, and a bundle for <filename> should be named <filename>.intoto.jsonl. The bundle as a whole is unauthenticated, so the specification warns that an attacker might delete or replay individual attestations inside it; verify each envelope and require the ones your policy expects.

Where does SLSA fit on top?

SLSA (see our SLSA supply chain levels guide) defines what a provenance claim about a build should contain and how strong the guarantees behind it are. It does not reinvent how that claim is packaged: SLSA's own attestation-model documentation recommends in-toto attestations for the Statement layer of a software attestation. In practice this means a build pipeline producing SLSA provenance is, at the wire-format level, producing an in-toto Statement with a SLSA-defined Predicate; the two specifications are complementary layers of the same stack rather than competing standards.

How does a device maker wire in-toto into a Yocto or Buildroot pipeline?

A firmware pipeline has a few natural steps, each a candidate for its own signed evidence. A workable sequence:

  1. Decide the subjectsList the files that leave the building: update package, factory image, SDK installer. Hash them after the final packaging step.
  2. Record the fetch stepYocto and Buildroot already verify source checksums (see the Yocto and Buildroot SBOM guide). If you use the layout/link model, wrap the fetch in in-toto-run so the link lists every tarball as a material.
  3. Attest the buildLet the CI platform emit SLSA provenance as an in-toto Statement, signed by a key or identity the build steps cannot reach.
  4. Attach the SBOMWrap the image SBOM in a CycloneDX or SPDX predicate with the same subjects. cosign offers cosign attest --predicate <file> and cosign verify-attestation; witness and in-toto-golang are other in-toto implementations.
  5. Attest testsHardware-in-the-loop or fuzzing results go into a Test Result predicate.
  6. Bundle and publishWrite all envelopes to gw-4.2.0.swu.intoto.jsonl and publish it next to the update package.
  7. Verify before release and on intakeA release gate checks every expected predicate type, signer and subject digest. A customer integrating your module does the same before accepting it.

Attestations protect the path to the device; they are not checked by the bootloader. On the device, image authenticity comes from signed updates and secure boot. SBOM attestations also support SSDF task PS.3.2 on sharing component provenance; see the NIST SSDF guide.

What are the common pitfalls?

  • Attesting a directory instead of the shipped file. A subject digest of a build directory says nothing about the .swu a customer installs.
  • Trusting the media type. payloadType is a hint; read predicateType from the verified payload.
  • Treating a bundle as signed. Each envelope is signed, the bundle file is not; a missing attestation must fail the policy, not pass silently.
  • Signing with a key the build can read. The attestation then proves only that the build job ran, not that it ran untampered.
  • Writing layouts that never expire. Layouts carry an expiration date for a reason; rotate them with your keys.
  • Mixing up "found" and "affects". A scanner result in a VULNS predicate is not a statement that the product is affected; keep that judgement in VEX.

What is a workable starting point?

  1. Decide which in-toto model fits your pipelineA fixed, auditable build process with distinct human/automated actors can use the original layout/link model directly; most modern CI-driven pipelines instead produce in-toto attestations (Statement + a chosen Predicate, such as SLSA provenance) as part of the build.
  2. Start by generating, then move to signing and verifyingAn unsigned or self-signed attestation still establishes the schema and habit; the integrity guarantee only becomes real once a verifier outside the build job checks the signature and artifact chain.
  3. Treat in-toto as the envelope, SLSA as the contentIf the goal is build provenance specifically, implement SLSA's requirements and let the in-toto Attestation Framework define how that provenance is packaged and verified.
  4. Publish and keep attestations alongside the artifact, not in a separate system that can drift out of sync: an attestation only protects a consumer who can actually fetch and check it against the artifact they received.

SoftWSP does not create, sign or verify in-toto attestations. Its part is the content of one predicate: it extracts an SBOM from the shipped firmware binary as CycloneDX 1.6 JSON, which your pipeline can wrap as a CycloneDX predicate, and it matches components against NVD, CISA KEV, FIRST EPSS and CISA's ICS advisories in a cited, AI-drafted report an engineer reviews. Background on why an image-derived SBOM matters is in our firmware SBOM guide; the free SBOM viewer opens any CycloneDX or SPDX file in your browser. See device firmware security.

This guide summarises public in-toto, CNCF, USENIX, Sigstore and SLSA documentation, read 2026-11-10; it does not constitute legal or compliance advice.

Put this guide to work

Frequently asked questions

What is in-toto?

A framework to secure the integrity of software supply chains, run as a CNCF (Cloud Native Computing Foundation) graduated project. in-toto's own site describes it as designed "to ensure the integrity of a software product from initiation to end-user installation," making it transparent "what steps were performed, by whom and in what order" across a supply chain, so a consumer can verify the chain of custody rather than trusting the final artifact on faith.

Who created in-toto, and is it based on published research?

in-toto originates from an academic collaboration; the project page states it "is led by Prof. Santiago Torres-Arias at Purdue University" with contributors including "members of the Secure Systems Lab at NYU and the NJIT Cybersecurity Research Center," and that development was supported by the US National Science Foundation (NSF), DARPA and the Air Force Research Laboratory (AFRL). It was published as a peer-reviewed paper, "in-toto: Providing farm-to-table guarantees for bits and bytes," by Santiago Torres-Arias (NYU), Hammad Afzali (NJIT), Trishank Karthik Kuppusamy (Datadog), Reza Curtmola (NJIT) and Justin Cappos (NYU), at the 28th USENIX Security Symposium in August 2019.

What are layout and link metadata?

The two core metadata types in the original in-toto specification. Layout metadata defines the expected shape of a supply chain: an expiration date, the public keys authorized for each functionary (a person or automated process performing a step), the sequence of required steps with their expected materials/products, and client-side inspections to run at verification time. Link metadata is the evidence that a step actually happened: it records the command run, the materials (inputs) and products (outputs) as hashes, byproducts such as stdout/stderr/return code, and the environment the step ran in — signed by the functionary who performed it, so a verifier can check each recorded step against what the layout required.

How does in-toto relate to SLSA provenance?

The in-toto Attestation Framework supplies the standard envelope SLSA recommends for carrying provenance. SLSA's own attestation-model documentation recommends "[in-toto attestations](https://github.com/in-toto/attestation/)" for the Statement layer of a software attestation — the layer that binds a claim to a specific artifact by identifying its subject. In practice, SLSA defines *what* a provenance attestation should claim (see our [SLSA guide](/guides/slsa-supply-chain-levels/)); in-toto's attestation framework defines the generic *Statement* and *Predicate* structure used to package that claim as a verifiable, signed document.

Sources

  1. in-toto: project overview
  2. in-toto: documentation hub (technical specification, Python reference implementation, demo)
  3. GitHub: in-toto/specification — the in-toto specification document (v1.0.0)
  4. GitHub: in-toto/attestation — in-toto Attestation Framework
  5. USENIX: "in-toto: Providing farm-to-table guarantees for bits and bytes" (USENIX Security '19)
  6. SLSA: Attestation model (recommended Statement layer: in-toto attestations)
  7. CNCF: in-toto project page (maturity dates)
  8. GitHub: in-toto Attestation Framework spec README (layers, versioning)
  9. GitHub: in-toto attestation Statement layer specification (v1)
  10. GitHub: in-toto attestation Envelope layer specification (v1)
  11. GitHub: in-toto attestation Bundle layer specification (v1)
  12. GitHub: in-toto ResourceDescriptor field type specification
  13. GitHub: in-toto attestation vetted predicates
  14. GitHub: in-toto CycloneDX predicate type
  15. GitHub: DSSE, Dead Simple Signing Envelope
  16. Sigstore: cosign, verifying attestations
  17. in-toto Python reference implementation: in-toto-run
Was this guide helpful?

In this cluster

in-toto, explained: supply chain layouts, links and attestations