stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

docs(ops): Complete operations runbooks for Epic 3500

Browse Source 
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).
This commit is contained in:
StellaOps Bot
2025-12-20 22:30:02 +02:00
parent 09c7155f1b
commit 4b3db9ca85
13 changed files with 5630 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

450
docs/cli/score-proofs-cli-reference.md Normal file
View File

@@ -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