sbom-formats
Overview
Two specification families dominate the SBOM landscape. CycloneDX is the
OWASP-curated, security-focused format and this skill's primary subject;
SPDX is the Linux Foundation's license-focused standard, covered in
references/spdx.md.
Per cyclonedx.org/specification/overview, CycloneDX's
distinguishing features vs SPDX:
- Vulnerability schema - first-class
vulnerabilities[] block
with VEX-style status assertions
- Services + dataflow -
services[] block describes service
endpoints + data flows
- Formulation - describes how the software was built (build
steps, tools, env)
- ML BOMs (CycloneDX 1.5+) - first-class ML model + dataset
components
- SaaS BOMs - describes hosted services not just shipped
artifacts
This is a reference skill - defines the schemas + tooling landscape;
doesn't run scans. Pair with syft-generation to generate SBOMs in either
format from real codebases.
Choosing a format
| Signal | Pick |
|---|
| Security-focused consumer (vuln tracking, supply-chain attestation) | CycloneDX |
| US Federal procurement (NIST SP 800-218 + EO 14028 guidance) | SPDX (references/spdx.md) |
| License-compliance focus (richest license-expression vocabulary) | SPDX |
| Linux Foundation member organization workflow | SPDX |
| EU consumers / broad modern tooling | CycloneDX (most common) |
| Consumer dictates the format | Whatever the consumer requires |
When no consumer constraint exists, CycloneDX is the default here: its
embedded VEX (vulnerabilities[].analysis) feeds the triage workflow
directly. Generating both (Syft emits either) satisfies mixed audiences.
Note SPDX license IDs are the cross-format standard - even CycloneDX
license blocks use them.
When to use
- The team adopts CycloneDX as the primary SBOM format, or must pick a
format (see Choosing a format).
- The use case is security-focused (vuln tracking, supply-chain
attestation) over licensing-focused.
- A consumer (vendor, customer, regulator) requires CycloneDX or SPDX
format specifically (SPDX: references/spdx.md).
- Per-language CycloneDX-native tooling is preferred over Syft+convert.
How to use
Work the numbered Steps in order: generate the BOM (Steps 1-2), add a
VEX-style analysis record per triaged finding (Steps 3, 5), validate
against the schema (Step 4), then sign + attest in CI (Step 6). Pin the
specVersion your consumer agreed; bump version on each re-issue.
For an SPDX consumer, follow references/spdx.md
instead.
Step 1 - Top-level structure
A minimal CycloneDX 1.6 BOM (JSON):
{
"$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"metadata": {
"timestamp": "2026-05-06T12:00:00Z",
"tools": [{"vendor": "anchore", "name": "syft", "version": "1.16.0"}],
"component": {
"type": "application",
"name": "my-app",
"version": "1.0.0",
"purl": "pkg:generic/my-app@1.0.0"
}
},
"components": [
{
"type": "library",
"bom-ref": "pkg:npm/lodash@4.17.20",
"name": "lodash",
"version": "4.17.20",
"purl": "pkg:npm/lodash@4.17.20",
"licenses": [{"license": {"id": "MIT"}}]
}
],
"dependencies": [
{
"ref": "pkg:generic/my-app@1.0.0",
"dependsOn": ["pkg:npm/lodash@4.17.20"]
}
]
}
Step 2 - Required fields per spec
Per cdx-spec:
| Field | Required? | Use |
|---|
bomFormat | yes | Must be "CycloneDX" |
specVersion | yes | "1.6" (current) / "1.5" / "1.4" |
serialNumber | recommended | URN UUID identifying the BOM |
version | recommended | BOM revision (incremented per re-issue) |
metadata | recommended | Generation context (timestamp, tools, top-level component) |
components[] | required for non-empty BOMs | Inventory of dependencies |
dependencies[] | recommended | Dependency-graph edges via bom-ref |
services[] | optional | Hosted services (SaaS BOM) |
vulnerabilities[] | optional | Per-finding records |
formulation[] | optional | Build metadata |
Component types and per-language native generators are cataloged in
references/component-types-and-tooling.md;
the purl (Package URL) field is the canonical component identifier.
Step 3 - Vulnerability block (VEX-equivalent)
CycloneDX has first-class vuln support (unlike SPDX which delegates
to companion files):
"vulnerabilities": [
{
"id": "CVE-2024-1234",
"source": {"name": "NVD", "url": "https://nvd.nist.gov/vuln/detail/CVE-2024-1234"},
"ratings": [
{"source": {"name": "NVD"}, "severity": "critical", "method": "CVSSv3", "score": 9.8}
],
"cwes": [798],
"description": "Hardcoded credential in lodash sortBy function",
"affects": [{"ref": "pkg:npm/lodash@4.17.20"}],
"analysis": {
"state": "not_affected",
"justification": "code_not_present",
"detail": "Vulnerable function not exported in current build"
}
}
]
The analysis.state field uses VEX-equivalent values:
resolved, resolved_with_pedigree, exploitable,
in_triage, false_positive, not_affected.
Step 4 - Validation
Validate a CycloneDX SBOM against the schema:
# Using cyclonedx-cli
cyclonedx validate --input-file sbom.json --input-version v1_6
# Or via npm
npx @cyclonedx/cyclonedx-bom validate sbom.json
Validation catches structural issues (missing required fields,
invalid PURLs, unknown component types) before publishing. For SPDX
validation (pyspdxtools), see references/spdx.md.
Step 5 - VEX integration
The Step 3 vulnerabilities[] record IS embedded VEX (Vulnerability
Exploitability Exchange, CycloneDX 1.4+). To assert a triaged CVE does
not affect the shipped product, extend that same record - deltas only:
analysis.justification: "vulnerable_code_not_in_execute_path" with a
concrete analysis.detail (e.g. "vulnerable parser only invoked under
--debug; production builds disable it").analysis.response: ["will_not_fix"] - the planned action.
This lets downstream consumers filter the false-positive finding instead
of re-doing reachability analysis.
Step 6 - CI integration
jobs:
cyclonedx:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
# Per-language native (recommended for richer SBOM)
- run: npx @cyclonedx/cyclonedx-npm --output-file=sbom.cyclonedx.json
# OR via Syft (broader source coverage)
- uses: anchore/sbom-action@v0
with:
format: cyclonedx-json
output-file: sbom.cyclonedx.json
# Validate
- run: cyclonedx validate --input-file sbom.cyclonedx.json --input-version v1_6
# Sign + attest
- run: cosign attest --predicate sbom.cyclonedx.json --type cyclonedx my-image:1.0
Worked example
A Node.js service must ship a CycloneDX SBOM to a security-focused
customer. The team:
- Generates the BOM natively:
npx @cyclonedx/cyclonedx-npm --output-file=sbom.cyclonedx.json.
Output is bomFormat: "CycloneDX", specVersion: "1.6", with a
components[] entry per dependency (each carrying a purl) and a
dependencies[] edge list.
- A scan flags
CVE-2024-1234 on pkg:npm/lodash@4.17.20. Triage
shows the vulnerable function is not in the execute path, so the
team adds a vulnerabilities[] record with
analysis.state: "not_affected" and
justification: "vulnerable_code_not_in_execute_path" (Step 3).
- Validates:
cyclonedx validate --input-file sbom.cyclonedx.json --input-version v1_6 - passes.
- Attests to the image:
cosign attest --predicate sbom.cyclonedx.json --type cyclonedx my-image:1.0.
Result: a schema-valid, attested CycloneDX 1.6 BOM whose embedded VEX
lets the customer drop the lodash finding without re-doing
reachability analysis.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
Skip serialNumber field | Can't deduplicate across re-generations | Generate URN UUID per BOM |
Use metadata.tools[] v1.4 schema in 1.6+ | Schema evolution; tools shape changed | Use metadata.tools.components[] (newer schema) |
Skip dependencies[] block | Loss of dep-graph info; downstream tools degrade | Always include (Step 1) |
| Hand-author CycloneDX | Schema is large; errors easy to introduce | Use generators (references) |
| Skip schema validation | Invalid SBOMs pass into prod; downstream consumers fail | Validate in CI (Step 4) |
| Pick format by tooling habit, not consumer | Consumer rejects the delivery | Format-choice table (Choosing a format) |
Limitations
- Both specs are large + evolve; pin schema version per consumer
agreement.
- Per-language tools have varying quality; some are community-maintained
- occasionally lag releases.
- VEX assertions are only as good as the analysis behind them;
unfounded
not_affected claims are worse than no claim.
- ML / SaaS BOM features are newer (CycloneDX 1.5+) and not all tooling
supports them.
- SPDX-specific limitations (weaker vuln support, strict license
expressions, 3.0 tooling maturity) are in
references/spdx.md.
References
- cdx-spec - official CycloneDX specification
- references/spdx.md - SPDX 2.3 + 3.0 format reference
- references/component-types-and-tooling.md - CycloneDX component types + per-language native tooling
- references/spdx3-profiles-and-tooling.md - SPDX 3.0 profiles + tooling landscape
- cyclonedx.org - landing
- github.com/CycloneDX - org with per-language tools
- github.com/package-url/purl-spec - Package URL spec
- openvex.dev - OpenVEX standalone spec (compatible with CycloneDX
1.4+ embedded VEX)
syft-generation,
trivy-image,
vex-author - sister tools