Advanced Usage

May 28, 2026 · View on GitHub

Include pattern

cdxgen uses the default set of glob patterns to locate language-specific package manifests and lock files. To customise these patterns, use the argument --include-regex.

Example:

Parse only the pyproject.toml files present in directories ending with google.

--include-regex "**/*google/pyproject.toml"

Parse only the requirements.txt files present in directories ending with nvidia.

--include-regex "**/*nvidia/requirements.txt"

Combine this with --exclude, --exclude-type, and other filters to customise the exact set of manifests and lock files used for the generated BOM.

Exclude project types, files, and directories

To exclude specific project types from the BOM, use the --exclude-type argument. Multiple values are allowed.

Example:

Generate an SBOM for all types except js

--exclude-type js

Generate an SBOM for all types except github and dotnet

--exclude-type github --exclude-type dotnet

Generate a JavaScript SBOM but drop shipped AI skill files and MCP config artifacts:

cdxgen -t js --exclude-type ai-skill --exclude-type mcp

Use the argument --exclude to provide a glob pattern for files and directories to exclude from the BOM. Multiple values are allowed.

Example:

Exclude quickstarts directory.

--exclude "**/quickstarts/**"

Brace expansion is supported. {openshift,kubernetes}-maven-plugin in the below example, expands to openshift-maven-plugin and kubernetes-maven-plugin.

--exclude "**/quickstarts/**" --exclude "**/{openshift,kubernetes}-maven-plugin/**"

Excluding packages using package manager configuration

Some package managers support filtering dependencies. For example, maven dependency:tree command supports filtering. It is possible to use some of the existing environment variables to utilize these features.

Java maven example:

export MVN_ARGS="-Dexcludes=:::*-SNAPSHOT"

Gradle example:

export GRADLE_ARGS="--configuration runtimeClasspath"

Filtering components

cdxgen can filter the components and the dependency tree before writing to a BOM json file. Three kinds of filters are allowed:

Required only filter

Pass --required-only to only store components with the scope attribute set to required. These are usually considered direct dependencies.

cdxgen -t java -o /tmp/bom.json -p --required-only

Languages supported:

  • Java with Maven
  • Node.js
  • Go
  • Php

Purl and properties filter

Use --filter to filter components containing the string in the purl or components.properties.value. Since the purl string includes the namespace (group), you can use this argument as a namespace filter too. Filters are case-insensitive.

Example 1: Filter all "springframework" packages (purl or namespace)

cdxgen -t java -o /tmp/bom.json -p --filter org.springframework

Example 2: Filter components belonging to the gradle profile "debugAndroidTestCompileClasspath" or "debugRuntimeClasspath"

cdxgen -t gradle -o /tmp/bom.json -p --filter debugAndroidTestCompileClasspath --filter debugRuntimeClasspath

Include only filter

Use --only to include only those components containing the string in the purl. This can be used to generate BOM with "first party" components only.

cdxgen -t java -o /tmp/bom.json -p --only org.springframework

Minimum confidence filter

Use --min-confidence with a value between 0 and 1 to filter components based on the confidence of their purl identify. The logic involves looking for field=purl in evidence.identity and collecting the maximum confidence value. This is then compared against the minimum confidence passed as an argument.

cdxgen -t c . --min-confidence 0.1

The above would filter out all the zero confidence components in c/c++, so use it with caution.

Analysis technique filter

Use --technique to list the techniques that cdxgen is allowed to use for the xBOM generation. Leaving this argument or using the value auto enables default behaviour.

Example 1 - only allow manifest-analysis:

cdxgen -t c . --technique manifest-analysis

Example 2 - allow manifest-analysis and source-code-analysis:

cdxgen -t c . --technique manifest-analysis --technique source-code-analysis

List of supported techniques:

  • auto (default)
  • source-code-analysis
  • binary-analysis
  • manifest-analysis
  • hash-comparison
  • instrumentation
  • filename

Currently, this capability is implemented as a filter during post-processing, so unlikely to yield any performance benefits.

Component type filter

Use --component-type to include only selected CycloneDX component types in the generated BOM. The option is repeatable and is validated against the selected --spec-version before scanning starts. Leaving this argument unset preserves the default behaviour.

This option is a filter, not an inventory enabler. It cannot make cdxgen generate component classes that are not implemented for the selected project type. For example, passing --component-type machine-learning-model does not enable machine-learning model discovery; if the scan would not otherwise produce machine-learning model components, filtering to that type can result in an empty component list.

Example - include only libraries and frameworks:

cdxgen -t docker alpine:3.20 --component-type library --component-type framework

The accepted values depend on the CycloneDX spec version:

  • 1.4: application, framework, library, container, operating-system, device, firmware, file
  • 1.5: all 1.4 values plus platform, device-driver, machine-learning-model, data
  • 1.6, 1.7, and 2.0: all 1.5 values plus cryptographic-asset

For example, --spec-version 1.5 --component-type cryptographic-asset is rejected early because CycloneDX 1.5 does not define cryptographic-asset. When older spec versions are requested, cdxgen also removes component types unsupported by that schema during post-processing so generated BOMs remain schema-valid.

The dedicated cbom command does not accept --component-type; use cdxgen --include-crypto instead when you need normal SBOM generation plus component-type filtering.

Go Evinse data-flow and crypto-flow evidence

For Go projects, generate the base SBOM first and then enrich it with evinse -l go. The Go Evinse path uses the optional golem helper from @cdxgen/cdxgen-plugins-bin to attach occurrence evidence, call-stack frames, usage scopes, security signals, crypto components, and data-flow/crypto-flow properties.

Routine semantic evidence:

cdxgen -t go -o bom.json /absolute/path/to/go/project
evinse -i bom.json -o bom.evinse.json -l go --golem-callgraph static /absolute/path/to/go/project

Bounded data-flow and crypto-flow evidence:

evinse -i bom.json -o bom.evinse.json -l go \
  --with-data-flow \
  --golem-dataflow crypto \
  --golem-dataflow-pattern-packs crypto \
  /absolute/path/to/go/project

--deep enables the same Golem data-flow collection with performance safeguards. cdxgen caps worker count and GOMAXPROCS, applies slice and trace limits, skips generated files by default, and skips tests unless --golem-tests is supplied. Use --golem-memory-limit 4GiB, narrower --golem-patterns, or --golem-dataflow crypto when a large repository needs predictable CI runtime.

The enriched BOM uses cdx:golem:* properties. High-value pivots include cdx:golem:dataFlowMode, cdx:golem:dataFlowSliceCount, cdx:golem:cryptoDataFlow, cdx:golem:cryptoDataFlowCount, cdx:golem:cryptoAlgorithms, cdx:golem:usageScopes, cdx:golem:securitySignalSeverity, cdx:golem:localReplacement, and cdx:golem:vendored. Rendered crypto components are type: "cryptographic-asset" and intentionally do not have purls.

After enrichment, run the focused audit and inspect interactively:

cdx-audit --bom bom.evinse.json --direct-bom-audit --categories golem
cdxi bom.evinse.json

Automatic compositions

When using any filters, cdxgen would automatically set the compositions.aggregate property to "incomplete" or "incomplete_first_party_only".

To disable this behavior, pass --no-auto-compositions.

Purl source resolution

cdxgen can accept a package URL (pkg:*) as the input path and automatically resolve it to a cloneable repository URL.

Supported purl types for automatic git URL detection:

  • pkg:npm/... (registry metadata lookup)
  • pkg:pypi/... (registry metadata lookup)
  • pkg:gem/... (registry metadata lookup)
  • pkg:cargo/... (registry metadata lookup)
  • pkg:pub/... (registry metadata lookup)
  • pkg:github/... (direct repository mapping)
  • pkg:bitbucket/... (direct repository mapping)
  • pkg:maven/... (POM scm metadata lookup; version required)
  • pkg:composer/... (Packagist metadata lookup)
  • pkg:generic/... (requires vcs_url or download_url qualifier)

Examples:

cdxgen -t js -o bom.json "pkg:npm/lodash@4.17.21"
cdxgen -t js -o bom.json "pkg:generic/example@1.0.0?vcs_url=git+https://github.com/cdxgen/cdxgen.git"

Unsupported or malformed purl source types fail fast with explicit validation errors in both CLI and server mode.

Configuration files

Tired of passing command line arguments to cdxgen?

JSON format

  • .cdxgenrc
  • .cdxgen.json

YAML format

  • .cdxgen.yml
  • .cdxgen.yaml

Examples:

{
  "type": "java",
  "print": true,
  "output": "bom.json"
}

# Java type
type: java
# Print the BOM as table and tree
print: true
# Set the output file
output: bom.json
# Only include these components in the BOM
only: org.springframework

Environment variables

All command line arguments can also be passed as environment variables using the "CDXGEN_" prefix.

export CDXGEN_TYPE=java
export CDXGEN_PROJECT_NAME=foo

Environment variables override values from the configuration files.

Config value ordering

  • Command-line arguments
  • Environment variables
  • Configuration files (JSON first, followed by yaml)

Evinse Mode / SaaSBOM

Evinse (Evinse Verification Is Nearly SBOM Evidence) generates component evidence and SaaSBOM data for supported languages. The tool is powered by atom for Java, JavaScript, TypeScript, Python, and C/C++ flows, by dosai for .NET flows, and by golem for Go semantic evidence. cdxgen also supports --evidence during BOM generation. This section focuses on direct evinse usage for advanced workflows. See EVINSE.md for the dedicated command guide.

occurrence evidence occurrence evidence occurrence evidence

Pre-requisites

  • Java > 21 installed
  • Application source code
  • Input SBOM in CycloneDX >1.5 format. Use cdxgen to generate one.

Usage

evinse -h
Options:
  -i, --input                    Input SBOM file. Default bom.json
                                                           [default: "bom.json"]
  -o, --output                   Output file. Default bom.evinse.json
                                                    [default: "bom.evinse.json"]
  -l, --language                 Application language
  [choices: "java", "jar", "javascript", "python", "android", "cpp"] [default: "
                                                                          java"]
      --force                    Force creation of the database
                                                      [boolean] [default: false]
      --skip-maven-collector     Skip collecting jars from maven and gradle cach
                                 es. Can speedup re-runs if the data was cached
                                 previously.          [boolean] [default: false]
      --with-deep-jar-collector  Enable collection of all jars from maven cache
                                 directory. Useful to improve the recall for cal
                                 lstack evidence.     [boolean] [default: false]
      --annotate                 Include contents of atom slices as annotations
                                                      [boolean] [default: false]
      --with-data-flow           Enable inter-procedural data-flow slicing.
                                                      [boolean] [default: false]
      --with-reachables          Enable auto-tagged reachable slicing. Requires
                                 SBOM generated with --deep mode.
                                                      [boolean] [default: false]
      --exclude, --exclude-regex Additional glob pattern(s) to ignore during
                                 Atom evidence generation.          [array]
      --usages-slices-file       Use an existing usages slices file.
                                                 [default: "usages.slices.json"]
      --data-flow-slices-file    Use an existing data-flow slices file.
                                              [default: "data-flow.slices.json"]
      --reachables-slices-file   Use an existing reachables slices file.
                                             [default: "reachables.slices.json"]
  -p, --print                    Print the evidences as table          [boolean]
      --version                  Show version number                   [boolean]
  -h                             Show help                             [boolean]

To generate an SBOM with evidence for a java project.

evinse -i bom.json -o bom.evinse.json <path to the application>

By default, only occurrence evidence is determined by creating usages slices. To generate callstack evidence, pass either --with-data-flow or --with-reachables.

Reachability-based call stack evidence

atom supports reachability-based evidence generation for Java, JavaScript, and TypeScript applications. Reachability refers to data flows that originate from entry points (sources) ending at a sink (which are invocations to external libraries). The technique used is called "Forward-Reachability".

Two necessary prerequisites for this slicing mode are that the input SBOM must be generated with cdxgen and in deep mode (only for java, jars, python type) and must be placed within the application directory.

cd <path to the application>
cdxgen -t java --deep -o bom.json --evidence .

cd <path to the application>
cdxgen -t python --deep -o bom.json --evidence .

For JavaScript and TypeScript applications, deep mode is optional.

cd <path to the application>
cdxgen -t js -o bom.json .
evinse -i bom.json -o bom.evinse.json -l js --with-reachables .

Data flow-based call stack evidence

Often reachability cannot be computed reliably due to the presence of wrapper libraries or mitigating layers. Further, the repository being analyzed could be a common module containing only the sink methods without entry points (sources). In such cases, data-flow-based slicing can be used to compute call stack using a "Reverse-Reachability" algorithm. This is however a time and resource-consuming operation and might even require atom to be run externally in java mode.

evinse -i bom.json -o bom.evinse.json --with-data-flow <path to the application>

Performance tuning

To improve performance, you can cache the generated usages and data-flow slices file along with the bom file.

evinse -i bom.json -o bom.evinse.json --usages-slices-file usages.json --data-flow-slices-file data-flow.json --with-data-flow <path to the application>

Other languages

For .NET projects, generate the input BOM in deep mode so dosai can add source-backed occurrence evidence and API endpoint services. Use --profile research when you also want dosai data-flow call stacks and crypto analysis.

cdxgen -t dotnet --deep --evidence -o bom.json <path to the application>
evinse -i bom.json -o bom.evinse.json -l dotnet --profile research <path to the application>

dosai-derived services are sanitized before being written to the BOM. cdxgen strips URL credentials, query strings, and fragments, and emits authorization policy and role counts rather than raw policy or role values.

For JavaScript or TypeScript projects, pass -l javascript.

evinse -i bom.json -o bom.evinse.json --usages-slices-file usages.json --data-flow-slices-file data-flow.json -l javascript --with-data-flow <path to the application>

For Go projects, generate the base BOM first and then run evinse -l go. When the optional golem binary is available from @cdxgen/cdxgen-plugins-bin, Evinse maps Go module inventory to semantic source evidence.

cdxgen -t go -o bom.json <path to the application>
evinse -i bom.json -o bom.evinse.json -l go --golem-callgraph static <path to the application>

Golem adds occurrence and call-stack evidence plus cdx:golem:* properties for usage scopes, occurrence kinds, security signals, local replacements, vendoring, private module candidates, license-file evidence, build directives, generated files, native artifacts, and Go toolchain directives.

Use --golem-callgraph static for normal CI, and use rta or vta for more precise root-based call graph evidence where higher runtime and memory use are acceptable. Use --golem-tags when build tags change the reachable packages, and --golem-tests when test-only dependency use is part of the review.

After enrichment, import the BOM into cdxi and use .golemsummary, .golemhotspots, .golemcoverage, .occurrences, and .callstack. To audit the Golem properties, run cdx-audit --bom bom.evinse.json --direct-bom-audit --categories golem.

See Go Evinse with Golem, the Go Evinse threat model, and the Go Evinse tutorial for the complete workflow.

Excluding source paths from Atom evidence

When cdxgen or evinse invokes atom to create occurrence, reachability, or data-flow evidence, --exclude glob patterns are converted to Scala/Java-compatible regular expressions and applied to Atom evidence. Directory fragments are also forwarded through CHEN_IGNORE_DIRS, which Atom applies across supported frontends. For JavaScript and TypeScript, the same directory fragments are forwarded through ASTGEN_IGNORE_DIRS to improve astgen traversal performance.

cdxgen -t js --profile research --exclude "**/fixtures/**" --exclude "**/*.spec.js" -o bom.json <path to the application>

The same behavior applies when running evinse directly:

evinse -i bom.json -o bom.evinse.json -l javascript --exclude "**/fixtures/**" <path to the application>

This prevents excluded source files and directories from contributing package usage and occurrence evidence. cdxgen extracts stable literal directory fragments from excludes such as **/fixtures/** and merges them with any existing CHEN_IGNORE_DIRS value before invoking Atom. For JavaScript and TypeScript projects, directory fragments are also merged with ASTGEN_IGNORE_DIRS; full glob patterns such as **/*.spec.js are converted to regular expressions for evidence filtering.

For Python with cached usages and reachables file.

evinse -i bom.json -o bom.evinse.json --usages-slices-file usages.json --reachables-slices-file reachables.json -l python --with-reachables <path to the application>

Generate SBOM from maven or gradle cache

There could be Java applications with complex dependency requirements. Or you might be interested in cataloging your Maven or gradle cache. A bonus of this mode is that the resulting SBOM would have a property called Namespaces with a list of class names belonging to each jar.

Generate evidence of usage

After generating an SBOM from a cache, you can look for evidence of direct usage with evinse.

# compile or build your application
evinse -i <bom from cache> -o bom.evinse.json <application path>
# Generate data-flow evidence (Takes a while)
# evinse -i <bom from cache> -o bom.evinse.json --with-data-flow <application path>

Evinse would populate component.evidence objects with occurrences (default) and call stack (in data-flow mode). Those without evidence are either transitive or unused dependencies.

Mixed Java Projects

If a java project uses maven and gradle, maven is selected for SBOM generation under default settings. To force cdxgen to use gradle, use the argument -t gradle. Similarly, use -t scala for scala SBT.

Generating container SBOM on Windows

cdxgen supports generating container SBOM for Linux images on Windows. Follow the steps listed below.

  • Ensure cdxgen-plugins-bin >= 2.2.0 is installed.
npm install -g @cdxgen/cdxgen-plugins-bin
  • Run "Docker for Desktop" as an administrator with the 'Exposing daemon on TCP without TLS' setting turned on. Run Powershell terminal as administrator. Without this, cdxgen would fail while extracting symlinks.
  • Invoke cdxgen with -t docker
cdxgen -t docker -o bom.json <image name>

Generate SBOM with evidence for the cdxgen repo

Why not?

cdxgen -t php -t js -t jar -t ruby --exclude "**/test/**" -o bom.json
evinse -i bom.json -o bom.evinse.json -l javascript

# Don't be surprised to see the service endpoint offered by cdxgen!
# Review the reachables.slices.json and file any vulnerabilities or bugs!

Use Atom in Java mode

For large projects (> 1 million lines of code), atom must be invoked separately for the slicing operation. Follow the instructions below.

unzip atom.zip
cd atom-1.0.0/bin

# Java project
./atom -J-Xmx16g usages -o app.atom --slice-outfile usages.json -l java <path to repo>

# C project
./atom -J-Xmx16g usages -o app.atom --slice-outfile usages.json -l c <path to repo>

node bin/cdxgen.js -o bom.json -t c --usages-slices-file usages.json <path to repo>

Change 16g to 32g or above for very large projects. For the Linux kernel, a minimum of 128GB is required.

Customize metadata.authors in BOM

Use the argument --author to override the author name. Use double quotes when the name includes spaces. Multiple values are allowed.

cdxgen --author "OWASP Foundation" --author "Apache Foundation" -t java ...

Generate bash/zsh command completions

Run the commands such as cdxgen, evinse, etc with completion as the argument.

cdxgen completion >> ~/.zshrc

# cdxgen completion >> ~/.bashrc

# evinse completion >> ~/.zshrc

BOM Profile

With profiles, cdxgen can generate a BOM that is optimized for a specific use case or purpose. The default is generic.

ProfilePurposeConfigurations enabled
appsecBOM will be consumed by application security for vulnerability managementEnable deep mode
researchBOM for security researchEnables deep and evidence mode
operationalGenerate OBOMprojectType set to os
license-complianceFetch license dataSet FETCH_LICENSE environment variable

BOM lifecycles

By default, cdxgen attempts to generate a BOM for the build lifecycle phase for applications and post-build phase for container images. Using the argument, --no-install-deps it is possible to generate pre-build BOM for certain languages and ecosystems (Eg: Python) by disabling the package installation feature. Or explicitly pass --lifecycle post-build to generate an SBOM for android, dotnet, and go binaries.

Example:

cdxgen -t android --lifecycle post-build -o bom.json <path to apks>

cdxgen -t dotnet --lifecycle post-build -o bom.json <path to dotnet binaries>

cdxgen -t go --lifecycle post-build -o bom.json <path to go binaries>

Legacy dotnet and Java projects

To obtain transitive dependencies and a complete dependency tree for dotnet projects, dotnet restore command needs to be executed. Recent versions of cdxgen would attempt to restore all the solution and .csproj files when there are no project.assets.json files found.

This, however, requires the correct version of dotnet SDK to be installed. The official container image bundles version 8.0 of the SDK.

docker run --rm -v /tmp:/tmp -v $(pwd):/app:rw -it ghcr.io/cyclonedx/cdxgen -r /app -o bom.json -t dotnet

If the project requires a different version of the SDK, such as .Net core 3.1 or dotnet 6.0, then try with the below custom images.

docker run --rm -v /tmp:/tmp -v $(pwd):/app:rw -it ghcr.io/cyclonedx/cdxgen-dotnet:v12 -r /app -o bom.json -t dotnet

If the project requires legacy frameworks such as .Net Framework 4.6/4.7, then a Windows operating system or container is required to generate the SBOM correctly. A workaround is to commit the project.assets.json and the lock files to the repository from Windows and run cdxgen from Linux as normal.

For Java projects that require a specific runtime, use the custom images ghcr.io/cyclonedx/cdxgen-java11:v12 (Java 11) or ghcr.io/cyclonedx/cdxgen-java17:v12 (Java 17). Alternatively, use Java version aliases via CLI as shown.

cdxgen -t java11
cdxgen -t java17
cdxgen -t java25
cdxgen -t java26

sdkman must be installed and setup for these arguments to work.

Nydus - next-generation container image

Nydus enhances the current OCI image specification by improving container launch speed, image space and network bandwidth efficiency, and data integrity. cdxgen container images are available in nydus format with the -nydus suffix.

ghcr.io/cyclonedx/cdxgen:master-nydus

Example invocation using nerdctl

Refer to the nydus-demo.yml workflow for an example github action that demonstrates the use of nydus snapshotter to improve the performance of cdxgen.

sudo nerdctl --snapshotter nydus run --rm -v $HOME/.m2:/root/.m2 -v $(pwd):/app ghcr.io/cyclonedx/cdxgen:master-nydus -p -t java /app

Lima VM usage

Refer to the dedicated readme. Rancher Desktop on macOS with nerdctl is supported by default.

Export as protobuf binary

Pass the argument --export-proto to serialize and export the BOM as a protobuf binary.

--export-proto --proto-bin-file bom.cdx.bin

The resulting protobuf BOM can be consumed directly by companion commands such as:

  • cdx-convert -i bom.cdx -o bom.spdx.json
  • cdx-validate -i bom.cdx
  • hbom diagnostics --input hbom.cdx

hbom can also emit a protobuf sidecar with --export-proto --proto-bin-file hbom.cdx.

Signature note: keep the original JSON BOM when you need JSF signature verification. Local protobuf BOM input is supported for decode and structural processing, but cdx-proto does not currently preserve JSF signature blocks, so cdx-verify and cdx-validate --public-key ... require the source JSON BOM.

Include formulation

Pass the argument --include-formulation to collect the following information under the formulation section:

  • git metadata such as files in the tree, origin url, branch, and CI environment variables
  • build tools versions (Java, Python, Node.js, gcc, dotnet, rustc)

Example:

"formulation": [
    {
      "bom-ref": "f8324846-fad6-4927-a8e7-49379f57489b",
      "components": [
        {
          "type": "file",
          "name": ".gitattributes",
          "version": "eba1110b5794582b53554bb1e4224b860d4e173f"
        },
        {
          "type": "file",
          "name": "README_zh.md",
          "version": "70e6883720e454e3f2fe30c9730b3e56c35adc28"
        },
        {
          "type": "file",
          "name": "docker-compose.yml",
          "version": "7e9c878ee725717b3922225f26b99931332ae6c8"
        },
        {
          "type": "file",
          "name": "pom.xml",
          "version": "8da3449df64e6eb1d63ca3ca5fbd123a374d738e"
        },
        {
          "type": "file",
          "name": "src/main/java/org/joychou/Application.java",
          "version": "41169b9a018f38ee62e300047d5a6bd93562f512"
        },
        {
          "type": "file",
          "name": "src/main/resources/url/url_safe_domain.xml",
          "version": "ee81efcf364e18221c401e03f1d890348fe73e87"
        },
        {
          "type": "platform",
          "name": "dotnet",
          "version": "8.0.101",
          "description": "Microsoft.AspNetCore.App 6.0.26 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]\\nMicrosoft.AspNetCore.App 8.0.1 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]\\nMicrosoft.NETCore.App 6.0.26 [/usr/share/dotnet/shared/Microsoft.NETCore.App]\\nMicrosoft.NETCore.App 8.0.1 [/usr/share/dotnet/shared/Microsoft.NETCore.App]"
        },
        {
          "type": "platform",
          "name": "rustc",
          "version": "rustc 1.75.0 (82e1608df 2023-12-21)",
          "description": "cargo 1.75.0 (1d8b05cdd 2023-11-20)"
        },
        {
          "type": "platform",
          "name": "go",
          "version": "go version go1.21.6 linux/amd64"
        }
      ],
      "workflows": [
        {
          "bom-ref": "9f66ea8d-b1b7-4c79-8294-376903ec1bc8",
          "uid": "c451097b-5c74-49db-ada7-81bd77cdb390",
          "inputs": [
            {
              "source": {
                "ref": "git@github.com:HooliCorp/java-sec-code.git"
              },
              "environmentVars": [
                {
                  "name": "GIT_BRANCH",
                  "value": "master"
                }
              ]
            }
          ],
          "taskTypes": [
            "clone"
          ]
        }
      ]
    }
  ]

Generate Cryptography Bill of Materials (CBOM)

Use the cbom alias to generate a CBOM. This is primarily useful for ecosystems where cdxgen can identify cryptographic libraries and related evidence.

cbom -t java
# cdxgen -t java --include-crypto --evidence --deep --spec-version 1.7 .

cbom -t python
# cdxgen -t python --include-crypto --evidence --deep --spec-version 1.7 .

For .NET projects, cdxgen invokes dosai crypto analysis when --include-crypto or the research profile is enabled. dosai-discovered algorithms are emitted as CycloneDX cryptographic-asset components only when they can be mapped to a known OID, and cryptographic assets are intentionally emitted without package URLs.

cbom -t dotnet
# cdxgen -t dotnet --include-crypto --evidence --deep --spec-version 1.7 .

Using the cbom alias sets the following options:

  • includeCrypto: true
  • evidence: true
  • deep: true
  • specVersion: 1.7

For service-oriented evidence collection, use the saasbom alias or the dedicated evinse guide.

Choosing a Container Image

cdxgen publishes several images because different users care about different things: exact language-version alignment, smaller pulls, stronger runtime restrictions, or broad all-in-one convenience.

This section gives you a faster way to choose than reading the full table top to bottom.

ASCII decision tree

need a cdxgen image
   |
   +--> just need a broad default image?
   |        |
   |        +--> use ghcr.io/cyclonedx/cdxgen:master
   |
   +--> need stricter runtime permissions?
   |        |
   |        +--> use cdxgen-secure:master or cdxgen-deno:master
   |
   +--> need a specific SDK version?
   |        |
   |        +--> use the matching language-specific image
   |
   +--> need the smallest practical image?
            |
            +--> prefer an alpine variant if your toolchain allows it

Mermaid decision tree

flowchart TD
    A[choose a cdxgen image] --> B{need the default broad toolset?}
    B -->|yes| C[ghcr.io/cyclonedx/cdxgen:master]
    B -->|no| D{need stronger permission defaults?}
    D -->|yes| E[cdxgen-secure or cdxgen-deno]
    D -->|no| F{need a specific SDK or runtime version?}
    F -->|yes| G[use a language-specific image]
    F -->|no| H{need a smaller image?}
    H -->|yes| I[prefer an alpine variant]
    H -->|no| C

Fast recommendations by scenario

ScenarioRecommended image
you want the least thinking and broadest compatibilityghcr.io/cyclonedx/cdxgen:master
you want Node.js permission restrictions by defaultghcr.io/cyclonedx/cdxgen-secure:master
you prefer Deno runtime and permissionsghcr.io/cyclonedx/cdxgen-deno:master
you need an exact Java, .NET, Python, Ruby, Go, or Swift runtimethe matching language-specific image from the table below
you care a lot about image sizean Alpine variant if the ecosystem and native dependencies tolerate it

How to think about the major image families

1. Default all-in-one images

These are the best starting point for most teams. They trade image size for convenience and broad tool coverage.

ImageBest for
ghcr.io/cyclonedx/cdxgen:mastergeneral use, local experimentation, broad CI coverage
ghcr.io/cyclonedx/cdxgen-deno:masterusers who want Deno runtime behavior
ghcr.io/cyclonedx/cdxgen-secure:masterenvironments that prefer stricter runtime permissions

2. Language-specific images

Use these when the project depends on a runtime or SDK version that matters for dependency resolution. That often applies to Java, .NET, Python, Ruby, Go, and Swift projects.

A good rule is this. If the project build itself is version-sensitive, your cdxgen image probably should be too.

3. Alpine variants

Alpine images are smaller and often faster to pull. They are a strong choice in CI when you already know the target ecosystem behaves well with musl-based user space.

They are a weaker choice when the workflow depends on native extensions or tooling that assumes glibc behavior.

Scenario walkthroughs

Scenario A: default project scanning in CI

If your repo is mostly lockfile-driven and does not need an exact old SDK, start with:

docker run --rm -v $(pwd):/app ghcr.io/cyclonedx/cdxgen:master -r /app -t java -o bom.json

Scenario B: legacy Java project

If the project only builds or resolves correctly on Java 11 or Java 17, use a matching image rather than hoping the default image behaves the same way.

docker run --rm -v $(pwd):/app ghcr.io/cyclonedx/cdxgen-java11:v12 -r /app -t java -o bom.json

Scenario C: security-sensitive environment

If the runtime environment itself is highly controlled, prefer an image whose permission posture matches that expectation.

docker run --rm -v $(pwd):/app ghcr.io/cyclonedx/cdxgen-secure:master -r /app -t js -o bom.json

Scenario D: exact Python version alignment

docker run --rm -v $(pwd):/app ghcr.io/cyclonedx/cdxgen-python311:v12 -r /app -t py -o bom.json

Special note for .NET Framework users

Classic .NET Framework support is a special case. If the project truly depends on Windows-specific tooling, you may need to run on Windows or rely on committed assets and lock files rather than expecting Linux-container parity.

A practical selection order

If you are still undecided, use this order.

  1. start with ghcr.io/cyclonedx/cdxgen:master
  2. switch to a language-specific image only if runtime alignment clearly matters
  3. switch to secure or deno if the environment requires that permission model
  4. switch to Alpine only after confirming native-dependency behavior is acceptable

Custom Container Images

Below table summarizes all available container image versions. These images include additional language-specific build tools and development libraries to enable automatic restore and build operations.

LanguageVersionContainer Image TagsComments
Java25ghcr.io/cyclonedx/cdxgen:masterDefault all-in-one container image with all the latest and greatest tools with Node 24 runtime. Permission model is opt-in.
Java25ghcr.io/cyclonedx/cdxgen-deno:masterDefault all-in-one container image with all the latest and greatest tools with deno runtime. Uses deno permissions model by default.
Java25ghcr.io/cyclonedx/cdxgen-secure:masterSecure all-in-one container image with all the latest and greatest tools with Node 24 runtime. Uses Node.js permissions model by default.
Java8ghcr.io/cyclonedx/cdxgen-temurin-java8:v12Java 8 version.
Java11ghcr.io/cyclonedx/cdxgen-java11-slim:v12, ghcr.io/cyclonedx/cdxgen-java11:v12Java 11 version.
Java17ghcr.io/cyclonedx/cdxgen-java17-slim:v12, ghcr.io/cyclonedx/cdxgen-java17:v12Java 17 version.
Java21ghcr.io/cyclonedx/cdxgen-temurin-java21:v12, ghcr.io/cyclonedx/cdxgen-alpine-java21:v12Java 21 version.
Java24ghcr.io/cyclonedx/cdxgen-temurin-java24:v12, ghcr.io/cyclonedx/cdxgen-alpine-java24:v12Java 24 version.
Java26ghcr.io/cyclonedx/cdxgen-temurin-java26:v12, ghcr.io/cyclonedx/cdxgen-alpine-java26:v12Java 26 version.
Dotnet.Net Framework 4.6 - 4.8ghcr.io/cyclonedx/cdxgen-debian-dotnet6:v12.Net Framework
Dotnet.Net Core 2.1, 3.1, .Net 5.0ghcr.io/cyclonedx/cdxgen-debian-dotnet6:v12Invoke with --platform=linux/amd64 for better compatibility.
Dotnet.Net 6ghcr.io/cyclonedx/cdxgen-debian-dotnet6:v12.Net 6
Dotnet.Net 7ghcr.io/cyclonedx/cdxgen-dotnet7:v12 (amd64 only).Net 7
Dotnet.Net 8ghcr.io/cyclonedx/cdxgen-debian-dotnet8:v12, ghcr.io/cyclonedx/cdxgen-dotnet8:v12 (amd64 only).Net 8
Dotnet.Net 9ghcr.io/cyclonedx/cdxgen-debian-dotnet9:v12, ghcr.io/cyclonedx/cdxgen-alpine-dotnet9:v12, ghcr.io/cyclonedx/cdxgen-dotnet9:v12 (amd64 only).Net 9
Dotnet.Net 10ghcr.io/cyclonedx/cdxgen-debian-dotnet10:v12, ghcr.io/cyclonedx/cdxgen-alpine-dotnet10:v12.Net 10
php8.3ghcr.io/cyclonedx/cdxgen-debian-php83:v12php 8.3
php8.4ghcr.io/cyclonedx/cdxgen-debian-php84:v12, ghcr.io/cyclonedx/cdxgen-alpine-php84:v12php 8.4
php8.5ghcr.io/cyclonedx/cdxgen-debian-php85:v12, ghcr.io/cyclonedx/cdxgen-alpine-php85:v12php 8.5
Python3.6ghcr.io/cyclonedx/cdxgen-python36:v12No dependency tree
Python3.9ghcr.io/cyclonedx/cdxgen-opensuse-python39:v12, ghcr.io/cyclonedx/cdxgen-python39:v12
Python3.10ghcr.io/cyclonedx/cdxgen-opensuse-python310:v12, ghcr.io/cyclonedx/cdxgen-python310:v12
Python3.11ghcr.io/cyclonedx/cdxgen-python311:v12
Python3.12ghcr.io/cyclonedx/cdxgen-python312:v12
Python3.13ghcr.io/cyclonedx/cdxgen-python313:v12
Node.js20ghcr.io/cyclonedx/cdxgen-node20:v12, ghcr.io/cyclonedx/cdxgen-alpine-node20:v12Use --platform=linux/amd64 in case of npm install errors.
Node.js24ghcr.io/cyclonedx/cdxgen:master, ghcr.io/cyclonedx/cdxgen-alpine-node24:v12
Node.js25ghcr.io/cyclonedx/cdxgen-alpine-node25:v12
Ruby4.0.xghcr.io/cyclonedx/cdxgen:v12Supports automatic Ruby installation for 3.4.x. Example: Pass -t ruby3.4.1 to install Ruby 3.4.1.
Ruby3.3.6ghcr.io/cyclonedx/cdxgen-debian-ruby33:v12Supports automatic Ruby installation for 3.3.x. Example: Pass -t ruby3.3.1 to install Ruby 3.3.1.
Ruby3.4.xghcr.io/cyclonedx/cdxgen-debian-ruby34:v12Supports automatic Ruby installation for 3.4.x. Example: Pass -t ruby3.4.0 to install Ruby 3.4.0.
Ruby2.5.0ghcr.io/cyclonedx/cdxgen-ruby25:v12Supports automatic Ruby installation for 2.5.x. Example: Pass -t ruby2.5.1 to install Ruby 2.5.1.
Ruby2.6.10ghcr.io/cyclonedx/cdxgen-debian-ruby26:v12Supports automatic Ruby installation for 2.6.x. Example: Pass -t ruby2.6.1 to install Ruby 2.6.1.
Ruby3.4.5ghcr.io/cyclonedx/cdxgen-alpine-ruby34:v12Ruby 3.4.5
Ruby4.0.xghcr.io/cyclonedx/cdxgen-debian-ruby4:v12, ghcr.io/cyclonedx/cdxgen-alpine-ruby4:v12Ruby 4.0.x
Ruby1.8.xghcr.io/cyclonedx/debian-ruby18:masterBase image for bundle install only. No cdxgen equivalent with Ruby 1.8.x. --deep mode and research profile unsupported.
Swift6.3.xghcr.io/cyclonedx/cdxgen-debian-swift:v12Swift 6
golang1.23ghcr.io/cyclonedx/cdxgen-debian-golang123:v12, ghcr.io/cyclonedx/cdxgen-alpine-golang123:v12Golang 1.23
golang1.24ghcr.io/cyclonedx/cdxgen-debian-golang124:v12, ghcr.io/cyclonedx/cdxgen-alpine-golang124:v12Golang 1.24
golang1.26ghcr.io/cyclonedx/cdxgen-debian-golang126:v12, ghcr.io/cyclonedx/cdxgen-debian-golang:v12, ghcr.io/cyclonedx/cdxgen-alpine-golang126:v12, ghcr.io/cyclonedx/cdxgen-alpine-golang:v12Golang 1.26
Rust1ghcr.io/cyclonedx/cdxgen-debian-rust, ghcr.io/cyclonedx/cdxgen-debian-rust1:v12This is a rolling version that will get the latest released version. Currently, 1.87.

Replace :v12 with a release version tag or sha256 hash for fine-grained control over the image tag.

cdxgen badge

Copy the below block to your markdown files to show your ❤️ for cdxgen.

[![SBOM](https://img.shields.io/badge/SBOM-with_%E2%9D%A4%EF%B8%8F_by_cdxgen-FF753D)](https://github.com/cdxgen/cdxgen)