Guides

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

An organization-wide SBOM standard
RuleStandardWhy
1. FormatCycloneDX 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 truthGenerate from the committed lockfile, in CI, for every release.Lockfiles pin transitive versions; laptops do not produce release evidence.
3. ScopeRuntime 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 componentType application (or container), name = product name, version = release tag.Lets you find every SBOM for a product version.
5. IdentityEvery component has a purl. Hashes where the lockfile has them.purls are what vulnerability databases match on.
6. Quality floorSchema-valid, at least one component, minimum quality score agreed per product.Catches empty or broken SBOMs before anyone relies on them.
7. IntegritySign or attest the SBOM, bound to the artifact digest.Proves which build the SBOM describes.
8. RetentionImmutable 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

Generator matrix (all produce CycloneDX JSON)
EcosystemUseWatch out for
npmnpm sbom --sbom-format cyclonedx --omit dev --package-lock-onlyWithout --omit dev, dev dependencies are marked required when node_modules exists. CycloneDX 1.5 only.
pnpmpnpm sbom --sbom-format cyclonedx --prodNo component hashes; copy them from pnpm-lock.yaml integrity values. Prints NDJSON without --out.
Yarncdxgen or syftNeither npm's nor pnpm's command reads yarn.lock.
Python (uv)uv export --format cyclonedx1.5 --all-packages --no-devPreview feature. No licenses. Hashes only on distribution references. Empty without --all-packages at a workspace root.
Python (Poetry, pip)cyclonedx-pyNo dependency graph from requirements.txt.
Java, KotlinCycloneDX Maven or Gradle plugin, or cdxgenBuild-tool plugins see the resolved classpath; scanners guess.
Go, Rustcyclonedx-gomod, cargo-cyclonedx, or syftScan the built binary too: it shows what was linked in.
.NET, Ruby, PHPCycloneDX tool for the ecosystem, or syftCommit packages.lock.json, Gemfile.lock, composer.lock.
Container imagessyft on the image, or BuildKit --sbom=trueKeep 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 spdxjson

A 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 high

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

Do-it-yourself step and the SBOMBox equivalent
StepOpen-source wayWith SBOMBox
Entry pointsbom.sh in a shared CI templatesbombox generate: same lockfile-first choice, plus fallbacks and hash backfill for pnpm and uv
FormatAgree on CycloneDX 1.6CycloneDX 1.6 by default, --format spdx for SPDX 2.3; uploads of either are normalized
Validate and scorecyclonedx validate, sbomqsValidated and scored on every upload; sbombox score locally
ComplianceManual checklistsNTIA, CISA, BSI TR-03183-2 and CRA readiness rulesets
ProvenanceSigned attestationsKeyless upload: the CI job's identity is verified, recorded and audited
StorageRegistry or object storage with retention rulesContent-addressed, immutable storage per project and release
MonitoringNightly grype or osv-scanner jobsNightly matching against OSV, GHSA, NVD and CISA KEV, with VEX
SharingEmail files to customersTrust 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.