up

2025-12-13 09:37:15 +02:00
parent e00f6365da
commit 6e45066e37
349 changed files with 17160 additions and 1867 deletions
--- a/docs/reachability/function-level-evidence.md
+++ b/docs/reachability/function-level-evidence.md
@@ -1,175 +1,535 @@
-# Function-Level Evidence Readiness (Nov 2025 Advisory)
+# Function-Level Evidence Guide

-_Last updated: 2025-11-12. Owner: Business Analysis Guild._
+_Last updated: 2025-12-13. Owner: Docs Guild._

-This memo captures the outstanding work required to make Stella Ops scanners emit stable, function-level evidence that matches the November 2025 advisory. It does **not** implement any code; instead it enumerates requirements, links them to sprint tasks, and spells out the schema/API updates that the next agent must land.
+This guide documents the cross-module function-level evidence chain that enables provable reachability claims. It covers the schema, identifiers, API usage, CLI commands, and integration patterns for Scanner, Signals, Policy, and Replay.

 ---

-## 1. Goal & Scope
+## 1. Overview

-**Goal.** Anchor every vulnerability finding to an immutable `{artifact_digest, code_id}` tuple plus optional symbol hints so replayers can prove reachability against stripped binaries.
+StellaOps implements a **function-level evidence chain** that anchors every vulnerability finding to immutable identifiers (`code_id`, `symbol_id`, `graph_hash`) enabling:

-**Scope.** Scanner analyzers, runtime ingestion, Signals scoring, Replay manifests, Policy/VEX emission, CLI/UI explainers, and documentation/runbooks needed to operationalise the advisory.
+- **Provable reachability:** Deterministic call-path evidence from entry points to vulnerable functions.
+- **Stripped binary support:** `code_id` + `code_block_hash` provides identity when symbols are absent.
+- **Evidence replay:** Sealed artifacts with DSSE attestation allow offline verification.
+- **Cross-module linking:** Scanner -> Signals -> Policy -> VEX -> UI/CLI evidence chain.

-Out of scope: implementing disassemblers or symbol servers; those will be handled inside the module-specific backlog tasks referenced below.
+### 1.1 Core Identifiers
+
+| Identifier | Format | Purpose | Example |
+|------------|--------|---------|---------|
+| `symbol_id` | `sym:{lang}:{base64url}` | Canonical function identity | `sym:java:R3JlZXRpbmc...` |
+| `code_id` | `code:{lang}:{base64url}` | Identity for name-less code blocks | `code:binary:YWJjZGVm...` |
+| `graph_hash` | `blake3:{hex}` | Content-addressable graph identity | `blake3:a1b2c3d4e5f6...` |
+| `symbol_digest` | `sha256:{hex}` | Hash of symbol_id for edge linking | `sha256:e5f6a7b8c9d0...` |
+| `build_id` | `gnu-build-id:{hex}` | ELF/PE debug identifier | `gnu-build-id:5f0c7c3c...` |
+
+### 1.2 Evidence Chain Flow
+
+```
+Scanner -> richgraph-v1 -> Signals -> Scoring -> Policy -> VEX -> UI/CLI
+   |            |             |          |         |        |        |
+   |            |             |          |         |        |        +-- stella graph explain
+   |            |             |          |         |        +-- OpenVEX with call-path proofs
+   |            |             |          |         +-- Policy gates + reachability.state
+   |            |             |          +-- Lattice state + confidence + riskScore
+   |            |             +-- Runtime facts + static paths
+   |            +-- BLAKE3 graph_hash + DSSE attestation
+   +-- code_id, symbol_id, build_id per node
+```

 ---

-## 2. Advisory Requirements vs. System Gaps
+## 2. Schema Reference

-| Requirement | Current gap | Task references | Notes |
-|-------------|-------------|-----------------|-------|
-| Immutable code identity (`code_id` = `{format, build_id, start, length}` + optional `code_block_hash`) | Callgraph nodes are opaque strings with no address metadata. | Sprint 401 `GRAPH-CAS-401-001`, `GAP-SCAN-001`, `GAP-SYM-007` | `code_id` should live alongside existing `SymbolID` helpers so analyzers can emit it without duplicating logic. |
-| Symbol hints (demangled name, source, confidence) | No schema fields for symbol metadata; demangling is ad-hoc per analyzer. | `GAP-SYM-007` | Require deterministic casing + `symbol.source ∈ {DWARF,PDB,SYM,none}`. |
-| Runtime facts mapped to code anchors | `/signals/runtime-facts` now accepts JSON and NDJSON (gzip) streams, stores symbol/code/process/container metadata. | Sprint 400 `ZASTAVA-REACH-201-001`, Sprint 401 `SIGNALS-RUNTIME-401-002`, `GAP-ZAS-002`, `GAP-SIG-003` | Provenance enrichment (process/socket/container) persisted; next step is exposing CAS URIs + context facts and emitting events for Policy/Replay. |
-| Replay/DSSE coverage | Replay manifests don’t enforce hash/CAS registration for graphs/traces. | Sprint 400 `REPLAY-REACH-201-005`, Sprint 401 `REPLAY-401-004`, `GAP-REP-004` | Extend manifest v2 with analyzer versions + BLAKE3 digests; add DSSE predicate types. |
-| Policy/VEX/UI explainability | Policy uses coarse `reachability:*` tags; UI/CLI cannot show call paths or evidence hashes. | Sprint 401 `POLICY-VEX-401-006`, `UI-CLI-401-007`, `GAP-POL-005`, `GAP-VEX-006`, `EXPERIENCE-GAP-401-012` | Evidence blocks must cite `code_id`, graph hash, runtime CAS URI, analyzer version. |
-| Operator documentation & samples | No guide shows how to replay `{build_id,start,len}` across CLI/API. | Sprint 401 `QA-DOCS-401-008`, `GAP-DOC-008` | Produce samples under `samples/reachability/**` plus CLI walkthroughs. |
-| Build-id propagation | Build-id not consistently captured or threaded into `SymbolID`/`code_id`; SBOM/runtime joins are brittle. | Sprint 401 `SCANNER-BUILDID-401-035` | Capture `.note.gnu.build-id`, include in code identity, expose in SBOM exports and runtime events. |
-| Load-time constructors as roots | Graph roots omit `.preinit_array`/`.init_array`/`_init`, missing load-time edges. | Sprint 401 `SCANNER-INITROOT-401-036` | Add synthetic roots with `phase=load`; include `DT_NEEDED` deps’ constructors. |
-| PURL-resolved edges | Call edges do not carry `purl` or `symbol_digest`, slowing SBOM joins. | Sprint 401 `GRAPH-PURL-401-034` | Annotate edges per `docs/reachability/purl-resolved-edges.md`; keep deterministic graph hash. |
-| Unknowns handling | Unresolved symbols/edges disappear silently. | Sprint 0400 `SIGNALS-UNKNOWN-201-008` | Emit Unknowns records (see `docs/signals/unknowns-registry.md`) and feed `unknowns_pressure` into scoring. |
-| Patch-oracle QA | No guard-rail tests proving binary analyzers see real patch deltas. | Sprint 401 `QA-PORACLE-401-037` | Add paired vuln/fixed fixtures and expectations; wire to CI using `docs/reachability/patch-oracles.md`. |
+### 2.1 SymbolID Construction

---
+Per-language canonical tuple format (NUL-separated, then SHA-256 -> base64url):

-## 3. Workstreams & Expectations
+| Language | Tuple Components | Example |
+|----------|------------------|---------|
+| Java | `{package}\0{class}\0{method}\0{descriptor}` | `com.example\0Foo\0bar\0(Ljava/lang/String;)V` |
+| .NET | `{assembly}\0{namespace}\0{type}\0{member_signature}` | `MyApp\0Controllers\0UserController\0GetById(int)` |
+| Go | `{module}\0{package}\0{receiver}\0{func}` | `github.com/user/repo\0handler\0*Server\0Handle` |
+| Node | `{pkg_or_path}\0{export_path}\0{kind}` | `lodash\0get\0function` |
+| Binary | `{file_hash}\0{section}\0{addr}\0{name}\0{linkage}\0{code_block_hash?}` | `sha256:abc...\0.text\00x401000\0ssl3_read\0global\0` |
+| Python | `{pkg_or_path}\0{module}\0{qualified_name}` | `requests\0api\0get` |
+| Ruby | `{gem_or_path}\0{module}\0{method}` | `rails\0ActionController::Base\0render` |
+| PHP | `{composer_pkg}\0{namespace}\0{qualified_name}` | `symfony/http-kernel\0Kernel\0handle` |

-### 3.1 Scanner Symbolization (GAP-SCAN-001 / GAP-SYM-007)
+### 2.2 CodeID Construction

-* Define `SymbolID` helpers that glue together `{artifact_digest, file`, optional `section`, `addr`, `length`, `code_block_hash`}.
-* Update analyzer contracts so every analyzer returns both `symbol_id` and `code_id`, with demangled names stored under the new `symbol` block.
-* Persist the data into `richgraph-v1` payloads and attach CAS URIs via `StellaOps.Scanner.Reachability`.
-* Deliver fixtures in `tests/reachability/StellaOps.ScannerSignals.IntegrationTests` that prove determinism (same hash when analyzer flags reorder).
-* **Helper status (2025-12-02):** `SymbolId.ForBinaryAddressed` + `CodeId.ForBinarySegment` now encode `{file_hash, section, addr, name, linkage, length, code_block_hash}` with normalized hex addresses. Analyzers should start emitting these tuples instead of ad-hoc hashes.
-* **Binary lifter (2025-12-03):** `BinaryReachabilityLifter` emits richgraph nodes for ELF/PE/Mach-O using file SHA-256 + section/address tuples, attaches `code_id` anchors, and turns imports/load commands into `import` edges.
-* **Schema wiring (2025-12-12):** `reachability-union` + `richgraph-v1` serializers now emit `symbol {mangled,demangled,source,confidence}` and optional `code_block_hash` for stripped blocks; confidence is clamped to `[0,1]` and `source` normalized to uppercase (`DWARF|PDB|SYM|NONE`).
+For stripped binaries or name-less code blocks:

-### 3.2 Runtime + Signals (GAP-ZAS-002 / GAP-SIG-003)
+```
+code:{lang}:{base64url_sha256(format + file_hash + addr + length + section + code_block_hash)}
+```

-* Extend Zastava Observer NDJSON schema to emit: `symbol_id`, `code_id`, `hit_count`, `observed_at`, `loader_base`, `process.buildId`.
-* Implement `/signals/runtime-facts` ingestion (gzip + NDJSON) with CAS-backed storage under `cas://reachability/runtime/{sha256}`.
-* Update `ReachabilityScoringService` to lattice states and include runtime evidence references plus CAS URIs in `ReachabilityFactDocument.Metadata`.
+Example for stripped ELF:
+```
+code:binary:YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo
+```

-### 3.3 Replay & Evidence (GAP-REP-004)
+### 2.3 Graph Node Schema

-* Enforce CAS registration + BLAKE3 hashing before manifest writes (graphs and traces).
-* Teach `ReachabilityReplayWriter` to require analyzer name/version, graph kind, `code_id` coverage summary.
-* Update `docs/replay/DETERMINISTIC_REPLAY.md` once schema v2 is finalized.
-
-### 3.4 Policy, VEX, CLI/UI (GAP-POL-005 / GAP-VEX-006)
-
-* Policy Engine: ingest new reachability facts, expose `reachability.state`, `max_path_conf`, and `evidence.graph_hash` via SPL + API.
-* CLI/UI: add `stella graph explain` and explain drawer showing call path (`SymbolID` list), code anchors, runtime hits, DSSE references.
-* Notify templates: include short evidence summary (first hop + truncated `code_id`).
-
-### 3.5 Documentation & Samples (GAP-DOC-008)
-
-* Publish schema diffs in `docs/data/evidence-schema.md` (new file) covering SBOM evidence nodes, runtime NDJSON, and API responses.
-* Write CLI/API walkthroughs in `docs/09_API_CLI_REFERENCE.md` and `docs/api/policy.md` showing how to request reachability evidence and verify DSSE chains.
-* Produce OpenVEX + replay samples under `samples/reachability/` showing `facts.type = "stella.reachability"` with `graph_hash` and `code_id` arrays.
-
-### 3.6 Native lifter & Reachability Store (SCANNER-NATIVE-401-015 / SIG-STORE-401-016)
-
-* Stand up `Scanner.Symbols.Native` + `Scanner.CallGraph.Native` libraries that:
-  * parse ELF (DWARF + `.symtab`/`.dynsym`), PE/COFF (CodeView/PDB), and stripped binaries via probabilistic carving;
-  * emit deterministic `FuncNode` + `CallEdge` records with demangled names, language hints, and `{confidence,evidence}` arrays; and
-  * attach analyzer + toolchain identifiers consumed by `richgraph-v1`.
-* Introduce `Reachability.Store` collections in Mongo:
-  * `func_nodes` – keyed by `func:<format>:<sha256>:<va>` with `{binDigest,name,addr,size,lang,confidence,sym}`.
-  * `call_edges` – `{from,to,kind,confidence,evidence[]}` linking internal/external nodes.
-  * `cve_func_hits` – `{cve,purl,func_id,match_kind,confidence,source}` for advisory alignment.
-* Build indexes (`binDigest+name`, `from→to`, `cve+func_id`) and expose repository interfaces so Scanner, Signals, and Policy can reuse the same canonical data without duplicating queries.
-
---
-
-## 4. Schema & API Touchpoints
-
-Authoritative field list lives in `docs/reachability/evidence-schema.md`; use it for DTOs and CAS writers.
-
-The next implementation pass must cover the following documents/files (create them if missing):
-
-1. `docs/data/evidence-schema.md` – authoritative schema for `{code_id, symbol, tool}` blocks.
-2. `docs/runbooks/reachability-runtime.md` – operator steps for staging runtime ingestion bundles, retention, and troubleshooting.
-3. `docs/runbooks/replay_ops.md` – add section detailing replay verification using the new graph/runtime CAS entries.
-
-API contracts to amend:
-
- `POST /signals/callgraphs` response includes `graphHash` (sha256) for the normalized callgraph; richgraph-v1 uses BLAKE3 for graph CAS hashes.
- `POST /signals/runtime-facts` request body schema (NDJSON) with `symbol_id`, `code_id`, `hit_count`, `loader_base`.
- `GET /policy/findings` payload must surface `reachability.evidence[]` objects.
-
-### 4.1 Signals runtime ingestion snapshot (Nov 2025)
-
- `/signals/runtime-facts` (JSON) and `/signals/runtime-facts/ndjson` (streaming, optional gzip) accept the following event fields:
-  - `symbolId` (required), `codeId`, `loaderBase`, `hitCount`, `processId`, `processName`, `socketAddress`, `containerId`, `evidenceUri`, `metadata`.
-  - Subject context (`scanId` / `imageDigest` / `component` / `version`) plus `callgraphId` is supplied either in the JSON body or as query params for the NDJSON endpoint.
- Signals dedupes events, merges metadata, and persists the aggregated `RuntimeFacts` onto `ReachabilityFactDocument`. These facts now feed reachability scoring (SIGNALS-24-004/005) as part of the runtime bonus lattice.
- Outstanding work: record CAS URIs for runtime traces, emit provenance events, and expose the enriched context to Policy/Replay consumers.
-
-### 4.2 Reachability store layout (SIG-STORE-401-016)
-
-All producers **must** persist native function evidence using the shared collections below (names are advisory; exact names live in Mongo options):
+Each node in a richgraph-v1 document includes:

 ```json
-// func_nodes
 {
-  "_id": "func:ELF:sha256:4012a0",
-  "binDigest": "sha256:deadbeef...",
-  "name": "ssl3_read_bytes",
-  "addr": "0x4012a0",
-  "size": 312,
-  "lang": "c",
-  "confidence": 0.92,
-  "symbol": { "mangled": "_Z15ssl3_read_bytes", "demangled": "ssl3_read_bytes", "source": "DWARF" },
-  "sym": "present"
-}
-
-// call_edges
-{
-  "from": "func:ELF:sha256:4012a0",
-  "to": "func:ELF:sha256:40f0ff",
-  "kind": "static",
-  "confidence": 0.88,
-  "evidence": ["reloc:.plt.got", "bb-target:0x40f0ff"]
-}
-
-// cve_func_hits
-{
-  "cve": "CVE-2023-XXXX",
-  "purl": "pkg:generic/openssl@1.1.1u",
-  "func_id": "func:ELF:sha256:4012a0",
-  "match": "name+version",
-  "confidence": 0.77,
-  "source": "concelier:openssl-advisory"
+  "id": "sym:java:R3JlZXRpbmdTZXJ2aWNl...",
+  "symbol_id": "sym:java:R3JlZXRpbmdTZXJ2aWNl...",
+  "code_id": "code:java:...",
+  "lang": "java",
+  "kind": "method",
+  "display": "com.example.GreetingService.greet(String)",
+  "purl": "pkg:maven/com.example/greeting-service@1.0.0",
+  "build_id": "gnu-build-id:5f0c7c3c...",
+  "symbol_digest": "sha256:e5f6a7b8...",
+  "code_block_hash": "sha256:deadbeef...",
+  "symbol": {
+    "mangled": null,
+    "demangled": "com.example.GreetingService.greet(String)",
+    "source": "DWARF",
+    "confidence": 0.98
+  },
+  "evidence": ["import", "bytecode"],
+  "attributes": {}
 }
 ```

-Writers **must**:
+### 2.4 Graph Edge Schema

-1. Upsert `func_nodes` before emitting edges/hits to ensure `_id` lookups remain stable.
-2. Serialize evidence arrays in deterministic order (`reloc`, `bb-target`, `import`, …) and normalise hex casing.
-3. Attach analyzer fingerprints (`scanner.native@sha256:...`) so Replay/Policy can enforce provenance.
+Edges carry callee `purl` and `symbol_digest` for SBOM correlation:
+
+```json
+{
+  "from": "sym:java:caller...",
+  "to": "sym:java:callee...",
+  "kind": "call",
+  "purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1",
+  "symbol_digest": "sha256:f1e2d3c4...",
+  "confidence": 0.92,
+  "evidence": ["bytecode", "import"],
+  "candidates": []
+}
+```
+
+### 2.5 Evidence Block Schema
+
+Evidence blocks in Policy/VEX responses cite all relevant identifiers:
+
+```json
+{
+  "evidence": {
+    "graph_hash": "blake3:a1b2c3d4e5f6...",
+    "graph_cas_uri": "cas://reachability/graphs/a1b2c3d4e5f6...",
+    "dsse_uri": "cas://reachability/graphs/a1b2c3d4e5f6....dsse",
+    "path": [
+      {"symbol_id": "sym:java:...", "display": "main()"},
+      {"symbol_id": "sym:java:...", "display": "processRequest()"},
+      {"symbol_id": "sym:java:...", "display": "log4j.error()"}
+    ],
+    "path_length": 3,
+    "confidence": 0.85,
+    "runtime_hits": ["probe:jfr:1234"],
+    "analyzer": {
+      "name": "scanner.java",
+      "version": "1.2.0",
+      "toolchain_digest": "sha256:..."
+    }
+  }
+}
+```

 ---

-## 5. Test & Fixture Expectations
+## 3. API Usage

- **Reachbench fixtures**: update golden cases with `code_id` + `symbol` metadata. Ensure both reachable/unreachable variants still pass once graphs contain the richer IDs.
- **Signals unit tests**: add deterministic tests for lattice scoring + runtime evidence linking (`tests/reachability/StellaOps.Signals.Reachability.Tests`).
- **Replay tests**: extend `tests/reachability/StellaOps.Replay.Core.Tests` to assert manifest v2 serialization and hash enforcement.
+### 3.1 Signals Callgraph Ingestion

-All fixtures must remain deterministic: sort nodes/edges, normalise casing, and freeze timestamps in test data.
+Submit a callgraph and receive a deterministic `graph_hash`:
+
+```http
+POST /signals/callgraphs
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "schema": "richgraph-v1",
+  "analyzer": {"name": "scanner.java", "version": "1.2.0"},
+  "nodes": [...],
+  "edges": [...],
+  "roots": [...]
+}
+```
+
+**Response:**
+
+```json
+{
+  "graphHash": "blake3:a1b2c3d4e5f6...",
+  "casUri": "cas://reachability/graphs/a1b2c3d4e5f6...",
+  "dsseUri": "cas://reachability/graphs/a1b2c3d4e5f6....dsse",
+  "nodeCount": 1247,
+  "edgeCount": 3891
+}
+```
+
+### 3.2 Signals Runtime Facts
+
+Submit runtime observations with `code_id` anchors:
+
+```http
+POST /signals/runtime-facts/ndjson?scanId=scan-123&imageDigest=sha256:abc123
+Authorization: Bearer <token>
+Content-Type: application/x-ndjson
+Content-Encoding: gzip
+
+{"symbolId":"sym:java:...","codeId":"code:java:...","hitCount":47,"loaderBase":"0x7f...","processId":1234,"observedAt":"2025-12-13T10:00:00Z"}
+{"symbolId":"sym:java:...","codeId":"code:java:...","hitCount":12,"loaderBase":"0x7f...","processId":1234,"observedAt":"2025-12-13T10:00:01Z"}
+```
+
+**Response:**
+
+```json
+{
+  "accepted": 128,
+  "duplicates": 2,
+  "evidenceUri": "cas://reachability/runtime/sha256:xyz789..."
+}
+```
+
+### 3.3 Fetch Reachability Facts
+
+Query reachability state for a subject:
+
+```http
+GET /signals/facts/{subjectKey}
+Authorization: Bearer <token>
+```
+
+**Response:**
+
+```json
+{
+  "subjectKey": "scan:123:pkg:maven/log4j:2.14.1:CVE-2021-44228",
+  "metadata": {
+    "fact": {
+      "digest": "sha256:abc123...",
+      "version": 3
+    }
+  },
+  "states": [
+    {
+      "symbol": "sym:java:...",
+      "latticeState": "CR",
+      "bucket": "runtime",
+      "confidence": 0.92,
+      "score": 0.78,
+      "path": ["sym:java:main...", "sym:java:process...", "sym:java:log4j..."],
+      "evidence": {
+        "static": {"graphHash": "blake3:...", "pathLength": 3, "confidence": 0.85},
+        "runtime": {"probeId": "probe:jfr:1234", "hitCount": 47, "observedAt": "2025-12-13T10:00:00Z"}
+      }
+    }
+  ],
+  "score": 0.78,
+  "aggregateTier": "T2",
+  "riskScore": 0.65
+}
+```
+
+### 3.4 Policy Findings with Reachability Evidence
+
+```http
+GET /api/policy/findings/{policyId}/{findingId}/explain?mode=verbose
+Authorization: Bearer <token>
+```
+
+**Response (excerpt):**
+
+```json
+{
+  "findingId": "P-7:S-42:pkg:maven/log4j@2.14.1:CVE-2021-44228",
+  "reachability": {
+    "state": "CR",
+    "confidence": 0.92,
+    "evidence": {
+      "graph_hash": "blake3:a1b2c3d4...",
+      "path": [
+        {"symbol_id": "sym:java:...", "display": "main()"},
+        {"symbol_id": "sym:java:...", "display": "Logger.error()"}
+      ],
+      "runtime_hits": 47,
+      "fact_digest": "sha256:abc123..."
+    }
+  },
+  "steps": [
+    {"rule": "reachability_gate", "state": "CR", "allowed": true},
+    {"rule": "severity_baseline", "severity": {"normalized": "Critical", "score": 10.0}}
+  ]
+}
+```

 ---

-## 6. Handoff Checklist for the Next Agent
+## 4. CLI Usage

-1. Confirm sprint entries (`SPRINT_400` and `SPRINT_401`) remain in sync when moving `GAP-*` tasks to DOING/DONE.
-2. Start with `GAP-SYM-007` (schema/helper implementation) because downstream work depends on the new `code_id` payload shape.
-3. Once schema PR merges, coordinate with Signals + Policy guilds to align on CAS naming and DSSE predicates before wiring APIs.
-4. Update the docs listed in §4 as each component lands; keep this file current with statuses and links to PRs/ADRs.
-5. Before shipping, run the reachbench fixtures end-to-end and capture hashes for inclusion in replay docs.
+### 4.1 Graph Explain Command

-Keep this document updated as tasks change state; it is the authoritative hand-off note for the advisory.
+View the call path and evidence for a finding:
+
+```bash
+stella graph explain --finding "pkg:maven/log4j@2.14.1:CVE-2021-44228" --scan-id scan-123
+
+# Output:
+Finding: CVE-2021-44228 in pkg:maven/log4j@2.14.1
+Reachability: CONFIRMED_REACHABLE (CR)
+Confidence: 0.92
+Graph Hash: blake3:a1b2c3d4e5f6...
+
+Call Path (3 hops):
+  1. main() [sym:java:R3JlZXRpbmcuLi4=]
+     -> processRequest() [direct call]
+  2. processRequest() [sym:java:cHJvY2Vzcy4uLg==]
+     -> Logger.error() [virtual call]
+  3. Logger.error() [sym:java:bG9nNGouLi4=]
+     [VULNERABLE: CVE-2021-44228]
+
+Runtime Evidence:
+  - JFR probe hit: 47 times
+  - Last observed: 2025-12-13T10:00:00Z
+
+DSSE Attestation: cas://reachability/graphs/a1b2c3d4....dsse
+```
+
+### 4.2 Graph Export Command
+
+Export a reachability graph for offline analysis:
+
+```bash
+stella graph export --scan-id scan-123 --output ./evidence-bundle/
+
+# Creates:
+# ./evidence-bundle/richgraph-v1.json       # Canonical graph
+# ./evidence-bundle/richgraph-v1.json.dsse  # DSSE envelope
+# ./evidence-bundle/meta.json               # Metadata
+# ./evidence-bundle/runtime-facts.ndjson    # Runtime observations
+```
+
+### 4.3 Graph Verify Command
+
+Verify a graph's DSSE signature and Rekor inclusion:
+
+```bash
+stella graph verify --graph ./evidence-bundle/richgraph-v1.json \
+                    --dsse ./evidence-bundle/richgraph-v1.json.dsse \
+                    --rekor-log
+
+# Output:
+Graph Hash: blake3:a1b2c3d4e5f6...
+DSSE Signature: VALID (key: scanner-signing-2025)
+Rekor Entry: 12345678 (verified)
+Timestamp: 2025-12-13T09:30:00Z
+```
+
+---
+
+## 5. OpenVEX Integration
+
+### 5.1 OpenVEX with Reachability Evidence
+
+When Policy emits VEX decisions, reachability evidence is included:
+
+```json
+{
+  "@context": "https://openvex.dev/ns/v0.2.0",
+  "@id": "https://stellaops.example/vex/2025-12-13/001",
+  "author": "StellaOps Policy Engine",
+  "timestamp": "2025-12-13T10:00:00Z",
+  "version": 1,
+  "statements": [
+    {
+      "vulnerability": {"@id": "CVE-2021-44228"},
+      "products": [{"@id": "pkg:oci/myapp@sha256:abc123..."}],
+      "status": "affected",
+      "justification": "vulnerable_code_in_container",
+      "impact_statement": "Vulnerable Log4j method reachable from main entry point.",
+      "action_statement": "Upgrade to log4j 2.17.1 or later.",
+      "stellaops:reachability": {
+        "state": "CR",
+        "confidence": 0.92,
+        "graph_hash": "blake3:a1b2c3d4e5f6...",
+        "path_length": 3,
+        "evidence_uri": "cas://reachability/graphs/a1b2c3d4..."
+      }
+    }
+  ]
+}
+```
+
+### 5.2 VEX "not_affected" with Unreachability Evidence
+
+When code is provably unreachable:
+
+```json
+{
+  "statements": [
+    {
+      "vulnerability": {"@id": "CVE-2023-XXXXX"},
+      "products": [{"@id": "pkg:oci/myapp@sha256:abc123..."}],
+      "status": "not_affected",
+      "justification": "vulnerable_code_not_in_execute_path",
+      "impact_statement": "Vulnerable function not reachable from any entry point.",
+      "stellaops:reachability": {
+        "state": "CU",
+        "confidence": 0.88,
+        "graph_hash": "blake3:d4e5f6a7b8c9...",
+        "evidence_uri": "cas://reachability/graphs/d4e5f6a7b8c9...",
+        "runtime_observation_window": "72h",
+        "runtime_hits": 0
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 6. Replay Manifest v2
+
+### 6.1 Manifest Structure
+
+Replay manifests now enforce BLAKE3 hashing and CAS registration:
+
+```json
+{
+  "schema": "stellaops.replay.manifest@v2",
+  "subject": "scan:123",
+  "generatedAt": "2025-12-13T10:00:00Z",
+  "hashAlg": "blake3",
+  "artifacts": [
+    {
+      "kind": "richgraph",
+      "uri": "cas://reachability/graphs/blake3:a1b2c3d4e5f6...",
+      "hash": "blake3:a1b2c3d4e5f6...",
+      "dsseUri": "cas://reachability/graphs/blake3:a1b2c3d4e5f6....dsse"
+    },
+    {
+      "kind": "runtime-facts",
+      "uri": "cas://reachability/runtime/sha256:xyz789...",
+      "hash": "sha256:xyz789..."
+    },
+    {
+      "kind": "sbom",
+      "uri": "cas://scanner-artifacts/sbom.cdx.json",
+      "hash": "sha256:def456..."
+    }
+  ],
+  "analyzer": {
+    "name": "scanner.java",
+    "version": "1.2.0",
+    "toolchain_digest": "sha256:..."
+  },
+  "code_id_coverage": {
+    "total_symbols": 1247,
+    "with_code_id": 1189,
+    "coverage_pct": 95.3
+  }
+}
+```
+
+### 6.2 Determinism Verification
+
+Replay a manifest to verify determinism:
+
+```bash
+stella replay verify --manifest ./manifest.json --sealed
+
+# Output:
+Manifest: stellaops.replay.manifest@v2
+Subject: scan:123
+Artifacts: 3
+
+Verifying richgraph...
+  Computed: blake3:a1b2c3d4e5f6...
+  Expected: blake3:a1b2c3d4e5f6...
+  Status: MATCH
+
+Verifying runtime-facts...
+  Computed: sha256:xyz789...
+  Expected: sha256:xyz789...
+  Status: MATCH
+
+Verifying sbom...
+  Computed: sha256:def456...
+  Expected: sha256:def456...
+  Status: MATCH
+
+All artifacts verified. Determinism check PASSED.
+```
+
+---
+
+## 7. Module Integration Guide
+
+### 7.1 Scanner -> Signals
+
+Scanner emits richgraph-v1 with `code_id` and `symbol_id`:
+
+1. Scanner analyzes container/artifact
+2. Callgraph generators emit nodes with `symbol_id`, `code_id`, `build_id`
+3. RichGraphWriter canonicalizes (sorted arrays/keys) and computes `graph_hash` (BLAKE3)
+4. DSSE signer wraps canonical JSON
+5. CAS store persists body + envelope
+6. Signals ingestion API receives URI reference
+
+### 7.2 Signals -> Policy
+
+Signals provides reachability facts to Policy:
+
+1. Policy queries `/signals/facts/{subjectKey}`
+2. Response includes `metadata.fact.digest`, `states[]`, `score`
+3. Policy gates check `latticeState` (U, SR, SU, RO, RU, CR, CU, X)
+4. Evidence blocks in findings reference `graph_hash`, `path[]`, `runtime_hits[]`
+
+### 7.3 Policy -> VEX/UI
+
+Policy emits OpenVEX with evidence:
+
+1. VexDecisionEmitter serializes OpenVEX with `stellaops:reachability` extension
+2. UI explain drawer fetches evidence via `/api/policy/findings/{id}/explain`
+3. CLI `stella graph explain` renders call path and attestation refs
+
+---
+
+## 8. CAS Layout Reference
+
+```
+cas://reachability/
+  graphs/
+    {blake3}/                    # Graph body (canonical JSON)
+    {blake3}.dsse                # DSSE envelope
+  edges/
+    {graph_hash}/{bundle_id}     # Edge bundle body (optional)
+    {graph_hash}/{bundle_id}.dsse
+  runtime/
+    {sha256}/                    # Runtime facts NDJSON
+```
+
+---
+
+## 9. Related Documentation
+
+- [Reachability Lattice Model](./lattice.md) - State definitions and join rules
+- [richgraph-v1 Contract](../contracts/richgraph-v1.md) - Schema specification
+- [Evidence Schema](./evidence-schema.md) - Detailed field definitions
+- [Signals API Contract](../api/signals/reachability-contract.md) - API reference
+- [Policy Gates](./policy-gate.md) - Gate configuration
+- [Hybrid Attestation](./hybrid-attestation.md) - Graph and edge-bundle DSSE
+- [Ground Truth Schema](./ground-truth-schema.md) - Test fixture format
+
+---
+
+_Last updated: 2025-12-13. See Sprint 0401 GAP-DOC-008 for change history._