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

docs consolidation

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-24 12:38:14 +02:00
parent 7503c19b8f
commit 9a08d10b89
215 changed files with 2188 additions and 9623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

334
docs/modules/cli/guides/commands/reachability.md
View File

@@ -1,265 +1,157 @@
# stella reachability — Command Guide
# 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.
The `stella reachability` command group uploads call graphs and queries reachability analyses for vulnerability exploitability assessment.
Typical flow:
1. Generate a call graph locally (optional): `stella scan graph ...`
2. Upload the call graph: `stella reachability upload-callgraph ...`
3. List analyses: `stella reachability list ...`
4. Explain reachability: `stella reachability explain ...`
Notes:
- In multi-tenant environments, pass `--tenant` explicitly.
- Outputs are deterministic: stable ordering, UTC timestamps, and cursor-based paging where applicable.
## Generate a call graph (stella scan graph)
`stella scan graph` extracts a call graph from source code using a language-specific extractor:
- Executable name: `stella-callgraph-<lang>`
- Must be available in `PATH`
Examples:
```bash
# .NET solution
stella scan graph \
--lang dotnet \
--target . \
--sln ./MySolution.sln \
--output ./callgraph.json
# Node.js project (writes JSON to stdout)
stella scan graph \
--lang node \
--target ./service \
--format json > ./callgraph.json
```
Supported `stella scan graph` output formats:
- `json` (default; suitable for upload)
- `dot`
- `summary` (prints only a summary; does not emit graph JSON)
If you generate call graphs with other tooling, uploads support `json`, `proto`, and `dot` formats (or `auto` detection).
## Commands
### Upload Call Graph (CLI-SIG-26-001)
### upload-callgraph
Upload a call graph for reachability analysis.
```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]
--path ./callgraph.json \
--scan-id scan-12345 \
--tenant acme \
--format auto
```
**Options:**
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` |
| --- | --- |
| `--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` | `auto` (default), `json`, `proto`, `dot`. |
| `--tenant`, `-t` | Tenant identifier (recommended in multi-tenant envs). |
| `--json` | Emit raw JSON payload instead of formatted output. |
**Required:** At least one of `--scan-id` or `--asset-id`.
Required: at least one of `--scan-id` or `--asset-id`.
**Supported Call Graph Formats:**
- JSON (native format)
- Protocol Buffers (proto)
- DOT/GraphViz format
### list
### List Reachability Analyses (CLI-SIG-26-001)
List reachability analyses.
```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]
--scan-id scan-12345 \
--status completed \
--limit 20 \
--json
```
**Options:**
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 |
| --- | --- |
| `--scan-id` | Filter by scan identifier. |
| `--asset-id`, `-a` | Filter by asset identifier. |
| `--status` | Filter by status (`pending`, `processing`, `completed`, `failed`). |
| `--limit`, `-l` | Maximum number of results (default 100). |
| `--offset`, `-o` | Pagination offset. |
| `--tenant`, `-t` | Tenant identifier. |
| `--json` | Emit raw JSON payload. |
**Output Columns:**
- Analysis ID
- Asset name/ID
- Status (pending, processing, completed, failed)
- Reachable count
- Unreachable count
- Unknown count
- Created timestamp
### explain
### Explain Reachability (CLI-SIG-26-001)
Explain reachability for a vulnerability ID or a package PURL.
```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]
--analysis-id RA-abc123 \
--vuln-id CVE-2024-1234 \
--call-paths
```
**Options:**
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 |
| --- | --- |
| `--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. |
| `--tenant`, `-t` | Tenant identifier. |
| `--json` | Emit raw JSON payload. |
**Required:** At least one of `--vuln-id` or `--purl`.
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)
## Policy simulation integration
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-state "pkg:npm/lodash@4.17.21: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
Override formats:
- State: `<identifier>:<reachable|unreachable|unknown|indeterminate>`
- Score: `<identifier>:<0..1>`
**Identifier Types:**
- Vulnerability ID: `CVE-XXXX-XXXX`, `GHSA-xxxx-xxxx-xxxx`
- Package URL: `pkg:npm/package@version`, `pkg:maven/group/artifact@version`
Identifier types:
- Vulnerability ID: `CVE-...`, `GHSA-...`
- Package URL: `pkg:...`
## Exit Codes
## Reachability states
| State | Meaning |
| --- | --- |
| `reachable` | Vulnerable code is reachable from entry points. |
| `unreachable` | Vulnerable code is not reachable. |
| `unknown` | Insufficient data to decide. |
| `indeterminate` | Inconclusive (dynamic dispatch/reflection/etc). |
## 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
| --- | --- |
| `0` | Success. |
| `1` | Command failed. |
| `4` | Input validation error. |
| `130` | Operation cancelled. |