cdxgen

[![JSR][badge-jsr]][jsr-cdxgen] [![NPM][badge-npm]][npmjs-cdxgen] [![GitHub Releases][badge-github-releases]][github-releases] [![NPM Downloads][badge-npm-downloads]][npmjs-cdxgen] [![GitHub License][badge-github-license]][github-license] [![GitHub Contributors][badge-github-contributors]][github-contributors] [![SWH][badge-swh]][swh-cdxgen]

CycloneDX Generator (cdxgen)

cdxgen is a CLI tool, library, REPL, and server to create, validate, sign, and verify software BOMs. It generates CycloneDX JSON BOMs and supports SPDX 3.0.1 JSON-LD export. CycloneDX is a full-stack BOM specification that is easily created, human and machine-readable, and simple to parse. The tool generates BOMs targeting CycloneDX specification versions 1.6, 1.7, and 2.0, and the output can be downgraded to 1.4 or 1.5 for legacy consumers.

Supported BOM formats:

• Hardware (HBOM) - For supported live hosts such as Apple Silicon macOS and Linux amd64/arm64 systems.
• Software (SBOM) - For many languages and container images.
• Cryptography (CBOM) - For Java keystores and certificates, plus JavaScript and TypeScript source-level algorithm inventory.
• 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.
• AI/ML (AI-BOM) - For prompt files, AI services, MCP configs, and model metadata with explainable AI-governance, security, performance, and agentic findings.
• 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.

Supported output document formats:

• CycloneDX JSON (primary native format)
• SPDX 3.0.1 JSON-LD (cdxgen --format spdx or cdx-convert)

Choose your path

Persona	What cdxgen helps you do	First command	Read next
Developers	Generate a CycloneDX BOM from a local repo, git URL, purl, or container image	cdxgen -o bom.json .	[CLI Usage][docs-cli], [Supported Project Types][docs-project-types]
AI platform teams	Generate AI/ML BOMs, catalog prompt/model/MCP surfaces, and run AI-BOM governance	aibom .	AI-BOM Guide, AI-BOM lesson
Hardware teams	Generate an HBOM or merged HBOM+OBOM host view for the current host	hbom -o hbom.json	HBOM guide, HBOM lesson
AppSec	Enrich BOMs with evidence, run BOM audit rules, and feed downstream security workflows	cdxgen -o bom.json --profile appsec --evidence --bom-audit .	BOM Audit, Threat Model
Build engineers	Grade how completely the SBOM captured the project, and get ranked fixes when the build environment degraded it	cdxgen --profile introspect --introspect-fail-below 70 -o bom.json .	Build Introspection, Fidelity loop skill
SOC analysts	Build OBOM inventories for live hosts and triage runtime posture issues	obom -o obom.json --deep --bom-audit --bom-audit-categories obom-runtime	OBOM lessons, [Server Usage][docs-server]
Compliance teams	Validate BOM quality, check SCVS/CRA posture, and export SPDX deliverables	cdx-validate -i bom.json --benchmark scvs-l2,cra	cdx-validate, cdx-convert, [Permissions][docs-permissions]
Security Teams	Dynamically trace executions to capture cryptographic activities, CBOM properties, software components, and services	tracebom --cmd "npm test" --trace-crypto -o cbom.json	Threat Model

Role-based quick starts

For developers

• Start with a local path, git URL, or purl and generate a BOM in one command.
• Use [Supported Project Types][docs-project-types] to confirm ecosystem coverage before wiring cdxgen into CI.

For hardware and platform teams

• Use hbom when you need a CycloneDX hardware inventory for the current host rather than a software dependency graph.
• Start with the HBOM guide and the HBOM lesson for supported platforms, enrichment options, and validation workflows.
• Use hbom --dry-run first when you want a read-only partial HBOM plus an exact list of blocked hardware probe commands before a full collection run.
• Use hbom diagnostics when you want a focused summary of missing native utilities and permission-denied enrichments before deciding whether to install host packages or rerun with --privileged.
• Use hbom --include-runtime when you want one topology-aware CycloneDX host document that merges hardware inventory with runtime evidence using strict, non-guessing joins.

For AppSec

• Use --profile appsec, --evidence, and --bom-audit when you want richer security context.
• Combine generation with BOM Audit, cdx-validate, signing, and verification for a fuller secure-SBOM workflow.
• Use tracebom to dynamically profile applications & services and capture negotiated TLS cipher suites, protocols, cryptographic libraries, dynamically resolved software components, and services in CycloneDX 1.7 format.

For AI platform and governance teams

• Use --include-formulation plus --bom-audit --bom-audit-categories ai-bom when you want one AI-BOM workflow for prompt files, AI services, MCP configs, and model metadata.
• Use aibom when you want the same defaults in one dedicated CLI, including direct Hugging Face purls/URLs and direct Modelfile / .gguf inputs.
• Start with the AI-BOM Guide and the AI-BOM lesson for the preferred alias, review flow, and category breakdown.

For SOC analysts

• Use obom for live-system and runtime inventory on Linux, Windows, and macOS hosts.
• Focus on OBOM lessons when you need host triage, persistence review, Linux GTFOBins-backed runtime analysis, hardening drift review, or incident-response evidence.

For compliance and platform governance

• Use cdx-validate to assess structural and compliance posture, then cdx-convert when SPDX output is required.
• Review [Permissions][docs-permissions] and hardened-environment guidance before adopting cdxgen in controlled pipelines.

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.
• Machine Learning: Optimize the generated data for Machine Learning (ML) purposes by considering the various model properties.
• Safety: Execute external build tools and handle untrusted inputs defensively, with hardened defaults, a secure mode for sensitive environments, and a read-only --dry-run mode for review-first workflows.

Documentation

Please visit our [documentation site][docs-homepage] for detailed usage, tutorials, and support documentation.

Sections include:

• [Getting Started][docs-homepage]
• [CLI Usage][docs-cli]
• Migration to v13
• HBOM Guide
• Merged Host View Lesson
• [Server Usage][docs-server]
• Hands-on Lessons
• Container Escape & Privilege Lesson
• HBOM Lesson
• [Supported Project Types][docs-project-types]
• [Environment Variables][docs-env-vars]
• [Advanced Usage][docs-advanced-usage]
• [Permissions][docs-permissions]
• cdx-audit Guide
• cdx-convert Guide
• cdx-validate Guide
• cdx-verify Guide
• cdx-sign Guide
• Tracebom Guide
• AI-BOM Guide
• MCP Inventory
• REPL Guide
• Custom Properties
• Claude Code Plugin
• Deprecations
• Security Policy
• Threat Model
• [Support (Enterprise & Community)][docs-support]

Usage

Installing

[!IMPORTANT] The npm package was renamed in v13. v13 and later are published as [@cdxgen/cdxgen][npmjs-cdxgen]. v12 and earlier are published as [@cyclonedx/cdxgen][npmjs-cdxgen-v12], which stays on npm and continues to receive fixes on the release/12.0.x branch, but does not receive v13 features.

Upgrading means changing the package name, not just the version:

npm uninstall -g @cyclonedx/cdxgen
npm install -g @cdxgen/cdxgen --ignore-scripts --min-release-age=2

The cdxgen command, the CLI flags, and the container images are unchanged. If you import cdxgen as a library, update the specifier: import { createBom } from "@cdxgen/cdxgen".

cdxgen is distributed three ways. The standalone executables and container images are the recommended choice for CI, production, and any environment where you want a self-contained tool with no Node.js dependency. The npm package is an alternative when you already manage JavaScript tooling or need cdxgen as a