# stella reachability - Command Guide

## Overview

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-callgraph

Upload a call graph for reachability analysis.

```bash
stella reachability upload-callgraph \
  --path ./callgraph.json \
  --scan-id scan-12345 \
  --tenant acme \
  --format auto
```

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` | `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`.

### list

List reachability analyses.

```bash
stella reachability list \
  --scan-id scan-12345 \
  --status completed \
  --limit 20 \
  --json
```

Options:

| Flag | Description |
| --- | --- |
| `--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. |

### explain

Explain reachability for a vulnerability ID or a package PURL.

```bash
stella reachability explain \
  --analysis-id RA-abc123 \
  --vuln-id CVE-2024-1234 \
  --call-paths
```

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. |
| `--tenant`, `-t` | Tenant identifier. |
| `--json` | Emit raw JSON payload. |

Required: at least one of `--vuln-id` or `--purl`.

## 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.21:reachable" \
  --reachability-score "CVE-2024-5678:0.25"
```

Override formats:
- State: `<identifier>:<reachable|unreachable|unknown|indeterminate>`
- Score: `<identifier>:<0..1>`

Identifier types:
- Vulnerability ID: `CVE-...`, `GHSA-...`
- Package URL: `pkg:...`

## 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` | Command failed. |
| `4` | Input validation error. |
| `130` | Operation cancelled. |