stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
56c687253fbacabc25d8e1944f4fd43cb8dcef9c
git.stella-ops.org/docs/reachability/DELIVERY_GUIDE.md
master 56c687253f
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat(ruby): Implement RubyManifestParser for parsing gem groups and dependencies 
feat(ruby): Add RubyVendorArtifactCollector to collect vendor artifacts

test(deno): Add golden tests for Deno analyzer with various fixtures

test(deno): Create Deno module and package files for testing

test(deno): Implement Deno lock and import map for dependency management

test(deno): Add FFI and worker scripts for Deno testing

feat(ruby): Set up Ruby workspace with Gemfile and dependencies

feat(ruby): Add expected output for Ruby workspace tests

feat(signals): Introduce CallgraphManifest model for signal processing
2025-11-10 09:27:03 +02:00

7.5 KiB
Raw Blame History

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. For a task-centric view of remaining gaps, see docs/reachability/REACHABILITY_GAP_TASKS.md.

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 (gzip or JSON) EntryTrace schema, CAS pointer, process/socket/container metadata, 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 (JSON + NDJSON/gzip), /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).
  • Function-level evidence guide captures the Nov 2025 advisory scope, task references, and schema expectations; keep it in lockstep with sprint status.
  • 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.