Skip to content
Blog

in-toto and Attestations: Proving How Images Were Built

From in-toto's layout-and-link framework to the DSSE-wrapped attestation statement format — how cosign, syft, and CI systems emit verifiable claims about container images, and how to check them.

Published on • November 15, 2026

AI Assistant

“Signing a image” only answers who signed it. The harder question — the one auditors, deployment gates, and incident responders actually ask — is what claims do we have about this image, and can we prove they’re true? That’s the niche the in-toto project fills. There are two things called “in-toto” — a rigorous process-verification framework from academia, and a tiny JSON statement format that became the lingua franca of container attestations. Understanding both is the key to reading modern supply-chain tooling correctly.

Two Things Named in-toto

The original in-toto framework (from research led by Santiago Torres-Arias at Purdue and NYU’s Secure Systems Lab) is a full supply-chain integrity model: a project owner defines a layout — the authorized steps, who may perform them, and how artifacts must flow — and verification proves the final product was produced exactly that way. It’s process enforcement, and it ships as a Python toolset (pip install in-toto) with in-toto-run, in-toto-record, and in-toto-verify.

The in-toto attestation format, defined in the separate in-toto/attestation repository, is something else: a deliberately minimal JSON statement that says “this set of digests has this typed claim attached.” It’s what cosign attest produces, what SLSA provenance rides in, and what registries store as OCI referrers. The name is shared; the artifacts, tooling, and use cases are nearly disjoint. Most “container attestation” conversations are about the second one — so let’s start there.

The Attestation Statement

An attestation is a Statement — and a Statement is almost boringly simple:

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "ghcr.io/acme/ledger-service",
      "digest": { "sha256": "9b4d...c7f1" }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://actions.github.com/buildtypes/workflow/v1",
      "externalParameters": { "workflow": { "repository": "acme/ledger-service", "ref": "refs/heads/main" } },
      "resolvedDependencies": [{ "uri": "git+https://github.com/acme/ledger-service", "digest": { "gitCommit": "e5a1..." } }]
    },
    "runDetails": { "builder": { "id": "https://github.com/acme/ledger-service/.github/workflows/release.yml" } }
  }
}

Three fields do all the work:

  • _type — the statement format version (https://in-toto.io/Statement/v1; you’ll still encounter v0.1 in older artifacts).
  • subject — the artifact(s) the claim is about, identified by digest, not tag. A claim is meaningless against a mutable tag.
  • predicateType + predicate — the typed claim itself. Common predicate types: https://slsa.dev/provenance/v1 (build provenance), https://spdx.dev/Document (SPDX SBOM), https://in-toto.io/attestation/vuln/v0.1 (vulnerability/VEX), https://in-toto.io/attestation/test-result/v0.1, and https://in-toto.io/attestation/link/v0.1 (the framework’s own link record, closing the loop between the two meanings of in-toto).

The statement itself isn’t signed. It’s wrapped in a DSSE envelope — Dead Simple Signing Envelope — which carries a base64-encoded payload, declares the payload type (application/vnd.in-toto+json), and holds one or more signatures over the whole envelope:

{
  "payloadType": "application/vnd.in-toto+json",
  "payload": "eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEiLCJzdWJqZWN0Ijpb...",
  "signatures": [{ "keyid": "sha256:4f8c...", "sig": "MEUCIQ..." }]
}

That separation — content in the statement, signing in the envelope — is why the same statement format works with cosign keys, Fulcio certificates, Tekton Chains, and build-platform KMS keys without ever changing shape.

The original framework deserves its own section, because you’ll encounter “in-toto” in this strict sense in high-assurance settings. The layout is the project owner’s policy document, and it contains:

  • an expiration date and optional readme;
  • functionary keys — the public keys allowed to sign step metadata;
  • steps, each with a unique name, the functionaries (by key ID) authorized to run it, and material/product rules;
  • inspections — commands re-run at verification time;
  • one or more signatures from the project owner’s key over the whole layout.

When a functionary runs a step through in-toto-run (a single command) or in-toto-record start/stop (multi-part steps), the tool records the command, materials, and products into a link metadata file signed with the functionary’s key. The rule language chains steps together:

CREATE src/*
MODIFY package.deb
MATCH package.tar.gz WITH PRODUCTS FROM code-review
REQUIRE tests.passed
DISALLOW *

DISALLOW * as the final rule is the recommended default — without it, artifacts not explicitly disallowed are tolerated. Verification (in-toto-verify) then checks, against the released product: the layout’s signatures and expiration, that every step was performed by an authorized functionary using the specified command, that materials and products obeyed the rules, and that inspections pass.

This proves the sequence of the supply chain, not merely the build’s origin — a stronger statement than a single provenance attestation, and the reason the framework sees little everyday container CI use: someone must own the layout, ship link metadata with every release, and manage functionary keys per step. The container ecosystem standardized on the attestation format instead, using SLSA provenance to carry build-origin claims and CI platform identities to stand in for per-step functionary keys. The link predicate type (https://in-toto.io/attestation/link/v0.1) is the bridge: an attestation statement that records one step’s materials and products in the framework’s own vocabulary.

Emitting Attestations: Who Writes Them

Cosign is the most common emitter. Signing an image signature proves identity; cosign attest attaches typed claims:

# SBOM attestation (syft generates the predicate)
syft packages ghcr.io/acme/ledger-service:2.3.1 -o spdx-json=/tmp/ledger.spdx.json
cosign attest --yes \
  --predicate /tmp/ledger.spdx.json \
  --type https://spdx.dev/Document \
  ghcr.io/acme/ledger-service@sha256:9b4d...c7f1

# Provenance attestation
cosign attest --yes \
  --predicate provenance.json \
  --type https://slsa.dev/provenance/v1 \
  ghcr.io/acme/ledger-service@sha256:9b4d...c7f1

Syft’s role is predicate production: it scans the image (or filesystem) and emits SPDX or CycloneDX JSON; cosign turns that JSON into a signed, logged attestation. GitHub’s actions/attest-build-provenance emits SLSA provenance statements signed by the workflow’s OIDC identity — it’s the same in-toto statement underneath the “attestations” branding. Tekton Chains speaks in-toto/DSSE natively: every TaskRun becomes a signed statement whose predicate is provenance. BuildKit can generate both SBOM and provenance attestations during docker buildx build (--sbom=true --provenance=mode=max), producing in-toto statements attached to the image — self-asserted until you sign them with cosign.

Storage follows the same pattern everywhere: statements are attached to the image in the registry via the OCI referrers API (cosign’s legacy sha256-<digest>.att tag scheme still exists), and signatures are optionally recorded in Rekor for public auditability.

Verification Workflows

Verifying an attestation has two layers: authenticity (cosign’s job) and content (your policy’s job).

cosign verify-attestation \
  --type https://slsa.dev/provenance/v1 \
  --certificate-identity-regexp 'https://github.com/acme/ledger-service/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/acme/ledger-service@sha256:9b4d...c7f1

That proves a workflow in your repository made the claim about that digest. Then check the predicate — authenticity says the claim is trustworthy, not that it says what you need:

cosign verify-attestation \
  --type https://spdx.dev/Document \
  ghcr.io/acme/ledger-service@sha256:9b4d...c7f1 \
  | jq -e '.predicate.packages
      | map(select(.name == "openssl" and (.versionInfo | startswith("3.0."))))
      | length > 0'

A realistic admission gate chains several checks: provenance exists and its resolvedDependencies commit matches your release tag; the SBOM is present and contains no packages on your denylist; the signer identity matches the producing repository; and — crucially — the subject digest equals the digest your deployment manifest pins. cosign verify-attestation fails closed when the attestation type is missing, which is exactly what validationFailureAction: Enforce in Kyverno’s verifyImages or a Sigstore ClusterImagePolicy will do at pod admission.

Relationship to SLSA

The pieces layer cleanly, and the layering is worth internalizing:

  1. in-toto defines the envelope and statement — subject digests, typed predicate, DSSE signature. It says how a claim is shaped and signed, not what the claim must contain.
  2. SLSA defines the predicate’s content — for provenance, exactly which fields (build platform, invocation, resolved dependencies, builder identity) the https://slsa.dev/provenance/v1 predicate must carry, and the build levels that say how trustworthy the signing platform is.
  3. Sigstore defines identity and distribution — Fulcio binds the signing key to an OIDC identity, Rekor logs the event, cosign stores the envelope with the image in the registry.

So when someone says “our images carry SLSA provenance,” the precise statement is: the images have in-toto attestation statements attached, whose predicate type is a SLSA provenance predicate, signed through a Sigstore (or platform) identity, stored as OCI referrers. Each layer can be swapped — cosign for notation, Rekor for an internal log, SLSA predicate for a VEX predicate — without breaking the others.

And the classic layout/link framework from the earlier section still has a home: high-assurance pipelines that must prove every step — package, test, sign, release — was performed by an authorized actor under a project-owner-signed policy. It’s heavier than attaching one provenance statement, which is why most container teams start with attestations and reach for layouts only when the process itself, not just the build, must be provable.

References