7040984215
- Introduced a new document outlining the inline DSSE provenance for SBOM, VEX, scan, and derived events. - Defined the Mongo schema for event patches, including key fields for provenance and trust verification. - Documented the write path for ingesting provenance metadata and backfilling historical events. - Created CI/CD snippets for uploading DSSE attestations and generating provenance metadata. - Established Mongo indexes for efficient provenance queries and provided query recipes for various use cases. - Outlined policy gates for managing VEX decisions based on provenance verification. - Included UI nudges for displaying provenance information and implementation tasks for future enhancements. --- Implement reachability lattice and scoring model - Developed a comprehensive document detailing the reachability lattice and scoring model. - Defined core types for reachability states, evidence, and mitigations with corresponding C# models. - Established a scoring policy with base score contributions from various evidence classes. - Mapped reachability states to VEX gates and provided a clear overview of evidence sources. - Documented the event graph schema for persisting reachability data in MongoDB. - Outlined the integration of runtime probes for evidence collection and defined a roadmap for future tasks. --- Introduce uncertainty states and entropy scoring - Created a draft document for tracking uncertainty states and their impact on risk scoring. - Defined core uncertainty states with associated entropy values and evidence requirements. - Established a schema for storing uncertainty states alongside findings. - Documented the risk score calculation incorporating uncertainty and its effect on final risk assessments. - Provided policy guidelines for handling uncertainty in decision-making processes. - Outlined UI guidelines for displaying uncertainty information and suggested remediation actions. --- Add Ruby package inventory management - Implemented Ruby package inventory management with corresponding data models and storage mechanisms. - Created C# records for Ruby package inventory, artifacts, provenance, and runtime details. - Developed a repository for managing Ruby package inventory documents in MongoDB. - Implemented a service for storing and retrieving Ruby package inventories. - Added unit tests for the Ruby package inventory store to ensure functionality and data integrity.
8.5 KiB
8.5 KiB
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
- Deterministic inputs – canonical IDs, sorted payloads, normalized timestamps.
- Provable facts – every artifact has a DSSE envelope anchored in Authority + Rekor mirror.
- Replay-first – manifests pin feed snapshots, analyzer digests, and policies so auditors can rerun.
- 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 |
|---|---|---|
| Native symbols & callgraphs | Scanner Worker · Symbols Guild | Ship Scanner.Symbols.Native + Scanner.CallGraph.Native, integrate Symbol Manifest v1, demangle Itanium/MSVC names, emit FuncNode/CallEdge CAS bundles (task SCANNER-NATIVE-401-015). |
| Reachability store | Signals · BE-Base Platform | Provision shared Mongo collections (func_nodes, call_edges, cve_func_hits), indexes, and repositories plus REST hooks for reuse (task SIG-STORE-401-016). |
| 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
- Lifter SDK – Define
RichGraphWriter, canonical SymbolID helpers, analyzer interface updates. - Language passes – deliverables per language: discovery, graph build, framework wiring, predicate extraction, runtime overlay.
- Replay hooks – plug lifter output + runtime traces into
ReachabilityReplayWriter; enforce CAS registration before emitting manifest references. - Fixture runs – add tests under
tests/reachability/StellaOps.ScannerSignals.IntegrationTeststo execute lifter outputs against reachbench A/B cases.
5.2 Signals Service
- Callgraph CAS layout – migrate from filesystem to CAS (
cas://reachability/graphs/{hash}), include metadata doc. - Runtime facts API – accept NDJSON or gzip, dedupe events, compute hit stats, link to graph nodes.
- Scoring engine v2 – support multi-state lattice (
Unknown → Observed), record predicates, blocked edges, runtime evidence CAS URIs. - API responses –
/graphs/{scanId}returns graph CAS refs + manifest pointers;/reachability/recomputeaccepts replay manifest IDs.
5.3 Replay Core & Authority
- Manifest schema v2 – YAML + JSON versions, includes feeds/analyzers/policies.
- CAS naming – standardize
cas://reachability/{kind}/{sha256}. - DSSE predicate types –
SbomAttestation,GraphAttestation,VexAttestation,ReplayManifest. - Authority integration – new endpoints for submitting reachability predicates, rotation tests, Rekor mirror update instructions.
5.4 Policy / Web / UI / CLI
- Policy Engine – ingest reachability fact from Signals, expose via SPL, produce metrics, integrate into explanation tree.
- Web API – join reachability fields in vuln responses, add override endpoints, simulate support.
- UI/CLI – Visual explain drawer/CLI command showing signed call-path, predicates, runtime hits; counterfactual toggles.
- VEX emitter – generate OpenVEX statements with evidence references, DSSE sign via Signer.
6. Acceptance Tests
- Hash-lock – reorder analyzer flags and confirm graph hash unchanged.
- Replay – delete caches, replay manifest, verify DSSE + hash equality.
- Tamper – alter single edge and expect VEX verification failure with specific path mismatch.
- Golden corpus – run all reachbench cases; ensure NotReachable vs Reachable twins align with expectations JSON.
- Runtime sanity – feed staged runtime traces and ensure confidence bump +
observed=truepath 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.
- Reachability runtime runbook now 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.
- 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.