Table of contents
- Installing cdxgen
- Generating SBOM
- Attestations and Signing BOMs
- Cryptography BOM (CBOM)
- Operations BOM (OBOM)
- Software-as-a-Service BOM (SaaSBOM)
- Attestations (CDXA) - Generate SBOM with Templates and Sign BOM for Authenticity
- Vulnerability Disclosure Report (VDR)
- Server Mode
- Example CI/CD pipeline scenarios
- Compliance Check
A Bill of Materials (BOM) is a crucial component in software development and supply chain management, providing a detailed list of components, libraries, and dependencies used in creating a software product. Security is heavily involved in this process, especially with Software Bills of Materials (SBOMs), which help in identifying and mitigating risks associated with vulnerable components. Tools like CycloneDX and OWASP Dependency-Scan (dep-scan) are designed to generate SBOMs and assess vulnerabilities within these components.
CycloneDX focuses on offering a standard format for SBOMs, enabling the identification of software vulnerabilities by tracking every component used in the product, including third-party libraries, thus reducing supply chain risks. By integrating this into the development pipeline, organizations can detect potential threats early, helping with vulnerability disclosures and exploitability analysis. Similarly, dep-scan helps automate the detection of known vulnerabilities across the dependencies used in a project, making it easier to track and mitigate risks in real-time during development
Installing cdxgen
You can install cdxgen
globally using npm:
npm install -g @cyclonedx/cdxgen
Alternatively, install using Homebrew:
brew install cdxgen
For containerized usage, pull the Docker image:
docker run --rm -e CDXGEN_DEBUG_MODE=debug -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen:master -r /app -o /app/bom.json
Generating SBOM
- SBOM for Java Projects
cdxgen
automatically detects project types like Maven, Gradle, or SBT for Java projects. To generate an SBOM for a Java project, use:
cdxgen -t java -o bom.json
To output the SBOM in a human-readable table:
cdxgen -t java -o bom.json -p
- SBOM for JavaScript Projects
For JavaScript/Node.js projects, cdxgen
can scan package.json
files and generate an SBOM:
cdxgen -t nodejs -o bom.json
If you have a multi-project setup, use recursive mode:
cdxgen -r -o bom.json
- SBOM for Python Projects
cdxgen -t python -o bom.json
- SBOM for Containers
cdxgen
supports Docker container images. You can scan a container image to generate its SBOM:
cdxgen -t oci -o bom.json --deep
Alternatively, use Docker:
docker run --rm -e CDXGEN_DEBUG_MODE=debug -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen:master -r /app -o /app/bom.json
- SBOM for C/C++ Projects
For C or C++ projects, ensure Java >= 21 is installed. You can then generate an SBOM with:
cdxgen -t c -o bom.json
Attestations and Signing BOMs
Generate signed SBOMs with granular attestations to ensure authenticity:
cdxgen --generate-key-and-sign -o bom.json
Server Mode
Run cdxgen
as a server to generate SBOMs via REST API:
cdxgen --server --server-host 0.0.0.0 --server-port 9090
Test the server's health:
curl "http://127.0.0.1:9090/health"
Scan a local path:
curl "http://127.0.0.1:9090/sbom?path=/your/project/path&type=js"
Scan a Git repository:
curl "http://127.0.0.1:9090/sbom?url=https://github.com/your-repo.git&type=js"
Universal SBOM
You can generate a universal SBOM that scans all package, container, and Kubernetes manifests:
cdxgen -t universal -o bom.json
A typical bom.json
output might look like this:
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"components": [
{
"type": "library",
"name": "lodash",
"version": "4.17.21",
"purl": "pkg:npm/[email protected]",
"licenses": [
{
"license": {
"id": "MIT"
}
}
]
},
{
"type": "library",
"name": "requests",
"version": "2.25.1",
"purl": "pkg:pypi/[email protected]",
"licenses": [
{
"license": {
"id": "Apache-2.0"
}
}
]
}
]
}
This JSON output contains the software components, their versions, and associated licenses.
Cryptography BOM (CBOM)
You can use cdxgen
to generate a cryptographic BOM (CBOM) that captures cryptographic dependencies in your projects.
cbom -t java
# cdxgen -t java --include-crypto -o bom.json
This will create a cryptobom_java.json
or cryptobom_python.json
file that includes cryptographic information of dependencies used in the respective Java or Python projects.
Operations BOM (OBOM)
cdxgen
can generate an operations BOM (OBOM) for container images or virtual machines (VMs) by analyzing the package installations.
For Linux container images:
# Generate an OBOM for a Linux container image
cdxgen -t container -i your-container-image -o obom_linux.json
For Windows VMs:
# Generate an OBOM for a Windows VM
cdxgen -t windows -o obom_windows.json path/to/windows-vm/instance
These commands will generate BOMs with the list of operating system packages installed on your container or VM.
Software-as-a-Service BOM (SaaSBOM)
A Software-as-a-Service BOM (SaaSBOM) captures dependencies and vulnerabilities for SaaS-based software environments.
using Evinse Mode / SaaSBOM for generating component evidence and SBOMs (Software Bill of Materials) with cdxgen. The tool is backed by Atom for occurrence and callstack evidence.
Generate SBOM with occurrence evidence for a Java project:
evinse -i bom.json -o bom.evinse.json <path to the application>
To generate callstack evidence, use the --with-data-flow
flag:
evinse -i bom.json -o bom.evinse.json --with-data-flow <path to the application>
Cache Usages and Data-Flow Slices for Re-runs:
- You can improve performance by caching generated usages and data-flow slices:
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>
Running for JavaScript Projects:
- Specify the language with
-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>
Generate SBOM from Maven or Gradle Cache:
- Use this for applications with complex dependencies:
cdxgen -t maven -o bom.json
evinse -i bom.json -o bom.evinse.json <application path>
Generating Evidence of Usage:
- After generating an SBOM from the Maven or Gradle cache, run:
evinse -i bom.json -o bom.evinse.json <application path>
To generate data-flow evidence, which may take longer:
evinse -i bom.json -o bom.evinse.json --with-data-flow <application path>
Optimize Re-runs:
- Use
--skip-maven-collector
to avoid re-fetching data from Maven:
evinse -i bom.json -o bom.evinse.json --skip-maven-collector <application path>
Handling Large Projects (Atom)
For larger projects, atom may need to be invoked separately for the slicing operation.
Atom Usage:
Download the latest
atom.zip
.Unzip and run the following for large projects (adjust memory limits)
./atom -J-Xmx16g usages -o app.atom --slice-outfile usages.json -l java <path to repo>
node bin/cdxgen.js -o bom.json -t java --usages-slices-file usages.json <path to repo>
- Memory Configuration:
- For projects like the Linux kernel, at least 128GB of memory may be required.
- Example for Generating SBOM with Evidence for cdxgen Repo:
cdxgen -t js -o bom.json -p --no-recurse
evinse -i bom.json -o bom.evinse.json -l javascript
Attestations (CDXA) - Generate SBOM with Templates and Sign BOM for Authenticity
cdxgen
can help generate and sign SBOM documents following various templates and standards for attestations.
Generate SBOM with a specific template
# Generate SBOM with a CycloneDX template for Java
cdxgen -t java -o sbom_signed_java.json --template cyclonedx.json path/to/your/java/project
Sign SBOM at a granular level
You can use tools like cosign
or openssl
to sign your SBOM for added authenticity.
# Sign the SBOM using OpenSSL
openssl dgst -sha256 -sign private-key.pem -out sbom_signature.sha256 sbom_signed_java.json
After generating and signing, you can verify the authenticity of the SBOM using the public key.
Vulnerability Disclosure Report (VDR)
OWASP dep-scan is a security tool that scans application dependencies for known vulnerabilities and license issues. It supports local repositories, container images, and Kubernetes manifests.
Key Features
Scans local repos, container images, and OS.
Generates Software Bill-of-Materials (SBOM) and Common Security Advisory Framework (CSAF) documents.
Performs advanced reachability analysis for multiple programming languages.
Supports various vulnerability data sources like OSV, NVD, and GitHub.
Vulnerability Data Sources
OSV
NVD
GitHub
NPM
Various Linux distributions (e.g., Debian, Ubuntu, RHEL/CentOS)
Installation
To install dep-scan, run the following commands:
# Install the normal version (MIT license)
pip install owasp-depscan
# For a performant version (BSD-3-Clause)
pip install owasp-depscan[perf]
Scanning Projects Locally (Python Version)
Navigate to the project directory and run:
cd <project_to_scan>
depscan --src $PWD --reports-dir $PWD/reports
Scanning Containers Locally (Python Version)
To scan a Java project:
depscan --src <path> -o containertests/depscan-scan.json -t java
To scan the latest tag of a container image:
depscan --src shiftleft/scan-slim -o containertests/depscan-scan.json -t docker
To include license auditing:
depscan --src shiftleft/scan-slim -o containertests/depscan-scan.json -t docker,license
You can also specify the image using the sha256 digest:
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests/depscan-redmine.json -t docker
To scan a saved container image:
docker save -o /tmp/scanslim.tar shiftleft/scan-slim:latest
depscan --src /tmp/scanslim.tar -o reports/depscan-scan.json -t docker
Scanning Projects Locally (Docker Container)
You can use the dep-scan Docker image for scanning:
To scan with default settings:
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan --src /app --reports-dir /app/reports
To scan with custom environment variables:
docker run --rm \
-e VDB_HOME=/db \
-e GITHUB_TOKEN=<token> \
-v /tmp:/db \
-v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan --src /app --reports-dir /app/reports
Reachability Analysis
To perform reachability analysis:
For a Java project:
depscan --profile research -t java -i <source_directory> --reports-dir <reports_directory> --explain
For a JavaScript project:
depscan --profile research -t js -i <source_directory> --reports-dir <reports_directory> --explain
For a PHP project:
depscan --profile research -t php -i <source_directory> --reports-dir <reports_directory> --explain
Server Mode
Start the server:
docker compose up
depscan --server --server-host 0.0.0.0 --server-port 7070
Use the /cache
endpoint to cache the vulnerability database:
curl http://0.0.0.0:7070/cache
Scan a local directory or SBOM file:
curl --json '{"path": "/tmp/vulnerable-aws-koa-app/sbom_file.json", "type": "js"}' http://0.0.0.0:7070/scan
Scan a GitHub repository:
curl --json '{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}' http://0.0.0.0:7070/scan
Example CI/CD pipeline scenarios
1. Software Bill of Materials (SBOM)
Scenario: Generate SBOM for a Node.js project.
name: Generate SBOM for Node.js Project
on:
push:
branches:
- main
jobs:
generate-sbom:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Install Dependencies
run: npm install
- name: Generate SBOM
run: syft packages ./ --output json > sbom.json
- name: Upload SBOM Artifact
uses: actions/upload-artifact@v2
with:
name: sbom
path: sbom.json
2. Cryptography Bill of Materials (CBOM)
Scenario: Create a CBOM for a Java project.
name: Create CBOM for Java Project
on:
push:
branches:
- main
jobs:
generate-cbom:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Set Up JDK
uses: actions/setup-java@v2
with:
java-version: '11'
- name: Build Project
run: ./gradlew build
- name: Generate CBOM
run: cyclonedx-maven-plugin:generate
- name: Upload CBOM Artifact
uses: actions/upload-artifact@v2
with:
name: cbom
path: target/cyclonedx-bom.xml
3. Operations Bill of Materials (OBOM)
Scenario: Create an OBOM for a Docker container image.
name: Generate OBOM for Docker Image
on:
push:
branches:
- main
jobs:
generate-obom:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Build Docker Image
run: docker build -t my-image:latest .
- name: Generate OBOM
run: syft my-image:latest -o json > obom.json
- name: Upload OBOM Artifact
uses: actions/upload-artifact@v2
with:
name: obom
path: obom.json
4. Software-as-a-Service Bill of Materials (SaaSBOM)
Scenario: Generate a SaaSBOM for a Python project.
name: Generate SaaSBOM for Python Project
on:
push:
branches:
- main
jobs:
generate-saasbom:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Set Up Python
uses: actions/setup-python@v2
with:
python-version: '3.8'
- name: Install Dependencies
run: pip install -r requirements.txt
- name: Generate SaaSBOM
run: pip-audit --format json > saasbom.json
- name: Upload SaaSBOM Artifact
uses: actions/upload-artifact@v2
with:
name: saasbom
path: saasbom.json
5. Attestations (CDXA)
Scenario: Generate and sign SBOM documents with multiple standards.
name: Generate and Sign SBOM
on:
push:
branches:
- main
jobs:
generate-and-sign-sbom:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Generate SBOM
run: syft packages ./ --output json > sbom.json
- name: Sign SBOM
run: cosign sign --key cosign.key sbom.json
- name: Upload SBOM and Signature
uses: actions/upload-artifact@v2
with:
name: sbom-and-signature
path: |
sbom.json
sbom.json.sig
6. Vulnerability Disclosure Report (VDR)
Scenario: Use cdxgen
and dep-scan
to create a vulnerability disclosure report.
name: Generate Vulnerability Disclosure Report
on:
push:
branches:
- main
jobs:
generate-vdr:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v2
- name: Install Dependencies
run: |
npm install -g cdxgen dep-scan
- name: Generate SBOM
run: cdxgen -o sbom.json
- name: Scan for Vulnerabilities
run: dep-scan --sbom sbom.json --output vdr.json
- name: Upload VDR Artifact
uses: actions/upload-artifact@v2
with:
name: vdr
path: vdr.json
Compliance Check
We can customizing the Scan template structure, along with relevant commands and code snippets to generate a Software Bill of Materials (SBOM) compliant with different standards like FDA, NIST, SPDX, and CycloneDX.
For example use this command
npx cdxgen -o sbom_pcidss.json --template my-template-pcidss.json
Example Template my-template-pcidss.json
for PCI/DSS
{
"schemaVersion": "1.0.0",
"metadata": {
"componentType": "application",
"componentName": "PaymentGateway",
"version": "1.2.3",
"author": "Acme Corporation",
"license": "Proprietary",
"pciCompliance": "PCI DSS 3.2.1"
},
"components": [
{
"componentType": "library",
"componentName": "EncryptionLibrary",
"version": "4.5.0",
"licenses": ["Proprietary"],
"pciCompliance": "PCI DSS 3.2.1"
},
{
"componentType": "framework",
"componentName": "AuthenticationFramework",
"version": "2.1.0",
"licenses": ["Proprietary"],
"pciCompliance": "PCI DSS 3.2.1"
},
// ... other components ...
]
}
pciCompliance: Specifies the PCI DSS version the component or system adheres to.
encryptionLibrary: Includes details about the encryption library used, ensuring it's compliant with PCI DSS requirements.
authenticationFramework: Details the authentication framework used, which must meet PCI DSS's strong authentication requirements.
other components: Ensure that all components, including third-party libraries and frameworks, are PCI DSS compliant.
Cover by babydolll