sbom-tools

Know exactly what changed in your software supply chain.

Semantic SBOM diff and analysis tool. Compare, validate, and assess the quality of SBOMs across CycloneDX and SPDX formats.

Features

• Semantic Diffing — Component-level change detection (added, removed, modified), dependency graph diffing, vulnerability tracking, and license change analysis
• Multi-Format Support — CycloneDX (1.4–1.6) and SPDX (2.2–2.3) in JSON, XML, tag-value, and RDF/XML with automatic format detection
• Streaming Parser — Memory-efficient parsing for very large SBOMs (>512MB) with progress reporting
• Fuzzy Matching — Multi-tier matching engine using exact PURL match, alias lookup, ecosystem-specific normalization, and string similarity with adaptive thresholds and LSH indexing
• Vulnerability Enrichment — Integration with OSV and KEV databases to track new and resolved vulnerabilities (feature-gated)
• EOL Detection — End-of-life status for components via endoflife.date API with TUI visualization and compliance integration (feature-gated)
• Quality Assessment — Score SBOMs against compliance standards including NTIA, FDA, CRA (Cyber Resilience Act), NIST SSDF, and EO 14028
• Fleet Comparison — 1:N baseline comparison, timeline analysis across versions, and NxN matrix analysis
• Incremental Diff — Track changes across SBOM versions with drift detection and divergence analysis
• Multiple Output Formats — JSON, SARIF, HTML, Markdown, CSV, table, side-by-side, summary, and an interactive TUI
• Ecosystem-Aware — Configurable per-ecosystem normalization rules, typosquat detection, and cross-ecosystem package correlation

Installation

From crates.io

cargo install sbom-tools

Build from source

Requires Rust 1.86+.

# Release build (includes vulnerability enrichment by default)
cargo build --release

# Without enrichment (lightweight build)
cargo build --release --no-default-features

The binary is placed at target/release/sbom-tools.

Usage

# Compare two SBOMs
sbom-tools diff old-sbom.json new-sbom.json

# View SBOM contents interactively
sbom-tools view sbom.json

# Search for components across SBOMs
sbom-tools query "log4j" --version "<2.17.0" fleet/*.json

# Validate compliance
sbom-tools validate sbom.json --standard ntia

# Assess quality
sbom-tools quality sbom.json --profile security --recommendations

Diff

sbom-tools diff old-sbom.json new-sbom.json

Compares two SBOMs and reports added, removed, and modified components with version diffs, vulnerability changes, and license deltas.

sbom-tools diff old-sbom.json new-sbom.json --enrich-vulns

SBOM Diff: old-sbom.json → new-sbom.json

Components: 142 → 145 (+5 added, -2 removed, ~3 modified)

 + pkg:npm/express@4.19.2           (added)
 + pkg:npm/zod@3.23.8               (added)
 + pkg:npm/opentelemetry-api@1.9.0  (added)
 + pkg:npm/ws@8.18.0                (added)
 + pkg:npm/pino@9.3.2               (added)
 - pkg:npm/body-parser@1.20.2       (removed)
 - pkg:npm/winston@3.11.0           (removed)
 ~ pkg:npm/lodash@4.17.20 → 4.17.21  (version bump)
 ~ pkg:npm/axios@1.6.0 → 1.7.4       (version bump)
 ~ pkg:npm/semver@7.5.4 → 7.6.3      (version bump)

Vulnerabilities:
 ✗ CVE-2024-29041 (HIGH) — express <4.19.2  [resolved by upgrade]
 ✗ CVE-2024-4068  (HIGH) — braces <3.0.3    [new, in transitive dep]

License changes: none

View

sbom-tools view sbom.json

Launches an interactive TUI with component tree, vulnerability details, license breakdown, and dependency graph.

Validate

sbom-tools validate sbom.json --standard ntia
sbom-tools validate sbom.json --standard cra -o sarif -O results.sarif

Checks an SBOM against a compliance standard and reports missing fields or failing requirements.

Quality

sbom-tools quality sbom.json --profile security --recommendations

Scores an SBOM from 0–100 using a weighted profile. Use --min-score to fail CI if quality drops below a threshold.

Query

sbom-tools query "log4j" sbom1.json sbom2.json sbom3.json

Search for components across multiple SBOMs by name, version, ecosystem, license, supplier, or vulnerability ID. Answers the "where is Log4j?" question across your entire SBOM fleet.

$ sbom-tools query "log4j" --version "<2.17.0" fleet/*.cdx.json

Query: "log4j" AND version=<2.17.0 across 5 SBOMs (1247 total components)

COMPONENT  VERSION  ECOSYSTEM  LICENSE     VULNS  FOUND IN
log4j      2.14.0   maven      Apache-2.0      1  firmware-v1, device-a
log4j      2.14.1   maven      Apache-2.0      1  gateway

2 components found across 5 SBOMs

$ sbom-tools query --ecosystem pypi *.json --group-by-sbom

Query: ecosystem=pypi across 2 SBOMs (33 total components)

── backend-v3 (4 matches / 18 components) ──
  django 4.2.11 (pypi)
  flask 3.0.2 (pypi)
  celery 5.3.6 (pypi)
  numpy 1.26.4 (pypi)

── backend-v2 (4 matches / 15 components) ──
  django 3.2.23 (pypi)
  flask 2.2.5 (pypi)
  celery 5.3.4 (pypi)
  numpy 1.24.4 (pypi)

8 components found across 2 SBOMs

Fleet comparison

Compare multiple SBOMs across a project portfolio:

# Compare a baseline against multiple targets (1:N)
sbom-tools diff-multi baseline.json target1.json target2.json target3.json

# Track evolution over time (provide SBOMs in chronological order)
sbom-tools timeline v1.json v2.json v3.json

# All-pairs comparison matrix (NxN)
sbom-tools matrix sbom1.json sbom2.json sbom3.json

Shell completions

sbom-tools completions bash > ~/.local/share/bash-completion/completions/sbom-tools
sbom-tools completions zsh > ~/.zfunc/_sbom-tools
sbom-tools completions fish > ~/.config/fish/completions/sbom-tools.fish

Global flags

Interactive TUI

Both diff and view commands launch an interactive terminal UI by default when connected to a TTY.

Diff Mode

Compare two SBOMs with semantic change detection across 9 tabs.

Summary — Overall change score with component, vulnerability, and compliance breakdowns at a glance.

Components — Every added, removed, and modified component with version diffs and ecosystem tags.

View Mode

Explore a single SBOM interactively across 8 tabs.

Overview — SBOM metadata, component statistics, and vulnerability summary.

Components — Expandable component tree grouped by ecosystem.

Navigation

Output Formats

Select with -o / --output:

CI/CD Integration

Use sbom-tools in CI pipelines to gate deployments on SBOM changes, new vulnerabilities, or quality regressions.

# Fail if any components changed
sbom-tools diff old.json new.json --fail-on-change -o summary

# Fail if new vulnerabilities are introduced, output SARIF for dashboards
sbom-tools diff old.json new.json --fail-on-vuln --enrich-vulns -o sarif -O results.sarif

# Fail if quality score drops below 80
sbom-tools quality sbom.json --profile security --min-score 80 -o json

# Validate CRA compliance
sbom-tools validate sbom.json --standard cra -o sarif -O compliance.sarif

# Check for vulnerable Log4j versions across all SBOMs (exits 1 if found)
sbom-tools query "log4j" --version "<2.17.0" fleet/*.json -o json

name: SBOM Check

on:
  pull_request:
    paths: ['sbom.json']

jobs:
  sbom-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Install sbom-tools
        run: cargo install sbom-tools

      - name: Diff SBOM against main
        run: |
          git show HEAD~1:sbom.json > /tmp/old-sbom.json
          sbom-tools diff /tmp/old-sbom.json sbom.json \
            --fail-on-vuln --enrich-vulns \
            -o sarif -O results.sarif

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Exit codes

Configuration

sbom-tools looks for configuration in the following order:

1. CLI argument: --ecosystem-rules <path>
2. Environment variable: SBOM_TOOLS_ECOSYSTEM_RULES
3. Project local: .sbom-tools/ecosystem-rules.yaml
4. User config: ~/.config/sbom-tools/ecosystem-rules.yaml

See examples/ecosystem-rules.yaml for a full configuration example covering per-ecosystem normalization, aliases, matching presets, and enrichment settings.

Matching presets

Project Structure

src/
├── cli/          Command handlers (diff, view, validate, quality, query, fleet commands)
├── config/       YAML/JSON config with presets, validation, schema generation
├── model/        Canonical SBOM representation (NormalizedSbom, Component, CanonicalId)
├── parsers/      Format detection + parsing (streaming for >512MB)
├── matching/     Multi-tier fuzzy matching (PURL, alias, ecosystem, adaptive, LSH)
├── diff/         Semantic diffing engine with graph support + incremental diff
├── enrichment/   OSV/KEV vulnerability data + EOL detection (feature-gated), file cache with TTL
├── quality/      NTIA/FDA/CRA/NIST SSDF/EO 14028 compliance scoring
├── pipeline/     parse → enrich → diff → report orchestration
├── reports/      Output format generators + streaming reporter
└── tui/          Ratatui-based interactive UI

See docs/ARCHITECTURE.md for detailed module responsibilities and data flow.

Testing

# Run all tests
cargo test

# Run benchmarks
cargo bench

Documentation

• Architecture overview
• Pipeline diagrams
• Releases and changelog

Contributing

Contributions are welcome! Please open an issue to discuss your idea before submitting a pull request. Make sure cargo test passes and follow the existing code style.

License

MIT