stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
80b82547631dd8c46b7dae5fbde1b09d771a195a
git.stella-ops.org/docs/cli/reachability-cli-reference.md
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

559 lines
12 KiB
Markdown
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.
```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
Reference in New Issue View Git Blame Copy Permalink