up

2025-11-28 18:21:46 +02:00
parent 05da719048
commit d1cbb905f8
103 changed files with 49604 additions and 105 deletions
--- a/docs/modules/cli/guides/commands/reachability.md
+++ b/docs/modules/cli/guides/commands/reachability.md
@@ -0,0 +1,265 @@
+# stella reachability — Command Guide
+
+## Overview
+
+The `stella reachability` command group provides reachability analysis capabilities for vulnerability exploitability assessment. It supports call graph upload, analysis listing, and detailed reachability explanations.
+
+## Commands
+
+### Upload Call Graph (CLI-SIG-26-001)
+
+```bash
+# Upload a call graph for reachability analysis
+stella reachability upload-callgraph \
+  --path <call-graph-file> \
+  [--tenant <id>] \
+  [--scan-id <id>] \
+  [--asset-id <id>] \
+  [--format auto|json|proto|dot] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--path` / `-p` | Path to the call graph file (required) |
+| `--scan-id` | Scan identifier to associate with the call graph |
+| `--asset-id` / `-a` | Asset identifier to associate with the call graph |
+| `--format` / `-f` | Call graph format: `auto` (default), `json`, `proto`, `dot` |
+
+**Required:** At least one of `--scan-id` or `--asset-id`.
+
+**Supported Call Graph Formats:**
+- JSON (native format)
+- Protocol Buffers (proto)
+- DOT/GraphViz format
+
+### List Reachability Analyses (CLI-SIG-26-001)
+
+```bash
+# List reachability analyses
+stella reachability list \
+  [--tenant <id>] \
+  [--scan-id <id>] \
+  [--asset-id <id>] \
+  [--status pending|processing|completed|failed] \
+  [--limit <num>] \
+  [--offset <num>] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--scan-id` | Filter by scan identifier |
+| `--asset-id` / `-a` | Filter by asset identifier |
+| `--status` | Filter by analysis status |
+| `--limit` / `-l` | Maximum number of results (default 100) |
+| `--offset` / `-o` | Pagination offset |
+
+**Output Columns:**
+- Analysis ID
+- Asset name/ID
+- Status (pending, processing, completed, failed)
+- Reachable count
+- Unreachable count
+- Unknown count
+- Created timestamp
+
+### Explain Reachability (CLI-SIG-26-001)
+
+```bash
+# Explain reachability for a vulnerability or package
+stella reachability explain \
+  --analysis-id <id> \
+  [--tenant <id>] \
+  [--vuln-id <cve-id>] \
+  [--purl <package-url>] \
+  [--call-paths] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--analysis-id` / `-i` | Analysis identifier (required) |
+| `--vuln-id` / `-v` | Vulnerability identifier to explain |
+| `--purl` | Package URL to explain |
+| `--call-paths` | Include detailed call paths in the explanation |
+
+**Required:** At least one of `--vuln-id` or `--purl`.
+
+**Output:**
+- Reachability state (reachable, unreachable, unknown)
+- Reachability score (0-1)
+- Confidence level
+- Reasoning explanation
+- Affected functions list
+- Call paths (when `--call-paths` is used)
+
+## Integration with Policy Simulation (CLI-SIG-26-002)
+
+Reachability overrides can be applied during policy simulation:
+
+```bash
+stella policy simulate P-7 \
+  --reachability-state "CVE-2024-1234:unreachable" \
+  --reachability-state "pkg:npm/lodash@4.17.0:reachable" \
+  --reachability-score "CVE-2024-5678:0.25"
+```
+
+**Override Format:**
+- State: `<identifier>:<state>` where state is `reachable`, `unreachable`, `unknown`, or `indeterminate`
+- Score: `<identifier>:<score>` where score is a decimal between 0 and 1
+
+**Identifier Types:**
+- Vulnerability ID: `CVE-XXXX-XXXX`, `GHSA-xxxx-xxxx-xxxx`
+- Package URL: `pkg:npm/package@version`, `pkg:maven/group/artifact@version`
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error or upload failure |
+| 4 | Input validation error |
+| 130 | Operation cancelled by user |
+
+## JSON Schema: ReachabilityExplainResult
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "analysisId": { "type": "string" },
+    "vulnerabilityId": { "type": "string" },
+    "packagePurl": { "type": "string" },
+    "reachabilityState": {
+      "type": "string",
+      "enum": ["reachable", "unreachable", "unknown", "indeterminate"]
+    },
+    "reachabilityScore": { "type": "number", "minimum": 0, "maximum": 1 },
+    "confidence": { "type": "string" },
+    "reasoning": { "type": "string" },
+    "callPaths": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "pathId": { "type": "string" },
+          "depth": { "type": "integer" },
+          "entryPoint": { "$ref": "#/$defs/function" },
+          "frames": { "type": "array", "items": { "$ref": "#/$defs/function" } },
+          "vulnerableFunction": { "$ref": "#/$defs/function" }
+        }
+      }
+    },
+    "affectedFunctions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/function" }
+    }
+  },
+  "$defs": {
+    "function": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "signature": { "type": "string" },
+        "className": { "type": "string" },
+        "packageName": { "type": "string" },
+        "filePath": { "type": "string" },
+        "lineNumber": { "type": "integer" }
+      }
+    }
+  }
+}
+```
+
+## Examples
+
+### Upload a call graph
+
+```bash
+# Upload call graph for a specific scan
+stella reachability upload-callgraph \
+  --path ./callgraph.json \
+  --scan-id scan-12345 \
+  --format json
+
+# Upload with auto-detection
+stella reachability upload-callgraph \
+  --path ./app-callgraph.dot \
+  --asset-id my-application
+```
+
+### List recent analyses
+
+```bash
+# List all completed analyses for an asset
+stella reachability list \
+  --asset-id my-application \
+  --status completed \
+  --json
+
+# List analyses with pagination
+stella reachability list \
+  --limit 20 \
+  --offset 40
+```
+
+### Explain vulnerability reachability
+
+```bash
+# Explain with call paths
+stella reachability explain \
+  --analysis-id RA-abc123 \
+  --vuln-id CVE-2024-1234 \
+  --call-paths
+
+# Explain package reachability
+stella reachability explain \
+  --analysis-id RA-abc123 \
+  --purl "pkg:npm/lodash@4.17.21" \
+  --json
+```
+
+### Policy simulation with reachability overrides
+
+```bash
+# Mark specific vulnerability as unreachable
+stella policy simulate P-7 \
+  --reachability-state "CVE-2024-1234:unreachable" \
+  --explain
+
+# Set low reachability score
+stella policy simulate P-7 \
+  --reachability-score "pkg:npm/axios@0.21.0:0.1"
+```
+
+## Reachability States
+
+| State | Description |
+|-------|-------------|
+| `reachable` | Vulnerable code is reachable from application entry points |
+| `unreachable` | Vulnerable code cannot be reached during execution |
+| `unknown` | Reachability cannot be determined with available information |
+| `indeterminate` | Analysis inconclusive due to dynamic dispatch or reflection |
+
+## Call Graph Generation
+
+Call graphs can be generated using various tools:
+
+- **Java:** [WALA](https://github.com/wala/WALA), [Soot](https://github.com/soot-oss/soot)
+- **JavaScript/Node.js:** [callgraph](https://www.npmjs.com/package/callgraph)
+- **Python:** [pycg](https://github.com/vitsalis/pycg)
+- **Go:** `go build -gcflags="-m"` + static analysis
+- **C/C++:** [LLVM](https://llvm.org/) call graph pass
+
+## Best Practices
+
+1. **Upload call graphs after each build** to maintain accurate reachability data
+2. **Use asset IDs** for long-lived applications to track reachability changes over time
+3. **Include call paths** when debugging unexpected reachability results
+4. **Apply reachability overrides** in policy simulation to model remediation scenarios
+5. **Monitor unreachable counts** as a metric for dependency hygiene