Cdxgen
Creates CycloneDX Bill of Materials (BOM) for your projects from source and container images. Supports many languages and package managers. Integrate in your CI/CD pipeline with automatic submission to Dependency Track server
Install / Use
/learn @cdxgen/CdxgenREADME
CycloneDX Generator (cdxgen)
<img src="./docs/_media/cdxgen.png" width="200" height="auto" />cdxgen is a CLI tool, library, REPL, and server to create a valid and compliant [CycloneDX][cyclonedx-homepage] Bill of Materials (BOM) containing an aggregate of all project dependencies in JSON format. CycloneDX is a full-stack BOM specification that is easily created, human and machine-readable, and simple to parse. The tool supports CycloneDX specification versions from 1.4 - 1.7.
Supported BOM formats:
- Software (SBOM) - For many languages and container images.
- Cryptography (CBOM) - For Java and Python projects.
- Operations (OBOM) - For Linux container images and VMs running Linux or Windows operating systems.
- Software-as-a-Service (SaaSBOM) - For Java, Python, JavaScript, TypeScript, and PHP projects.
- Attestations (CDXA) - Generate SBOM with templates for multiple standards. Sign the BOM document at a granular level to improve authenticity.
- Vulnerability Disclosure Report (VDR) - Use cdxgen with OWASP depscan to automate the generation of VDR at scale.
Why cdxgen?
Most SBOM tools are like simple barcode scanners. For easy applications, they can parse a few package manifests and create a list of components only based on these files without any deep inspection. Further, a typical application might have several repos, components, and libraries with complex build requirements. Traditional techniques to generate an SBOM per language or package manifest either do not work in enterprise environments or don't provide the confidence required for both compliance and automated analysis. So we built cdxgen - the universal polyglot SBOM generator that is user-friendly, precise, and comprehensive!
Our philosophy:
- Explainability: Don't list, but explain with evidence.
- Precision: Try using multiple techniques to improve precision, even if it takes extra time.
- Personas: Cater to the needs of a range of personas such as security researchers, compliance auditors, developers, and SOC.
- Lifecycle: Support BOM generation for various product lifecycles.
- Machine Learning: Optimize the generated data for Machine Learning (ML) purposes by considering the various model properties.
Documentation
Please visit our [GPT app][cdxgen-gpt] or the [documentation site][docs-homepage] for detailed usage, tutorials, and support documentation.
Sections include:
- [Getting Started][docs-homepage]
- [CLI Usage][docs-cli]
- [Server Usage][docs-server]
- [Supported Project Types][docs-project-types]
- [Environment Variables][docs-env-vars]
- [Advanced Usage][docs-advanced-usage]
- [Permissions][docs-permissions]
- [Support (Enterprise & Community)][docs-support]
Usage
Installing
npm install -g @cyclonedx/cdxgen
To run cdxgen without installing (hotloading), use the pnpm dlx command.
corepack pnpm dlx @cyclonedx/cdxgen --help
If you are a [Homebrew][homebrew-homepage] user, you can also install [cdxgen][homebrew-cdxgen] via:
$ brew install cdxgen
If you are a [Winget][winget-homepage] user on windows, you can also install cdxgen via:
winget install cdxgen
Deno and bun runtime can be used with limited support.
deno install --allow-read --allow-env --allow-run --allow-sys=uid,systemMemoryInfo,gid,homedir --allow-write --allow-net -n cdxgen "npm:@cyclonedx/cdxgen/cdxgen"
You can also use the cdxgen container image with node, deno, or bun runtime versions.
The default version uses Node.js 23
docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen:master -r /app -o /app/bom.json
To use the deno version, use ghcr.io/cyclonedx/cdxgen-deno as the image name.
docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen-deno:master -r /app -o /app/bom.json
For the bun version, use ghcr.io/cyclonedx/cdxgen-bun as the image name.
docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen-bun:master -r /app -o /app/bom.json
In deno applications, cdxgen could be directly imported without any conversion. Please see the section on integration as a library
import { createBom, submitBom } from "npm:@cyclonedx/cdxgen@^12.1.0";
Getting Help
cdxgen [command]
Commands:
cdxgen completion Generate bash/zsh completion
Options:
-o, --output Output file. Default bom.json [default: "bom.json"]
-t, --type Project type. Please refer to https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES for supp
orted languages/platforms. [array]
--exclude-type Project types to exclude. Please refer to https://cdxgen.github.io/cdxgen/#/PROJECT_TY
PES for supported languages/platforms.
-r, --recurse Recurse mode suitable for mono-repos. Defaults to true. Pass --no-recurse to disable.
[boolean] [default: true]
-p, --print Print the SBOM as a table with tree. [boolean]
-c, --resolve-class Resolve class names for packages. jars only for now. [boolean]
--deep Perform deep searches for components. Useful while scanning C/C++ apps, live OS and oc
i images. [boolean]
--server-url Dependency track url. Eg: https://deptrack.cyclonedx.io
--skip-dt-tls-check Skip TLS certificate check when calling Dependency-Track. [boolean] [default: false]
--api-key Dependency track api key
--project-group Dependency track project group
--project-name Dependency track project name. Default use the directory name
--project-version Dependency track project version [string] [default: ""]
--project-tag Dependency track project tag. Multiple values allowed. [array]
--project-id Dependency track project id. Either provide the id or the project name and version tog
ether [string]
--parent-project-id Dependency track parent project id [string]
--required-only Include only the packages with required scope on the SBOM. Would set compositions.aggr
egate to incomplete unless --no-auto-compositions is passed. [boolean]
--fail-on-error Fail if any dependency extractor fails. [boolean]
--no-babel Do not use babel to perform usage analysis for JavaScript/TypeScript projects.
[boolean]
--generate-key-and-sign Generate an RSA public/private key pair and then sign the generated SBOM using JSON We
b Signatures. [boolean]
--server Run cdxgen as a server [boolean]
--server-host Listen address [default: "127.0.0.1"]
--server-port Listen port [default: "9090"]
--install-deps Install dependencies automatically for some projects. Defaults to true but disabled fo
r containers and oci scans. Use --no-install-deps to disable this feature.
[boolean] [default: true]
--validate Validate the generated SBOM using json schema. Defaults to true. Pass --no-validate to
disable. [boolean] [default: true]
--evidence Generate SBOM with evidence for supported languages. [boolean] [default: false]
--spec-version CycloneDX Specification version to use. Defaults to 1.6
[number] [choices: 1.4, 1.5, 1.6, 1.7] [default: 1.6]
--filter Filter components containing this word in purl or component.properties.value. Multiple
values allowed. [array]
--only Include components only containing this word in purl. Useful to generate BOM with firs
t party components alone. Multiple values allowed. [array]
--autho
