Unify SBOMs across every stack
Ten languages should not mean ten SBOM processes. This guide sets one standard that every team can meet with open-source tools, then shows which parts SBOMBox takes over if you want it to. Nothing here requires SBOMBox.
Why SBOMs get messy in a polyglot company
Each ecosystem has its own tool, and each tool makes different choices: CycloneDX or SPDX, which spec version, whether dev dependencies are included, how the root component is named, whether hashes and licenses are filled in. In our tests on 16 November 2026, three package managers' own commands scored 8.1, 6.0 and 4.8 out of 10 on comparable projects before any clean-up. Consumers of those SBOMs, such as security, legal, customers and regulators, then see three different shapes of document.
The fix is not one tool. It is one contract that every tool's output has to meet, and one entry point that every repository calls.
The contract: eight rules
| Rule | Standard | Why |
|---|---|---|
| 1. Format | CycloneDX 1.6 JSON. Convert to SPDX 2.3 only at the edge, when a customer asks. | One schema for every downstream tool. CycloneDX also carries VEX and dependency graphs. |
| 2. Source of truth | Generate from the committed lockfile, in CI, for every release. | Lockfiles pin transitive versions; laptops do not produce release evidence. |
| 3. Scope | Runtime dependencies only in the release SBOM. Dev and test dependencies in a separate build SBOM if you need one. | The release SBOM describes what ships. |
| 4. Root component | Type application (or container), name = product name, version = release tag. | Lets you find every SBOM for a product version. |
| 5. Identity | Every component has a purl. Hashes where the lockfile has them. | purls are what vulnerability databases match on. |
| 6. Quality floor | Schema-valid, at least one component, minimum quality score agreed per product. | Catches empty or broken SBOMs before anyone relies on them. |
| 7. Integrity | Sign or attest the SBOM, bound to the artifact digest. | Proves which build the SBOM describes. |
| 8. Retention | Immutable storage, keyed by product, version and digest, for the support period. | CRA, FDA and customers ask for SBOMs of old releases. |
One entry point for every repository
Give every repository the same script and call it from every pipeline. It picks the package manager's own command when the lockfile is present, else syft, always writes CycloneDX JSON, and refuses to produce an empty SBOM. Tested with npm 12.2, pnpm 11.28 and uv 0.12.
#!/bin/sh
# sbom.sh - one SBOM entry point for every repository.
# Usage: sbom.sh [project-dir] [output-file] (default: . sbom.cdx.json)
# Uses the package manager's own SBOM command when its lockfile is present,
# else syft. Always writes CycloneDX JSON and leaves dev dependencies out.
set -eu
dir="${1:-.}"
out="${2:-sbom.cdx.json}"
case "$out" in /*) ;; *) out="$PWD/$out" ;; esac
cd "$dir"
if [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then
tool="npm sbom"
npm sbom --sbom-format cyclonedx --sbom-type application \
--omit dev --package-lock-only > "$out"
elif [ -f pnpm-lock.yaml ]; then
tool="pnpm sbom"
pnpm sbom --sbom-format cyclonedx --sbom-type application \
--prod --out "$out"
elif [ -f uv.lock ]; then
tool="uv export"
uv export --format cyclonedx1.5 --frozen --all-packages \
--no-dev --output-file "$out" > /dev/null
else
tool="syft"
syft "dir:." -o "cyclonedx-json=$out"
fi
# Fail loudly on an empty SBOM instead of shipping one.
if ! tr -d ' \t\r\n' < "$out" | grep -q '"components":\[{'; then
echo "sbom.sh: $tool wrote an SBOM with no components: $out" >&2
exit 1
fi
echo "sbom.sh: $tool -> $out"Ship it in a shared CI template rather than copying it into each repository, so a fix lands everywhere at once. Pin each tool's version in that template.
Pick one generator per ecosystem
| Ecosystem | Use | Watch out for |
|---|---|---|
| npm | npm sbom --sbom-format cyclonedx --omit dev --package-lock-only | Without --omit dev, dev dependencies are marked required when node_modules exists. CycloneDX 1.5 only. |
| pnpm | pnpm sbom --sbom-format cyclonedx --prod | No component hashes; copy them from pnpm-lock.yaml integrity values. Prints NDJSON without --out. |
| Yarn | cdxgen or syft | Neither npm's nor pnpm's command reads yarn.lock. |
| Python (uv) | uv export --format cyclonedx1.5 --all-packages --no-dev | Preview feature. No licenses. Hashes only on distribution references. Empty without --all-packages at a workspace root. |
| Python (Poetry, pip) | cyclonedx-py | No dependency graph from requirements.txt. |
| Java, Kotlin | CycloneDX Maven or Gradle plugin, or cdxgen | Build-tool plugins see the resolved classpath; scanners guess. |
| Go, Rust | cyclonedx-gomod, cargo-cyclonedx, or syft | Scan the built binary too: it shows what was linked in. |
| .NET, Ruby, PHP | CycloneDX tool for the ecosystem, or syft | Commit packages.lock.json, Gemfile.lock, composer.lock. |
| Container images | syft on the image, or BuildKit --sbom=true | Keep the image SBOM separate from the application SBOM, or merge them hierarchically. |
Per-language commands are in the language guides.
Normalize, merge and convert
The CycloneDX CLI does the mechanical work:
# Validate against the schema; non-zero exit on errors
cyclonedx validate --input-file sbom.cdx.json --fail-on-errors
# One SBOM per product: nest service SBOMs under the product
cyclonedx merge --hierarchical --name payments --version 4.2.0 \
--input-files api.cdx.json worker.cdx.json image.cdx.json \
--output-file payments-4.2.0.cdx.json
# SPDX for a customer that asks for it
cyclonedx convert --input-file payments-4.2.0.cdx.json \
--output-file payments-4.2.0.spdx.json --output-format spdxjsonA hierarchical merge needs each input to describe its subject in metadata.component, which is why rule 4 matters.
Check quality before anyone relies on it
Schema-valid is not the same as useful. An SBOM with no hashes, licenses or suppliers passes validation and fails every regulator's checklist. Score it in CI with an open-source scorer such as sbomqs (sbomqs score sbom.cdx.json), or with the free SBOM checker, and fail below an agreed minimum.
Sign, store and monitor
# Attach the SBOM to the image as a signed attestation
cosign attest --type cyclonedx --predicate sbom.cdx.json "$IMAGE@$DIGEST"
# Or store it next to the image in the registry
oras attach --artifact-type application/vnd.cyclonedx+json "$IMAGE@$DIGEST" sbom.cdx.json
# Check it for known vulnerabilities (re-run on a schedule, not only at build time)
osv-scanner scan source -L sbom.cdx.json
grype sbom:./sbom.cdx.json --fail-on highRe-scanning matters more than scanning: most vulnerabilities in a release are published after it ships. Keep every release's SBOM and run the scanner against all of them nightly. Record your exploitability decisions as VEX so the same false positive is not triaged twice (what VEX is).
The same standard with SBOMBox
Everything above works without SBOMBox. If you would rather not run and maintain each piece, this is what it replaces. You can adopt it one row at a time: keep your generators and send their output with sbombox push.
| Step | Open-source way | With SBOMBox |
|---|---|---|
| Entry point | sbom.sh in a shared CI template | sbombox generate: same lockfile-first choice, plus fallbacks and hash backfill for pnpm and uv |
| Format | Agree on CycloneDX 1.6 | CycloneDX 1.6 by default, --format spdx for SPDX 2.3; uploads of either are normalized |
| Validate and score | cyclonedx validate, sbomqs | Validated and scored on every upload; sbombox score locally |
| Compliance | Manual checklists | NTIA, CISA, BSI TR-03183-2 and CRA readiness rulesets |
| Provenance | Signed attestations | Keyless upload: the CI job's identity is verified, recorded and audited |
| Storage | Registry or object storage with retention rules | Content-addressed, immutable storage per project and release |
| Monitoring | Nightly grype or osv-scanner jobs | Nightly matching against OSV, GHSA, NVD and CISA KEV, with VEX |
| Sharing | Email files to customers | Trust Center and per-release CRA evidence |
Start with the end-to-end workflow, or install the CLI and run sbombox init.
Frequently asked questions
Should we pick CycloneDX or SPDX?
Pick one for internal use and convert at the edge. CycloneDX fits security workflows (VEX, dependency graph, services); SPDX is common for license compliance. See CycloneDX vs SPDX.
One SBOM per repository or per product?
Generate per repository or service, then merge hierarchically into one SBOM per product release. Customers and regulators ask about products, not repositories.
Is a package manager's own SBOM command good enough?
It is the most faithful view of the dependency tree, but none we tested fills in suppliers, and pnpm and uv leave out hashes or licenses. Add a quality check and fill the gaps before you share the file.