# 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

```bash
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:

1. **Archive Integrity**: Validates all file hashes against `manifest.json`.
2. **DSSE Envelope Signature**: Verifies the DSSE envelope structure and signatures.
3. **SBOM Schema**: Validates SBOM content against SPDX or CycloneDX schemas.
4. **Tool Version**: Verifies tool version metadata is present and valid.
5. **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

```bash
# 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
```

### Related Commands

- `stella sbom generate` — Generate SBOM from container image
- `stella sbom publish` — Publish canonical SBOM as OCI referrer
- `stella attest verify --offline` — Verify attestation bundles offline
- `stella evidence export` — Export evidence bundle with signed SBOM

---

## stella sbom publish — OCI SBOM Publication

### Synopsis

```bash
stella sbom publish --image <ref> [--file <path>] [--format cdx|spdx] [--overwrite]
```

Publishes a canonical (volatile-fields-stripped, key-sorted) SBOM as an OCI referrer artifact attached to the specified container image. The published artifact is discoverable via the OCI Distribution Spec 1.1 referrers API.

### Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--image <ref>` | `-i` | **Required.** Target image reference (`registry/repo@sha256:...`). Must include digest. |
| `--file <path>` | `-f` | Path to SBOM file. If omitted, fetches from Scanner CAS for this image. |
| `--format <fmt>` | | SBOM format: `cdx` (CycloneDX) or `spdx`. Auto-detected from file content if omitted. |
| `--overwrite` | | Supersede the current active SBOM referrer for this image. |
| `--registry-url <url>` | | Override registry URL (defaults to parsed from `--image`). |
| `--verbose` | | Show detailed output including blob digest and normalization info. |

### Behavior

1. **Normalization**: The SBOM is canonicalized before publication:
   - Volatile fields stripped: `serialNumber`, `metadata.tools`, `metadata.authors`, `metadata.timestamp` (CycloneDX); `creationInfo.created`, `creationInfo.creators`, `creationInfo.licenseListVersion` (SPDX).
   - Object keys sorted lexicographically (ordinal).
   - Arrays of objects sorted by deterministic keys (bom-ref, purl, name@version).
   - See `docs/contracts/sbom-volatile-fields.json` for the authoritative field list.

2. **Publication**: The canonical SBOM bytes are pushed as an OCI artifact with:
   - `artifactType`: `application/vnd.stellaops.sbom.cdx+json` or `application/vnd.stellaops.sbom.spdx+json`
   - `subject`: points to the image manifest digest
   - Annotations: `dev.stellaops/sbom-version`, `dev.stellaops/sbom-format`

3. **Overwrite/Supersede**: When `--overwrite` is specified:
   - The current active SBOM referrer is resolved (highest version number).
   - A new referrer is pushed with `version = prior + 1` and a `dev.stellaops/sbom-supersedes` annotation pointing to the prior manifest digest.
   - No registry deletes are performed (purely additive).

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Publication succeeded |
| 1 | Publication failed (registry error, auth failure) |
| 2 | Error (file not found, invalid image reference, parse error) |

### Examples

```bash
# Publish a CycloneDX SBOM to an image
stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file app.cdx.json

# Publish with explicit format
stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file app.json --format cdx

# Overwrite existing SBOM (supersede)
stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file improved.cdx.json --overwrite

# Verbose output
stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file app.cdx.json --verbose
```

### Sample Output

```
Published SBOM as OCI referrer:
  Blob digest:     sha256:e3b0c44298fc1c149afbf4c8996fb924...
  Manifest digest: sha256:7d865e959b2466918c9863afca942d0f...
  Version:         1
  Artifact type:   application/vnd.stellaops.sbom.cdx+json
```

### Verifier Discovery

Third-party verifiers can discover published SBOMs via the OCI referrers API:

```bash
# List SBOM referrers for an image (using oras CLI)
oras discover registry.example.com/myapp@sha256:abc123... \
  --artifact-type application/vnd.stellaops.sbom.cdx+json

# Pull the latest SBOM
oras pull registry.example.com/myapp@sha256:abc123... \
  --artifact-type application/vnd.stellaops.sbom.cdx+json
```