git.stella-ops.org/docs/reachability/DELIVERY_GUIDE.md

Reachability Evidence Delivery Guide

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

This guide translates the deterministic reachability blueprint into concrete work streams that average contributors can pick up without re-reading the entire proposal. Use it as the single navigation point when you land a reachability ticket.

---

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

Stage	Producer	Artifact	Requirements
SBOM per layer & composed image	Scanner Worker + Sbomer	sbom.layer.cdx.json, sbom.image.cdx.json	Deterministic CycloneDX 1.6, DSSE envelope, CAS URI
Static reachability graph	Scanner Worker lifters (DotNet, Go, Node/Deno, Rust, Swift, JVM, Binary, Shell)	richgraph-v1.json + sha256	Canonical SymbolIDs, framework entries, predicates, graph hash
Runtime facts	Zastava Observer / runtime probes	runtime-trace.ndjson	EntryTrace schema, CAS pointer, optional compression
Replay manifest	Scanner Worker + Replay Core	replay.yaml	Contains analyzer versions, feed locks, graph hash, runtime trace digests
VEX statements	Scanner WebService + Policy Engine	reachability.json + OpenVEX doc	Links SBOM attn, graph attn, runtime evidence IDs
Signed bundle	Authority + Signer	DSSE envelope referencing above	Support FIPS + PQ variants (Dilithium where required)

---

3. Work Streams (modules + hand-offs)

Stream	Owner Guild(s)	Key deliverables
Language lifters	Scanner Worker	CLI/hosted lifters for DotNet, Go, Node/Deno, JVM, Rust, Swift, Binary, Shell with CAS uploads and richgraph output
Signals ingestion & scoring	Signals	/callgraphs, /runtime-facts, /graphs/{id}, /reachability/recompute GA; CAS-backed storage, runtime dedupe, BFS+predicates scoring
Runtime capture	Zastava + Runtime Guild	EntryTrace/eBPF samplers, NDJSON batches (symbol IDs + timestamps + counts)
Replay evidence	Replay Core + Scanner Worker	Manifest schema v2, ReachabilityReplayWriter integration, hash-lock tests
Authority attestations	Authority + Signer	DSSE predicates for SBOM, Graph, Replay, VEX; Rekor mirror alignment
Policy & VEX	Policy Engine + Web + CLI + UI	Accept reachability states, render “Why safe” call paths, CLI/UI explain flows
QA & Docs	QA + Docs Guilds	reachbench-2025-expanded fixtures wired to CI; operator + developer runbooks

---

4. Sprint Targets

Sprint	Nickname	Focus	Exit Criteria
401	Evidence Pipeline	Finish static lifters + CAS graph storage + runtime ingestion endpoint	Graph CAS layout documented, lifter fixtures passing, /runtime-facts receives NDJSON batches
402	Replay & Attest	Manifest v2, DSSE envelopes, Authority/Rekor publishing	Replay packs include hashes + analyzer fingerprint; DSSE statements passed integration; Rekor mirror updated
403	Policy & Explain	VEX generation, SPL predicates, UI/CLI explainers	Policy engine uses reachability states, CLI stella graph explain returns signed paths, UI shows explain drawer

Each sprint is two weeks; refer to docs/implplan/SPRINT_401_reachability_evidence_chain.md (new) 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.

---

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/reachability).
• Operator runbooks (docs/runbooks/reachability-runtime.md) – TODO reference to be added when runtime pipeline lands.
• 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 reachbench matrix, post report to Confluence + link in docs/reachability/DELIVERY_GUIDE.md.
• Decision log – Append ADRs under docs/adr/reachability-* for schema changes.

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