# Deterministic Reachability — Product Moat (Nov 2025)

Source: internal advisory “23-Nov-2025 - Where Stella Ops Can Truly Lead”. Supersedes/extends archived binary reachability advisories (18-Nov-2025 - Binary-Reachability-Engine, Encoding Binary Reachability with PURL-Resolved Edges, CSharp-Binary-Analyzer). This page is the canonical, high-level articulation of our reachability moat for architects, PMM, and field teams. Detailed schemas live in `docs/reachability/evidence-schema.md` and `docs/reachability/hybrid-attestation.md`.

## Why it matters
- Most scanners list every CVE; reachability asks whether vulnerable code is actually callable.
- Competitors infer paths and rarely sign evidence; we **prove** paths with deterministic graphs and attestations.
- Outcome targets: ≥40% fewer noisy vulns shown; ≥25% faster triage via explainable “why” paths.

## Moat elements
1) **Deterministic call-graphs per artifact**
   - Stable node IDs: `purl@version!build-id!symbol-signature` (or code offset when stripped).
   - Stable edge IDs: `SHA256(nodeA||nodeB||tool-version||inputs-hash)`.
   - Graph hash: BLAKE3 over canonical JSON; locked by manifest.
2) **Signed evidence**
   - Graph-level DSSE for every scan (mandatory).
   - Optional edge-bundle DSSE (≤512 edges) for runtime/init/contested edges; Rekor publish capped. See `docs/reachability/hybrid-attestation.md`.
3) **Explainability**
   - Each finding carries call-chain + per-edge reason + VEX gate decision + layer attribution.
4) **Container layer provenance**
   - Track file-to-layer mapping; show “introduced in layer X from base Y”.
5) **Replayability**
   - Determinism manifest locks feeds, toolchain hashes, analyzer flags; replay yields identical graph and attestations.

## Minimal architecture slice
- **Sbomer/Scanner**: emit SBOM + symbol maps + per-layer file index; capture Build-IDs.
- **Cartographer**: build deterministic call-graphs (language + native), output `EdgeList.jsonl` with stable IDs.
- **Attestor**: wrap graph (and edge bundles when emitted) into DSSE; log digests to Rekor/mirror.
- **Vexer/Policy**: evaluate lattice, produce OpenVEX with linked edge proofs.
- **Ledger**: retain manifests and DSSE; mirror to Rekor where allowed.

## Practical spec (condensed)
- **Node fields**: `symbol_id`, `code_id`, `purl`, `build_id`, `symbol_digest`, `lang`, `evidence[]`.
- **Edge fields**: `from`, `to`, `kind` (direct|plt|runtime|init), `purl`, `symbol_digest`, `reason`, `confidence`, `evidence[]`.
- **Roots**: exports, entrypoints, **.init_array/.ctors/TLS callbacks**, plugin hooks.
- **Attestation layout**:
  - Graph: `cas://reachability/graphs/{blake3}` + `{blake3}.dsse` (Rekor always).
  - Edge bundle: `cas://reachability/edges/{graph_hash}/{bundle_id}[.dsse]` (Rekor optional, capped).

### Example: Edge-bundle DSSE payload (abridged)
```json
{
  "graph_hash": "blake3:...",
  "bundle_reason": "runtime-hit",
  "edges": [{
    "edge_id": "sha256:...",
    "from": "sym:...caller",
    "to": "sym:...callee",
    "reason": "plt",
    "purl": "pkg:deb/openssl@3.0.2?arch=amd64",
    "symbol_digest": "sha256:...",
    "revoked": false
  }]
}
```

### Field cheat sheet (for sprint readers)
- `graph_hash` — BLAKE3 of canonical graph JSON.
- `bundle_reason` — `runtime-hit | init-root | contested | third-party`.
- `edge_id` — sha256(from||to||reason||tool-version||inputs-hash).
- `revoked` — when true, policy/Signals must drop this edge before reachability scoring.
- `purl` + `symbol_digest` — bind edge to SBOM component and callee identity.

## Quick wins (ship order)
1) Capture Build-IDs in Scanner and thread into `symbol_id`/`code_id`.
2) Emit Graph Determinism Manifest (feeds + toolchain hashes) per scan.
3) Turn on edge-bundle DSSE for runtime/init edges first; keep Rekor cap low.
4) Surface “why path” + layer attribution in CLI/UI explainers.

## APIs (strawman)
- `POST /graph/edges: attest` — idempotent; same inputs → same edge IDs.
- `GET /findings/:id/proof` — returns call-chain + Rekor inclusion proofs.
- `GET /vex/:artifact` — streams OpenVEX with embedded proofs.

## Links
- Advisory source: `docs/product-advisories/23-Nov-2025 -  Where Stella Ops Can Truly Lead.md`
- Schemas: `docs/reachability/evidence-schema.md`, `docs/reachability/hybrid-attestation.md`
- Sprint tracking: `docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md`