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). Pushed gateway, sandbox, and supervisor images carry an SPDX SBOM and minimal SLSA provenance as OCI attestations. Branch E2E, Release Dev, Release, and Pre-release image binaries embed cargo-auditable metadata, so their image SBOMs include linked Rust crates. Stable Release builds retain images and attestations in OCI archive artifacts. Publication copies every platform and attestation to GHCR with preserved digests, then runs the SBOM verification before updating `latest`. ## Prerequisites - `mise install` has been run (installs Syft and other tools) - The repository is checked out at the root ## Inspecting an Image SBOM BuildKit uses its default Syft scanner and attaches one SPDX document per platform. Read one without pulling the image: ```bash docker buildx imagetools inspect ghcr.io/nvidia/openshell/gateway:latest \ --format '{{ json (index .SBOM "linux/amd64").SPDX }}' ``` Validate the final attestation, requiring a Cargo package for an auditable image: ```bash tasks/scripts/verify-image-sbom.sh ghcr.io/nvidia/openshell/gateway:latest --require-cargo ``` ## Inspecting an Auditable Image Binary Opt into auditable metadata when staging a local image binary: ```bash OPENSHELL_AUDITABLE=1 PREBUILT_ARCH=amd64 \ tasks/scripts/stage-prebuilt-binaries.sh gateway ``` Scan the staged binary rather than the source tree: ```bash 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) ```bash 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: ```bash 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) ```bash 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): ```bash 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>` |