Tooling Ecosystem for CycloneDX#

This page introduces a selection of tools that can help generate SBOMs across different programming languages and ecosystems. While not exhaustive, it aims to offer a starting point for creating SBOMs in the CycloneDX format.

Environment

Ecosystem/Build System

Tool

Java

Maven

cyclonedx-for-maven

Gradle

cyclonedx-for-gradle

Python

All

cyclonedx-for-python

Github Actions

gh-python-generate-sbom

Nodejs

All

cyclonedx-bom

NPM

cyclonedx-npm

Yarn

yarn-plugin-cyclonedx

React

webpack-plugin with React

Github Actions

gh-node-module-generatebom

Go

Modules

cyclonedx-gomod

Multi-Ecosystem

All

cdxgen

Github Actions

cdxgen-action

Java#

Java is a compiled language, meaning an SBOM should be generated whenever a release version of the project is built. Since Java build systems are responsible for downloading all the dependencies required to compile and package the project, the optimal choice is to generate an SBOM during the build process.

Maven#

CycloneDX for Maven#

  • Website: https://cyclonedx.github.io/cyclonedx-maven-plugin/

  • Source: https://github.com/CycloneDX/cyclonedx-maven-plugin

  • Supported data sources: pom.xml files

Usage#

CycloneDX plugin is available on Maven central. To start using it, add the following plugin into the pom.xml file:

<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <version>2.7.0</version>
</plugin>

To generate the SBOM, select the suitable goal and use the mvn cyclonedx:<goal> command. More details on goals can be found below.

Integration#

By integrating a plugin into the Maven setup, projects can automatically generate SBOMs for each release, as part of the CI pipeline. The plugin supports 3 different methods of generating the record (goals):

More details in can be found in the official documentation.

<plugins>
   <plugin>
       <groupId>org.cyclonedx</groupId>
       <artifactId>cyclonedx-maven-plugin</artifactId>
       <executions>
           <execution>
               <phase>package</phase>
               <goals>
                   <goal>makeAggregateBom</goal>
               </goals>
           </execution>
       </executions>
   </plugin>
</plugins>

Configuration#

The CycloneDX Maven Plugin offers several configuration options that allow customization of how the SBOM is generated for the project, such as: tool version, output format, output location, whether to include license text, whether to include specific dependencies, whether attach it to the build artifacts.

Below is an example of the default configuration:

<plugins>
    <plugin>
        <groupId>org.cyclonedx</groupId>
        <artifactId>cyclonedx-maven-plugin</artifactId>
        <configuration>
            <projectType>library</projectType>
            <schemaVersion>1.6</schemaVersion>
            <includeBomSerialNumber>true</includeBomSerialNumber>
            <includeCompileScope>true</includeCompileScope>
            <includeProvidedScope>true</includeProvidedScope>
            <includeRuntimeScope>true</includeRuntimeScope>
            <includeSystemScope>true</includeSystemScope>
            <includeTestScope>false</includeTestScope>
            <includeLicenseText>false</includeLicenseText>
            <outputReactorProjects>true</outputReactorProjects>
            <outputFormat>all</outputFormat>
            <outputName>bom</outputName>
            <outputDirectory>${project.build.directory}</outputDirectory><!-- usually target, if not redefined in pom.xml -->
            <verbose>false</verbose><!-- = ${cyclonedx.verbose} -->
        </configuration>
    </plugin>
</plugins>

Additional Reading#

Gradle#

CycloneDX for Gradle#

  • Website: https://plugins.gradle.org/plugin/org.cyclonedx.bom

  • Source: https://github.com/CycloneDX/cyclonedx-gradle-plugin

  • Supported data sources: build.gradle or build.gradle.kts file

Usage#

To start using it, add the following plugin into the build.gradle file:

plugins {
  id("org.cyclonedx.bom") version "1.10.0"
}

To generate the SBOM, run the gradle cyclonedxBom command.

Integration#

In Gradle, SBOM generation with the CycloneDX plugin requires a manual setup within CI, as it doesn’t automatically align with predefined build phases like Maven does. The details depend on project specifics, but in broad terms, in order to integrate, invoking the cyclonedxBom task directly in the CI pipeline after successful builds is necessary. This ensures an SBOM is generated with each stable release.

As opposed to Maven’s goals, Gradle relies on the single cyclonedxBom task, meaning it appears to be generating a single SBOM for the project, instead of one per artifact. For publishing, it requires some additional configuration, see issue link.

Configuration#

The CycloneDX Gradle Plugin offers several configuration options that allow customization of how the SBOM is generated for the project. More details about each configuration option can be found in the plugin README.

Below is an example of the a configuration. To customise the configuration for your project, simply append it to the gradle file.

cyclonedxBom {
    includeConfigs = ["runtimeClasspath"]
    skipConfigs = ["compileClasspath", "testCompileClasspath"]
    skipProjects = [rootProject.name, "yourTestSubProject"]
    projectType = "application"
    schemaVersion = "1.6"
    destination = file("build/reports")
    outputName = "bom"
    outputFormat = "json"
    includeBomSerialNumber = false
    includeLicenseText = false
    includeMetadataResolution = true
    componentVersion = "2.0.0"
    componentName = "my-component"
}

Python#

CycloneDX for Python#

  • Website: https://pypi.org/project/cyclonedx-bom/

  • Source: https://github.com/CycloneDX/cyclonedx-python

  • Requirements: Python >=3.8,<4

Supported data sources#

  • Python (virtual) environment

  • Poetry manifest and lockfile

  • Pipenv manifest and lockfile

  • Pip’s requirements.txt format

  • PDM’s Python virtual environments

  • conda’s Python environments

Installation#

  • Install via pip: python -m pip install cyclonedx-bom

  • Install via pipx: pipx install cyclonedx-bom

  • Install via poetry: poetry add cyclonedx-bom

Usage#

  • Call script: cyclonedx-py <source> -o sbom.json

  • Call python module CLI: python3 -m cyclonedx_py <source> -o sbom.json

Integration#

In order to automate SBOM generation and publishing for new releases, depending on the CI tool you’re using, the next step is to add a command that generates the SBOM as part of your build process.

For projects that use GitHub Actions, a workflow can be defined with steps for:

  • Generation

- name: Install cyclonedx-py
  run: pipx install cyclonedx-bom
- name: Generate sbom
  run: cyclonedx-py poetry -o bom.json

  • Upload

- name: Upload sbom
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
        with:
          name: bom.json
          path: bom.json

A complete workflow example for SBOM generation and upload to DependencyTrack can be found here: generate-sbom.yml.

gh-python-generate-sbom#

  • Website: https://github.com/marketplace/actions/cyclonedx-python-generate-sbom

  • Source: https://github.com/CycloneDX/gh-python-generate-sbom

  • Supported data sources: Pip’s requirements.txt format

  • Requirements: cyclonedx-bom>=1.4.0,<4

Usage#

- name: Generate Python SBOM
  uses: CycloneDX/gh-python-generate-sbom@v2
  with:
    input: ./requirements.txt
    output: ./bom.json
    format: json

Nodejs#

CycloneDX BOM#

  • Website: https://www.npmjs.com/package/@cyclonedx/bom?activeTab=readme

  • Source: https://github.com/CycloneDX/cyclonedx-node-module

As per the official website above, CycloneDX BOM is a “meta-package”, a collection of optional dependencies. The dependencies are tools with the common purpose of generating SBOMs for node-based projects. To identify the optimal tooling for your ecosystem, check the table bellow or the README of the project for the most up to date information about available tooling.

Ecosystem/System

Actual Tool

npm

cyclonedx/cyclonedx-npm

yarn

cyclonedx/yarn-plugin-cyclonedx

Angular

cyclonedx/webpack-plugin with Angular

React

cyclonedx/webpack-plugin with React

Rollup

rollup-plugin-sbom

Vite

rollup-plugin-sbom with Vite

webpack

cyclonedx/webpack-plugin

Nodejs: npm#

cyclonedx-npm#

  • Website: https://www.npmjs.com/package/%40cyclonedx/cyclonedx-npm?activeTab=readme

  • Requirements: node >=14, npm in range 6 - 10

Supported data sources#

As per cyclonedx-node-npm/docs/how.md:

This tool utilizes npm-ls on the target project and parses its output.
This way the tool does not depend on libraries that are already part of npm. All logic and analysis is done by npm itself, the output is just interpreted and used.
Sometimes npm-ls got hiccups - caused by individual broken project installation or bugs with npm. Then, this tool may also read package.json files inside the node_module directory as an additional information source.

Installation#

  • Install as a global tool via npm: npm install --global @cyclonedx/cyclonedx-npm

  • Install as a global tool via npx: npx --package @cyclonedx/cyclonedx-npm --call exit

  • Install as a development dependency of the current project: npm install --save-dev @cyclonedx/cyclonedx-npm

Usage#

  • If installed via npm: cyclonedx-npm --help

  • If installed via npx/project dependency: npx @cyclonedx/cyclonedx-npm --help

Integration#

Integration steps depend on project details and CI tools. In broad terms, when using Github Actions a new workflow can be set up, similar to the Python example above. For Jenkins usage, including a new stage in the pipeline can help with SBOM generation and artifact upload.

Nodejs: yarn#

yarn-plugin-cyclonedx#

  • Website: https://www.npmjs.com/package/%40cyclonedx/yarn-plugin-cyclonedx

  • Requirements: node >=18, yarn >=3 (berry)

Installation#

  • Zero-install

  • Install as a development dependency of the current project (cli-wrapper):
    yarn add --dev @cyclonedx/yarn-plugin-cyclonedx

  • Install the latest version from Github:
    yarn plugin import https://github.com/CycloneDX/cyclonedx-node-yarn/releases/latest/download/yarn-plugin-cyclonedx.cjs

Usage#

  • Zero-install via dlx-wrapper: yarn dlx -q @cyclonedx/yarn-plugin-cyclonedx --help

  • Cli-wrapper: yarn exec cyclonedx-yarn --help

  • Plugin: yarn cyclonedx --help

Integration#

Depends on installation method, project details and CI tools.

Nodejs: React#

webpack-plugin with React#

  • Website: https://github.com/CycloneDX/cyclonedx-node-module

  • Requirements: Node.js >=14, webpack ^5;

  • Requirements (older plugin versions): Node.js v8.0.0 or higher, webpack v4.0.0 or higher;

Installation#

  • Install via npm: npm i -D @cyclonedx/webpack-plugin

  • Install via yarn: yarn add -D @cyclonedx/webpack-plugin

Usage#

Initialize and confifure the plugin through:
new CycloneDxWebpackPlugin(options?: object)

Configuration#

Configuration options can be found in this table.

An example of configuring the CycloneDX plugin in webpack config can be found in the plugin documentation:

const { CycloneDxWebpackPlugin } = require('@cyclonedx/webpack-plugin');

/** @type {import('@cyclonedx/webpack-plugin').CycloneDxWebpackPluginOptions} */
const cycloneDxWebpackPluginOptions = {
  includeWellknown: true,
  wellknownLocation: './.well-known'
}

module.exports = {
  // ...
  plugins: [
    new CycloneDxWebpackPlugin(cycloneDxWebpackPluginOptions)
  ]
}

See extended examples.

Nodejs#

gh-node-module-generatebom#

  • Website: https://github.com/marketplace/actions/cyclonedx-node-js-generate-sbom

  • Source: https://github.com/CycloneDX/gh-node-module-generatebom

  • Requirements: @cyclonedx/bom@ <4

  • Supported data sources:

This GitHub action requires a node_modules directory so this action will typically need to run after an npm build.

Usage#

  • Simple usage:

uses: CycloneDX/gh-node-module-generatebom@v1

  • Usage with defining output and path:

- name: Create SBOM step
  uses: CycloneDX/gh-node-module-generatebom@v1
  with:
    path: './node_project/'
    output: './bom_directory/bom.xml'

Configuration#

  • path to a node.js project, default is ./

  • output output filename, default is bom.xml

Go: Modules#

cyclonedx-gomod#

  • Source: https://github.com/CycloneDX/cyclonedx-gomod

Installation#

  • Install via Homebrew: brew install cyclonedx/cyclonedx/cyclonedx-gomod

  • Install from source: go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest

Usage#

  • Simple usage:

cyclonedx-gomod <SUBCOMMAND> [FLAGS...] [<ARG>...]

Subcommands:

  • app: Generate SBOMs for applications, include only those modules that the target application actually depends on

  • mod: Generate SBOMs for modules, include the aggregate of modules required by all packages in the target module (optionally includes modules required by tests and test packages)

  • bin: Generate SBOMs for binaries

  • version: Show version information

More info about subcommands and usage can be found in README:Usage. SBOM examples for each subcommand can be found in the examples directory.

Integration#

Support with integrating the plugin with various tools:

Configuration#

Options can be configured through flags, depending on the subcommand of choice. See README:Subcommands for the full list of options.

Multi-Ecosystem Tools#

cdxgen#

  • Website: https://cyclonedx.github.io/cdxgen

  • Source: https://github.com/CycloneDX/cdxgen

Supported Languages/Platforms: Comprehensive List#

  • Java (Maven, Gradle, sbt, more)

  • Node.js

  • Python

  • Golang

  • Rust

  • PHP

  • .NET

  • C++

  • Container (docker, podman)

  • Container files (docker, podman)

  • Swift

  • OpenAPI

Installation: Instructions#

  • Via Npm: npm install -g @cyclonedx/cdxgen

  • Via Homebrew: brew install cdxgen

Usage#

  • Generate an SBOM for cwd: cdxgen -t <lang> .

  • Generate an SBOM for cwd for a Multi-Language project: cdxgen -t <lang> -t <lang> .

cdxgen-action#

  • Website: https://github.com/marketplace/actions/cdxgen

  • Source: https://github.com/CycloneDX/cdxgen-action

Supported Languages/Platforms: Comprehensive List#

  • Java (Maven, Gradle, sbt, more)

  • Node.js

  • Python

  • Golang

  • Rust

  • PHP

  • .NET

  • C++

  • Container (docker, podman)

  • Container files (docker, podman)

  • Swift

  • OpenAPI

Usage#

To simply print the SBOM to console, add the following step to a workflow:

uses: AppThreat/cdxgen-action@v1

Integration#

Workflow can be defined that integrate a variation of following steps:

  • Upload to dependency track server

- uses: AppThreat/cdxgen-action@v1
  with:
    output: "./bom.xml"
    serverUrl: "<server_url>"
    apiKey: ${{ secrets.apiKey }}

  • Upload to dependency track server and store artefacts:

- uses: AppThreat/cdxgen-action@v1
  with:
    output: "./sboms/bom.xml"
    serverUrl: "<server_url>"
    apiKey: ${{ secrets.apiKey }}
- uses: actions/upload-artifact@v1
  with:
    name: sboms
    path: sboms