git.stella-ops.org/docs/modules/cli/guides/commands/reachability.md

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)

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

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

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

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

{
  "$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

# 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

# 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

# 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

# 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, Soot
• JavaScript/Node.js: callgraph
• Python: pycg
• Go: go build -gcflags="-m" + static analysis
• C/C++: LLVM 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