Guides

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

  1. Developer machinepre-commitCatches a low score before the commit. Offline, uploads nothing.sbombox check
  2. Pull requestCI on every PRGenerates and scores the SBOM, checks compliance, fails below your minimum.fail-under: 7
  3. Release buildCI on main or a tagGenerates the SBOM of what ships and uploads it with the repository, commit and run attached.sbombox push
  4. IngestSBOMBoxParses, validates, scores and evaluates policies, then stores the file content-addressed and immutable.
  5. MonitorSBOMBox, nightlyMatches every stored SBOM against OSV, GHSA, NVD and CISA KEV. VEX statements suppress false positives.
  6. Report and shareSBOMBoxCRA evidence per release, Trust Center, notifications, exports and the audit log.
Every stage is optional except generate and upload. Start with those two and add gates as teams are ready.

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 workflow

sbombox 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.json

2. 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: B

3. 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/10

The 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.

Generator order for a single-language project (measured 16 November 2026)
LockfileRuns firstThenScore of the result
package-lock.jsonnpm sbom (npm 9.5+)cyclonedx-npm, cdxgen, syft8.1/10 (B)
pnpm-lock.yamlpnpm sbom (pnpm 11.1+)pnpm sbom --lockfile-only, cdxgen, syft7.9/10 (C), after SBOMBox adds hashes from the lockfile
uv.lockuv export --format cyclonedx1.5 (uv 0.9.11+)cyclonedx-py, cdxgen, syft6.6/10 (D), after SBOMBox adds hashes; uv records no licenses
poetry.lock, Pipfile.lock, requirements.txtcyclonedx-pycdxgen, syftDepends on the project
Cargo.lock, go.sumcargo-cyclonedx, cyclonedx-gomodcdxgen, syftDepends on the project
Anything else, or several languagescdxgen 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

Where each control lives
ControlSet it inEffect
Minimum scorefail-under input, or sbombox score --fail-underFails the job below the score. Start at 0, raise it once teams have fixed their lockfiles.
Compliance rulesetsprofiles input, or sbombox compliance -pShows NTIA, CISA, BSI or CRA results in the job summary.
Organization policiesSBOMBox project settingsLicense allow and deny lists, minimum scores and required metadata, evaluated on every upload.
Required checkGitHub rulesets or GitLab merge checksMakes the SBOM job mandatory before merge.

Roll it out across an organization

What SBOMBox does not do for you

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.