SBOMs in Azure Pipelines
One azure-pipelines.yml that generates, scores and uploads an SBOM on every pull request, push to main and release tag. The token lives in a secret variable group and is mapped into the one step that needs it.
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 Azure DevOps, open Pipelines, Library, and create a variable group named
sbombox. AddSBOMBOX_TOKEN, select the lock icon to make it secret, and save. Allow your pipeline to use the group when it first runs. You can also link the group to Azure Key Vault.
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 azure-pipelines.yml and put in your project ID:
# azure-pipelines.yml
trigger:
branches:
include: [main]
tags:
include: ["v*"]
pr:
branches:
include: [main]
pool:
vmImage: ubuntu-24.04
variables:
- group: sbombox # holds SBOMBOX_TOKEN as a secret
- name: SBOMBOX_PROJECT
value: 0193c0de-... # your project ID (not a secret)
- name: SBOMBOX_FAIL_UNDER
value: "7" # minimum score, 0 turns the gate off
steps:
- checkout: self
- bash: |
set -eu
curl -fsSL https://sbombox.com/install.sh | SBOMBOX_NO_MODIFY_PATH=1 sh
echo "##vso[task.prependpath]$HOME/.local/bin"
displayName: Install SBOMBox CLI
- bash: |
set -eu
sbombox generate --output sbom.json
sbombox score sbom.json --format detailed
displayName: Generate and score SBOM
# Upload before enforcing the gate, so failing runs are on record too.
- bash: |
set -eu
# An unset secret arrives as the unexpanded macro text, not as empty.
case "${SBOMBOX_TOKEN:-}" in ''|'$('*)
echo "No SBOMBOX_TOKEN (for example a pull request from a fork). Skipping upload."
exit 0;;
esac
case "$BUILD_SOURCEBRANCH" in
refs/tags/*) sbombox push sbom.json --version "${BUILD_SOURCEBRANCH#refs/tags/}" ;;
*) sbombox push sbom.json ;;
esac
displayName: Upload to SBOMBox
env:
SBOMBOX_TOKEN: $(SBOMBOX_TOKEN) # secrets are only visible to scripts when mapped
- bash: sbombox score sbom.json --fail-under "$SBOMBOX_FAIL_UNDER"
displayName: Enforce minimum score
- publish: sbom.json
artifact: sbom
condition: succeededOrFailed()
displayName: Keep the SBOM with this run- Secret variables are not passed to scripts automatically. The
env:mapping on the upload step is what makesSBOMBOX_TOKENavailable, and only to that step. - Never pass the token on the command line or echo it. Azure masks secrets in logs, but environment variables are the safe route.
- Plain variables such as
SBOMBOX_PROJECTandSBOMBOX_FAIL_UNDERreach every script as environment variables of the same name.
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 ID, repository, branch and commit detected from Azure Pipelines 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
- The
prtrigger scores and gates every pull request intomain. Pull requests from forks get no secrets by default, so the upload is skipped there and the gate still runs. - The
triggersection runs on pushes tomainand on tags that start withv. Tag builds upload with the tag as the release label. - Azure reports the branch as a full ref, such as
refs/heads/main, and the CLI records it as given.
To check a compliance ruleset on releases only, add a step with a condition:
- bash: |
sbombox compliance sbom.json -p cra-readiness
displayName: Check CRA readiness
condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/tags/'))See the end-to-end guide for the full flow.
Monorepos
Use a job matrix with one entry per service. Each entry sets the directory and its own project; keep the upload, gate and publish steps as above, and give the published artifact a distinct name such as sbom-$(SERVICE):
strategy:
matrix:
api:
SERVICE: api
SBOMBOX_PROJECT: 0193c0de-...
web:
SERVICE: web
SBOMBOX_PROJECT: 0193c0df-...
steps:
# ... install step as above, then:
- bash: |
set -eu
sbombox generate --dir "services/$SERVICE" --output sbom.json
sbombox score sbom.json --format detailed
displayName: Generate and score SBOMProject API tokens are scoped to one project, so put one token per project in the variable group, e.g. SBOMBOX_TOKEN_API and SBOMBOX_TOKEN_WEB, and map the right one in each entry's upload step. To report the services as one product, see Unify SBOMs.
Options
Set these under variables:, in the variable group, or in the pipeline settings.
| 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 step, e.g. SBOMBOX_VERSION=0.2.0. On self-hosted agents that cannot reach sbombox.com, 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 |
|---|---|---|
No SBOMBOX_TOKEN ... Skipping upload. on your own branches | The variable group is not linked, the secret has another name, or the pipeline is not yet allowed to use the group. | Check the group: name, the secret's name, and the group's pipeline permissions. |
sbombox: command not found | The install step's prependpath line is missing. | Keep the ##vso[task.prependpath] line in the install step. |
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. |