SBOM
What is CycloneDX?
CycloneDX is an open standard for bills of materials, run by the OWASP Foundation and published by Ecma International as ECMA-424. It is best known as an SBOM format: a machine-readable list of the components in a piece of software, how they depend on each other and what is known about their vulnerabilities. The current version is CycloneDX 1.7, and the same format also describes services, hardware, cryptography and machine learning models.
Updated
CycloneDX at a glance
| Maintained by | The OWASP Foundation's CycloneDX project, with Ecma International Technical Committee 54 (TC54) |
|---|---|
| Standard | ECMA-424. The 1st edition (June 2024) is CycloneDX 1.6; the 2nd edition (December 2025) is CycloneDX 1.7 |
| Current version | CycloneDX 1.7, released October 2025 |
| Encodings | JSON, XML and Protocol Buffers |
| Media type | application/vnd.cyclonedx+json, with a version parameter such as version=1.7 |
| File names | bom.json, bom.xml, *.cdx.json, *.cdx.xml |
The first version, CycloneDX 1.0, came out in 2018 as a security-focused bill of materials. Ecma chartered TC54 for supply chain standards in December 2023, and CycloneDX 1.6 became ECMA-424 in June 2024. The specification overview and the ECMA-424 page are the primary references.
What a CycloneDX SBOM contains
A CycloneDX document is one object, usually called a BOM. Only two fields are required, bomFormat (always
"CycloneDX") and specVersion. Everything else is optional, which is why two valid CycloneDX
files can differ so much in what they actually tell you.
| Element | What it holds |
|---|---|
metadata |
When and how the BOM was made: timestamp, tools, authors, the lifecycle phase, and the component the BOM describes |
components |
Each library, framework, container, file, firmware, device or model, with its version, identifiers, hashes and licenses |
services |
External services the software calls, such as APIs, with their endpoints and data flows |
dependencies |
Which component or service depends on which, so the tree can be rebuilt, transitive levels included |
compositions |
How complete each part of the BOM is: complete, incomplete, unknown or not specified |
vulnerabilities |
Known vulnerabilities, their ratings and, for VEX, whether and how they affect the product |
formulation |
How the product was built: the workflows, tasks and environment behind it |
annotations |
Comments and notes attached to other parts of the BOM, with who made them and when |
declarations, definitions, citations |
Attestations of conformance to standards, the standards themselves, and where data in the BOM came from |
The metadata.lifecycles field says when the BOM was made: design, pre-build, build, post-build,
operations, discovery or decommission. A build-phase SBOM and a post-build scan of the same product can list different
components, so the phase matters when you compare two files.
CycloneDX BOM types
The same object model covers more than software. The CycloneDX project lists these capabilities:
| Type | Describes |
|---|---|
| SBOM | Software components and their dependencies |
| SaaSBOM | Services, endpoints and data flows of a hosted application |
| HBOM | Hardware components |
| CBOM | Cryptographic assets: algorithms, keys, certificates and protocols |
| ML-BOM | Machine learning models and the datasets behind them |
| OBOM and MBOM | Operational environments, and the manufacturing of a product |
| VEX, VDR and BOV | Whether a vulnerability affects a product (VEX), a vendor's report of known vulnerabilities (VDR), and a bill of vulnerabilities |
| CDXA | Attestations that a product meets a standard or requirement |
These are uses of one format, not separate formats. A VEX document, for example, is a CycloneDX BOM whose
vulnerabilities entries carry an analysis state and point at components in an SBOM.
Identifiers: purl, CPE and hashes
A component's name is not enough to match it to a vulnerability, because the same name can mean different packages in
different ecosystems. CycloneDX components carry identifiers for that: a
package URL (purl) such as pkg:npm/[email protected], a CPE, a SWID tag,
OmniBOR and SWHID identifiers, and cryptographic hashes. Purl is the one most tools match on for open source packages,
and it became its own Ecma standard, ECMA-427, in December 2025. Inside the document, each element can also have a
bom-ref, a local ID that the dependencies, compositions and vulnerabilities sections use to point at it.
A CycloneDX JSON example
A small but complete SBOM for an application, acme-api, that uses one npm package, debug,
which in turn depends on ms. It validates against the CycloneDX 1.7 JSON schema.
{
"bomFormat": "CycloneDX",
"specVersion": "1.7",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"metadata": {
"timestamp": "2026-11-16T09:30:00Z",
"lifecycles": [{ "phase": "build" }],
"component": {
"type": "application",
"bom-ref": "acme-api",
"name": "acme-api",
"version": "1.4.0"
}
},
"components": [
{
"type": "library",
"bom-ref": "pkg:npm/[email protected]",
"name": "debug",
"version": "4.4.0",
"purl": "pkg:npm/[email protected]",
"licenses": [{ "license": { "id": "MIT" } }]
},
{
"type": "library",
"bom-ref": "pkg:npm/[email protected]",
"name": "ms",
"version": "2.1.3",
"purl": "pkg:npm/[email protected]",
"licenses": [{ "license": { "id": "MIT" } }]
}
],
"dependencies": [
{ "ref": "acme-api", "dependsOn": ["pkg:npm/[email protected]"] },
{ "ref": "pkg:npm/[email protected]", "dependsOn": ["pkg:npm/[email protected]"] },
{ "ref": "pkg:npm/[email protected]", "dependsOn": [] }
],
"compositions": [
{ "aggregate": "complete", "dependencies": ["acme-api"] }
]
}
-
serialNumberandversionidentify this BOM. Every newly generated BOM gets a new serial number; when an existing BOM is modified, it keeps the serial number and its version goes up by one. -
metadata.componentis the product the SBOM describes, and the root of the dependency tree. -
dependenciesmakesmsa transitive dependency: the application never asked for it,debugdid. An emptydependsOnsays the component has no dependencies. Leaving a component out of the graph means its dependencies are unknown, not that it has none. -
compositionsstates that the dependency tree underacme-apiis complete. A tool that could not see everything should sayincompleteorunknowninstead, so a reader knows not to treat a missing package as absent.
For a larger file with hashes, suppliers and a matching SPDX version of the same application, see SBOM examples.
How to generate a CycloneDX SBOM
There are three ways to produce one, and they describe different things.
| Method | How it works | What it misses |
|---|---|---|
| Manifest and lockfile scanning | Reads package-lock.json, requirements.txt, pom.xml and similar files |
Anything fetched outside the package manager, such as install scripts, build scripts and base images |
| Image, file system or binary analysis | Inspects a finished container image, directory or binary for package metadata and signatures | Components with no metadata left behind, and compiled code it has to guess at |
| Build-time recording | Records what the build actually fetched while it runs | Only what the recorder cannot see, which a good one states as incomplete |
Free tools that write CycloneDX:
-
cdxgen, an OWASP project, for many languages and container images:
cdxgen -o bom.json. It writes CycloneDX 1.7 by default. -
The CycloneDX ecosystem plugins, such as
@cyclonedx/cyclonedx-npm, cyclonedx-python, the CycloneDX Maven plugin and cyclonedx-gomod, each for one package manager:npx @cyclonedx/cyclonedx-npm --output-file bom.json. -
Syft, from Anchore, for container images and file systems:
syft <image> -o cyclonedx-json.
The CycloneDX Tool Center lists many more. For how these approaches compare in practice, see open source SBOM generators and Docker image SBOMs.
How to validate a CycloneDX file
The official CycloneDX CLI checks a file against the schema of its version:
cyclonedx validate --input-file bom.json --input-version v1_7 --fail-on-errors
The same tool converts between JSON, XML and Protocol Buffers, between spec versions, and to SPDX JSON, with
cyclonedx convert. Schema validation only proves the file is well formed. It cannot tell you whether a
component is missing. For that, check the content against a list such as the
SBOM quality checklist.
CycloneDX vs SPDX
SPDX is the other widely used SBOM format, hosted by the Linux Foundation and published as ISO/IEC 5962:2021. It grew out of license compliance, while CycloneDX started from security, which is why CycloneDX carries vulnerabilities and VEX in the same format. Both describe components, identifiers, licenses and relationships, tools convert between them, and the EU Cyber Resilience Act names neither. Which one you produce usually depends on what your customers and tools read. The full comparison is in CycloneDX vs SPDX.
How CRACI produces CycloneDX SBOMs
CRACI is a GitHub Actions runner that records every package each job fetches while it runs, at every depth of the dependency tree and including packages restored from CI caches. So every component in the SBOM was actually in the build. Each package carries its purl and declared license, and each job's SBOM has a completeness state that says what the job could not see. The SBOM exports as CycloneDX or SPDX, with the transitive dependencies and the vulnerabilities found in its components, and the API returns it as CycloneDX 1.7 JSON. See build-time SBOM generation or SBOM best practices.
When CRACI is not the answer
- Hardware, cryptography or service BOMs. CRACI records software packages a build fetches. An HBOM, CBOM or SaaSBOM needs other sources.
- Builds outside GitHub Actions. GitHub Actions is the only supported CI today; other CI systems are on the roadmap. Use a generator such as cdxgen in the meantime.
- Software you receive as a binary. If you did not build it, you cannot record its build. Ask the supplier for an SBOM, or use binary analysis.
CycloneDX: frequently asked questions
What is CycloneDX used for?
Mostly for SBOMs: listing the components in a piece of software so you can track vulnerabilities and licenses and share the list with customers. The same format also covers VEX, services, hardware, cryptography and machine learning models.
Who maintains CycloneDX?
The OWASP Foundation runs the CycloneDX project, and Ecma International's Technical Committee 54 publishes it as the ECMA-424 standard.
What is the latest version of CycloneDX?
CycloneDX 1.7, released in October 2025. It is also the 2nd edition of ECMA-424, published in December 2025. The 1st edition corresponds to CycloneDX 1.6.
Is CycloneDX JSON or XML?
Both, and Protocol Buffers too. JSON is the most common, with the media type application/vnd.cyclonedx+json and file names such as bom.json or name.cdx.json.
Is CycloneDX better than SPDX?
Neither is better in general. CycloneDX started from security and carries vulnerabilities and VEX natively, SPDX from license compliance and is an ISO standard. Produce what your customers and tools read; converters exist in both directions.
How do I check that a CycloneDX file is valid?
Run the official CycloneDX CLI: cyclonedx validate --input-file bom.json --fail-on-errors. It checks the structure against the schema, not whether any component is missing.
CycloneDX from the build itself
Record every package your GitHub Actions jobs fetch, with a completeness state, and export it as CycloneDX or SPDX.
Book a demo