DevOps AcademyLearn the delivery system
Chapter 30Lesson 03~150 minutes

SBOMs, SPDX/CycloneDX, in-toto Attestations, SLSA Provenance, Signatures, and Verification Workflows: Configuration, Design Choices, and Tradeoffs

Choose evidence formats, provenance depth, signing identity, storage location, and policy scope by tracing the portability, trust, privacy, cost, and operational consequences of each option.

CycloneDXPolicyKeyless identityRegistry artifactsTradeoffs

Learning objectives

  • Choose SPDX or CycloneDX based on consumer requirements rather than fashion.
  • Select provenance depth that exposes enough build facts without leaking unnecessary build metadata.
  • Compare local-key, KMS/HSM, and keyless identities as different trust and operations models.
  • Decide when registry referrers are preferable to exported evidence files and how portability changes the answer.
  • Define a promotion policy that checks subject digest, signer identity, and required predicate claims independently.

1. Design starts with the decision you need to make

Supply-chain evidence has a cost: builders generate it, registries store it, CI moves it, verifiers parse it, and humans maintain policy. The design target is therefore not “collect every possible attestation.” The target is a small, explicit evidence set that can answer your promotion questions repeatedly.

A typical policy might require: the deployment reference resolves to an immutable digest; an SBOM exists for that digest; provenance names an approved build path and source revision; a signature verifies against an approved workload identity; and the evidence was evaluated recently enough for the release process. Each requirement maps to a different object or claim.

2. SPDX versus CycloneDX

Choice Strength in this Docker workflow Tradeoff / prerequisite
SPDX Native BuildKit SBOM attestation path; mature license/package representation; standard ecosystem BuildKit’s generated document may not match a consumer expecting CycloneDX-specific fields.
CycloneDX Strong BOM-oriented component/service/dependency model; current spec 1.7; common security-tool interoperability Requires an explicit generator/conversion path in this course because BuildKit’s native SBOM attestation is SPDX-oriented.
Both Can satisfy different downstream consumers Duplicate generation is not proof of agreement; bind both to the same digest and compare generator scope.

Do not judge quality only by format name. Record generator, version, configuration, subject, and scope. Two valid SPDX documents can differ because one scanner understands language packages that another misses.

3. Provenance mode=min versus mode=max

Mode What you gain Risk / operational note
min Compact default facts sufficient for basic origin traceability May omit details a strict policy needs.
max Richer parameters, environment/source/material metadata Can disclose build arguments, source details, or environment metadata; review before publishing.
v1 schema Modern SLSA provenance predicate requested explicitly in BuildKit Your verifier/toolchain must support the version you require.
Secrets belong outside provenance. Build secrets should use BuildKit secret/SSH mounts from Chapter 28. If a secret appears in provenance or build args, changing attestation mode does not solve the original secret-handling error.

4. Local key, managed key, or keyless identity?

Signer model Trust anchor Best fit Failure/rotation considerations
Local file key Pinned public key Offline lab, controlled small environment Private-key theft/backup/passphrase handling are your responsibility.
KMS/HSM Cloud/on-prem key service and access policy Centralized production signing with protected private keys Provider IAM, availability, cost, and audit logs become dependencies.
Keyless OIDC Certificate identity + issuer + Sigstore trust roots/transparency evidence Ephemeral CI identities with strong workflow binding Verifier must constrain identity/issuer; token/workflow configuration errors become trust failures.

“Keyless” does not mean “identity-less.” It replaces long-lived signing keys held by the workload with short-lived certificates rooted in an identity provider and Sigstore trust infrastructure. Verification must constrain the expected identity and issuer; accepting any valid certificate defeats the point.

5. Registry referrers versus exported evidence

Registry-attached evidence travels naturally with a digest and is discoverable by tooling. OCI 1.1’s subject/referrers model is the architectural fit for signatures and attestations. But exported evidence files remain useful for air-gapped review, change tickets, audit archives, or registries with incomplete artifact support.

Storage model Advantages Risks / evidence you must retain
Registry referrer Discoverable from subject digest; easy automated verification Registry retention/GC/copy behavior must preserve associated artifacts.
Exported file Simple archival and offline review You must record the subject digest and protect file integrity/chain of custody.
Both Operational verification plus independent archive Need reconciliation rules so the archive does not silently drift from registry state.

6. Sign the image, the attestation, or both?

Policies differ. Signing the image digest provides an identity assertion over the release subject. Signing an attestation additionally authenticates a specific statement. Some systems use provenance generated and signed by the build platform, others sign the image and trust the build system/registry channel for attached provenance. The policy must say which object is authoritative and which identity is expected for each claim.

Do not infer that “image signature valid” means “every attached referrer is authenticated.” A malicious or misconfigured registry could present an unrelated unsigned attestation unless your verifier also checks the attestation’s authentication or trusts a controlled registry/builder path.

7. Promotion policy scope

Policy check Observable evidence Reject when…
Subject identity resolved image/index digest + platform tag moved or policy evaluated a different digest.
SBOM presence/scope SBOM predicate names subject and expected format/generator scope missing, wrong subject, unsupported/empty inventory.
Provenance predicate version, builder ID, source/material claims unexpected builder/source/material, insufficient claim depth.
Signature identity public key or certificate identity + issuer signature invalid or signer not authorized.
Transparency requirement bundle/log inclusion if policy requires it local-only signature used where transparency is mandatory.
Freshness/rollover verification time + key/policy versions evidence predates required rotation or policy generation.

8. Worked scenario: internal API release

Scenario: a team builds an internal API in CI, pushes to an OCI registry, and deploys only through an admission controller. Developers want fast local builds; security wants traceable release builds.

  1. Local development: no mandatory signature; optional local SBOM for debugging.
  2. Release build: BuildKit SBOM + SLSA provenance v1, generated by the approved CI builder.
  3. Signing: keyless CI identity constrained to the release workflow/repository.
  4. Storage: registry referrers plus an audit export of digest, provenance summary, verifier result, and policy version.
  5. Admission: reject if the digest, identity, provenance builder/source, or required evidence is wrong.

This design gives different assurance levels to development and release without pretending every workstation is a trusted release builder.

9. Compatibility and privacy checklist

Before adopting a format or signer:
  • Can your builder generate the predicate version?
  • Can your registry store/copy/referrer-discover the artifact?
  • Can your verifier parse and authenticate it?
  • Will provenance expose sensitive build parameters?
  • What happens during key/identity rotation?
  • Does copying an image between registries preserve associated evidence?
  • Which policy version made the release decision?
Next

Diagnose failures without disabling verification

Lesson 4 breaks the subject, registry, identity, and legacy-tool assumptions one by one.

Knowledge check

If BuildKit can generate SPDX SBOMs natively, when might CycloneDX still be appropriate?

Why can mode=max provenance be a privacy concern?

Does “keyless signing” remove identity verification?

A registry copy preserved the image digest but dropped its referrers. Is the release evidence complete?

What is the safest interpretation of a valid image signature when provenance is unsigned/untrusted?

Official references and version notes

Format note: Current standards referenced here are SPDX 3.0.1, CycloneDX 1.7, and SLSA 1.2. BuildKit’s documented provenance default remains SLSA v0.2 unless version=v1 is requested; policy should validate the actual predicate rather than infer it from the current SLSA website version.

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20
0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this address.