docs(ops): Complete operations runbooks for Epic 3500

Sprint 3500.0004.0004 (Documentation & Handoff) - T2 DONE Operations Runbooks Added: - score-replay-runbook.md: Deterministic replay procedures - proof-verification-runbook.md: DSSE/Merkle verification ops - airgap-operations-runbook.md: Offline kit management CLI Reference Docs: - reachability-cli-reference.md - score-proofs-cli-reference.md - unknowns-cli-reference.md Air-Gap Guides: - score-proofs-reachability-airgap-runbook.md Training Materials: - score-proofs-concept-guide.md UI API Clients: - proof.client.ts - reachability.client.ts - unknowns.client.ts All 5 operations runbooks now complete (reachability, unknowns-queue, score-replay, proof-verification, airgap-operations).
2025-12-20 22:30:02 +02:00
parent 09c7155f1b
commit 4b3db9ca85
13 changed files with 5630 additions and 12 deletions
--- a/docs/cli/reachability-cli-reference.md
+++ b/docs/cli/reachability-cli-reference.md
@@ -0,0 +1,558 @@
+# Reachability CLI Reference
+
+**Sprint:** SPRINT_3500_0004_0004  
+**Version:** 1.0.0
+
+## Overview
+
+The Reachability CLI commands enable call graph management, reachability computation, and explain queries. All commands support air-gapped operation.
+
+---
+
+## Commands
+
+### stella reachability
+
+Manage reachability analysis.
+
+```bash
+stella reachability <SUBCOMMAND> [OPTIONS]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `compute` | Trigger reachability computation |
+| `findings` | List reachability findings |
+| `explain` | Explain reachability verdict |
+| `explain-all` | Export all explanations |
+| `summary` | Show reachability summary |
+| `job-status` | Check computation job status |
+| `job-logs` | View job logs |
+| `job-cancel` | Cancel running job |
+
+---
+
+### stella reachability compute
+
+Trigger reachability computation for a scan.
+
+```bash
+stella reachability compute [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--max-depth <N>` | Maximum path length to explore | 10 |
+| `--indirect-resolution <MODE>` | Handle indirect calls: `conservative`, `aggressive`, `skip` | `conservative` |
+| `--timeout <DURATION>` | Maximum computation time | 300s |
+| `--parallel` | Enable parallel BFS | `true` |
+| `--include-runtime` | Merge runtime evidence | `true` |
+| `--offline` | Run in offline mode | `false` |
+| `--symbol-db <PATH>` | Symbol resolution database | System default |
+| `--deterministic` | Enable deterministic mode | `true` |
+| `--seed <BASE64>` | Random seed for determinism | Auto |
+| `--graph-digest <HASH>` | Use specific call graph version | Latest |
+| `--partition-by <KEY>` | Partition analysis: `artifact`, `entrypoint` | — |
+| `--force` | Force recomputation | `false` |
+| `--wait` | Wait for completion | `false` |
+
+#### Examples
+
+```bash
+# Basic computation
+stella reachability compute --scan-id $SCAN_ID
+
+# With custom options
+stella reachability compute --scan-id $SCAN_ID \
+  --max-depth 20 \
+  --timeout 600s \
+  --indirect-resolution conservative
+
+# Wait for completion
+stella reachability compute --scan-id $SCAN_ID --wait
+
+# Offline computation
+stella reachability compute --scan-id $SCAN_ID --offline
+```
+
+---
+
+### stella reachability findings
+
+List reachability findings for a scan.
+
+```bash
+stella reachability findings [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--status <STATUS>` | Filter by status (comma-separated) | All |
+| `--cve <ID>` | Filter by CVE ID | — |
+| `--purl <PURL>` | Filter by package URL | — |
+| `--min-confidence <N>` | Minimum confidence (0-1) | 0 |
+| `--output <PATH>` | Output file path | stdout |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table`, `sarif` | `table` |
+
+#### Status Values
+
+| Status | Description |
+|--------|-------------|
+| `UNREACHABLE` | No path found |
+| `POSSIBLY_REACHABLE` | Path with heuristic edges |
+| `REACHABLE_STATIC` | Statically proven path |
+| `REACHABLE_PROVEN` | Runtime confirmed |
+| `UNKNOWN` | Insufficient data |
+
+#### Examples
+
+```bash
+# List all findings
+stella reachability findings --scan-id $SCAN_ID
+
+# Filter by status
+stella reachability findings --scan-id $SCAN_ID \
+  --status REACHABLE_STATIC,REACHABLE_PROVEN
+
+# Export as SARIF for CI
+stella reachability findings --scan-id $SCAN_ID \
+  --status REACHABLE_STATIC,REACHABLE_PROVEN \
+  --output-format sarif \
+  --output findings.sarif
+
+# JSON output
+stella reachability findings --scan-id $SCAN_ID --output-format json
+```
+
+---
+
+### stella reachability explain
+
+Explain a reachability verdict.
+
+```bash
+stella reachability explain [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--cve <ID>` | CVE ID | Required |
+| `--purl <PURL>` | Package URL | Required |
+| `--all-paths` | Show all paths, not just shortest | `false` |
+| `--max-paths <N>` | Maximum paths to show | 5 |
+| `--verbose` | Show detailed explanation | `false` |
+| `--offline` | Run in offline mode | `false` |
+| `--output <PATH>` | Output file path | stdout |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `text` | `text` |
+
+#### Examples
+
+```bash
+# Explain single finding
+stella reachability explain --scan-id $SCAN_ID \
+  --cve CVE-2024-1234 \
+  --purl "pkg:npm/lodash@4.17.20"
+
+# Show all paths
+stella reachability explain --scan-id $SCAN_ID \
+  --cve CVE-2024-1234 \
+  --purl "pkg:npm/lodash@4.17.20" \
+  --all-paths
+
+# JSON output
+stella reachability explain --scan-id $SCAN_ID \
+  --cve CVE-2024-1234 \
+  --purl "pkg:npm/lodash@4.17.20" \
+  --output-format json
+```
+
+#### Output Example
+
+```
+Status: REACHABLE_STATIC
+Confidence: 0.70
+
+Shortest Path (depth=3):
+[0] MyApp.Controllers.OrdersController::Get(Guid)
+    Entrypoint: HTTP GET /api/orders/{id}
+[1] MyApp.Services.OrderService::Process(Order)
+    Edge: static (direct_call)
+[2] Lodash.merge(Object, Object) [VULNERABLE]
+    Edge: static (direct_call)
+
+Why Reachable:
+- Static call path exists from HTTP entrypoint /api/orders/{id}
+- All edges are statically proven (no heuristics)
+- Vulnerable function Lodash.merge() is directly invoked
+
+Confidence Factors:
+  staticPathExists: +0.50
+  noHeuristicEdges: +0.20
+  runtimeConfirmed: +0.00
+
+Alternative Paths: 2
+```
+
+---
+
+### stella reachability explain-all
+
+Export all reachability explanations.
+
+```bash
+stella reachability explain-all [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--status <STATUS>` | Filter by status | All |
+| `--output <PATH>` | Output file path | Required |
+| `--offline` | Run in offline mode | `false` |
+
+#### Examples
+
+```bash
+# Export all explanations
+stella reachability explain-all --scan-id $SCAN_ID --output explanations.json
+
+# Export only reachable findings
+stella reachability explain-all --scan-id $SCAN_ID \
+  --status REACHABLE_STATIC,REACHABLE_PROVEN \
+  --output reachable-explanations.json
+```
+
+---
+
+### stella reachability summary
+
+Show reachability summary for a scan.
+
+```bash
+stella reachability summary [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
+
+#### Examples
+
+```bash
+# Show summary
+stella reachability summary --scan-id $SCAN_ID
+
+# Output:
+# Total vulnerabilities: 45
+# Unreachable: 38 (84%)
+# Possibly reachable: 4 (9%)
+# Reachable (static): 2 (4%)
+# Reachable (proven): 1 (2%)
+# Unknown: 0 (0%)
+```
+
+---
+
+### stella reachability job-status
+
+Check computation job status.
+
+```bash
+stella reachability job-status [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--job-id <ID>` | Job ID | Required |
+
+#### Examples
+
+```bash
+stella reachability job-status --job-id reachability-job-001
+
+# Output:
+# Status: running
+# Progress: 67% (8,234 / 12,345 nodes visited)
+# Started: 2025-12-20T10:00:00Z
+# Estimated completion: 2025-12-20T10:02:30Z
+```
+
+---
+
+## Call Graph Commands
+
+### stella scan graph
+
+Manage call graphs.
+
+```bash
+stella scan graph <SUBCOMMAND> [OPTIONS]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `upload` | Upload call graph |
+| `summary` | Show call graph summary |
+| `entrypoints` | List entrypoints |
+| `export` | Export call graph |
+| `validate` | Validate call graph |
+| `visualize` | Generate visualization |
+| `convert` | Convert graph format |
+| `partition` | Partition large graph |
+| `merge` | Merge multiple graphs |
+
+---
+
+### stella scan graph upload
+
+Upload a call graph to a scan.
+
+```bash
+stella scan graph upload [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--file <PATH>` | Call graph file | Required |
+| `--format <FMT>` | Format: `json`, `ndjson` | Auto-detect |
+| `--streaming` | Use streaming upload | `false` |
+| `--framework <NAME>` | Framework hint | Auto-detect |
+
+#### Examples
+
+```bash
+# Basic upload
+stella scan graph upload --scan-id $SCAN_ID --file callgraph.json
+
+# Streaming upload (large graphs)
+stella scan graph upload --scan-id $SCAN_ID \
+  --file callgraph.ndjson \
+  --format ndjson \
+  --streaming
+
+# With framework hint
+stella scan graph upload --scan-id $SCAN_ID \
+  --file callgraph.json \
+  --framework aspnetcore
+```
+
+---
+
+### stella scan graph summary
+
+Show call graph summary.
+
+```bash
+stella scan graph summary [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+
+#### Examples
+
+```bash
+stella scan graph summary --scan-id $SCAN_ID
+
+# Output:
+# Nodes: 12,345
+# Edges: 56,789
+# Entrypoints: 42
+# Languages: [dotnet, java]
+# Size: 15.2 MB
+```
+
+---
+
+### stella scan graph entrypoints
+
+List detected entrypoints.
+
+```bash
+stella scan graph entrypoints [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--verbose` | Show detailed info | `false` |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
+
+#### Examples
+
+```bash
+# List entrypoints
+stella scan graph entrypoints --scan-id $SCAN_ID
+
+# Output:
+# Kind     | Route               | Framework   | Node
+# ─────────┼─────────────────────┼─────────────┼────────────────
+# http     | GET /api/orders     | aspnetcore  | OrdersController::Get
+# http     | POST /api/orders    | aspnetcore  | OrdersController::Create
+# grpc     | OrderService.Get    | grpc-dotnet | OrderService::GetOrder
+```
+
+---
+
+### stella scan graph validate
+
+Validate call graph structure.
+
+```bash
+stella scan graph validate [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Validate uploaded graph | — |
+| `--file <PATH>` | Validate local file | — |
+| `--strict` | Enable strict validation | `false` |
+
+#### Validation Checks
+
+- All edge targets exist as nodes
+- Entrypoints reference valid nodes
+- No orphan nodes
+- No cycles in entrypoint definitions
+- Schema compliance
+
+#### Examples
+
+```bash
+# Validate uploaded graph
+stella scan graph validate --scan-id $SCAN_ID
+
+# Validate before upload
+stella scan graph validate --file callgraph.json --strict
+```
+
+---
+
+### stella scan graph visualize
+
+Generate call graph visualization.
+
+```bash
+stella scan graph visualize [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--node <ID>` | Center on specific node | — |
+| `--depth <N>` | Visualization depth | 3 |
+| `--output <PATH>` | Output file (SVG/PNG/DOT) | Required |
+| `--format <FMT>` | Format: `svg`, `png`, `dot` | `svg` |
+
+#### Examples
+
+```bash
+# Visualize subgraph
+stella scan graph visualize --scan-id $SCAN_ID \
+  --node sha256:node123... \
+  --depth 3 \
+  --output subgraph.svg
+```
+
+---
+
+## Common Options
+
+### Authentication
+
+| Option | Description |
+|--------|-------------|
+| `--token <TOKEN>` | OAuth bearer token |
+| `--token-file <PATH>` | File containing token |
+| `--profile <NAME>` | Use named profile |
+
+### Output
+
+| Option | Description |
+|--------|-------------|
+| `--quiet` | Suppress non-error output |
+| `--verbose` | Enable verbose output |
+| `--debug` | Enable debug logging |
+| `--no-color` | Disable colored output |
+
+### Connection
+
+| Option | Description |
+|--------|-------------|
+| `--endpoint <URL>` | Scanner API endpoint |
+| `--timeout <DURATION>` | Request timeout |
+| `--insecure` | Skip TLS verification |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `STELLA_TOKEN` | OAuth token |
+| `STELLA_ENDPOINT` | API endpoint |
+| `STELLA_PROFILE` | Profile name |
+| `STELLA_OFFLINE` | Offline mode |
+| `STELLA_SYMBOL_DB` | Symbol database path |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | Authentication failed |
+| 4 | Resource not found |
+| 5 | Computation failed |
+| 6 | Network error |
+| 10 | Timeout |
+
+---
+
+## Related Documentation
+
+- [Score Proofs CLI Reference](./score-proofs-cli-reference.md)
+- [Unknowns CLI Reference](./unknowns-cli-reference.md)
+- [Reachability API Reference](../api/score-proofs-reachability-api-reference.md)
+- [Reachability Runbook](../operations/reachability-runbook.md)
+
+---
+
+**Last Updated**: 2025-12-20  
+**Version**: 1.0.0  
+**Sprint**: 3500.0004.0004
--- a/docs/cli/score-proofs-cli-reference.md
+++ b/docs/cli/score-proofs-cli-reference.md
@@ -0,0 +1,450 @@
+# Score Proofs CLI Reference
+
+**Sprint:** SPRINT_3500_0004_0004  
+**Version:** 1.0.0
+
+## Overview
+
+The Score Proofs CLI commands enable score computation, replay, proof verification, and proof bundle management. All commands support air-gapped operation.
+
+---
+
+## Commands
+
+### stella score
+
+Compute or replay vulnerability scores.
+
+```bash
+stella score <SUBCOMMAND> [OPTIONS]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `compute` | Compute scores for a scan |
+| `replay` | Replay score computation with different inputs |
+| `show` | Display score details for a scan |
+| `diff` | Compare scores between runs |
+| `manifest` | View/export scan manifest |
+| `inputs` | List scoring inputs |
+
+---
+
+### stella score compute
+
+Compute vulnerability scores for a scan.
+
+```bash
+stella score compute [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID to compute scores for | Required |
+| `--deterministic` | Enable deterministic mode | `true` |
+| `--seed <BASE64>` | Random seed for determinism | Auto-generated |
+| `--output <PATH>` | Output file path | stdout |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
+| `--include-proof` | Include proof ledger in output | `false` |
+
+#### Examples
+
+```bash
+# Compute scores
+stella score compute --scan-id $SCAN_ID
+
+# Compute with proof output
+stella score compute --scan-id $SCAN_ID --include-proof --output-format json
+
+# Compute in deterministic mode with fixed seed
+stella score compute --scan-id $SCAN_ID --deterministic --seed "AQIDBA=="
+```
+
+---
+
+### stella score replay
+
+Replay score computation with updated feeds or policies.
+
+```bash
+stella score replay [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID to replay | Required |
+| `--feed-snapshot <HASH>` | Override feed snapshot hash | Current |
+| `--vex-snapshot <HASH>` | Override VEX snapshot hash | Current |
+| `--policy-snapshot <HASH>` | Override policy hash | Current |
+| `--use-original-snapshots` | Use exact original snapshots | `false` |
+| `--diff` | Show diff from original | `false` |
+| `--skip-unchanged` | Skip if no input changes | `false` |
+| `--offline` | Run in offline mode | `false` |
+| `--bundle <PATH>` | Use offline bundle for replay | — |
+| `--output <PATH>` | Output file path | stdout |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
+
+#### Examples
+
+```bash
+# Replay with current feeds
+stella score replay --scan-id $SCAN_ID
+
+# Replay with specific feed snapshot
+stella score replay --scan-id $SCAN_ID --feed-snapshot sha256:newfeed...
+
+# Replay and compare with original
+stella score replay --scan-id $SCAN_ID --diff
+
+# Replay with original snapshots (exact reproduction)
+stella score replay --scan-id $SCAN_ID --use-original-snapshots
+
+# Offline replay
+stella score replay --scan-id $SCAN_ID --offline --bundle /path/to/bundle.zip
+```
+
+---
+
+### stella score show
+
+Display score details for a scan.
+
+```bash
+stella score show [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--verbose` | Show detailed breakdown | `false` |
+| `--include-evidence` | Include evidence references | `false` |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
+
+#### Examples
+
+```bash
+# Show score summary
+stella score show --scan-id $SCAN_ID
+
+# Show detailed breakdown
+stella score show --scan-id $SCAN_ID --verbose
+
+# JSON output
+stella score show --scan-id $SCAN_ID --output-format json
+```
+
+---
+
+### stella score diff
+
+Compare scores between two runs.
+
+```bash
+stella score diff [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID to compare | Required |
+| `--original` | Compare with original score | `false` |
+| `--replayed` | Compare with most recent replay | `false` |
+| `--base <RUN_ID>` | Base run ID for comparison | — |
+| `--target <RUN_ID>` | Target run ID for comparison | — |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
+
+#### Examples
+
+```bash
+# Compare original vs replayed
+stella score diff --scan-id $SCAN_ID --original --replayed
+
+# Compare two specific runs
+stella score diff --scan-id $SCAN_ID --base run-001 --target run-002
+```
+
+---
+
+### stella score manifest
+
+View or export scan manifest.
+
+```bash
+stella score manifest [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--output <PATH>` | Output file path | stdout |
+| `--include-dsse` | Include DSSE envelope | `false` |
+| `--verify` | Verify DSSE signature | `false` |
+
+#### Examples
+
+```bash
+# View manifest
+stella score manifest --scan-id $SCAN_ID
+
+# Export with DSSE
+stella score manifest --scan-id $SCAN_ID --include-dsse --output manifest.json
+
+# Verify manifest signature
+stella score manifest --scan-id $SCAN_ID --verify
+```
+
+---
+
+## Proof Commands
+
+### stella proof
+
+Manage proof bundles.
+
+```bash
+stella proof <SUBCOMMAND> [OPTIONS]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `verify` | Verify a proof bundle |
+| `download` | Download proof bundle |
+| `export` | Export proof bundle |
+| `inspect` | Inspect proof bundle contents |
+| `status` | Check proof status |
+| `list` | List proofs for a scan |
+| `retrieve` | Retrieve from cold storage |
+
+---
+
+### stella proof verify
+
+Verify a proof bundle.
+
+```bash
+stella proof verify [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--bundle-id <HASH>` | Proof bundle ID (sha256:...) | — |
+| `--bundle <PATH>` | Local proof bundle file | — |
+| `--offline` | Skip Rekor verification | `false` |
+| `--skip-rekor` | Alias for --offline | `false` |
+| `--check-rekor` | Force Rekor verification | `false` |
+| `--trust-anchor <PATH>` | Trust anchor file | System default |
+| `--public-key <PATH>` | Public key file | — |
+| `--self-contained` | Use embedded trust anchors | `false` |
+| `--verbose` | Show detailed verification | `false` |
+| `--check <CHECK>` | Verify specific check only | All |
+
+#### Verification Checks
+
+| Check | Description |
+|-------|-------------|
+| `signatureValid` | DSSE signature verification |
+| `idRecomputed` | Content-addressed ID match |
+| `merklePathValid` | Merkle tree construction |
+| `rekorInclusion` | Transparency log entry |
+
+#### Examples
+
+```bash
+# Verify online
+stella proof verify --bundle-id sha256:proof123...
+
+# Verify offline
+stella proof verify --bundle proof.zip --offline
+
+# Verify with specific trust anchor
+stella proof verify --bundle proof.zip --offline --trust-anchor anchors.json
+
+# Verify specific check
+stella proof verify --bundle-id sha256:proof123... --check signatureValid
+```
+
+---
+
+### stella proof download
+
+Download proof bundle.
+
+```bash
+stella proof download [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--root-hash <HASH>` | Specific proof root hash | Latest |
+| `--output <PATH>` | Output file path | `proof-{scanId}.zip` |
+| `--all` | Download all proofs for scan | `false` |
+| `--output-dir <PATH>` | Output directory (with --all) | `.` |
+
+#### Examples
+
+```bash
+# Download latest proof
+stella proof download --scan-id $SCAN_ID --output proof.zip
+
+# Download specific proof
+stella proof download --scan-id $SCAN_ID --root-hash sha256:proof123... --output proof.zip
+
+# Download all proofs
+stella proof download --scan-id $SCAN_ID --all --output-dir ./proofs/
+```
+
+---
+
+### stella proof export
+
+Export proof bundle with additional data.
+
+```bash
+stella proof export [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Scan ID | Required |
+| `--portable` | Create self-contained portable bundle | `false` |
+| `--include-manifest` | Include scan manifest | `true` |
+| `--include-chain` | Include full proof chain | `false` |
+| `--include-trust-anchors` | Include trust anchor keys | `false` |
+| `--output <PATH>` | Output file path | Required |
+
+#### Examples
+
+```bash
+# Export standard bundle
+stella proof export --scan-id $SCAN_ID --output proof-bundle.zip
+
+# Export portable bundle (for offline verification)
+stella proof export --scan-id $SCAN_ID --portable --include-trust-anchors --output portable.zip
+
+# Export with full chain
+stella proof export --scan-id $SCAN_ID --include-chain --output full-bundle.zip
+```
+
+---
+
+### stella proof inspect
+
+Inspect proof bundle contents.
+
+```bash
+stella proof inspect [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--bundle <PATH>` | Proof bundle file | Required |
+| `--output-dir <PATH>` | Extract to directory | — |
+| `--show-manifest` | Display manifest | `false` |
+| `--show-proof` | Display proof nodes | `false` |
+| `--show-meta` | Display metadata | `false` |
+
+#### Examples
+
+```bash
+# List bundle contents
+stella proof inspect --bundle proof.zip
+
+# Extract and inspect
+stella proof inspect --bundle proof.zip --output-dir ./inspection/
+
+# Show manifest
+stella proof inspect --bundle proof.zip --show-manifest
+```
+
+---
+
+## Common Options
+
+### Authentication
+
+| Option | Description |
+|--------|-------------|
+| `--token <TOKEN>` | OAuth bearer token |
+| `--token-file <PATH>` | File containing token |
+| `--profile <NAME>` | Use named profile |
+
+### Output
+
+| Option | Description |
+|--------|-------------|
+| `--quiet` | Suppress non-error output |
+| `--verbose` | Enable verbose output |
+| `--debug` | Enable debug logging |
+| `--no-color` | Disable colored output |
+
+### Connection
+
+| Option | Description |
+|--------|-------------|
+| `--endpoint <URL>` | Scanner API endpoint |
+| `--timeout <DURATION>` | Request timeout (e.g., 30s, 5m) |
+| `--insecure` | Skip TLS verification (dev only) |
+
+---
+
+## Environment Variables
+
+| Variable | Description | Equivalent Option |
+|----------|-------------|-------------------|
+| `STELLA_TOKEN` | OAuth token | `--token` |
+| `STELLA_ENDPOINT` | API endpoint | `--endpoint` |
+| `STELLA_PROFILE` | Profile name | `--profile` |
+| `STELLA_OFFLINE` | Offline mode | `--offline` |
+| `STELLA_TRUST_ANCHOR` | Trust anchor path | `--trust-anchor` |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | Authentication failed |
+| 4 | Resource not found |
+| 5 | Verification failed |
+| 6 | Network error |
+| 10 | Timeout |
+
+---
+
+## Related Documentation
+
+- [Reachability CLI Reference](./reachability-cli-reference.md)
+- [Unknowns CLI Reference](./unknowns-cli-reference.md)
+- [Score Proofs API Reference](../api/score-proofs-reachability-api-reference.md)
+- [Score Proofs Runbook](../operations/score-proofs-runbook.md)
+
+---
+
+**Last Updated**: 2025-12-20  
+**Version**: 1.0.0  
+**Sprint**: 3500.0004.0004
--- a/docs/cli/unknowns-cli-reference.md
+++ b/docs/cli/unknowns-cli-reference.md
@@ -0,0 +1,532 @@
+# Unknowns CLI Reference
+
+**Sprint:** SPRINT_3500_0004_0004  
+**Version:** 1.0.0
+
+## Overview
+
+The Unknowns CLI commands manage components that cannot be analyzed due to missing data, unrecognized formats, or resolution failures. These commands support triage workflows, escalation, and resolution tracking.
+
+---
+
+## Commands
+
+### stella unknowns
+
+Manage unknowns registry.
+
+```bash
+stella unknowns <SUBCOMMAND> [OPTIONS]
+```
+
+#### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List unknowns |
+| `show` | Show unknown details |
+| `summary` | Show unknowns summary |
+| `escalate` | Escalate unknown |
+| `resolve` | Mark unknown resolved |
+| `suppress` | Suppress unknown |
+| `bulk-triage` | Bulk triage unknowns |
+| `export` | Export unknowns |
+| `import` | Import unknown resolutions |
+
+---
+
+### stella unknowns list
+
+List unknowns for a scan or workspace.
+
+```bash
+stella unknowns list [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Filter by scan ID | — |
+| `--workspace-id <ID>` | Filter by workspace ID | — |
+| `--status <STATUS>` | Filter by status | All |
+| `--category <CAT>` | Filter by category | All |
+| `--priority <PRI>` | Filter by priority (1-10) | All |
+| `--min-score <N>` | Minimum 2-factor score | 0 |
+| `--max-age <DURATION>` | Maximum age | — |
+| `--purl <PATTERN>` | Filter by PURL pattern | — |
+| `--output <PATH>` | Output file path | stdout |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table`, `csv` | `table` |
+| `--limit <N>` | Maximum results | 100 |
+| `--offset <N>` | Pagination offset | 0 |
+| `--sort <FIELD>` | Sort field | `priority` |
+| `--order <DIR>` | Sort direction: `asc`, `desc` | `desc` |
+
+#### Status Values
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Awaiting triage |
+| `escalated` | Escalated for manual review |
+| `suppressed` | Suppressed (accepted risk) |
+| `resolved` | Resolved |
+
+#### Category Values
+
+| Category | Description |
+|----------|-------------|
+| `unmapped_purl` | No CPE/OVAL mapping |
+| `checksum_miss` | Binary checksum not in DB |
+| `language_gap` | Unsupported language |
+| `parsing_failure` | Manifest parsing failed |
+| `network_timeout` | Feed unavailable |
+| `unrecognized_format` | Unknown format |
+
+#### Examples
+
+```bash
+# List all pending unknowns
+stella unknowns list --status pending
+
+# List high-priority unknowns
+stella unknowns list --min-score 7
+
+# List by category
+stella unknowns list --category unmapped_purl
+
+# Export to CSV
+stella unknowns list --scan-id $SCAN_ID --output-format csv --output unknowns.csv
+
+# Filter by PURL pattern
+stella unknowns list --purl "pkg:npm/*"
+```
+
+---
+
+### stella unknowns show
+
+Show details of a specific unknown.
+
+```bash
+stella unknowns show [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--id <ID>` | Unknown ID | Required |
+| `--verbose` | Show extended details | `false` |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `text` | `text` |
+
+#### Examples
+
+```bash
+# Show unknown details
+stella unknowns show --id unknown-001
+
+# Output:
+# ID: unknown-001
+# PURL: pkg:npm/left-pad@1.3.0
+# Category: unmapped_purl
+# Status: pending
+# Priority: 6
+# Score: 7.2 (vuln: 3, impact: 4.2)
+# Created: 2025-12-20T10:00:00Z
+# Scans Affected: 5
+# Reason: No CVE/advisory mapping exists for this package
+
+# Verbose output
+stella unknowns show --id unknown-001 --verbose
+
+# JSON output
+stella unknowns show --id unknown-001 --output-format json
+```
+
+---
+
+### stella unknowns summary
+
+Show unknowns summary statistics.
+
+```bash
+stella unknowns summary [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Filter by scan ID | — |
+| `--workspace-id <ID>` | Filter by workspace ID | — |
+| `--output-format <FMT>` | Format: `json`, `yaml`, `table` | `table` |
+
+#### Examples
+
+```bash
+# Summary for workspace
+stella unknowns summary --workspace-id $WS_ID
+
+# Output:
+# Total unknowns: 127
+# 
+# By Status:
+#   pending: 89
+#   escalated: 15
+#   suppressed: 12
+#   resolved: 11
+# 
+# By Category:
+#   unmapped_purl: 67
+#   checksum_miss: 34
+#   language_gap: 18
+#   parsing_failure: 8
+# 
+# Priority Distribution:
+#   High (8-10): 12
+#   Medium (5-7): 45
+#   Low (1-4): 70
+```
+
+---
+
+### stella unknowns escalate
+
+Escalate an unknown for manual review.
+
+```bash
+stella unknowns escalate [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--id <ID>` | Unknown ID | Required |
+| `--reason <TEXT>` | Escalation reason | — |
+| `--assignee <USER>` | Assign to user/team | — |
+| `--severity <LEVEL>` | Severity: `low`, `medium`, `high`, `critical` | `medium` |
+| `--due-date <DATE>` | Due date (ISO 8601) | — |
+
+#### Examples
+
+```bash
+# Basic escalation
+stella unknowns escalate --id unknown-001 --reason "Potential supply chain risk"
+
+# Escalate with assignment
+stella unknowns escalate --id unknown-001 \
+  --reason "Missing mapping for critical dependency" \
+  --assignee security-team \
+  --severity high \
+  --due-date 2025-12-27
+```
+
+---
+
+### stella unknowns resolve
+
+Mark an unknown as resolved.
+
+```bash
+stella unknowns resolve [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--id <ID>` | Unknown ID | Required |
+| `--resolution <TYPE>` | Resolution type | Required |
+| `--comment <TEXT>` | Resolution comment | — |
+| `--mapping <JSON>` | Custom mapping data | — |
+| `--evidence <PATH>` | Evidence file | — |
+
+#### Resolution Types
+
+| Type | Description |
+|------|-------------|
+| `mapped` | Package/CVE mapping added |
+| `not_applicable` | Not applicable to context |
+| `false_positive` | Detection was incorrect |
+| `accepted_risk` | Risk accepted |
+| `replaced` | Component replaced |
+| `removed` | Component removed |
+
+#### Examples
+
+```bash
+# Resolve with mapping
+stella unknowns resolve --id unknown-001 \
+  --resolution mapped \
+  --comment "Added CPE mapping to internal DB"
+
+# Resolve as accepted risk
+stella unknowns resolve --id unknown-001 \
+  --resolution accepted_risk \
+  --comment "Internal component, no external exposure"
+
+# Resolve with evidence
+stella unknowns resolve --id unknown-001 \
+  --resolution not_applicable \
+  --evidence ./analysis-report.pdf
+```
+
+---
+
+### stella unknowns suppress
+
+Suppress an unknown (accept risk).
+
+```bash
+stella unknowns suppress [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--id <ID>` | Unknown ID | Required |
+| `--reason <TEXT>` | Suppression reason | Required |
+| `--expires <DATE>` | Expiration date | — |
+| `--scope <SCOPE>` | Scope: `scan`, `workspace`, `global` | `scan` |
+| `--approver <USER>` | Approver name/email | — |
+
+#### Examples
+
+```bash
+# Suppress with expiration
+stella unknowns suppress --id unknown-001 \
+  --reason "Internal tooling, no risk exposure" \
+  --expires 2026-01-01
+
+# Workspace-wide suppression
+stella unknowns suppress --id unknown-001 \
+  --reason "Deprecated component, scheduled for removal" \
+  --scope workspace \
+  --approver security@example.com
+```
+
+---
+
+### stella unknowns bulk-triage
+
+Bulk triage multiple unknowns.
+
+```bash
+stella unknowns bulk-triage [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--file <PATH>` | Triage decisions file (JSON/YAML) | Required |
+| `--dry-run` | Preview changes | `false` |
+| `--continue-on-error` | Continue on individual failures | `false` |
+
+#### Input File Format
+
+```json
+{
+  "decisions": [
+    {
+      "id": "unknown-001",
+      "action": "resolve",
+      "resolution": "mapped",
+      "comment": "Added mapping"
+    },
+    {
+      "id": "unknown-002",
+      "action": "suppress",
+      "reason": "Accepted risk",
+      "expires": "2026-01-01"
+    },
+    {
+      "id": "unknown-003",
+      "action": "escalate",
+      "reason": "Needs security review",
+      "assignee": "security-team"
+    }
+  ]
+}
+```
+
+#### Examples
+
+```bash
+# Bulk triage with preview
+stella unknowns bulk-triage --file triage-decisions.json --dry-run
+
+# Apply bulk triage
+stella unknowns bulk-triage --file triage-decisions.json
+```
+
+---
+
+### stella unknowns export
+
+Export unknowns data.
+
+```bash
+stella unknowns export [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--scan-id <ID>` | Filter by scan ID | — |
+| `--workspace-id <ID>` | Filter by workspace ID | — |
+| `--status <STATUS>` | Filter by status | All |
+| `--output <PATH>` | Output file path | Required |
+| `--format <FMT>` | Format: `json`, `yaml`, `csv`, `ndjson` | `json` |
+| `--include-history` | Include resolution history | `false` |
+
+#### Examples
+
+```bash
+# Export all unknowns
+stella unknowns export --workspace-id $WS_ID --output unknowns.json
+
+# Export pending as CSV
+stella unknowns export --status pending --output pending.csv --format csv
+
+# Export with history
+stella unknowns export --scan-id $SCAN_ID \
+  --output unknowns-history.json \
+  --include-history
+```
+
+---
+
+### stella unknowns import
+
+Import unknown resolutions.
+
+```bash
+stella unknowns import [OPTIONS]
+```
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--file <PATH>` | Resolutions file | Required |
+| `--format <FMT>` | Format: `json`, `yaml`, `csv` | Auto-detect |
+| `--dry-run` | Preview import | `false` |
+| `--conflict <MODE>` | Conflict handling: `skip`, `update`, `error` | `skip` |
+
+#### Examples
+
+```bash
+# Import resolutions
+stella unknowns import --file resolutions.json
+
+# Preview import
+stella unknowns import --file resolutions.json --dry-run
+
+# Update existing
+stella unknowns import --file resolutions.json --conflict update
+```
+
+---
+
+## Common Options
+
+### Authentication
+
+| Option | Description |
+|--------|-------------|
+| `--token <TOKEN>` | OAuth bearer token |
+| `--token-file <PATH>` | File containing token |
+| `--profile <NAME>` | Use named profile |
+
+### Output
+
+| Option | Description |
+|--------|-------------|
+| `--quiet` | Suppress non-error output |
+| `--verbose` | Enable verbose output |
+| `--debug` | Enable debug logging |
+| `--no-color` | Disable colored output |
+
+### Connection
+
+| Option | Description |
+|--------|-------------|
+| `--endpoint <URL>` | Scanner API endpoint |
+| `--timeout <DURATION>` | Request timeout |
+| `--insecure` | Skip TLS verification |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `STELLA_TOKEN` | OAuth token |
+| `STELLA_ENDPOINT` | API endpoint |
+| `STELLA_PROFILE` | Profile name |
+| `STELLA_WORKSPACE` | Default workspace ID |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | Authentication failed |
+| 4 | Resource not found |
+| 5 | Operation failed |
+| 6 | Network error |
+
+---
+
+## Workflows
+
+### Daily Triage Workflow
+
+```bash
+# 1. Check summary
+stella unknowns summary --workspace-id $WS_ID
+
+# 2. List high-priority pending
+stella unknowns list --status pending --min-score 7
+
+# 3. Review and escalate critical items
+stella unknowns escalate --id unknown-001 \
+  --reason "Security review needed" \
+  --severity high
+
+# 4. Bulk resolve known patterns
+stella unknowns bulk-triage --file daily-resolutions.json
+```
+
+### Weekly Report Export
+
+```bash
+# Export all unknowns with history
+stella unknowns export \
+  --workspace-id $WS_ID \
+  --include-history \
+  --output weekly-unknowns-$(date +%Y%m%d).json
+```
+
+---
+
+## Related Documentation
+
+- [Score Proofs CLI Reference](./score-proofs-cli-reference.md)
+- [Reachability CLI Reference](./reachability-cli-reference.md)
+- [Unknowns API Reference](../api/score-proofs-reachability-api-reference.md)
+- [Unknowns Queue Runbook](../operations/unknowns-queue-runbook.md)
+
+---
+
+**Last Updated**: 2025-12-20  
+**Version**: 1.0.0  
+**Sprint**: 3500.0004.0004