SBOM

Active contributors: knqyf263, simar7, DmitriyLewen

Purpose

Trivy treats SBOMs (Software Bill of Materials) as both an input format and an output format. You can:

• Generate an SBOM for any scan target (trivy image -f cyclonedx, trivy fs -f spdx-json, etc.).
• Scan an existing SBOM file as if it were a real artifact (trivy sbom my-app.cdx.json).
• Round-trip SBOMs through trivy convert to switch formats while preserving findings.

CycloneDX and SPDX (both JSON and tag-value) are first-class formats; smaller formats like GitHub Dependency Snapshot are also supported.

End-to-end flow

graph LR
    subgraph Generate
        Scan[trivy image] --> Report[types.Report]
        Report --> Encoder[pkg/sbom/<format> encoder]
        Encoder --> File[CycloneDX / SPDX JSON]
    end
    subgraph Consume
        File2[SBOM file] --> Detector[pkg/fanal/analyzer/sbom]
        Detector --> Decoder[pkg/sbom/<format> decoder]
        Decoder --> Synth[synthetic BlobInfo]
        Synth --> Local[local.Service]
        Local --> Vuln[vulnerability detection]
    end

Generation

pkg/sbom/ holds the encoders:

• pkg/sbom/cyclonedx/ — CycloneDX 1.5 / 1.6 JSON.
• pkg/sbom/spdx/ — SPDX 2.3 JSON and tag-value.
• pkg/sbom/core/ — internal BOM model that both encoders consume.
• pkg/sbom/io/ — read/write helpers and round-trip glue.

The CLI's --format flag selects the writer. The CycloneDX writer carries vulnerabilities inside the SBOM (a CycloneDX VEX-shaped section), so a single cyclonedx document is both an SBOM and a vulnerability report.

Consumption

pkg/fanal/artifact/sbom/sbom.go implements artifact.Artifact for SBOM inputs. It reads the SBOM, normalizes it into the internal BOM model, then emits a synthetic BlobInfo that contains the listed packages. Once that blob exists, the rest of the pipeline (cache → applier → detectors) is identical to a "real" scan.

This means: scanning an SBOM is exactly as accurate as scanning the original artifact, if the SBOM contains every package. If the SBOM omits OS packages or pulls in a different set of language packages than what trivy fs would see, results differ.

Conversion

trivy convert (pkg/commands/convert/) reads a Trivy JSON report and re-emits it in another format. Common uses:

trivy image -f json -o report.json my-image
trivy convert -f cyclonedx -o sbom.json report.json
trivy convert -f sarif -o report.sarif report.json

Conversion preserves more data than re-scanning because it is a serialization change, not a re-derivation.

SBOM references

CycloneDX SBOMs can carry references to other SBOMs (e.g., a top-level SBOM that points at component SBOMs). pkg/vex/sbomref.go understands this pattern for VEX flows.

Integration points

• Vulnerability scanning — both consumed-SBOM scans and generated CycloneDX SBOMs include vulnerabilities.
• VEX — VEX statements can be embedded inline in CycloneDX or distributed alongside an SBOM.
• Reports — SBOM is one of several output shapes.

Entry points for modification

• Add a format — implement an encoder under pkg/sbom/<format>/ and register it as a writer.
• Add a field round-trip — extend pkg/sbom/core/ and update both encoders.
• Tune what gets included — pkg/sbom/io/encode.go controls which findings flow into the SBOM.

Key source files

File	Purpose
pkg/sbom/sbom.go	Top-level helpers.
pkg/sbom/cyclonedx/	CycloneDX encoder/decoder.
pkg/sbom/spdx/	SPDX encoder/decoder.
pkg/sbom/core/	Internal BOM model.
pkg/sbom/io/encode.go	Encoder driver.
pkg/fanal/artifact/sbom/sbom.go	SBOM-as-input artifact handler.
pkg/commands/convert/convert.go	trivy convert implementation.
pkg/types/report.go	Report.BOM field.

See also

• VEX — works hand-in-hand with SBOMs.
• Vulnerability scanning — what fills the vulnerability section in the SBOM.