Tools Beginner

Practical guide to CycloneDX CLI tooling, including installation paths, format choices, validation, automation, and workflow recommendations.

By SBOM Generator Team Updated:
CycloneDX CLI tools SBOM generation DevOps security automation OWASP

CycloneDX CLI Guide: Generate SBOMs for Any Project

CycloneDX tooling is the right choice when you specifically need CycloneDX output and you care about validation, automation, and security-friendly downstream processing. The important detail is that the CycloneDX ecosystem is distributed across language-specific generators and plugins rather than one universal binary for every language.

This page focuses on the practical questions teams search for most often: how to install the right tool, how to generate a CycloneDX SBOM, how to validate it, and which generator fits each ecosystem.

Start Here

Use this page if you need to answer one of these quickly:

  • how do I install CycloneDX tooling for my stack?
  • which generator should I use for Node, Python, Java, .NET, Go, or Rust?
  • how do I validate a CycloneDX SBOM?
  • how do I automate CycloneDX generation in CI/CD?

Quick Answer

Use CycloneDX tooling when:

  • CycloneDX is the output format you actually need
  • security and automation are the main downstream use cases
  • you want strong support for modern dependency and vulnerability workflows
  • you are comfortable choosing a generator by ecosystem instead of forcing one tool everywhere
As of July 2026, CycloneDX 1.7 is the current specification line.

Common Commands

Node.js and npm

npm install -g @cyclonedx/cyclonedx-npm
cyclonedx-npm --output-format JSON --output-file bom.json

Python

pip install cyclonedx-bom
cyclonedx-py -o bom.json

Maven

mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom

Gradle

./gradlew cyclonedxBom

.NET

dotnet tool install --global CycloneDX
dotnet-CycloneDX MySolution.sln -o bom.xml

Go

go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest
cyclonedx-gomod app -json -output bom.json

Rust

cargo install cargo-cyclonedx
cargo cyclonedx --format json

Validate the result

# Then validate the generated file in the browser
# https://sbomgenerator.com/tools/validator

Best fit

CycloneDX tooling is usually the right choice if:

  • security teams are the main downstream consumer
  • you want a strong default for CI/CD automation
  • you need format-native validation with the CycloneDX Validator

Why Choose CycloneDX CLI Tools?

Key Advantages

🚀 Developer-Friendly
  • Simple, intuitive command-line interface
  • Minimal configuration required
  • Consistent experience across all languages
  • Excellent documentation and community support
⚡ Automated & Fast
  • Automatic dependency discovery
  • Multi-threaded scanning for large projects
  • Incremental updates for changed dependencies
  • Optimized for CI/CD pipeline integration
🔧 Comprehensive Language Support
  • Native support for 15+ programming languages
  • Deep integration with package managers
  • Transitive dependency resolution
  • Framework-aware component detection
📋 Enterprise Ready
  • Standards-compliant CycloneDX output
  • Configurable output formats (JSON, XML)
  • Detailed vulnerability correlation
  • License and copyright detection

📦 Installation Guide

Quick Installation

The fastest way to get started is to choose the generator that matches your ecosystem rather than looking for one command that covers every language:

# JavaScript / Node.js
npm install -g @cyclonedx/cyclonedx-npm

# Python
pip install cyclonedx-bom

If you are not sure which path to choose, start with the generator closest to your real build metadata rather than a generic filesystem scan.

Language-Specific Installation

JavaScript/Node.js

# Global installation
npm install -g @cyclonedx/cyclonedx-npm

# Or as project dependency
npm install --save-dev @cyclonedx/cyclonedx-npm

# Verify installation
cyclonedx-npm --version

Python

# Install via pip
pip install cyclonedx-bom

# Or via poetry
poetry add --group dev cyclonedx-bom

# Verify installation
cyclonedx-py --version

Java (Maven)

<!-- Add to pom.xml -->
<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <version>2.9.2</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>makeAggregateBom</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Java (Gradle)

// Add to build.gradle
plugins {
    id 'org.cyclonedx.bom' version '3.2.4'
}

// Configure SBOM generation
cyclonedxBom {
    includeConfigs = ['runtimeClasspath']
    skipConfigs = ['compileClasspath', 'testCompileClasspath']
    projectType = 'application'
    schemaVersion = '1.7'
    destination = file('build/reports')
    outputName = 'bom'
    outputFormat = 'json'
}

.NET/C#

# Install as global tool
dotnet tool install --global CycloneDX

# Verify installation
dotnet-CycloneDX --version

Go

# Install cyclonedx-gomod
go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest

# Verify installation
cyclonedx-gomod version

Rust

# Install cargo-cyclonedx
cargo install cargo-cyclonedx

# Verify installation
cargo cyclonedx --version

Verification

Verify your installation works correctly:

# Check version (varies by language)
cyclonedx-npm --version        # JavaScript/Node.js
cyclonedx-py --version         # Python
mvn org.cyclonedx:cyclonedx-maven-plugin:help  # Java/Maven
dotnet-CycloneDX --version     # .NET
cyclonedx-gomod version        # Go
cargo cyclonedx --version      # Rust

🎯 Basic Usage

Quick Start Example

Generate your first SBOM in under 30 seconds:

# Navigate to your project directory
cd /path/to/your/project

# Generate a JSON SBOM for a Node.js project
cyclonedx-npm --output-format JSON --output-file bom.json

# Output: bom.json created in current directory

Language-Specific Commands

JavaScript/Node.js Projects

# Basic SBOM generation
cyclonedx-npm --output-format JSON --output-file bom.json

# Specify output file
cyclonedx-npm --output-format JSON --output-file my-app-sbom.json

# Omit development dependencies
cyclonedx-npm --output-format JSON --output-file my-app-sbom.json --omit dev

# Custom project metadata
cyclonedx-npm --output-format JSON --output-file my-app-sbom.json

Python Projects

# Generate from requirements.txt
cyclonedx-py -r requirements.txt -o sbom.json

# Include development dependencies
cyclonedx-py -r requirements.txt -r requirements-dev.txt -o sbom.json

# From poetry project
cyclonedx-py --poetry -o sbom.json

# From conda environment
cyclonedx-py --conda-env myenv -o sbom.json

Java/Maven Projects

# Generate via Maven plugin
mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom

# Output location: target/bom.xml (or bom.json)

# Custom configuration
mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom \
  -DschemaVersion=1.7 \
  -DoutputFormat=json \
  -DoutputName=my-app-sbom

Java/Gradle Projects

# Generate SBOM
./gradlew cyclonedxBom

# Custom output
./gradlew cyclonedxBom --output-format=json --output-name=my-sbom

.NET Projects

# Generate SBOM for current project
dotnet-CycloneDX . -o .

# Specify project file
dotnet-CycloneDX MyProject.csproj -o ./sbom

# Custom output location
dotnet-CycloneDX MyProject.csproj -o ./sbom

# Include framework references
dotnet-CycloneDX MyProject.csproj -o ./sbom -rs

Go Projects

# Generate from go.mod
cyclonedx-gomod mod -json -output sbom.json

# Include license information
cyclonedx-gomod mod -licenses -json -output sbom.json

# Specify module path
cyclonedx-gomod mod -json -output sbom.json

Rust Projects

# Generate from Cargo.toml
cargo cyclonedx --format json --output-cdx sbom.json

# Include features
cargo cyclonedx --all-features --output-cdx sbom.json

# Workspace support
cargo cyclonedx --workspace --output-cdx sbom.json

⚙️ Advanced Configuration

Output Format Options

CycloneDX CLI tools support multiple output formats:

# JSON format (recommended)
cyclonedx-npm --output-format JSON --output-file bom.json

# XML format
cyclonedx-npm --output-format XML --output-file bom.xml

Schema Versions

Choose the appropriate CycloneDX schema version:

# Use the tool default unless a downstream system requires an older schema
cyclonedx-npm --output-format JSON --output-file bom.json

# Example compatibility override
cyclonedx-npm --output-format JSON --output-file bom.json --spec-version 1.6

Project Metadata Configuration

Provide comprehensive project information:

cyclonedx-npm --output-format JSON --output-file bom.json

Dependency Filtering

Control which dependencies are included:

# Exclude development dependencies
cyclonedx-npm --output-format JSON --output-file bom.json --omit dev

# Include specific scopes (Maven/Gradle)
mvn cyclonedx:makeAggregateBom -DincludeCompileScope=true -DincludeRuntimeScope=true

# Exclude test dependencies
mvn cyclonedx:makeAggregateBom -DexcludeTestScope=true

License Detection

Enable comprehensive license information:

# Include license detection
cyclonedx-gomod mod -licenses -json -output sbom.json

# Python with license scanning
cyclonedx-py -r requirements.txt --gather-license-texts -o sbom.json

# Node.js generator
cyclonedx-npm --output-format JSON --output-file bom.json

🚀 CI/CD Integration

GitHub Actions

Create .github/workflows/sbom.yml: 
name: Generate SBOM

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  sbom:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'

    - name: Install dependencies
      run: npm ci

    - name: Install CycloneDX CLI
      run: npm install -g @cyclonedx/cyclonedx-npm

    - name: Generate SBOM
      run: |
        cyclonedx-npm --output-format JSON --output-file sbom.json

    - name: Upload SBOM
      uses: actions/upload-artifact@v4
      with:
        name: sbom
        path: sbom.json

    - name: Validate SBOM
      run: |
        # Optional: Validate SBOM with external tools
        curl -X POST -H "Content-Type: application/json" \
          -d @sbom.json \
          https://validator.cyclonedx.org/api/validate

GitLab CI/CD

Add to .gitlab-ci.yml: 
generate-sbom:
  stage: build
  image: node:18-alpine

  before_script:
    - npm install -g @cyclonedx/cyclonedx-npm

  script:
    - |
      cyclonedx-npm --output-format JSON --output-file sbom.json

  artifacts:
    paths:
      - sbom.json
    expire_in: 1 week

  only:
    - main
    - merge_requests

Jenkins Pipeline

Create Jenkinsfile: 
pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Install Dependencies') {
            steps {
                sh 'npm ci'
                sh 'npm install -g @cyclonedx/cyclonedx-npm'
            }
        }

        stage('Generate SBOM') {
            steps {
                sh '''
                    cyclonedx-npm --output-format JSON --output-file sbom.json
                '''
            }
        }

        stage('Archive SBOM') {
            steps {
                archiveArtifacts artifacts: 'sbom.json', fingerprint: true
            }
        }
    }
}

Azure DevOps

Add to azure-pipelines.yml: 
trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18.x'
  displayName: 'Install Node.js'

- script: |
    npm ci
    npm install -g @cyclonedx/cyclonedx-npm
  displayName: 'Install dependencies'

- script: |
    cyclonedx-npm --output-format JSON --output-file sbom.json
  displayName: 'Generate SBOM'

- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: 'sbom.json'
    artifactName: 'SBOM'
  displayName: 'Publish SBOM'

🔧 Multi-Language Project Support

Monorepo Configuration

For projects with multiple languages:

# Generate individual SBOMs for each component
cd frontend && cyclonedx-npm --output-format JSON --output-file ../sboms/frontend-sbom.json
cd backend && cyclonedx-py -r requirements.txt -o ../sboms/backend-sbom.json
cd mobile && cyclonedx-npm --output-format JSON --output-file ../sboms/mobile-sbom.json

# Merge SBOMs (using custom script)
node merge-sboms.js sboms/*.json --output combined-sbom.json

Docker Multi-Stage Support

# Build stage with SBOM generation
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production

# Install CycloneDX and generate SBOM
RUN npm install -g @cyclonedx/cyclonedx-npm
RUN cyclonedx-npm --output-format JSON --output-file sbom.json

# Production stage
FROM node:18-alpine AS production
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/sbom.json ./sbom.json
COPY . .

EXPOSE 3000
CMD ["npm", "start"]

📊 Output Analysis and Validation

Understanding CycloneDX Output

A typical CycloneDX SBOM structure:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.7",
  "serialNumber": "urn:uuid:12345678-1234-1234-1234-123456789012",
  "version": 1,
  "metadata": {
    "timestamp": "2026-03-09T12:00:00Z",
    "component": {
      "type": "application",
      "name": "my-app",
      "version": "1.0.0"
    }
  },
  "components": [
    {
      "type": "library",
      "name": "express",
      "version": "4.18.2",
      "purl": "pkg:npm/express@4.18.2",
      "scope": "required",
      "licenses": [
        {
          "license": {
            "name": "MIT"
          }
        }
      ]
    }
  ]
}

Quality Validation

Validate your generated SBOMs:

# Online validation
curl -X POST -H "Content-Type: application/json" \
  -d @sbom.json \
  https://validator.cyclonedx.org/api/validate

# Local validation with cyclonedx-cli
npm install -g @cyclonedx/cli
cyclonedx validate --input-file sbom.json

# NTIA compliance check
cyclonedx validate --input-file sbom.json --ntia

Common Quality Issues

Missing Components
  • Ensure all package manager files are present
  • Check for private/internal dependencies
  • Verify transitive dependency resolution
Incorrect Metadata
  • Review project name and version
  • Validate license information
  • Check component relationships
Performance Issues
  • Large dependency trees may require increased memory
  • Use filtering options for faster generation
  • Consider parallel processing for monorepos

🛠️ Troubleshooting Guide

Common Installation Issues

Permission Errors (npm) 
# Fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Or use npx without global install
npx @cyclonedx/cyclonedx-npm
Python Path Issues 
# Ensure Python path is correct
which python3
pip3 install --user cyclonedx-bom

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"
Java Plugin Resolution 
<!-- Ensure Maven can resolve plugin -->
<pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.cyclonedx</groupId>
      <artifactId>cyclonedx-maven-plugin</artifactId>
      <version>2.9.2</version>
    </plugin>
  </plugins>
</pluginManagement>

Generation Issues

Empty or Incomplete SBOMs
  1. Check Dependencies Are Installed
# Ensure dependencies are installed
   npm ci                    # Node.js
   pip install -r requirements.txt  # Python
   mvn dependency:resolve    # Maven
  1. Verify Package Manager Files
# Check required files exist
   ls package-lock.json     # Node.js
   ls requirements.txt      # Python
   ls pom.xml              # Maven
  1. Enable Debug Logging
# Start with a normal generation run and check the output file
   cyclonedx-npm --output-format JSON --output-file bom.json
   cyclonedx-py --debug -r requirements.txt -o sbom.json
   mvn cyclonedx:makeAggregateBom -X
Memory Issues with Large Projects 
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
cyclonedx-npm --output-format JSON --output-file bom.json

# Java heap size for Maven
export MAVEN_OPTS="-Xmx2g"
mvn cyclonedx:makeAggregateBom
Network/Proxy Issues 
# Configure npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
<!-- Maven proxy configuration in settings.xml -->
<proxy>
  <id>corporate-proxy</id>
  <active>true</active>
  <protocol>http</protocol>
  <host>proxy.company.com</host>
  <port>8080</port>
</proxy>

Performance Optimization

Faster Generation 
# Skip unnecessary scopes
mvn cyclonedx:makeAggregateBom -DexcludeTestScope=true

# Production dependencies only
npm ci --production
cyclonedx-npm --output-format JSON --output-file bom.json --omit dev

# Reuse installed dependencies and lock files
cyclonedx-npm --output-format JSON --output-file bom.json
Caching Dependencies 
# Cache npm dependencies
npm ci --cache .npm-cache

# Maven dependency caching
mvn dependency:go-offline

📈 Best Practices

Project Configuration

1. Standardize Across Teams 
# Create project-wide configuration
echo '{
  "output-format": "json",
  "output-file": "bom.json"
}' > .cyclonedx.json
2. Version Consistency 
# Regenerate the SBOM after tagging or versioning a release
cyclonedx-npm --output-format JSON --output-file bom.json
3. Metadata Completeness 
# Keep authoritative metadata in package manifests and build files
cyclonedx-npm --output-format JSON --output-file bom.json

Security Considerations

1. Sensitive Information
  • Never include credentials in SBOMs
  • Review generated SBOMs for proprietary information
  • Use filtering to exclude internal components
2. Storage and Distribution 
# Sign SBOMs for integrity
gpg --armor --detach-sign sbom.json

# Store with checksums
sha256sum sbom.json > sbom.json.sha256

Automation Best Practices

1. Fail-Safe Generation 
#!/bin/bash
set -e

# Generate SBOM with error handling
if ! cyclonedx-npm --output-format JSON --output-file sbom.json; then
    echo "SBOM generation failed"
    exit 1
fi

# Validate SBOM was created
if [[ ! -f sbom.json ]]; then
    echo "SBOM file not created"
    exit 1
fi

# Check SBOM is valid JSON
if ! jq empty sbom.json; then
    echo "Invalid SBOM JSON"
    exit 1
fi

echo "SBOM generated successfully"
2. Incremental Updates 
# Only regenerate if dependencies changed
if [[ package-lock.json -nt sbom.json ]]; then
    echo "Dependencies changed, regenerating SBOM"
    cyclonedx-npm --output-format JSON --output-file sbom.json
else
    echo "SBOM up to date"
fi

🔗 Integration with Security Tools

Vulnerability Scanning

Grype Integration 
# Generate SBOM and scan for vulnerabilities
cyclonedx-npm --output-format JSON --output-file sbom.json
grype sbom:sbom.json
Snyk Integration 
# Import SBOM into Snyk
snyk test --file=sbom.json --package-manager=cyclonedx
Trivy Integration 
# Scan SBOM with Trivy
cyclonedx-npm --output-format JSON --output-file sbom.json
trivy sbom sbom.json

License Compliance

FOSSA Integration 
# Upload SBOM to FOSSA
curl -X POST \
  -H "Authorization: token YOUR_API_TOKEN" \
  -F "file=@sbom.json" \
  https://app.fossa.com/api/builds/custom+1/sbom
License Scanning 
# Generate SBOM with license information
cyclonedx-npm --output-format JSON --output-file sbom.json

# Extract licenses for review
jq -r '.components[].licenses[]?.license.name' sbom.json | sort -u

🚀 Advanced Use Cases

Custom Component Enrichment

// enrich-sbom.js - Add custom metadata
const fs = require('fs');
const sbom = JSON.parse(fs.readFileSync('sbom.json', 'utf8'));

// Add custom properties
sbom.metadata.properties = [
  {
    name: "build.environment",
    value: process.env.NODE_ENV || "production"
  },
  {
    name: "build.timestamp",
    value: new Date().toISOString()
  }
];

// Enrich components with additional data
sbom.components.forEach(component => {
  if (component.name === 'express') {
    component.properties = [
      {
        name: "security.review.status",
        value: "approved"
      }
    ];
  }
});

fs.writeFileSync('enriched-sbom.json', JSON.stringify(sbom, null, 2));

SBOM Diffing

#!/bin/bash
# compare-sboms.sh - Compare two SBOMs

OLD_SBOM="sbom-old.json"
NEW_SBOM="sbom-new.json"

echo "=== Added Components ==="
jq -r '.components[].name' "$NEW_SBOM" | sort > new-components.txt
jq -r '.components[].name' "$OLD_SBOM" | sort > old-components.txt
comm -23 new-components.txt old-components.txt

echo "=== Removed Components ==="
comm -13 new-components.txt old-components.txt

echo "=== Version Changes ==="
jq -r '.components[] | "\(.name)@\(.version)"' "$NEW_SBOM" | sort > new-versions.txt
jq -r '.components[] | "\(.name)@\(.version)"' "$OLD_SBOM" | sort > old-versions.txt
comm -23 new-versions.txt old-versions.txt | head -20

📚 Resources and References

Official Documentation

Community Resources

Validation and Testing

Conclusion

CycloneDX CLI tools provide the most comprehensive, developer-friendly solution for automated SBOM generation. With support for all major programming languages, excellent CI/CD integration, and a thriving community, they're the ideal choice for organizations serious about supply chain security.

Key Takeaways:
  • Start Simple: Use basic commands to generate your first SBOMs quickly
  • Automate Everything: Integrate SBOM generation into your CI/CD pipelines
  • Validate Quality: Always validate generated SBOMs for completeness and accuracy
  • Stay Updated: Keep tools updated to benefit from the latest improvements
  • Community Support: Leverage the active CycloneDX community for help and best practices
Ready to get started? Pick your language, install the appropriate CycloneDX tool, and generate your first SBOM in minutes. The future of software supply chain security starts with complete visibility into your dependencies.

Happy SBOM generation! 🚀

Table of Contents