stella sbom — Command Guide

Commands

stella sbom generate --image <ref> [--output sbom.spdx.json] [--offline]
stella sbom compose --fragment <path> --output composition.json --offline
stella sbom verify --file <sbom> --signature <sig> --key <keyfile>
stella sbom verify --archive <path.tar.gz> [--offline] [--trust-root <dir>] — Verify signed SBOM archive

Flags (common)

--offline: no network pulls; use local cache/OCI archive.
--format: spdx-json (default) or cyclonedx-json.
--attest: emit DSSE attestation alongside SBOM.
--hash: include layer/file hashes (deterministic ordering).

Inputs/outputs

Inputs: container image, directory, or fragments.
Outputs: deterministic SPDX/CycloneDX JSON, optional DSSE + checksums.
Exit codes per output-and-exit-codes.md; verification failure uses exit code 3 or 4 depending on cause.

Determinism rules

Stable ordering of packages/files; timestamps UTC.
Hashes hex-lowercase; no host-specific paths.

Offline/air-gap notes

With --offline, image sources must already be cached (tar/OCI archive); command fails with exit code 5 if it would fetch remotely.
Verification uses local trust roots; no remote key fetch.

stella sbom verify — Signed Archive Verification

Synopsis

stella sbom verify --archive <path.tar.gz> [options]

Verify a signed SBOM archive (tar.gz) containing SBOM, DSSE envelope, manifest, and verification materials.

Options

Option	Alias	Description
`--archive <path>`	`-a`	Required. Path to signed SBOM archive (tar.gz).
`--offline`		Perform offline verification using bundled certificates.
`--trust-root <dir>`	`-r`	Path to trust root directory containing CA certificates.
`--output <file>`	`-o`	Write verification report to file instead of stdout.
`--format <fmt>`	`-f`	Output format: `json`, `summary` (default), or `html`.
`--strict`		Fail if any optional verification step fails.
`--verbose`		Show detailed verification progress.

Verification Checks

The command performs the following verification checks:

Archive Integrity: Validates all file hashes against manifest.json.
DSSE Envelope Signature: Verifies the DSSE envelope structure and signatures.
SBOM Schema: Validates SBOM content against SPDX or CycloneDX schemas.
Tool Version: Verifies tool version metadata is present and valid.
Timestamp Validity: Checks generation timestamp is within acceptable window.

Exit Codes

Code	Meaning
0	Verification passed
1	Verification failed (one or more checks failed)
2	Error (file not found, parse error, etc.)

Examples

# Verify a signed SBOM archive with summary output
stella sbom verify --archive signed-sbom-sha256-abc123.tar.gz

# Verify offline with custom trust root
stella sbom verify --archive signed-sbom.tar.gz --offline --trust-root /path/to/roots/

# Generate JSON verification report
stella sbom verify --archive signed-sbom.tar.gz --format json --output report.json

# Generate HTML report for sharing
stella sbom verify --archive signed-sbom.tar.gz --format html --output report.html

# Strict mode (fail on optional check failures)
stella sbom verify --archive signed-sbom.tar.gz --strict

Sample Output

SBOM Verification Report
========================
Archive: signed-sbom-sha256-abc123.tar.gz
Status: VERIFIED

Checks:
  [PASS] Archive integrity (All 4 file hashes verified)
  [PASS] DSSE envelope signature (Valid, 1 signature(s))
  [PASS] SBOM schema (Valid, SPDX 2.3)
  [PASS] Tool version (Suite: 2027.Q1, Scanner: 1.2.3)
  [PASS] Timestamp validity (Within validity window, 2026-01-15)

SBOM Details:
  Format: SPDX 2.3
  Components: 142
  Artifact: sha256:abc123def456
  Generated: 2026-01-15T10:30:00Z
  Tool: StellaOps Scanner v2027.Q1

Archive Format

The signed SBOM archive follows the format defined in SPRINT_20260112_016_SCANNER_signed_sbom_archive_spec:

signed-sbom-{digest}-{timestamp}.tar.gz
├── sbom.spdx.json (or sbom.cdx.json)
├── sbom.dsse.json
├── manifest.json
├── metadata.json
├── certs/
│   ├── signing-cert.pem
│   └── fulcio-root.pem
├── rekor-proof/
│   ├── inclusion-proof.json
│   └── checkpoint.sig
├── schemas/
│   └── ...
└── VERIFY.md

stella sbom generate — Generate SBOM from container image
stella attest verify --offline — Verify attestation bundles offline
stella evidence export — Export evidence bundle with signed SBOM

4.6 KiB Raw Blame History