![](\"./docs/_media/cdxgen.png\")
\n\ncdxgen is a CLI tool, library, [REPL](./ADVANCED.md), 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 supports CycloneDX specification versions from 1.5 - 1.7.\n\nSupported BOM formats:\n\n- Hardware (HBOM) - For supported live hosts such as Apple Silicon macOS and Linux amd64/arm64 systems.\n- Software (SBOM) - For many languages and container images.\n- Cryptography (CBOM) - For Java keystores and certificates, plus JavaScript and TypeScript source-level algorithm inventory.\n- Operations (OBOM) - For Linux container images and VMs running Linux or Windows operating systems.\n- Software-as-a-Service (SaaSBOM) - For Java, Python, JavaScript, TypeScript, and PHP projects.\n- AI/ML (AI-BOM) - For prompt files, AI services, MCP configs, and model metadata with explainable AI-governance, security, performance, and agentic findings.\n- Attestations (CDXA) - Generate SBOM with templates for multiple standards. Sign the BOM document at a granular level to improve authenticity.\n- Vulnerability Disclosure Report (VDR) - Use cdxgen with [OWASP depscan](https://github.com/owasp-dep-scan/dep-scan) to automate the generation of VDR at scale.\n\nSupported output document formats:\n\n- CycloneDX JSON (primary native format)\n- SPDX 3.0.1 JSON-LD (`cdxgen --format spdx` or `cdx-convert`)\n\n## Choose your path\n\n| Persona | What cdxgen helps you do | First command | Read next |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |\n| **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] |\n| **AI platform teams** | Generate AI/ML BOMs, catalog prompt/model/MCP surfaces, and run AI-BOM governance | `aibom .` | [AI-BOM Guide](docs/AI_BOM.md), [AI-BOM lesson](docs/LESSON15.md) |\n| **Hardware teams** | Generate an HBOM or merged HBOM+OBOM host view for the current host | `hbom -o hbom.json` | [HBOM guide](docs/HBOM.md), [HBOM lesson](docs/LESSON13.md) |\n| **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](docs/BOM_AUDIT.md), [Threat Model](docs/THREAT_MODEL.md) |\n| **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](docs/OBOM_LESSONS.md), [Server Usage][docs-server] |\n| **Compliance teams** | Validate BOM quality, check SCVS/CRA posture, and export SPDX deliverables | `cdx-validate -i bom.json --benchmark scvs-l2,cra` | [cdx-validate](docs/CDX_VALIDATE.md), [cdx-convert](docs/CDX_CONVERT.md), [Permissions][docs-permissions] |\n| **Security Teams** | Dynamically trace executions to capture cryptographic activities, CBOM properties, software components, and services | `tracebom --cbom-output cbom.json -- npm test` | [Threat Model](docs/THREAT_MODEL.md) |\n\n### Role-based quick starts\n\n#### For developers\n\n- Start with a local path, git URL, or purl and generate a BOM in one command.\n- Use [Supported Project Types][docs-project-types] to confirm ecosystem coverage before wiring cdxgen into CI.\n\n#### For hardware and platform teams\n\n- Use `hbom` when you need a CycloneDX hardware inventory for the current host rather than a software dependency graph.\n- Start with the [HBOM guide](docs/HBOM.md) and the [HBOM lesson](docs/LESSON13.md) for supported platforms, enrichment options, and validation workflows.\n- 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.\n- 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`.\n- 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.\n\n#### For AppSec\n\n- Use `--profile appsec`, `--evidence`, and `--bom-audit` when you want richer security context.\n- Combine generation with [BOM Audit](docs/BOM_AUDIT.md), [cdx-validate](docs/CDX_VALIDATE.md), signing, and verification for a fuller secure-SBOM workflow.\n- 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.\n\n#### For AI platform and governance teams\n\n- 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.\n- Use `aibom` when you want the same defaults in one dedicated CLI, including direct Hugging Face purls/URLs and direct Modelfile / `.gguf` inputs.\n- Start with the [AI-BOM Guide](docs/AI_BOM.md) and the [AI-BOM lesson](docs/LESSON15.md) for the preferred alias, review flow, and category breakdown.\n\n#### For SOC analysts\n\n- Use `obom` for live-system and runtime inventory on Linux, Windows, and macOS hosts.\n- Focus on [OBOM lessons](docs/OBOM_LESSONS.md) when you need host triage, persistence review, Linux GTFOBins-backed runtime analysis, hardening drift review, or incident-response evidence.\n\n#### For compliance and platform governance\n\n- Use `cdx-validate` to assess structural and compliance posture, then `cdx-convert` when SPDX output is required.\n- Review [Permissions][docs-permissions] and hardened-environment guidance before adopting cdxgen in controlled pipelines.\n\n## Why cdxgen?\n\nMost 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!\n\n**Our philosophy:**\n\n- _Explainability:_ Don't list, but explain with evidence.\n- _Precision:_ Try using multiple techniques to improve precision, even if it takes extra time.\n- _Personas:_ Cater to the needs of a range of personas such as security researchers, compliance auditors, developers, and SOC.\n- _Machine Learning:_ Optimize the generated data for Machine Learning (ML) purposes by considering the various model properties.\n- _Safety:_ Execute external build tools and handle untrusted inputs defensively, with hardened defaults, a [secure mode](docs/PERMISSIONS.md) for sensitive environments, and a read-only `--dry-run` mode for review-first workflows.\n\n## Documentation\n\nPlease visit our [documentation site][docs-homepage] for detailed usage, tutorials, and support documentation.\n\nSections include:\n\n- [Getting Started][docs-homepage]\n- [CLI Usage][docs-cli]\n- [HBOM Guide](docs/HBOM.md)\n- [Merged Host View Lesson](docs/LESSON13.md)\n- [Server Usage][docs-server]\n- [Hands-on Lessons](docs/LESSON8.md)\n- [Container Escape & Privilege Lesson](docs/LESSON9.md)\n- [HBOM Lesson](docs/LESSON13.md)\n- [Supported Project Types][docs-project-types]\n- [Environment Variables][docs-env-vars]\n- [Advanced Usage][docs-advanced-usage]\n- [Permissions][docs-permissions]\n- [Security Policy](SECURITY.md)\n- [Threat Model](docs/THREAT_MODEL.md)\n- [Support (Enterprise & Community)][docs-support]\n\n## Usage\n\n## Installing\n\nInstall the npm package without the optional binary plugins for basic SBOM generation.\n\n**npm**:\n\n```shell\nnpm install -g @cyclonedx/cdxgen --omit=optional --ignore-scripts --min-release-age=2\n```\n\nFor a full and rich experience with support for multiple BOM types, remove `--omit=optional`.\n\n```shell\nnpm install -g @cyclonedx/cdxgen --ignore-scripts --min-release-age=2\n```\n\n**pnpm**:\n\n```shell\npnpm add -g @cyclonedx/cdxgen --omit=optional --ignore-scripts --minimum-release-age=2880\n```\n\n**bun**:\n\n```shell\nbun install -g @cyclonedx/cdxgen --ignore-scripts\n```\n\nInstalling `@cyclonedx/cdxgen` exposes these commands:\n\n| Command | Purpose | Standalone GitHub release binary |\n| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- |\n| `cdxgen` | Generate CycloneDX / SPDX BOMs from source, images, binaries, git URLs, or purls | yes |\n| `aibom` | Generate CycloneDX AI/ML BOMs from source, Hugging Face URLs/purls, Modelfiles, or GGUF artifacts (`-t ai` defaults) | yes |\n| `hbom` | Generate a CycloneDX hardware BOM for the current host | yes (`hbom`, `hbom-slim`) |\n| `tracebom` | Trace command execution to capture dynamic CBOM, cryptographic properties, software components, and services | yes |\n| `cdx-audit` | Prioritize existing BOM dependencies for upstream supply-chain review using explainable risk signals | yes |\n| `cdx-convert` | Convert CycloneDX JSON to SPDX 3.0.1 JSON-LD | yes |\n| `cdx-sign` | Sign BOMs with JSF signatures | yes |\n| `cdx-validate` | Validate BOMs and benchmark posture | yes |\n| `cdx-verify` | Verify BOM signatures | yes |\n| `cdxi` | Open the interactive REPL | no |\n| `evinse` | Add evidence, reachability, and service context | no |\n| `cbom` | Alias for CBOM-oriented `cdxgen` defaults | yes |\n| `obom` | Alias for `cdxgen -t os` | yes |\n| `saasbom` | Alias for SaaSBOM-oriented `cdxgen` defaults | yes |\n| `spdxgen` | Alias for `cdxgen --format spdx` | use `cdxgen` |\n| `cdxgen-secure` | Alias for hardened `cdxgen` defaults | use `cdxgen` |\n\nStandalone GitHub release binaries are published for `cdxgen`, `cdxgen-slim`, `aibom`, `cbom`, `obom`, `saasbom`, `hbom`, `hbom-slim`, `cdx-audit`, `cdx-convert`, `cdx-sign`, `cdx-validate`, `cdx-verify`, and `tracebom`.\n\n`hbom` release binaries bundle both `@cdxgen/cdx-hbom` and the matching `@cdxgen/cdxgen-plugins-bin*` companion helpers for the target platform. `hbom-slim` keeps the dedicated hardware collector (`@cdxgen/cdx-hbom`) but omits the companion plugin bundle when you want the smallest single-file HBOM executable.\n\nThe `cbom` and `saasbom` release binaries bundle the Atom analysis stack (`@appthreat/atom` and `@appthreat/atom-parsetools`) plus protobuf export support (`@cdxgen/cdx-proto` and `@bufbuild/protobuf`). The `obom` release binary bundles the matching platform plugin package, pruned to runtime OS inventory helpers, plus the same protobuf export support. These aliases therefore support `--export-proto --proto-bin-file \n ![](\"./docs/_media/GithubLogo-LightBg.png\")
\n ![](\"./docs/_media/MicrosoftLogo.png\")
\n
\n\nSome features are funded through [NGI Zero Core](https://nlnet.nl/core), a fund established by [NLnet](https://nlnet.nl) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu) program. Learn more at the [NLnet project page](https://nlnet.nl/project/OWASP-dep-scan).\n\n[\n \n![\"NLnet](\"https://nlnet.nl/logo/banner.png\"){kind=logo}
](https://nlnet.nl)\n[![\"NGI](\"https://nlnet.nl/image/logos/NGI0_tag.svg\")
](https://nlnet.nl/core)\n\ncdxgen is an OWASP Foundation production project.\n\n[![](\"https://owasp.org/assets/images/logo.png\"){kind=logo}
](https://owasp.org)\n\n## cdxgen badge\n\nCopy the below block to your markdown files to show your ❤️ for cdxgen.\n\n```markdown\n[](https://github.com/cdxgen/cdxgen)\n```\n\n\n\n\n[badge-github-contributors]: https://img.shields.io/github/contributors/cyclonedx/cdxgen\n[badge-github-license]: https://img.shields.io/github/license/cyclonedx/cdxgen\n[badge-github-releases]: https://img.shields.io/github/v/release/cyclonedx/cdxgen\n[badge-jsr]: https://img.shields.io/jsr/v/%40cyclonedx/cdxgen\n[badge-npm]: https://img.shields.io/npm/v/%40cyclonedx%2Fcdxgen\n[badge-npm-downloads]: https://img.shields.io/npm/dy/%40cyclonedx%2Fcdxgen\n[badge-swh]: https://archive.softwareheritage.org/badge/origin/https://github.com/cdxgen/cdxgen/\n\n\n\n[github-contribute]: https://github.com/cdxgen/cdxgen/contribute\n[github-contributors]: https://github.com/cdxgen/cdxgen/graphs/contributors\n[github-issues]: https://github.com/cdxgen/cdxgen/issues\n[github-license]: https://github.com/cdxgen/cdxgen/blob/master/LICENSE\n[github-releases]: https://github.com/cdxgen/cdxgen/releases\n\n\n\n[docs-homepage]: https://cdxgen.github.io/cdxgen\n[docs-advanced-usage]: https://cdxgen.github.io/cdxgen/#/ADVANCED\n[docs-cli]: https://cdxgen.github.io/cdxgen/#/CLI\n[docs-env-vars]: https://cdxgen.github.io/cdxgen/#/ENV\n[docs-permissions]: https://cdxgen.github.io/cdxgen/#/PERMISSIONS\n[docs-project-types]: https://cdxgen.github.io/cdxgen/#/PROJECT_TYPES\n[docs-server]: https://cdxgen.github.io/cdxgen/#/SERVER\n[docs-support]: https://cdxgen.github.io/cdxgen/#/SUPPORT\n\n\n\n[appthreat-homepage]: https://www.appthreat.com\n[cyclonedx-homepage]: https://cyclonedx.org\n[cyclonedx-cli-github]: https://github.com/CycloneDX/cyclonedx-cli\n[depscan-github]: https://github.com/cyclonedx/dep-scan\n[github-rate-limit]: https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api#primary-rate-limit-for-github_token-in-github-actions\n[homebrew-homepage]: https://brew.sh\n[homebrew-cdxgen]: https://formulae.brew.sh/formula/cdxgen\n[winget-homepage]: https://learn.microsoft.com/en-us/windows/package-manager/winget/\n[jsr-cdxgen]: https://jsr.io/@cyclonedx/cdxgen\n[jwt-homepage]: https://jwt.io\n[jwt-libraries]: https://jwt.io/libraries\n[librariesio]: https://libraries.io/npm/@cyclonedx%2Fcdxgen\n[npmjs-cdxgen]: https://www.npmjs.com/package/@cyclonedx/cdxgen\n[podman-github-rootless]: https://github.com/containers/podman/blob/master/docs/tutorials/rootless_tutorial.md\n[podman-github-remote]: https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md\n[swh-cdxgen]: https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/cdxgen/cdxgen\n[cdxgen-gpt]: https://chatgpt.com/g/g-673bfeb4037481919be8a2cd1bf868d2-cyclonedx-generator-cdxgen\n","readmeFilename":"README.md"}