sbom

SBOM Generation and License Resolution

Generate CycloneDX SBOMs, resolve missing licenses, and export to CSV for compliance review.

Overview

The OpenShell SBOM tooling produces source-tree CycloneDX JSON SBOMs using Syft, resolves missing or hash-based licenses by querying public registries (crates.io, npm, PyPI), and exports the results to CSV for stakeholder review.

SBOMs are release artifacts only -- they are generated on demand and not committed to the repository. Output lands in deploy/sbom/output/ (gitignored).

Release Dev and Release Tag image builds separately embed cargo-auditable metadata in the staged gateway and supervisor binaries. This metadata describes the binary's Rust dependency graph and lets Syft discover Cargo packages from the binary itself. It is not a complete image SBOM and is not an OCI SBOM attestation; publishing such an attestation remains separate work.

Prerequisites

• mise install has been run (installs Syft and other tools)
• The repository is checked out at the root

Inspecting an Auditable Image Binary

Opt into auditable metadata when staging a local image binary:

OPENSHELL_AUDITABLE=1 PREBUILT_ARCH=amd64 \
  tasks/scripts/stage-prebuilt-binaries.sh gateway

Scan the staged binary rather than the source tree:

mise x -- syft \
  "file:deploy/docker/.build/prebuilt-binaries/amd64/openshell-gateway" \
  -o cyclonedx-json

This output is limited to packages Syft discovers from that binary. Use mise run sbom for the broader source-tree license-compliance inventory.

Workflow 1: Full SBOM Generation (One Command)

mise run sbom

This single command chains three stages:

1. Generate (sbom:generate): Syft scans the workspace source tree and produces a CycloneDX JSON SBOM
2. Resolve (sbom:resolve): Public registry APIs fill in missing or hash-based licenses in the JSON
3. CSV (sbom:csv): JSON SBOMs are converted to CSV for review

Output directory: deploy/sbom/output/

After running, the user can find:

• deploy/sbom/output/*.cdx.json -- full CycloneDX SBOMs
• deploy/sbom/output/*.csv -- CSV exports ready for spreadsheet review

Workflow 2: Individual Stages

Run stages independently when debugging or iterating:

mise run sbom:generate   # Generate JSON SBOMs only (requires Syft)
mise run sbom:resolve    # Resolve licenses in existing JSONs (queries APIs)
mise run sbom:csv        # Convert existing JSONs to CSV

Workflow 3: License Check (CI Advisory)

mise run sbom:check

Reports unresolved licenses without failing. Intended for PR CI as a non-blocking advisory check. Requires that SBOMs have already been generated (mise run sbom:generate).

Workflow 4: Processing External SBOMs

The Python scripts accept explicit file paths, so they can process SBOMs from any source (e.g., NVIDIA nSpect pipeline output):

uv run python deploy/sbom/resolve_licenses.py /path/to/external-sbom.json
uv run python deploy/sbom/sbom_to_csv.py /path/to/external-sbom.json

License Resolution Details

The resolver queries these public registries:

Registry	Package URL prefix	Method
crates.io	pkg:cargo/*	REST API
npm	pkg:npm/*	Registry API
PyPI	pkg:pypi/*	JSON API
Go modules	pkg:golang/*	Known license map (no API)
Debian/Ubuntu	pkg:deb/*	Known license map

Components from private registries (e.g., @openclaw/* npm packages) are not resolved and will appear in the "unresolved" report.

Output Files

Pattern	Description
deploy/sbom/output/openshell-source-{version}.cdx.json	CycloneDX JSON SBOM
deploy/sbom/output/openshell-source-{version}.csv	CSV export (name, version, type, purl, licenses, bom-ref)

Key Files

File	Purpose
deploy/sbom/resolve_licenses.py	License resolution script
deploy/sbom/sbom_to_csv.py	JSON-to-CSV converter
tasks/sbom.toml	Mise task definitions
mise.toml	Syft tool definition (under [tools])

Quick Reference

Task	Command
Full pipeline	mise run sbom
Generate only	mise run sbom:generate
Resolve licenses	mise run sbom:resolve
Export CSV	mise run sbom:csv
CI license check	mise run sbom:check
Process external SBOM	uv run python deploy/sbom/resolve_licenses.py <file>