79 lines
4.3 KiB
Markdown
79 lines
4.3 KiB
Markdown
# 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`
|