Setting up the CycloneDX SBOM generation

A guide on how to use the CycloneDX plugins for the main package managers to create SBOM files.

📘

Best Practice - CycloneDX SBOM generation

We strongly suggest using the SBOM plugins provided by the CycloneDX initiative for combined use with VSM. For the main package managers, these plugins are easy to embed and reliably extract all relevant information (dependency tree incl. transitive dependencies, consistent use of the PURL and licenses) from your build files.

Integrating CycloneDX plugins for various environments

We also provide a GitHub action that can easily be used in combination with the SBOM generation to streamline your onboarding of SBOMs to VSM.

Maven

GitHub project: https://github.com/CycloneDX/cyclonedx-maven-plugin
Slack channel: https://cyclonedx.slack.com/archives/CVCKP34A2

  1. Add the CycloneDX Maven plugin to your pom.xml:
<plugins>
    <plugin>
        <groupId>org.cyclonedx</groupId>
        <artifactId>cyclonedx-maven-plugin</artifactId>
        <version>2.7.3</version>
    </plugin>
</plugins>

There are more configuration options (see the GitHub project for details). But the default should suffice for most cases.

  1. Run the below command:
mvn org.cyclonedx:cyclonedx-maven-plugin:makeBom
  1. Find the CycloneDX SBOM JSON under ./target

Gradle / Kotlin

GitHub project: https://github.com/CycloneDX/cyclonedx-gradle-plugin
Slack channel: https://cyclonedx.slack.com/archives/CVC9GTY5V

  1. Add the CycloneDX Gradle plugin to your build.gradle or settings.gradle.kts for Kotlin:
plugins {
    id 'org.cyclonedx.bom' version '1.7.2'
}

tasks.cyclonedxBom {
    setDestination(project.File("."))

}

There are more configuration options (see the GitHub project for details). But the default should suffice for most cases.

  1. Run the below command:
gradle cyclonedxBom
  1. Find the CycloneDX SBOM JSON under ./bom.json.
via GitHub Action
name: Generate and register service

on:
  push:
    branches:
      - main

jobs:
  post-deploy:
      name: Post Deployment
      runs-on: ubuntu-latest
      steps:
          - name: Checkout
             uses: actions/[email protected]

      - name: Set up JDK temurin 17
        uses: actions/[email protected]
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Run gradlew cyclonedxBom task
        uses: gradle/[email protected]
        with:
          build-root-directory: .
          arguments: cyclonedxBom

       # Invoke the GitHub action to register the service with SBOM
       - name: VSM discovery
         uses: leanix/[email protected]
         with:
            api-token: ${{ secrets.VSM_LEANIX_API_TOKEN }}
          # dry-run: true

npm

GitHub project: https://github.com/CycloneDX/cyclonedx-node-npm
Slack channel: https://cyclonedx.slack.com/archives/CVCKR4WG6

  1. Install the CycloneDX npm plugin to your project by running:
npm install --global @cyclonedx/cyclonedx-npm
  1. Run the below command:
cyclonedx-npm --output-file "<path to the CycloneDX json file>"

There are more configuration options (see the GitHub project for details). But the above command should suffice for most cases.

  1. Find the CycloneDX SBOM JSON under <path to the CycloneDX json file>.
via GitHub Action
name: Generate and register service

on:
  push:
    branches:
      - main

jobs:
  post-deploy:
      name: Post Deployment
      runs-on: ubuntu-latest
      steps:
        - name: Setup Node ${{ env.NODE_VERSION }} Environment
            uses: actions/[email protected]
            with:
              node-version: ${{ env.NODE_VERSION }}
        
        # Use the respective command to generate SBOM file
        - name: Generate SBOM
            run:  |
                npm install --global @cyclonedx/cyclonedx-npm
                cyclonedx-npm --output-file "bom.json"
        
          # Invoke the GitHub action to register the service with SBOM
          - name: VSM discovery
            uses: leanix/[email protected]
            with:
              api-token: ${{ secrets.VSM_LEANIX_API_TOKEN }}
            # dry-run: true

pipy / poetry / conda

GitHub project: https://github.com/CycloneDX/cyclonedx-python
Slack channel: https://cyclonedx.slack.com/archives/CVA0QJEVA

  1. Install the CycloneDX python plugin to your python project by running:

with pip:

pip install cyclonedx-bom

with poetry:

poetry add cyclonedx-bom
  1. Run the below command:

for pip:

cyclonedx-py -pip --format json -o <path to the CycloneDX json file>

will look for the Pipefile.lock file in the current working directory.

for conda:

cyclonedx-py -c --format json -o <path to the CycloneDX json file>

will build a SBOM based on the output from conda list --explicit

for poetry:

cyclonedx-py -p --format json -o <path to the CycloneDX json file>

will look for the poetry.lock file in the current working directory.

for requirements.txt:

cyclonedx-py -r --format json -o <path to the CycloneDX json file>

will look for the requirements.txt file in the current working directory.

for the current virtual environment:

cyclonedx-py -e --format json -o <path to the CycloneDX json file>

based on the packages installed in your current Python environment.

  1. Find the CycloneDX SBOM JSON under <path to the CycloneDX json file> you specified in the -o parameter.
via GitHub Action

see a live example using the below workflow here:

name: Generate and register service with SBOM in VSM

on:
  push:
    branches:
      - "main"

jobs:
  build:
    name: Post Deployment
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/[email protected]

      - uses: actions/[email protected]
        with:
          python-version: "3.8.3"
          cache: "pip"
      - run: |
          pip install -r requirements.txt
          cyclonedx-py -r -F --format json -o bom.json

      # Invoke the GitHub action to register the service with SBOM
      - name: VSM discovery
        uses: leanix/[email protected]
        with:
          api-token: ${{ secrets.VSM_LEANIX_API_TOKEN }}
          # dry-run: true

Go

GitHub project: https://github.com/CycloneDX/cyclonedx-gomod
Slack channel: XXXXX

  1. Install the CycloneDX go plugin to your go project by running:
go install github.com/CycloneDX/cyclonedx-gomod/cmd/[email protected]
  1. Run the below command
$ cyclonedx-gomod app -json -output <path to the CycloneDX json file> -files -licenses -main cmd/acme-app /usr/src/acme-module

There are more configuration options (see the GitHub project for details). But the above command should suffice for most cases.

  1. Find the CycloneDX SBOM JSON under <path to the CycloneDX json file> you specified in the -output parameter.

Ruby

GitHub project: https://github.com/CycloneDX/cyclonedx-ruby-gem
Slack channel: https://cyclonedx.slack.com/archives/CUZ0DV9PD

  1. Install the CycloneDX Ruby Gem:
gem install cyclonedx-ruby 
  1. Run the below command:
cyclonedx-ruby -p /path/to/ruby/project
  1. Find the CycloneDX SBOM JSON in the project directory.

More

Please visit the GitHub project from the CycloneDX initiative to find plugins for other package managers as well.