Reachability Evidence Delivery Guide

Last updated: November 8, 2025. Owner: Reachability Tiger Team (Scanner, Signals, Replay, Policy, Authority, UI).

Audience: any contributor landing a reachability ticket across Scanner, Signals, Replay, Policy, Authority, or UI.

This guide translates the deterministic reachability blueprint into concrete work streams you can pick up without re-reading the full proposal. Use it as the single navigation point for the reachability program: it maps the evidence chain, the owning guilds, the sprint targets, and the per-module task breakdown, then points to the deeper specs.

1. Scope & Principles

Goal: ship a verifiable reachability signal for every scan by chaining SBOM → graph → runtime facts → VEX into DSSE-attested, replayable evidence.

Principles

1. Deterministic inputs – canonical IDs, sorted payloads, normalized timestamps.
2. Provable facts – every artifact has a DSSE envelope anchored in Authority + Rekor mirror.
3. Replay-first – manifests pin feed snapshots, analyzer digests, and policies so auditors can rerun.
4. Least surprise – same API and file layouts across languages; tests run fixture packs at CI time.

2. Evidence Chain Overview

3. Work Streams (modules + hand-offs)

4. Sprint Targets

Each sprint is two weeks; refer to docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md for per-task tracking.

5. Task Breakdown Cheat Sheet

5.1 Scanner Worker

1. Lifter SDK – Define RichGraphWriter, canonical SymbolID helpers, analyzer interface updates.
2. Language passes – deliverables per language: discovery, graph build, framework wiring, predicate extraction, runtime overlay.
3. Replay hooks – plug lifter output + runtime traces into ReachabilityReplayWriter; enforce CAS registration before emitting manifest references.
4. Fixture runs – add tests under tests/reachability/StellaOps.ScannerSignals.IntegrationTests to execute lifter outputs against reachbench A/B cases.

5.2 Signals Service

1. Callgraph CAS layout – migrate from filesystem to CAS (cas://reachability/graphs/{hash}), include metadata doc.
2. Runtime facts API – accept NDJSON or gzip, dedupe events, compute hit stats, link to graph nodes.
3. Scoring engine v2 – support multi-state lattice (Unknown → Observed), record predicates, blocked edges, runtime evidence CAS URIs.
4. API responses – /graphs/{scanId} returns graph CAS refs + manifest pointers; /reachability/recompute accepts replay manifest IDs.

5.3 Replay Core & Authority

1. Manifest schema v2 – YAML + JSON versions, includes feeds/analyzers/policies.
2. CAS naming – standardize cas://reachability/{kind}/{sha256}.
3. DSSE predicate types – SbomAttestation, GraphAttestation, VexAttestation, ReplayManifest.
4. Authority integration – new endpoints for submitting reachability predicates, rotation tests, Rekor mirror update instructions.

5.4 Policy / Web / UI / CLI

1. Policy Engine – ingest reachability fact from Signals, expose via SPL, produce metrics, integrate into explanation tree.
2. Web API – join reachability fields in vuln responses, add override endpoints, simulate support.
3. UI/CLI – Visual explain drawer/CLI command showing signed call-path, predicates, runtime hits; counterfactual toggles.
4. VEX emitter – generate OpenVEX statements with evidence references, DSSE sign via Signer.

5.5 Native binaries (build-id + init roots)

• Capture ELF build-id (.note.gnu.build-id) alongside soname/path and propagate into SymbolID/code_id so SBOM/runtime joins stay stable even when paths change.
• Treat .preinit_array, .init_array, .ctors, and _init as synthetic graph roots with phase=load; include constructors from DT_NEEDED deps. Persist the root list in scan evidence.
• Add deterministic tests covering build-id present/absent and init-array edge creation.

5.6 PURL-resolved edges

• Annotate every call edge with callee purl and symbol_digest per the PURL-resolved edges spec.
• Update richgraph-v1 schema, CAS metadata, and CLI/UI explainers to display purl@version + demangled name.
• Signals merges graphs by (purl, symbol_digest); Policy uses the same keys when mapping CVE-affected functions.

5.7 Unknowns Registry integration

• Emit structured Unknowns when symbol-to-purl mapping, edge targets, or hashes are ambiguous; write them via the Signals API per the Unknowns registry.
• Scoring adds unknowns_pressure so not_affected claims cannot bypass unresolved evidence.
• UI/CLI should surface unknown chips and triage actions.

5.8 Patch-oracle guardrails

• Add tests/reachability/patch-oracles/** with paired vuln/fixed binaries and oracle.yml expectations (functions/edges added/removed).
• Scanner binary analyzer tests must fail if expected guard functions or edges are missing; CI job ensures determinism.
• See the Patch-oracles QA pattern for fixture layout and manifest schema.

5.9 JS/PHP framework reachability

• Model framework entrypoints explicitly: Express/Fastify/Nest handlers, Laravel/Symfony routes/commands/hooks. Generate graph roots from route/handler catalogs instead of generic main only.
• Represent dynamic import/require/include resolution as graph nodes so ambiguity stays visible (resolution edges with confidence).
• Keep multi-layer graphs: source-level (TS/JS/PHP) plus bundled output (Webpack/Vite). Merge with runtime hints when available.
• Status model: always_reachable, conditional, not_reachable, not_analyzed, ambiguous, each with confidence and evidence tags.
• Deliver language-specific profiles + fixture cases to prove coverage; update CLI/UI explainers to show framework route context.

5.10 Vulnerability Surfaces (Sprint 3700)

Vulnerability surfaces identify which specific methods changed in a security fix, enabling precise reachability analysis:

• Surface computation: Download vulnerable and fixed package versions, fingerprint all methods, diff to find changed methods (sinks).
• Trigger extraction: Build internal call graphs, reverse BFS from sinks to public APIs (triggers).
• Per-ecosystem support:
  • NuGet: Cecil IL fingerprinting
  • npm: Babel AST fingerprinting
  • Maven: ASM bytecode fingerprinting
  • PyPI: Python AST fingerprinting
• Integration: ISurfaceQueryService queries triggers during scan; use triggers as sinks instead of all package methods.
• Storage: scanner.vuln_surfaces, scanner.vuln_surface_sinks, scanner.vuln_surface_triggers tables.
• Docs: Vuln-surface v1 contract for schema details.

5.11 Confidence Tiers

Reachability findings are classified into confidence tiers:

• Tier assignment logic in SurfaceAwareReachabilityAnalyzer
• API responses include confidenceTier and confidenceDisplay
• UI badges reflect tier colors
• VEX statements reference tier in justification

5.12 Reachability Drift (Sprint 3600)

Track function-level reachability changes between scans:

• New reachable: Sinks that became reachable (alert)
• Mitigated: Sinks that became unreachable (positive)
• Causal attribution: Why change occurred (guard removed, new route, code change)
• Components: DriftDetectionEngine, PathCompressor, DriftCauseExplainer
• API: POST /api/drift/analyze, GET /api/drift/{id}
• UI: PathViewerComponent, RiskDriftCardComponent
• Attestation: DSSE-signed drift predicates for evidence chain

6. Acceptance Tests

1. Hash-lock – reorder analyzer flags and confirm graph hash unchanged.
2. Replay – delete caches, replay manifest, verify DSSE + hash equality.
3. Tamper – alter single edge and expect VEX verification failure with specific path mismatch.
4. Golden corpus – run all reachbench cases; ensure NotReachable vs Reachable twins align with expectations JSON.
5. Runtime sanity – feed staged runtime traces and ensure confidence bump + observed=true path chips propagate to UI.

7. Documentation & Runbooks

• Place developer-facing updates here (docs/modules/reach-graph/guides).
• Function-level evidence guide captures the Nov 2025 advisory scope, task references, and schema expectations; keep it in lockstep with sprint status.
• Reachability runtime runbook documents ingestion, CAS staging, air-gap handling, and troubleshooting — link every runtime feature PR to this guide.
• VEX Evidence Playbook defines the bench repo layout, artifact shapes, verifier tooling, and metrics; keep it updated when Policy/Signer/CLI features land.
• Reachability lattice describes the confidence states, evidence/mitigation kinds, scoring policy, event-graph schema, and VEX gates; update it when lattices or probes change.
• PURL-resolved edges spec defines the purl + symbol-digest annotation rules for graphs and SBOM joins.
• Patch-oracles QA pattern describes the fixture layout and expectations for binary reachability guards.
• Unknowns registry documents how unresolved symbols/edges are recorded and how scoring uses unknowns_pressure.
• Evidence schema is the canonical field list for richgraph, runtime facts, and Unknowns CAS objects.
• Update module dossiers (Scanner, Signals, Replay, Authority, Policy, UI) once each guild lands work.

8. Contact & Rituals

• Daily reachability stand-up in #reachability-build.
• Fixture sync every Friday: QA leads run the reachbench matrix and post the report to the team wiki.
• Decision log — append ADRs under docs/architecture/decisions/ (e.g. ADR-NNN-reachability-*) for schema changes.

Keep this guide updated whenever scope shifts or a new sprint is added.