1995883476
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Introduces new marketing bridge documents for Decision Capsules, Hybrid Reachability, and Evidence-Linked VEX. Updates product vision, README, key features, moat, reachability, and VEX consensus docs to reflect four differentiating capabilities: signed reachability (hybrid static/runtime), deterministic replay, explainable policy with evidence-linked VEX, and sovereign/offline operation. All scan decisions are now described as sealed, reproducible, and audit-grade, with explicit handling of 'Unknown' states and hybrid reachability evidence.
91 lines
6.3 KiB
Markdown
91 lines
6.3 KiB
Markdown
# Hybrid Reachability Attestation (Graph + Edge-Bundle)
|
||
|
||
> Decision date: 2025-12-11 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild
|
||
|
||
<!-- TODO: Review for separate approval - updated hybrid attestation introduction -->
|
||
## 0. Context: Four Capabilities
|
||
|
||
This document supports **Signed Reachability**—one of four capabilities no competitor offers together:
|
||
|
||
1. **Signed Reachability** – Every reachability graph is sealed with DSSE; optional edge-bundle attestations for runtime/init/contested paths. Both static call-graph edges and runtime-derived edges can be attested—true hybrid reachability.
|
||
2. **Deterministic Replay** – Scans run bit-for-bit identical from frozen feeds and analyzer manifests.
|
||
3. **Explainable Policy (Lattice VEX)** – Evidence-linked VEX decisions with explicit "Unknown" state handling.
|
||
4. **Sovereign + Offline Operation** – FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class toggles.
|
||
|
||
All evidence is sealed in **Decision Capsules** for audit-grade reproducibility.
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
- Guarantee replayable, signed reachability evidence with **graph-level DSSE** for every scan while enabling **selective edge-level DSSE bundles** when finer provenance or dispute handling is required.
|
||
- Keep CI/offline bundles lean (graph-first), but allow auditors/regulators to quarantine or prove individual edges without regenerating whole graphs.
|
||
- Support **hybrid reachability** by attesting both static call-graph edges and runtime-derived edges.
|
||
|
||
## 2. Attestation levels
|
||
- **Level 0 (Graph DSSE) — Required**
|
||
- Payload: canonical `richgraph-v1` (nodes, edges, roots, graph_hash, analyzer metadata, policy_hash).
|
||
- Signature: one DSSE envelope per graph; submit digest to Rekor (or mirror) always.
|
||
- CAS: `cas://reachability/graphs/{blake3}` (body) + `cas://reachability/graphs/{blake3}.dsse` (envelope).
|
||
- **Level 1 (Edge-Bundle DSSE) — Optional/Selective**
|
||
- Payload: batch of edges (size ≤ 512) with per-edge reason, evidence hashes, `symbol_digest`, `purl`, `confidence`, and `phase`.
|
||
- Criteria to emit bundles:
|
||
- Edge reason is `runtime`, `init_array`/constructors/TLS callbacks, or comes from third-party provenance.
|
||
- Edge is contested/flagged in Unknowns registry or under policy quarantine.
|
||
- Signature: one DSSE envelope per bundle; Rekor submission **configurable** (default on for contested/high-risk bundles, off for bulk benign bundles in sealed mode).
|
||
- CAS: `cas://reachability/edges/{graph_hash}/{bundle_id}` JSON + `.../{bundle_id}.dsse`.
|
||
|
||
## 3. Producer responsibilities
|
||
- **Scanner**
|
||
- Always emit Level 0 graph + manifest.
|
||
- When criteria match, emit Level 1 bundles; include `bundle_reason` (e.g., `runtime-hit`, `init-root`, `third-party`, `disputed`).
|
||
- Canonicalise JSON (sorted keys/arrays) before hashing; BLAKE3 as graph hash, SHA-256 inside bundles.
|
||
- For hybrid reachability: tag edges with `source: static` or `source: runtime` to distinguish call-graph derived vs. runtime-observed edges.
|
||
- **Attestor/Signer**
|
||
- Apply DSSE for both levels; respect sovereign crypto modes (FIPS/GOST/SM/PQC) from environment.
|
||
- Rekor: push graph envelope digests; push edge-bundle digests only when `rekor_publish=true` (policy/default for high-risk bundles).
|
||
|
||
## 4. Consumer responsibilities
|
||
- **Signals**
|
||
- Ingest graph DSSE as the canonical source; ingest edge-bundles when present and attach to the same `graph_hash`.
|
||
- Store per-edge DSSE metadata for quarantine/override flows; surface missing edges as Unknowns only when absent from both graph and bundles.
|
||
- **Policy**
|
||
- Default trust path: graph DSSE + CAS object.
|
||
- When an edge is quarantined/contested, drop it from consideration if an edge-bundle DSSE marks it `revoked=true` or if the Unknowns registry lists it with policy quarantine flag.
|
||
- For "evidence-required" rules, require either (a) graph DSSE + policy_hash match **or** (b) edge-bundle DSSE that covers the vulnerable path edges.
|
||
- **Replay/Bench/CLI**
|
||
- `stella graph verify` should accept `--graph {hash}` and optional `--edge-bundles` to validate deeper provenance offline.
|
||
|
||
## 5. Verification and quarantine flows
|
||
- **Happy path**: verify graph DSSE → verify Rekor inclusion (or mirror) → hash graph body → match `graph_hash` in policy/replay manifest → accept.
|
||
- **Dispute/quarantine**: mark specific `edge_id` as `revoked` in an edge-bundle DSSE; Policy/Signals exclude it, recompute reachability, and surface delta in explainers.
|
||
- **Offline**: retain graph DSSE and selected edge-bundles inside replay pack; Rekor proofs cached when available.
|
||
- **Sovereign Verification Mode**: Even with no internet, all signatures and transparency proofs can be locally verified using Offline Update Kits.
|
||
|
||
## 6. Performance & storage guardrails
|
||
- Default: only graph DSSE is mandatory; edge-bundles capped at 512 edges per envelope and emitted only on criteria above.
|
||
- Rekor flood control: cap edge-bundle Rekor submissions per graph (config `reachability.edgeBundles.maxRekorPublishes`, default 5). Others stay CAS-only.
|
||
- Determinism: bundle ordering = stable sort by `(bundle_reason, edge_id)`; hash before signing.
|
||
|
||
## 7. Hybrid Reachability Details
|
||
|
||
<!-- TODO: Review for separate approval - added hybrid reachability details -->
|
||
Stella Ops provides **true hybrid reachability** by combining:
|
||
|
||
| Signal Type | Source | Attestation |
|
||
|-------------|--------|-------------|
|
||
| Static call-graph edges | IL/bytecode analysis, framework routing models, entry-point proximity | Graph DSSE (Level 0) |
|
||
| Runtime-observed edges | EventPipe, JFR, Node inspector, Go/Rust probes | Edge-bundle DSSE (Level 1) with `source: runtime` |
|
||
|
||
**Why hybrid matters:**
|
||
- Static analysis catches code paths that may not execute during observed runtime
|
||
- Runtime analysis catches dynamic dispatch, reflection, and framework-injected paths
|
||
- Combining both provides confidence across build and runtime contexts
|
||
- Each edge type is separately attestable for audit and dispute resolution
|
||
|
||
**Evidence linking:** Each edge in the graph or bundle includes `evidenceRefs` pointing to the underlying proof artifacts (static analysis artifacts, runtime traces), enabling **evidence-linked VEX decisions**.
|
||
|
||
## 8. Open decisions (tracked in Sprint 0401 tasks 53–56)
|
||
- Rekor publish defaults per deployment tier (regulated vs standard).
|
||
- CLI UX for selective bundle verification.
|
||
- Bench coverage for edge-bundle verification time/size.
|