# 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