SBOMs in Jenkins
A declarative Jenkinsfile that generates, scores and uploads an SBOM on every build. The token stays in the Jenkins credentials store and is exposed to one stage only, and the CLI attaches the branch, commit and build number by itself.
Before you start
- Install the CLI on your machine and run
sbombox login. - Pick or create the project this repository uploads to.
sbombox projects listshows the IDs; the project ID is not a secret. - Create an API token for that project: in SBOMBox open the project, then Settings, then API tokens. Tokens are scoped to one project, so a leaked token cannot touch any other.
- In Jenkins, add the token as a Secret text credential with the ID
sbombox-token, in the folder or job that runs this pipeline rather than globally where possible.
Keyless sign-in, which needs no stored token, is available on GitHub Actions and GitLab CI only. On other systems the token is the credential, so treat it like any other deploy secret: limit who can read it and rotate it on your usual schedule.
Add the pipeline
Commit this Jenkinsfile at the root of the repository and put in your project ID:
// Jenkinsfile
pipeline {
agent any // needs sh and curl; no root and no system Python
environment {
SBOMBOX_PROJECT = '0193c0de-...' // your project ID (not a secret)
SBOMBOX_FAIL_UNDER = '7' // minimum score, 0 turns the gate off
}
stages {
stage('Install SBOMBox') {
steps {
sh 'curl -fsSL https://sbombox.com/install.sh | SBOMBOX_NO_MODIFY_PATH=1 sh'
}
}
stage('Generate and score SBOM') {
steps {
sh '''
export PATH="$HOME/.local/bin:$PATH"
sbombox generate --output sbom.json
sbombox score sbom.json --format detailed
'''
}
}
// Upload before enforcing the gate, so failing runs are on record too.
stage('Upload to SBOMBox') {
steps {
withCredentials([string(credentialsId: 'sbombox-token', variable: 'SBOMBOX_TOKEN')]) {
sh '"$HOME/.local/bin/sbombox" push sbom.json ${TAG_NAME:+--version "$TAG_NAME"}'
}
}
}
stage('Enforce minimum score') {
steps {
sh '"$HOME/.local/bin/sbombox" score sbom.json --fail-under "$SBOMBOX_FAIL_UNDER"'
}
}
}
post {
always {
archiveArtifacts artifacts: 'sbom.json', allowEmptyArchive: true
}
}
}withCredentialsexposes the token only while the upload runs, and Jenkins masks it in the log.- The
shsteps use single quotes, so the shell expands the secret, not Groovy. Keep it that way if you edit them. - If you prefer one block,
SBOMBOX_TOKEN = credentials('sbombox-token')inenvironmentalso works, but makes the token available to every stage. - The agent needs
shandcurl. The installer fetches its own Python, so a plain Linux agent is enough.
What each run does
- Installs the CLI and a pinned, checksum-verified SBOM generator. Nothing needs root, and no system Python is needed.
- Generates the SBOM with the most accurate tool for the project: the package manager's own SBOM command when its lockfile is present (npm 9.5+, pnpm 11.1+, uv 0.9.11+), otherwise a native or universal generator. Dev dependencies are left out, so the SBOM describes what ships.
- Scores it from 0 to 10 and prints every check, so the log explains the score.
- Uploads it to the project, with the build number, repository, branch and commit (from the Git plugin's variables) detected from Jenkins automatically.
- Only then enforces the minimum score, so failing runs are on record too.
- Keeps
sbom.jsonwith the build as an artifact.
Uploads made with a token are recorded at provenance level P1: the branch, commit, build number and repository are attached as reported by the CI system. Keyless uploads from GitHub Actions and GitLab CI reach P2, where SBOMBox verifies the repository, commit and run itself.
Pull requests vs releases
In a multibranch pipeline, the same Jenkinsfile runs for branches, change requests and tags. By default every build uploads, so each change is on record. To upload only from main and release tags while still scoring and gating pull requests, add a when condition to the upload stage:
stage('Upload to SBOMBox') {
when {
anyOf {
branch 'main'
tag 'v*'
}
}
steps {
withCredentials([string(credentialsId: 'sbombox-token', variable: 'SBOMBOX_TOKEN')]) {
sh '"$HOME/.local/bin/sbombox" push sbom.json ${TAG_NAME:+--version "$TAG_NAME"}'
}
}
}- On a tag build, Jenkins sets
TAG_NAME, and the pipeline uploads with that release label. Tag builds need tag discovery enabled in the multibranch source. - Check compliance rulesets on releases with
sbombox compliance sbom.json -p cra-readinessin a further stage. - See the end-to-end guide for how pull request and release checks fit together.
Monorepos
Run one parallel stage per service. Each stage scans its own directory and uploads to its own project with that project's token. The install stage stays as it is, and each SBOM file has its own name so archiveArtifacts keeps them all (use sbom-*.json):
stage('SBOM per service') {
parallel {
stage('api') {
environment {
SERVICE = 'api'
SBOMBOX_PROJECT = '0193c0de-...'
}
steps {
withCredentials([string(credentialsId: 'sbombox-token-api', variable: 'SBOMBOX_TOKEN')]) {
sh '''
export PATH="$HOME/.local/bin:$PATH"
sbombox generate --dir "services/$SERVICE" --output "sbom-$SERVICE.json"
sbombox score "sbom-$SERVICE.json" --format detailed
sbombox push "sbom-$SERVICE.json"
sbombox score "sbom-$SERVICE.json" --fail-under "$SBOMBOX_FAIL_UNDER"
'''
}
}
}
stage('web') {
environment {
SERVICE = 'web'
SBOMBOX_PROJECT = '0193c0df-...'
}
steps {
// ... same as api, with credentialsId: 'sbombox-token-web'
}
}
}
}To report the services as one product, combine the uploads in SBOMBox. See Unify SBOMs.
Options
Set these in the environment block, or as job or folder properties.
| Variable | Default | What it does |
|---|---|---|
SBOMBOX_TOKEN | - | Project API token. Store it as a secret, never in the repository. Without it the upload step is skipped. |
SBOMBOX_PROJECT | - | Project ID to upload to. Not a secret. |
SBOMBOX_FAIL_UNDER | 7 in these examples | Minimum quality score, 0-10. The job fails below it, after the upload. 0 turns the gate off. |
SBOMBOX_GENERATOR | SBOMBox chooses | Force which generator runs, comma-separated in order of preference, e.g. npm-sbom or cyclonedx-npm,syft. |
SBOMBOX_VERSION | current version | Installer: pin the CLI version, e.g. 0.2.0, for reproducible builds. Versions below the supported minimum are refused. |
SBOMBOX_GENERATORS | auto | Installer: generators to install - syft, cyclonedx-py, cyclonedx-npm, cdxgen, auto, all or none. Add cdxgen for Java and Gradle. |
SBOMBOX_SYFT_VERSION | v1.57.1 | Installer: the syft version to install. It is checked against its published SHA-256. |
SBOMBOX_NO_MODIFY_PATH | - | Installer: set to 1 so CI shell profiles are left alone. Add $HOME/.local/bin to PATH yourself, as the examples do. |
SBOMBOX_API_URL | https://api.sbombox.com | Self-hosted SBOMBox: the API address, for both the installer and the CLI. |
Put installer variables in front of sh in the install stage, e.g. curl -fsSL https://sbombox.com/install.sh | SBOMBOX_VERSION=0.2.0 SBOMBOX_NO_MODIFY_PATH=1 sh. Agents that cannot reach sbombox.com can run a copy of the installer from an internal mirror; it still downloads its tools, so allow those downloads or mirror them too.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Could not find credentials entry with ID 'sbombox-token' | The credential does not exist, or is not visible from this job's folder. | Create it as Secret text with that ID in the job's folder or above it. |
sbombox: not found | PATH does not include $HOME/.local/bin, where the installer puts the CLI. | Call it as "$HOME/.local/bin/sbombox", or export PATH first, as the example does. |
Authentication failed: No CI identity token available. Set SBOMBOX_TOKEN, or run sbombox login. (exit 5) | SBOMBOX_TOKEN is not reaching the upload step. | Check the secret's name and that it is exposed to this job, as described in Before you start. |
Upload failed: Authentication failed: ... (exit 5) | The token was revoked, or belongs to another project. | Create a new token for this project and replace the secret. |
No project specified. (exit 2) | SBOMBOX_PROJECT is not set. | Set it in the pipeline file or as a CI variable. |
Network error: ... (exit 3) | The runner cannot reach the SBOMBox API. | Allow outbound HTTPS to api.sbombox.com, or set SBOMBOX_API_URL for a self-hosted deployment. |
Could not detect project ecosystem in <dir>: no supported manifest or lockfile. (exit 4) | The scan ran in a directory without a manifest. | Pass the right directory with sbombox generate --dir <path>. In a monorepo, run one job per service. |
No lockfile for npm: transitive dependencies may be missing | The lockfile is not committed, so versions are guessed. | Commit the lockfile (package-lock.json, uv.lock, go.sum and so on). See Languages. |
Generation failed: No SBOM generator found for ecosystems [...] (exit 4) | No generator for this ecosystem is installed on the runner. | Run the installer in the same job, or add one with SBOMBOX_GENERATORS, e.g. cdxgen for Java. |
Generation failed: SBOMBOX_GENERATOR names unknown generator(s) ... (exit 4) | A typo in SBOMBOX_GENERATOR. | Use a name from the list the message prints. |
Score 6.4 is below threshold 7.0. (exit 1) | The quality gate failed. The SBOM was already uploaded, so the run is on record. | Run sbombox score sbom.json --format detailed to see the weakest checks, or lower SBOMBOX_FAIL_UNDER while you improve it. |
| Exit 6, upgrade required | The pinned CLI version is below the minimum SBOMBox accepts. | Raise or remove SBOMBOX_VERSION. |