Skip to main content

Generate Verifiable Terraform Provenance SBOMs

· 4 min read
Erik Osterman
Erik Osterman
Founder @ Cloud Posse

Compliance reviews often start with a deceptively simple question: what exactly is in this infrastructure release? Answering it by hand means reconciling vendored sources, provider locks, module downloads, and registry artifacts—without accidentally mistaking missing evidence for an empty dependency set. Atmos now makes that evidence visible in one SBOM while keeping coverage boundaries explicit. It also integrates with native CI to upload the SBOM as a GitHub Actions workflow artifact when enabled.

The Problem​

An SBOM that quietly excludes a dependency category can create more risk than no SBOM at all. The person deciding whether an artifact is ready for compliance review needs to see gaps like these:

  • A provider version without its checksum
  • A module selected from a mutable ref
  • An unavailable module graph

Terraform's provider lock file, vendored source receipts, and OCI artifact digests already contain much of the evidence that infrastructure teams need. Until now, that evidence lived in separate places, and no tool could render it as a single standards-based document.

The Fix​

Generate a provenance/build-input SBOM for Terraform-managed infrastructure:

atmos sbom generate --format cyclonedx-json --output infra.sbom.json

The first release inventories four evidence domains:

  • Atmos-managed sources recorded in vendor.lock.yaml, including vendor.yaml, component.yaml, and mixins
  • OCI source artifacts pinned by their selected manifest digest
  • Terraform providers from .terraform.lock.hcl, including recorded archive checksums
  • Terraform modules from terraform modules -json, resolved to a commit, OCI digest, or content hash when possible

The command emits CycloneDX JSON or SPDX JSON from the same graph. The two documents describe the same components and relationships.

Compliance Without False Confidence​

An SBOM is only useful when its coverage is clear. The default provenance mode includes coverage diagnostics for each adapter and emits the evidence that is available. It deliberately does not claim that the document represents every dependency or deployed workload in the environment.

For a Terraform-scoped NTIA-baseline check, use --mode ntia and identify the subject:

atmos sbom generate \
  --mode ntia \
  --subject-name infra-live \
  --subject-version "$(git rev-parse --short HEAD)" \
  --subject-supplier "Example, Inc." \
  --format spdx-json \
  --output infra-live.spdx.json

NTIA mode fails when required provenance is incomplete, such as:

  • Missing subject information
  • A provider lock without a SHA-256 archive checksum
  • A module without immutable resolution evidence
  • An unavailable module-graph interface

A failed compliance-mode invocation is more useful than a document that silently leaves evidence out.

How to Use It​

Start with the default provenance mode to inspect the evidence and coverage for initialized Terraform components:

atmos sbom generate --format cyclonedx-json --output infra.sbom.json

Add --include-files when the exact vendor.lock.yaml file inventory belongs in the document:

atmos sbom generate --include-files --output infra.sbom.json

The command uses the Terraform executable configured by components.terraform.command in each component directory. If it is unset, Atmos uses terraform. Module inventory currently requires Terraform 1.10 or later because it relies on the stable terraform modules -json interface.

If your project configures tofu, Atmos honors that choice. Atmos does not parse Terraform's internal module-installation files as a fallback. Until OpenTofu exposes an equivalent stable structured interface, Atmos marks module coverage unavailable, and NTIA mode refuses the scope.

What's Next​

This is the foundation for broader dependency coverage — it's not yet feature complete. The next adapters extend coverage across the other component types Atmos already supports:

  • Helm and Helmfile locks
  • Kubernetes manifests
  • Typed deployed-container image discovery
  • OCI SBOM attestations or scanner integration for image contents
  • OpenTofu module graphs

The shared graph and coverage contract mean those additions extend both CycloneDX and SPDX consistently.

Read the full SBOM command reference and the provenance design.

Get Involved​

The initial release is experimental. Questions about the evidence model, new adapters, or compliance workflows are welcome in the Atmos GitHub repository and the community Slack.