finish off sprint advisories and sprints

2026-01-24 00:12:43 +02:00
parent 726d70dc7f
commit c70e83719e
266 changed files with 46699 additions and 1328 deletions
--- a/docs/modules/cli/guides/commands/reference.md
+++ b/docs/modules/cli/guides/commands/reference.md
@@ -593,6 +593,159 @@ Token expires: 2025-12-24T10:30:00Z

 ---

+## Score Commands
+
+### stella score compute
+
+Compute a unified trust score from signal values.
+
+**Usage:**
+```bash
+stella score compute [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--finding-id <ID>` | CVE@PURL finding identifier |
+| `--cvss <score>` | CVSS base score (0-10) |
+| `--epss <score>` | EPSS probability (0-1) |
+| `--reachability <value>` | Reachability signal (0-1) |
+| `--runtime <value>` | Runtime observation signal (0-1) |
+| `--exploit <value>` | Exploit maturity signal (0-1) |
+| `--backport <value>` | Backport availability signal (0-1) |
+| `--source <value>` | Source confidence signal (0-1) |
+| `--mitigation <value>` | Mitigation strength signal (0-1) |
+| `--weights-version <ver>` | Pin specific weight manifest version |
+| `--show-unknowns` | Include U metric and band in output |
+| `--show-deltas` | Include delta-if-present calculations |
+| `--format <fmt>` | Output format: `table`, `json`, `markdown` |
+| `--offline` | Use bundled weights (no server required) |
+
+**Examples:**
+```bash
+# Basic score computation
+stella score compute --finding-id CVE-2024-1234@pkg:npm/lodash@4.17.0 \
+    --cvss 7.5 --epss 0.15 --reachability 0.9
+
+# Full output with deltas
+stella score compute --finding-id CVE-2024-1234@pkg:npm/lodash@4.17.0 \
+    --cvss 7.5 --reachability 0.9 --runtime 0.7 \
+    --show-unknowns --show-deltas --format json
+```
+
+---
+
+### stella score explain
+
+Display detailed breakdown of a score computation.
+
+**Usage:**
+```bash
+stella score explain <FINDING-ID> [OPTIONS]
+```
+
+**Examples:**
+```bash
+stella score explain CVE-2024-1234@pkg:npm/lodash@4.17.0
+stella score explain CVE-2024-1234@pkg:npm/lodash@4.17.0 --format markdown
+```
+
+---
+
+### stella score replay
+
+Fetch the signed replay proof for a previously computed score.
+
+**Usage:**
+```bash
+stella score replay <SCORE-ID> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--format <fmt>` | Output format: `table`, `json`, `markdown` |
+| `--verify-rekor` | Also verify Rekor inclusion proof |
+
+**Examples:**
+```bash
+stella score replay score_a1b2c3d4e5f67890
+stella score replay score_a1b2c3d4e5f67890 --format json --verify-rekor
+```
+
+---
+
+### stella score verify
+
+Re-execute a score computation and verify it matches the original.
+
+**Usage:**
+```bash
+stella score verify <SCORE-ID> [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--format <fmt>` | Output format: `table`, `json`, `markdown` |
+| `--verify-rekor` | Also verify Rekor inclusion proof |
+
+**Examples:**
+```bash
+stella score verify score_a1b2c3d4e5f67890
+```
+
+---
+
+### stella gate score evaluate
+
+Compute unified score as part of a gate evaluation (enhanced with unknowns support).
+
+**Usage:**
+```bash
+stella gate score evaluate [OPTIONS]
+```
+
+**Additional Options (new):**
+
+| Option | Description |
+|--------|-------------|
+| `--show-unknowns` | Include U metric and unknowns band |
+| `--show-deltas` | Include delta-if-present for missing signals |
+| `--weights-version <ver>` | Pin specific weight manifest version |
+
+---
+
+### stella gate score weights
+
+Manage EWS weight manifests.
+
+**Usage:**
+```bash
+stella gate score weights <SUBCOMMAND>
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List available weight manifest versions |
+| `show <version>` | Display manifest details |
+| `diff <v1> <v2>` | Compare two manifests |
+
+**Examples:**
+```bash
+stella gate score weights list
+stella gate score weights show v2026-01-22
+stella gate score weights diff v2026-01-22 v2026-02-01
+```
+
+---
+
 ## Policy Commands

 ### stella policy test
@@ -781,6 +934,133 @@ stella analytics sbom-lake vulnerabilities --environment prod --min-severity hig

 ---

+## Function Map Commands
+
+### stella function-map generate
+
+Generate a function map predicate from an SBOM and optional static analysis.
+
+**Usage:**
+```bash
+stella function-map generate [OPTIONS]
+```
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--sbom <path>` | `-s` | Path to SBOM file (required) |
+| `--service <name>` | | Service name (required) |
+| `--subject <purl>` | | Subject artifact PURL (derived from SBOM if omitted) |
+| `--static-analysis <path>` | | Path to static analysis results |
+| `--hot-functions <glob>` | `-H` | Glob patterns for functions of interest (repeatable) |
+| `--min-rate <value>` | | Minimum observation rate 0.0-1.0 (default 0.95) |
+| `--window <seconds>` | | Observation window in seconds (default 1800) |
+| `--fail-on-unexpected` | | Fail verification on unexpected symbols |
+| `--output <path>` | `-o` | Output file path |
+| `--format <fmt>` | `-f` | Output format: `json`, `yaml` (default json) |
+| `--build-id <id>` | | Build ID for provenance correlation |
+
+**Examples:**
+```bash
+# Basic generation from SBOM
+stella function-map generate --sbom app.cdx.json --service my-backend
+
+# With hot function filtering and custom thresholds
+stella function-map generate \
+  --sbom app.cdx.json \
+  --service my-backend \
+  --hot-functions "crypto/*" --hot-functions "auth/*" \
+  --min-rate 0.90 --window 3600 \
+  --output function-map.json
+```
+
+---
+
+### stella function-map verify
+
+Verify runtime observations against a function map predicate.
+
+**Usage:**
+```bash
+stella function-map verify [OPTIONS]
+```
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--function-map <path>` | `-m` | Path or OCI reference to predicate (required) |
+| `--container <id>` | `-c` | Filter to specific container ID |
+| `--from <timestamp>` | | ISO 8601 start time (default: 30 min ago) |
+| `--to <timestamp>` | | ISO 8601 end time (default: now) |
+| `--output <path>` | `-o` | Output verification report path |
+| `--format <fmt>` | `-f` | Output format: `json`, `table`, `md` (default table) |
+| `--strict` | | Fail on any unexpected symbols |
+| `--offline` | | Use bundled observations file |
+| `--observations <path>` | | Path to observations file (NDJSON) |
+
+**Examples:**
+```bash
+# Online verification against live observations
+stella function-map verify \
+  --function-map function-map.json \
+  --from "2026-01-23T00:00:00Z" --to "2026-01-23T01:00:00Z"
+
+# Offline verification with bundled observations
+stella function-map verify \
+  --function-map function-map.json \
+  --offline --observations obs.ndjson \
+  --format json --output report.json
+```
+
+---
+
+## Observations Commands
+
+### stella observations query
+
+Query runtime observations from the observation store.
+
+**Usage:**
+```bash
+stella observations query [OPTIONS]
+```
+
+**Options:**
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--symbol <glob>` | `-s` | Glob pattern for symbol name |
+| `--node-hash <hash>` | `-n` | Exact node hash filter |
+| `--container <id>` | `-c` | Container ID filter |
+| `--pod <name>` | `-p` | Pod name filter |
+| `--namespace <ns>` | `-N` | Kubernetes namespace filter |
+| `--probe-type <type>` | | Probe type filter |
+| `--from <timestamp>` | | ISO 8601 start time (default: 1 hour ago) |
+| `--to <timestamp>` | | ISO 8601 end time (default: now) |
+| `--limit <n>` | `-l` | Maximum results (default 100) |
+| `--offset <n>` | | Pagination offset (default 0) |
+| `--format <fmt>` | `-f` | Output format: `json`, `table`, `csv` (default table) |
+| `--summary` | | Show statistics instead of individual records |
+| `--output <path>` | `-o` | Output file path |
+| `--offline` | | Use local observations file |
+| `--observations-file <path>` | | Path to observations file for offline mode |
+
+**Examples:**
+```bash
+# Query all crypto-related observations
+stella observations query --symbol "crypto_*" --from "2026-01-23T00:00:00Z"
+
+# Summary for a specific container
+stella observations query --container abc123 --summary
+
+# Export as CSV for analysis
+stella observations query --pod my-service-pod --format csv --output obs.csv
+```
+
+---
+
 ## Ground-Truth Corpus Commands

 ### stella groundtruth
@@ -1337,6 +1617,269 @@ KPIs:

 **See Also:** [Ground-Truth CLI Guide](../ground-truth-cli.md)

+---
+
+## Attestation Commands
+
+### stella attest attach
+
+Attach an attestation (DSSE envelope) to an OCI image via ORAS referrers.
+
+**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-01)
+
+**Usage:**
+```bash
+stella attest attach --image <ref> --attestation <path> [options]
+```
+
+**Options:**
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--image` | `-i` | OCI image reference (e.g., `registry.example.com/app:v1.2`) | (required) |
+| `--attestation` | `-a` | Path to DSSE envelope JSON file | (required) |
+| `--media-type` | | Media type for the attestation layer | `application/vnd.dsse.envelope.v1+json` |
+| `--registry-url` | | Override registry URL | From image reference |
+| `--verbose` | `-v` | Show detailed progress | `false` |
+
+**Example:**
+```bash
+stella attest attach \
+  --image registry.example.com/app:v1.2 \
+  --attestation delta-sig.dsse.json \
+  --verbose
+```
+
+**Exit Codes:**
+- `0` - Attestation attached successfully
+- `1` - Attachment failed (registry error, invalid envelope)
+- `2` - Invalid input or configuration error
+
+---
+
+### stella attest verify
+
+Verify attestations attached to an OCI image. Lists and validates DSSE envelopes, checks signatures, and optionally verifies Rekor annotations.
+
+**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-02)
+
+**Usage:**
+```bash
+stella attest verify --image <ref> [options]
+```
+
+**Options:**
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--image` | `-i` | OCI image reference to verify | (required) |
+| `--predicate-type` | | Filter by predicate type URI | (all) |
+| `--trusted-keys` | | Path to trusted public keys directory | (none) |
+| `--require-rekor` | | Require valid Rekor inclusion annotations | `false` |
+| `--output` | `-o` | Output format: `table`, `json` | `table` |
+| `--verbose` | `-v` | Show detailed verification steps | `false` |
+
+**Example:**
+```bash
+stella attest verify \
+  --image registry.example.com/app:v1.2 \
+  --predicate-type "https://stellaops.dev/delta-sig/v1" \
+  --require-rekor \
+  --output json
+```
+
+**Exit Codes:**
+- `0` - All attestations verified successfully
+- `1` - One or more attestations failed verification
+- `2` - Invalid input or configuration error
+
+---
+
+## Binary Analysis Commands
+
+### stella binary delta-sig attest
+
+Sign a delta-sig predicate with an EC key and optionally submit to a Rekor transparency log. Produces a DSSE envelope suitable for `stella attest attach`.
+
+**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-05)
+
+**Usage:**
+```bash
+stella binary delta-sig attest --predicate <path> --key <path> [options]
+```
+
+**Options:**
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--predicate` | `-p` | Path to delta-sig predicate JSON file | (required) |
+| `--key` | `-k` | Path to EC private key (PEM) for DSSE signing | (required) |
+| `--output` | `-o` | Path to write the DSSE envelope | stdout |
+| `--rekor-url` | | Rekor transparency log URL for submission | (none) |
+| `--receipt` | | Path to save Rekor receipt JSON | (none, only with `--rekor-url`) |
+| `--dry-run` | | Validate predicate and key without signing | `false` |
+| `--verbose` | `-v` | Show detailed signing and submission steps | `false` |
+
+**Example:**
+```bash
+# Sign predicate and submit to Rekor
+stella binary delta-sig attest \
+  --predicate delta-sig-predicate.json \
+  --key signing-key.pem \
+  --output signed-envelope.dsse.json \
+  --rekor-url https://rekor.sigstore.dev \
+  --receipt rekor-receipt.json \
+  --verbose
+
+# Dry run (validate only)
+stella binary delta-sig attest \
+  --predicate delta-sig-predicate.json \
+  --key signing-key.pem \
+  --dry-run
+```
+
+**Signing Behavior:**
+- Key must be an ECDSA private key (PEM format)
+- Produces an in-toto v1 statement wrapping the predicate as DSSE payload
+- PAE (Pre-Authentication Encoding) used per DSSE specification
+- Signature is Base64-encoded in the envelope
+
+**Rekor Submission:**
+- When `--rekor-url` is provided, the signed envelope is submitted to the transparency log
+- On success, Rekor UUID and log index are displayed
+- Receipt JSON includes `uuid`, `logIndex`, `integratedTime`, and `logUrl`
+
+**Exit Codes:**
+- `0` - Signing (and optional Rekor submission) succeeded
+- `1` - Signing or submission failed
+- `2` - Invalid predicate, key format, or configuration error
+
+---
+
+## Bundle Commands
+
+### stella bundle verify
+
+Verify offline evidence bundles with full cryptographic verification. Checks manifest integrity, blob digests, DSSE signatures, Rekor proofs, timestamps, payload types, and optionally replays large blob content verification.
+
+**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-06)
+
+**Usage:**
+```bash
+stella bundle verify --bundle <path> [options]
+```
+
+**Options:**
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--bundle` | `-b` | Path to bundle (tar.gz or directory) | (required) |
+| `--trust-root` | | Path to trusted root certificate (PEM) | (none) |
+| `--rekor-checkpoint` | | Path to Rekor checkpoint for offline proof verification | (none) |
+| `--offline` | | Run in offline mode (no network access) | `false` |
+| `--output` | `-o` | Output format: `table`, `json` | `table` |
+| `--strict` | | Fail on any warning (missing optional artifacts) | `false` |
+| `--signer` | | Path to signing key (PEM) for verification report | (none) |
+| `--signer-cert` | | Path to signer certificate PEM (for report metadata) | (none) |
+| `--replay` | | Verify binary content by fetching/reading large blobs referenced in attestations | `false` |
+| `--blob-source` | | Override blob source (registry URL or local directory path) | (auto-detect) |
+| `--verbose` | `-v` | Show detailed verification steps | `false` |
+
+**Verification Steps:**
+1. **Manifest checksum** - Validate bundle manifest integrity
+2. **Blob digests** - Verify all blob file SHA-256 digests match manifest
+3. **DSSE signatures** - Validate envelope signatures against trusted keys
+4. **Rekor proofs** - Verify inclusion proofs against checkpoint (when provided)
+5. **Timestamps** - Validate RFC 3161 timestamps against TSA certificates
+6. **Payload types** - Verify predicate types match expectations
+7. **Blob Replay** (when `--replay`) - Fetch and verify large blobs referenced in attestations
+
+**Blob Replay Behavior:**
+- For **full bundles** (blobs embedded): verifies content from `blobs/` directory against attestation digests
+- For **light bundles** (metadata only): fetches blobs from `--blob-source` (local dir or registry URL)
+- Supports `sha256`, `sha384`, `sha512` digest algorithms
+- In `--offline` mode, blob fetch from registries is blocked (only local sources work)
+
+**Example:**
+```bash
+# Basic verification
+stella bundle verify --bundle evidence-bundle.tar.gz
+
+# Full verification with replay and trust root
+stella bundle verify \
+  --bundle /path/to/bundle \
+  --trust-root /etc/stellaops/tsa-root.pem \
+  --rekor-checkpoint checkpoint.json \
+  --replay \
+  --verbose
+
+# Light bundle with local blob source
+stella bundle verify \
+  --bundle light-bundle/ \
+  --replay \
+  --blob-source /path/to/blobs/
+
+# Strict offline verification with signed report
+stella bundle verify \
+  --bundle evidence-bundle/ \
+  --offline \
+  --strict \
+  --signer report-key.pem \
+  --signer-cert report-cert.pem
+```
+
+**Exit Codes:**
+- `0` - All verifications passed
+- `1` - One or more verifications failed
+- `2` - Invalid input or configuration error
+
+---
+
+## Evidence Commands
+
+### stella evidence export-bundle
+
+Export evidence bundles for offline verification. Supports two-tier export modes: **light** (metadata and attestations only) and **full** (includes embedded binary blobs).
+
+**Sprint:** SPRINT_20260122_040_Platform_oci_delta_attestation_pipeline (040-04)
+
+**Usage:**
+```bash
+stella evidence export-bundle --image <ref> --output <path> [options]
+```
+
+**Options:**
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--image` | `-i` | OCI image reference to export evidence for | (required) |
+| `--output` | `-o` | Output bundle path (.tar.gz or directory) | (required) |
+| `--full` | | Export in full mode (embed binary blobs alongside attestations) | `false` (light mode) |
+| `--sign-with` | | Signing method for bundle: `cosign`, `sigstore`, `none` | `none` |
+| `--verbose` | `-v` | Show detailed export progress | `false` |
+
+**Export Modes:**
+
+| Mode | Flag | Contents | Size | Use Case |
+|------|------|----------|------|----------|
+| **Light** | (default) | Manifest, attestation envelopes, metadata | Small | Quick transfer, metadata audit |
+| **Full** | `--full` | Light + embedded binary blobs in `blobs/` dir | Large | Air-gap verification, replay |
+
+**Example:**
+```bash
+# Light export (default)
+stella evidence export-bundle \
+  --image registry.example.com/app:v1.2 \
+  --output evidence-light.tar.gz
+
+# Full export with embedded blobs
+stella evidence export-bundle \
+  --image registry.example.com/app:v1.2 \
+  --output evidence-full.tar.gz \
+  --full \
+  --verbose
+```
+
+**Exit Codes:**
+- `0` - Bundle exported successfully
+- `1` - Export failed
+- `2` - Invalid input or configuration error
+
 ---
 ## Reporting & Export Commands

--- a/docs/modules/cli/guides/commands/sbom.md
+++ b/docs/modules/cli/guides/commands/sbom.md
@@ -133,5 +133,95 @@ signed-sbom-{digest}-{timestamp}.tar.gz
 ### 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
+```