git.stella-ops.org/docs/cli/score-proofs-cli-reference.md

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.

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.

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

# 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.

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

# 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.

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

# 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.

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

# 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.

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

# 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.

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.

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

# 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.

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

# 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.

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

# 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.

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

# 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
• Unknowns CLI Reference
• Score Proofs API Reference
• Score Proofs Runbook

---

Last Updated: 2025-12-20
Version: 1.0.0
Sprint: 3500.0004.0004