Files

StellaOps Bot 4b3db9ca85 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

12 KiB

Raw Blame History

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.

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.

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

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

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

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

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

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

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

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

stella reachability summary [OPTIONS]

Options

Option	Description	Default
`--scan-id <ID>`	Scan ID	Required
`--output-format <FMT>`	Format: `json`, `yaml`, `table`	`table`

Examples

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

stella reachability job-status [OPTIONS]

Options

Option	Description	Default
`--job-id <ID>`	Job ID	Required

Examples

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.

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.

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

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

stella scan graph summary [OPTIONS]

Options

Option	Description	Default
`--scan-id <ID>`	Scan ID	Required

Examples

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.

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

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

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

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

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

# 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

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

12 KiB Raw Blame History

Reachability CLI Reference

Overview

Commands

stella reachability

Subcommands

stella reachability compute

Options

Examples

stella reachability findings

Options

Status Values

Examples

stella reachability explain

Options

Examples

Output Example

stella reachability explain-all

Options

Examples

stella reachability summary

Options

Examples

stella reachability job-status

Options

Examples

Call Graph Commands

stella scan graph

Subcommands

stella scan graph upload

Options

Examples

stella scan graph summary

Options

Examples

stella scan graph entrypoints

Options

Examples

stella scan graph validate

Options

Validation Checks

Examples

stella scan graph visualize

Options

Examples

Common Options

Authentication

Output

Connection

Environment Variables

Exit Codes

Related Documentation

12 KiB

Raw Blame History