feat: Add documentation and task tracking for Sprints 508 to 514 in Ops & Offline
- Created detailed markdown files for Sprints 508 (Ops Offline Kit), 509 (Samples), 510 (AirGap), 511 (Api), 512 (Bench), 513 (Provenance), and 514 (Sovereign Crypto Enablement) outlining tasks, dependencies, and owners. - Introduced a comprehensive Reachability Evidence Delivery Guide to streamline the reachability signal process. - Implemented unit tests for Advisory AI to block known injection patterns and redact secrets. - Added AuthoritySenderConstraintHelper to manage sender constraints in OpenIddict transactions.
This commit is contained in:
master
118
docs/reachability/DELIVERY_GUIDE.md
Normal file
118
docs/reachability/DELIVERY_GUIDE.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user