The SBOM workflow, end to end
One pipeline for every repository: generate the SBOM where the code is built, score and check it, upload it with verified provenance, then keep watching it for new vulnerabilities. This page walks through each stage on a real project.
The six stages
- Developer machinepre-commitCatches a low score before the commit. Offline, uploads nothing.
sbombox check - Pull requestCI on every PRGenerates and scores the SBOM, checks compliance, fails below your minimum.
fail-under: 7 - Release buildCI on main or a tagGenerates the SBOM of what ships and uploads it with the repository, commit and run attached.
sbombox push - IngestSBOMBoxParses, validates, scores and evaluates policies, then stores the file content-addressed and immutable.
- MonitorSBOMBox, nightlyMatches every stored SBOM against OSV, GHSA, NVD and CISA KEV. VEX statements suppress false positives.
- Report and shareSBOMBoxCRA evidence per release, Trust Center, notifications, exports and the audit log.
SBOMBox never clones your source code. Generation runs on your machines and CI runners; only the SBOM and its provenance are uploaded. See how CI sign-in works and the CLI reference.
Set it up once
From the root of any repository, after you install the CLI:
sbombox login # sign in through your browser
sbombox init # pick a project, trust this repo's CI, write the workflowsbombox init writes .github/workflows/sbombox.yml on GitHub, or prints the two lines to add to .gitlab-ci.yml. On GitHub and GitLab, CI uploads keylessly: the job proves which repository, branch and run it is, so there is no token to store or rotate. Other CI systems use a project token: see Jenkins, Azure Pipelines, Bitbucket and CircleCI.
Walk through it on a real project
A Node.js service with a committed package-lock.json, two runtime dependencies and one dev dependency. Output below is unedited.
1. Generate. SBOMBox sees the lockfile and npm 9.5 or later, so it uses npm's own npm sbom command. Nothing else is installed.
$ sbombox generate
Detected: npm - generated with npm sbom
SBOM written to sbom.json2. Score. A 0-10 quality score across eight categories. --format detailed shows every check.
$ sbombox score sbom.json --fail-under 7
Score: 8.1/10 - Grade: B3. Check compliance. The same file against the EU Cyber Resilience Act readiness ruleset (or ntia, cisa, bsi; see rulesets).
$ sbombox compliance sbom.json -p cra
│ cra-1 │ pass │ 2/2 components have a name. │
│ cra-3 │ pass │ 2/2 components have a purl. │
│ cra-4 │ fail │ 0/2 components have supplier information. │
│ cra-5 │ pass │ 2/2 components have hash digests. │
│ cra-6 │ pass │ 2/2 components have license information. │
│ cra-7 │ pass │ Dependency graph has 3 entries. │
...
Overall: MINOR GAPS - required 8.89/10, overall 9.11/10The one gap is supplier information: no package manager records who supplies a package. SBOMBox reports it rather than guessing. Provenance explains how to fill it in.
4. Gate locally (optional). The same check as a pre-commit hook. A failing commit shows the three weakest checks:
$ sbombox check --fail-under 9
Detected: npm - generated with npm sbom
SBOM score 8.1/10 (grade B), 2 components
lowest: cpe_coverage 0/2 - Components with a CPE identifier.
lowest: supplier_coverage 0/2 - Components with a named supplier.
lowest: author_coverage 0/2 - Components with a declared author.
Score 8.1 is below 9.0. Run `sbombox score <sbom> --format detailed` (use --keep to save the SBOM) to see why.5. Upload from CI. The GitHub Action or GitLab component runs steps 1-3 and uploads. Uploads happen before the score gate fails the job, so failing runs are on record too. Each upload is recorded in your organization's audit log with the verified repository, commit and run.
How SBOMBox picks the generator
The package manager's own SBOM command reads exactly what the lockfile resolved, and needs nothing extra installed on the runner. SBOMBox uses it first when the lockfile is committed and the tool is new enough, then falls back to the native CycloneDX tool, then to a universal scanner.
| Lockfile | Runs first | Then | Score of the result |
|---|---|---|---|
package-lock.json | npm sbom (npm 9.5+) | cyclonedx-npm, cdxgen, syft | 8.1/10 (B) |
pnpm-lock.yaml | pnpm sbom (pnpm 11.1+) | pnpm sbom --lockfile-only, cdxgen, syft | 7.9/10 (C), after SBOMBox adds hashes from the lockfile |
uv.lock | uv export --format cyclonedx1.5 (uv 0.9.11+) | cyclonedx-py, cdxgen, syft | 6.6/10 (D), after SBOMBox adds hashes; uv records no licenses |
poetry.lock, Pipfile.lock, requirements.txt | cyclonedx-py | cdxgen, syft | Depends on the project |
Cargo.lock, go.sum | cargo-cyclonedx, cyclonedx-gomod | cdxgen, syft | Depends on the project |
| Anything else, or several languages | cdxgen if installed, else syft | - | Depends on the project |
Release SBOMs leave dev dependencies out. To force a generator, set SBOMBOX_GENERATOR, for example SBOMBOX_GENERATOR=cyclonedx-npm or SBOMBOX_GENERATOR=npm-sbom,syft to set an order. An unknown name stops with the list of valid ones. Per-language details: JavaScript, Python, Java, Go, Rust, .NET, Ruby, PHP, containers.
Gates and policies
| Control | Set it in | Effect |
|---|---|---|
| Minimum score | fail-under input, or sbombox score --fail-under | Fails the job below the score. Start at 0, raise it once teams have fixed their lockfiles. |
| Compliance rulesets | profiles input, or sbombox compliance -p | Shows NTIA, CISA, BSI or CRA results in the job summary. |
| Organization policies | SBOMBox project settings | License allow and deny lists, minimum scores and required metadata, evaluated on every upload. |
| Required check | GitHub rulesets or GitLab merge checks | Makes the SBOM job mandatory before merge. |
Roll it out across an organization
- Start with generate and upload only. Every repository gets an SBOM on every push, with
fail-under: 0. Nobody is blocked. - Commit lockfiles everywhere. Without one, versions are guessed and transitive dependencies go missing;
sbombox generatewarns about it. - Use one central workflow. A reusable GitHub workflow or a GitLab include, pinned by commit, so a change is made once. See GitHub Actions and GitLab CI.
- Raise the gate per team. Move
fail-underto 6, then 7, once the job summary shows teams pass. - Make it required. Add the SBOM job as a required check for release branches.
- Mirror for locked-down runners. Point the installer at an internal mirror with the Action's
installer-urlinput, and pinversionfor reproducible builds.
What SBOMBox does not do for you
- It does not invent supplier data. Add it in your generator's configuration or from vendor records (provenance).
- It does not sign the SBOM file. It verifies who uploaded it. To sign the file itself, add an attestation step such as
actions/attest(withsbom-path) orcosign attest; see GitHub Actions. - It does not include dev dependencies by default. Run the package manager's command yourself with dev dependencies, then
sbombox pushthe file.
Already generating SBOMs with your own tools? Keep them. sbombox push accepts any CycloneDX or SPDX file. Unify SBOMs across stacks shows how to standardize them, with or without SBOMBox.
Frequently asked questions
Do I need to install a generator?
Not for npm 9.5+, pnpm 11.1+ or uv 0.9.11+ projects with a committed lockfile: the package manager makes the SBOM. The installer adds syft and cyclonedx-py for everything else, and cyclonedx-npm only on machines with an older npm.
What happens when the lockfile is out of date?
The package manager's command fails with a clear message, for example: npm sbom found packages missing from, or invalid in, package-lock.json. Run npm install, commit package-lock.json, and try again. SBOMBox then tries the next generator in the order above.
Can pull requests from forks upload?
No. Forked pull requests get no identity token, so with the default upload: auto the SBOM is generated and scored but not uploaded, and the job says why.
Which format should we standardize on?
CycloneDX 1.6 JSON is the default and what SBOMBox generates. Use --format spdx when a customer or regulator asks for SPDX 2.3.