sbom-report

Zero-dependency CLI tool that generates self-contained static HTML reports from SPDX JSON SBOMs, with an optional Grype vulnerability overlay.

Built for teams using Syft and Grype who want clean, interactive reports without the rest of the enterprise toolchain.

Features

• Zero dependencies — uses only Node.js built-ins (fs, path)
• Self-contained HTML — single file output, no external resources, works offline
• SPDX JSON → interactive report in one command
• Optional vulnerability overlay — accepts pre-generated Grype JSON output via --vulns
• License analysis — classifies packages as permissive, weak copyleft, copyleft, restrictive, or unknown
• Package origin detection — separates container/OS packages from application dependencies
• Clickable dashboards — severity cards, license cards, and package cards filter the tables
• Dark/light theme — dark by default, --light for print-friendly output
• Build metadata — extracts commit hash, branch, and build number from SPDX comment field
• Registry links — direct links to npm, PyPI, Maven Central, NuGet, OSV, NVD, deps.dev

Quick Start

Install globally

npm install -g sbom-report

Or use with npx (no install)

npx sbom-report my-app.spdx.json

Usage

1. Generate an SBOM with Syft

# Scan a container image
syft <image> -o spdx-json > my-app.spdx.json

# Scan a directory
syft dir:./my-project -o spdx-json > my-app.spdx.json

2. Generate the report

# Basic report (dark theme, output to my-app-report.html)
sbom-report my-app.spdx.json

# Custom output path and title
sbom-report my-app.spdx.json -o report.html -t "Release 3.2 Audit"

# Light theme for printing/sharing
sbom-report my-app.spdx.json --light

3. Add vulnerability data (optional)

Run Grype separately to generate a vulnerability scan, then pass it in:

# Scan with Grype
grype sbom:my-app.spdx.json -o json > vulnerabilities.json

# Generate report with vulnerability overlay
sbom-report my-app.spdx.json --vulns vulnerabilities.json

CLI Reference

sbom-report <input.spdx.json> [options]

Options:
  -o, --output <file>   Output HTML file path (default: <input>-report.html)
  -t, --title  <title>  Custom report title
  --vulns <file>        Grype JSON vulnerability scan results to overlay
  --dark                Force dark theme (default)
  --light               Force light theme
  -h, --help            Show help

Report Sections

| Section | Description | |---|---| | Vulnerability Banner | Total CVE count with severity breakdown (only with --vulns) | | Vulnerability Dashboard | Clickable severity cards: Critical, High, Medium, Low, Negligible, Fixable | | SBOM Facts | Clickable cards: Total Packages, Container/OS, Application, Copyleft, Unknown License, CPE count | | Document Information | SPDX metadata, creators, namespace, commit/branch/build info | | Package Origin | Stacked bar chart showing container vs application package distribution | | Vulnerabilities Table | Searchable, filterable, sortable table with expandable CVE details (only with --vulns) | | CVE Lookup | CPE-based links to NVD and OSV grouped by origin | | License Analysis | License risk classification cards, alerts, distribution chart | | All Packages | Full searchable, sortable package table with expandable details |

Pipeline Integration

Azure DevOps

steps:
  - script: |
      # Install tools
      curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
      curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin

      # Generate SBOM
      syft $(imageRef) -o spdx-json > sbom.spdx.json

      # Scan for vulnerabilities
      grype sbom:sbom.spdx.json -o json > vulnerabilities.json

      # Generate report
      npx sbom-report sbom.spdx.json --vulns vulnerabilities.json -o $(Build.ArtifactStagingDirectory)/sbom-report.html
    displayName: 'Generate SBOM Report'

  - publish: $(Build.ArtifactStagingDirectory)/sbom-report.html
    artifact: sbom-report

GitHub Actions

- name: Generate SBOM Report
  run: |
    # Install Syft & Grype
    curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
    curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin

    # Generate SBOM and scan
    syft ${{ env.IMAGE_REF }} -o spdx-json > sbom.spdx.json
    grype sbom:sbom.spdx.json -o json > vulnerabilities.json

    # Generate report
    npx sbom-report sbom.spdx.json --vulns vulnerabilities.json -o sbom-report.html

- uses: actions/upload-artifact@v4
  with:
    name: sbom-report
    path: sbom-report.html

Prerequisites

• Node.js >= 14.0.0
• Syft — to generate SPDX JSON SBOMs (install)
• Grype (optional) — to generate vulnerability scan JSON (install)

Note: This tool does not invoke Syft or Grype. It only reads their JSON output files. You run the scanners yourself, giving you full control over versions, databases, and scan configuration.

Why?

Enterprise SBOM platforms are heavy — they need databases, APIs, dashboards, and licenses. Sometimes you just want:

1. Run syft to get an SBOM
2. Run grype to get vulnerabilities
3. Get a single HTML file you can open in a browser, attach to a ticket, or publish as a build artifact

That's what this tool does. Nothing more.

License

MIT