Generate an SBOM for any container image with Syft

Produce a complete software bill of materials in SPDX or CycloneDX and feed it to Grype for fast CVE triage.

The question that an SBOM exists to answer arrives on a bad day: a CVE is published for a library, and somebody asks which of the two hundred images in the registry contain it. Without an inventory the answer is a week of pulling images and reading layers. With one SBOM stored per image digest, it is a query over JSON files, and the rebuilds can start the same afternoon. Syft produces the inventory and Grype reads it, and the operational choices are about formats, storage and thresholds rather than about the tools.

One format, one file per digest

Syft output formats and when each fits

#!/usr/bin/env bash
set -euo pipefail
IMAGE="registry.acme.dev/shop/api@$DIGEST"          # the digest CI just pushed, never a tag
SHORT="${DIGEST#sha256:}"
 
# one run, two files: the security format and the compliance format
syft "$IMAGE" -o cyclonedx-json="sbom-${SHORT}.cdx.json" -o spdx-json="sbom-${SHORT}.spdx.json" -q
 
# archive next to the image, under the same retention as the image
aws s3 cp "sbom-${SHORT}.cdx.json" "s3://acme-sboms/shop/api/${SHORT}.cdx.json"

Pick CycloneDX or SPDX once for the organisation and emit the other only when a consumer needs it; Syft writes several formats from one scan, so the cost of both is one flag. The file is named after the digest because a tag moves and an SBOM describes bytes. It is archived with the image's retention because an SBOM for an image that no longer exists is history, and an image with no SBOM is the question you cannot answer. Scanning at build time, against the pushed digest, is what makes the file describe what runs rather than what the Dockerfile intended.

Grype reads the file, and the exit code is 2

grype sbom: matches the stored inventory against the vulnerability database, so a re-scan costs seconds and needs no registry access; that is how the archive gets queried on the bad day (grype db update first, then the same command against the same file). --fail-on high is the merge gate, and its exit code is 2, which matters for any wrapper script that treats only exit 1 as a failure; without the flag the same findings exit 0, so the gate is the flag, not the table. --only-fixed keeps the gate on findings with an available fix, which is the set a rebuild can act on; on the image above it removed 14 of 63 matches, and the unfixed ones go to a tracked list rather than a red pipeline. The same gate against the syft-json SBOM of the same image returned the same exit code. When a component is present but the vulnerable code path is not, a VEX document passed with --vex records that judgement where the scanner can apply it, instead of in a wiki nobody re-reads.

When the gate is wrong: recovery in order of preference

The day the CVE lands

# every archived SBOM that contains openssl below the fixed version
aws s3 sync s3://acme-sboms ./sboms --quiet
find ./sboms -name '*.cdx.json' | while read -r f; do
  jq -r --arg f "$f" '.components[] | select(.name=="openssl" and (.version < "3.3.2-r0")) | "\($f)\t\(.version)"' "$f"
done | sort -u

The loop is deliberately crude: version comparison on Alpine strings is not lexicographic in general, and the list it prints is a candidate set to confirm with Grype, not a verdict. What matters is that the set exists in minutes and names digests, so the rebuild order can start with the images that are running. The fix is a base image bump, and the SBOM from the rebuilt image is the evidence that the bump took, which is worth more than the pipeline's green tick.

The inventory becomes enforceable when it is attached to the image as a signed attestation and checked at admission; SBOM and provenance attestations continues from there. The same Grype gate runs on an image reference in a Trivy or Grype GitLab job for teams that prefer scanning the registry directly; the SBOM route is the one that survives the day the registry is the thing under load.

Related posts

Quick reference