SBOMs, SPDX/CycloneDX, in-toto Attestations, SLSA Provenance, Signatures, and Verification Workflows: Concepts, Architecture, and Mental Model

1. The practical problem: “we have an SBOM” is not yet a trust decision

Chapter 29 bound vulnerability results to a digest. Chapter 30 adds the evidence needed to answer different questions: what software is in these bytes, how were these bytes produced, who is asserting something about them, and did a verifier accept those assertions under an explicit policy? Those are separate questions. A package list does not prove build integrity. Provenance does not prove the artifact is vulnerability-free. A signature proves only that a key or identity signed a particular payload; it says nothing useful until the verifier knows what identity was expected and what was signed.

A mutable tag such as demo:release is useful for discovery, not for evidence identity. Resolve it to a digest, record that digest, and verify every downstream object against it.

2. Mental model: subject → evidence → verifier → policy

flowchart TD
  A[Source + build inputs] --> B[Builder identity and build process]
  B --> C[Immutable image digest]
  C --> D[SBOM attestation: what is inside]
  C --> E[Provenance attestation: how it was built]
  C --> F[Signature: who vouches for this subject]
  D --> G[OCI registry/referrer storage]
  E --> G
  F --> G
  G --> H[Verifier checks subject + identity + policy]
  H --> I[Promote / deploy / reject]
            

The build starts with source, Dockerfile, base images, build parameters, and a builder. BuildKit produces an image whose digest identifies the manifest or index. It may also generate attestations. An SBOM describes components. Provenance describes build facts and materials. A signature adds cryptographic evidence from a signing key or workload identity. Registries can store associated artifacts and expose them through OCI-compatible relationships. A verifier then checks subject digest, evidence syntax, cryptographic identity, and organization policy before making a promotion or deployment decision.

Notice the arrows: the verifier does not ask whether “a signature exists.” It asks whether a signature from an expected identity covers the exact subject digest, whether required attestations are attached to that subject, and whether their claims match policy.

3. Define the state before touching it

4. SBOM: inventory evidence, not authenticity

Docker BuildKit can generate an SBOM attestation during the build with --sbom=true or --attest type=sbom. Docker documents that the generated attestation is JSON-encoded SPDX wrapped as an in-toto predicate. The default scanner plugin is BuildKit’s Syft-based generator. This is valuable because build-time scanning can describe artifacts used in build stages that may not appear in the final filesystem.

SPDX and CycloneDX are both widely used machine-readable BOM standards, but they are not interchangeable labels. The current SPDX specification is 3.0.1; CycloneDX’s current specification is 1.7. BuildKit’s native SBOM attestation path is SPDX-oriented. If your consumer requires CycloneDX, generate or convert it with a tool that explicitly supports that output, and record the generator/version rather than pretending the BuildKit SBOM magically changed format.

5. Provenance: build claims and materials

BuildKit provenance records facts such as build timestamps, parameters, environment, VCS metadata, source details, and materials consumed by the build. Buildx creates minimal provenance by default for build results that can retain attestations. You can request mode=max for richer evidence and explicitly request SLSA provenance v1 with version=v1. As of this chapter baseline, Docker documents v0.2 as the default schema while also supporting v1.

More provenance is not always better. Maximum mode can expose build arguments or source details that you would not publish to an untrusted registry. The design question is not “min or max?” in isolation; it is “which claims does the verifier need, and which details are safe to disclose in this evidence channel?”

# Read-only inspection of a registry image with attestations
# Replace IMAGE with an actual immutable or tagged registry reference.
docker buildx imagetools inspect "$IMAGE" --format '{{json .Provenance}}'
docker buildx imagetools inspect "$IMAGE" --format '{{json .SBOM}}'

6. Signatures: identity plus subject binding

Signing answers a different question. A signer uses a private key, hardware-backed key, KMS key, or keyless workload identity to produce cryptographic evidence. Verification succeeds only when the verifier trusts the corresponding public key or certificate chain and checks the intended identity. For local education we use a throwaway Cosign keypair because it is deterministic, free, and does not require OIDC or a public transparency service.

Cosign itself warns to sign image digests rather than tags. That matters because signing a tag creates a time-of-check race: the tag can move between resolution and signing. The lab therefore resolves localhost:5005/dca30/app:1 to a digest first, forms localhost:5005/dca30/app@sha256:..., and signs that immutable reference.

7. OCI subjects and referrers

OCI Image/Distribution 1.1 standardized a subject relationship and a Referrers API so registries and tools can discover signatures, attestations, and other artifacts associated with a digest. Conceptually, the application image is the subject; an SBOM, provenance statement, or signature is a separate object that refers to that subject. That avoids stuffing every evidence type into the runtime image filesystem.

Registry behavior still matters. A registry may implement OCI 1.1 referrers directly, use a compatibility fallback, impose media-type limits, or garbage-collect unreferenced artifacts differently. Evidence portability therefore includes a registry capability test, not just a tool capability test.

8. Engine 29 compatibility baseline

9. Chapter path

Lesson 2 builds and inspects evidence. Lesson 3 makes format, identity, storage, and policy choices explicit. Lesson 4 deliberately breaks subject/identity assumptions and diagnoses the failure. Lesson 5 produces one auditable packet in which the image digest, SBOM, provenance, signature, and policy verdict all agree.

Knowledge check

Official references and version notes

• Docker Docs — Build attestations — current BuildKit SBOM/provenance model and image-store requirements.
• Docker Docs — SBOM attestations — SPDX/in-toto output and imagetools inspect workflow.
• Docker Docs — Provenance attestations — mode=min|max and optional SLSA provenance v1.
• Docker Docs — buildx imagetools inspect — registry manifest, SBOM, and provenance inspection.
• Docker Engine 29 release notes — Engine 29 compatibility baseline and removal of Docker Content Trust from the CLI.
• OCI — Image and Distribution Specifications 1.1 — artifact subject, artifactType, and Referrers API.
• SPDX Specification 3.0.1 — current SPDX specification reference.
• CycloneDX Specification Overview — current CycloneDX 1.7 object model and media types.
• SLSA Specification 1.2 — current SLSA model and provenance guidance.
• Sigstore Cosign v3.1.3 — pinned local signing/verifying tool used as the 2026-09-22 lesson baseline.
• Docker Official Image — registry — disposable local registry; lesson baseline pins registry:3.1.1.