From 2de8d1784bc8e846ca9f320ddd99582b0d441582 Mon Sep 17 00:00:00 2001 From: master Date: Sun, 23 Nov 2025 23:38:25 +0200 Subject: [PATCH] new advisories --- AGENTS.md | 41 ++++++++-- docs/03_VISION.md | 11 +++ docs/04_FEATURE_MATRIX.md | 9 ++- docs/07_HIGH_LEVEL_ARCHITECTURE.md | 14 ++-- docs/benchmarks/signals/bench-determinism.md | 49 ++++++++++++ docs/implplan/AGENTS.md | 8 ++ ...1_0001_0001_reachability_evidence_chain.md | 20 +++++ docs/implplan/SPRINT_0512_0001_0001_bench.md | 3 +- docs/key-features.md | 10 +++ docs/market/competitive-landscape.md | 80 +++++++++++++++++++ docs/modules/devops/AGENTS.md | 11 ++- docs/modules/graph/AGENTS.md | 7 ++ .../modules/platform/architecture-overview.md | 1 + docs/modules/policy/architecture.md | 1 + docs/modules/scanner/architecture.md | 2 + docs/modules/signer/AGENTS.md | 7 ++ docs/modules/telemetry/AGENTS.md | 7 ++ docs/modules/ui/AGENTS.md | 6 ++ docs/modules/zastava/AGENTS.md | 7 ++ docs/reachability/corpus-plan.md | 12 +++ docs/reachability/evidence-schema.md | 13 +++ docs/reachability/hybrid-attestation.md | 55 +++++++++++++ docs/reachability/lead.md | 78 ++++++++++++++++++ src/Cli/StellaOps.Cli/AGENTS.md | 8 ++ 24 files changed, 443 insertions(+), 17 deletions(-) create mode 100644 docs/benchmarks/signals/bench-determinism.md create mode 100644 docs/market/competitive-landscape.md create mode 100644 docs/reachability/hybrid-attestation.md create mode 100644 docs/reachability/lead.md diff --git a/AGENTS.md b/AGENTS.md index 9b168f30c..1873e1996 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -329,7 +329,7 @@ If no design decision is required, you proceed autonomously, implementing the ch --- -### 5) Working Agreement (Global) +### 5) Working Agreement (Global) 1. **Task status discipline** @@ -352,10 +352,41 @@ If no design decision is required, you proceed autonomously, implementing the ch 5. **Completion** * When you complete all tasks in scope for your current instruction set, explicitly state that you are done with those tasks. -6. **AGENTS.md discipline** - * Project / technical managers ensure each module’s `AGENTS.md` exists, is up to date, and reflects current design and advisory decisions. - * Implementers must read and follow the relevant `AGENTS.md` before coding in a module. - * If a mismatch or gap is found, implementers log it via `BLOCKED` status and the sprint’s **Decisions & Risks**, and then continue with other work instead of asking for live clarification. +6. **AGENTS.md discipline** + * Project / technical managers ensure each module’s `AGENTS.md` exists, is up to date, and reflects current design and advisory decisions. + * Implementers must read and follow the relevant `AGENTS.md` before coding in a module. + * If a mismatch or gap is found, implementers log it via `BLOCKED` status and the sprint’s **Decisions & Risks**, and then continue with other work instead of asking for live clarification. + +--- + +### 7) Advisory Handling (do this every time a new advisory lands) + +**Trigger:** Any new or updated file under `docs/product-advisories/` (including archived) automatically starts this workflow. No chat approval required. + +1) **Doc sync (must happen for every advisory):** + - Create/update **two layers**: + - **High-level**: `docs/` (vision/key-features/market) to capture the moat/positioning and the headline promise. + - **Detailed**: closest deep area (`docs/reachability/*`, `docs/market/*`, `docs/benchmarks/*`, `docs/modules//*`, etc.). + - **Code & samples:** + - Inline only short fragments (≤ ~20 lines) directly in the updated doc for readability. + - Place runnable or longer samples/harnesses in `docs/benchmarks/**` or `tests/**` with deterministic, offline-friendly defaults (no network, fixed seeds), and link to them from the doc. + - If the advisory already contains code, carry it over verbatim into the benchmark/test file (with minor formatting only); don’t paraphrase away executable value. + - **Cross-links:** whenever moats/positioning change, add links from `docs/07_HIGH_LEVEL_ARCHITECTURE.md`, `docs/key-features.md`, and the relevant module dossier(s). + +2) **Sprint sync (must happen for every advisory):** + - Add Delivery Tracker rows in the relevant `SPRINT_*.md` with owners, deps, and doc paths; add an Execution Log entry for the change. + - If code/bench/dataset work is implied, create tasks and point to the new benchmark/test paths; add risks/interlocks for schema/feed freeze or transparency caps as needed. + +3) **De-duplication:** + - Check `docs/product-advisories/archived/` for overlaps. If similar, mark “supersedes/extends ` in the new doc and avoid duplicate tasks. + +4) **Defaults to apply (unless advisory overrides):** + - Hybrid reachability posture: graph DSSE mandatory; edge-bundle DSSE optional/targeted; deterministic outputs only. + - Offline-friendly benches/tests; frozen feeds; deterministic ordering/hashes. + +5) **Do not defer:** Execute steps 1–4 immediately; reporting is after the fact, not a gating step. + +**Lessons baked in:** Past delays came from missing code carry-over and missing sprint tasks. Always move advisory code into benchmarks/tests and open the corresponding sprint rows the same session you read the advisory. --- ### 6) Role Switching diff --git a/docs/03_VISION.md b/docs/03_VISION.md index d3b281fc7..2b167647f 100755 --- a/docs/03_VISION.md +++ b/docs/03_VISION.md @@ -368,6 +368,17 @@ opa eval -i gate-input.json -d policy/ -f pretty "data.stella.policy.allow" --- +## 9) Moats +- **Deterministic replay:** Hash-stable scans with frozen feeds and analyzer manifests; replay packs verifiable offline. +- **Hybrid reachability attestations:** Graph-level DSSE always; selective edge-bundle DSSE for runtime/init/contested edges with Rekor caps. +- **Lattice VEX engine:** Trust algebra across advisories, runtime, reachability, waivers; explainable paths. +- **Crypto sovereignty:** FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class configuration. +- **Proof graph:** DSSE + Rekor spanning SBOM, call-graph, VEX, replay manifests for chain-of-custody evidence. + +See also: `docs/market/competitive-landscape.md` for vendor comparison and talking points. + +--- + ## 8 · Change Log diff --git a/docs/04_FEATURE_MATRIX.md b/docs/04_FEATURE_MATRIX.md index 5af6cea9a..337b53dbc 100755 --- a/docs/04_FEATURE_MATRIX.md +++ b/docs/04_FEATURE_MATRIX.md @@ -25,9 +25,12 @@ | | High‑availability split services | — | — | ✅ (Add‑On) | HA Redis & Mongo | | **Extensibility** | .NET hot‑load plug‑ins | ✅ | N/A | — | AGPL reference SDK | | | Community plug‑in marketplace | — | ⏳ (β Q2‑2026) | — | Moderated listings | -| **Telemetry** | Opt‑in anonymous metrics | ✅ | — | — | Required for quota satisfaction KPI | -| **Quota & Tokens** | **Client‑JWT issuance** | ✅ (online 12 h token) | — | — | `/connect/token` | -| | **Offline Client‑JWT (30 d)** | ✅ via OUK | — | — | Refreshed monthly in OUK | +| **Telemetry** | Opt‑in anonymous metrics | ✅ | — | — | Required for quota satisfaction KPI | +| **Quota & Tokens** | **Client‑JWT issuance** | ✅ (online 12 h token) | — | — | `/connect/token` | +| | **Offline Client‑JWT (30 d)** | ✅ via OUK | — | — | Refreshed monthly in OUK | +| **Reachability & Evidence** | Graph-level reachability DSSE | ⏳ (Q1‑2026) | — | — | Mandatory attestation per graph; CAS+Rekor; see `docs/reachability/hybrid-attestation.md`. | +| | Edge-bundle DSSE (selective) | ⏳ (Q2‑2026) | — | — | Optional bundles for runtime/init/contested edges; Rekor publish capped. | +| | Cross-scanner determinism bench | ⏳ (Q1‑2026) | — | — | CI bench from 23-Nov advisory; determinism rate + CVSS σ. | > **Legend:** ✅ = Included ⏳ = Planned — = Not applicable > Rows marked “Commercial Add‑On” are optional paid components shipping outside the AGPL‑core; everything else is FOSS. diff --git a/docs/07_HIGH_LEVEL_ARCHITECTURE.md b/docs/07_HIGH_LEVEL_ARCHITECTURE.md index d8b29b406..e8d6f5b74 100755 --- a/docs/07_HIGH_LEVEL_ARCHITECTURE.md +++ b/docs/07_HIGH_LEVEL_ARCHITECTURE.md @@ -14,12 +14,14 @@ **Operating principles.** * **Scanner‑owned SBOMs.** We generate our own BOMs; we do not warehouse third‑party SBOM content (we can **link** to attested SBOMs). -* **Deterministic evidence.** Facts come from package DBs, installed metadata, linkers, and verified attestations; no fuzzy guessing in the core. -* **Per‑layer caching.** Cache fragments by **layer digest** and compose image SBOMs via **CycloneDX BOM‑Link** / **SPDX ExternalRef**. -* **Inventory vs Usage.** Always record the full **inventory** of what exists; separately present **usage** (entrypoint closure + loaded libs). -* **Backend decides.** PASS/FAIL is produced by **Policy** + **VEX** + **Advisories**. The scanner reports facts. -* **Attest or it didn’t happen.** Every export is signed as **in‑toto/DSSE** and logged in **Rekor v2**. -* **Sovereign‑ready.** Cloud is used only for licensing and optional endorsement; everything else is first‑party and self‑hostable. +* **Deterministic evidence.** Facts come from package DBs, installed metadata, linkers, and verified attestations; no fuzzy guessing in the core. +* **Per-layer caching.** Cache fragments by **layer digest** and compose image SBOMs via **CycloneDX BOM-Link** / **SPDX ExternalRef**. +* **Inventory vs Usage.** Always record the full **inventory** of what exists; separately present **usage** (entrypoint closure + loaded libs). +* **Backend decides.** PASS/FAIL is produced by **Policy** + **VEX** + **Advisories**. The scanner reports facts. +* **Attest or it didn’t happen.** Every export is signed as **in-toto/DSSE** and logged in **Rekor v2**. +* **Hybrid reachability attestations.** Every reachability graph ships with a graph-level DSSE (mandatory) plus optional edge-bundle DSSEs for runtime/init/contested edges; Policy/Signals consume graph DSSE as baseline and edge bundles for quarantine/disputes. +* **Sovereign-ready.** Cloud is used only for licensing and optional endorsement; everything else is first-party and self-hostable. +* **Competitive clarity.** Moats: deterministic replay, hybrid reachability proofs, lattice VEX, sovereign crypto, proof graph; see `docs/market/competitive-landscape.md`. --- diff --git a/docs/benchmarks/signals/bench-determinism.md b/docs/benchmarks/signals/bench-determinism.md new file mode 100644 index 000000000..08cb4a77b --- /dev/null +++ b/docs/benchmarks/signals/bench-determinism.md @@ -0,0 +1,49 @@ +# Determinism Benchmark (cross-scanner) — Draft + +Source: advisory “23-Nov-2025 - Benchmarking Determinism in Vulnerability Scoring”. This doc captures the runnable harness pattern and expected outputs for task BENCH-DETERMINISM-401-057. + +## Goal +- Measure determinism rate, order-invariance, and CVSS delta σ across scanners when fed identical SBOM+VEX inputs with frozen feeds. + +## Minimal harness (Python excerpt) +```python +# run_bench.py (excerpt) — deterministic JSON hashing +def canon(obj): + return json.dumps(obj, sort_keys=True, separators=(',', ':')).encode() + +def shas(b): + return hashlib.sha256(b).hexdigest() + +for sbom, vex in zip(SBOMS, VEXES): + for scanner, tmpl in SCANNERS.items(): + for mode in ("canonical", "shuffled"): + for i in range(10): + if mode == "shuffled": + sb, vx = shuffle(sbom), shuffle(vex) + out = run(tmpl.format(sbom=sb, vex=vx)) + norm = normalize(out) # purl, vuln id, base_cvss, effective + blob = canon({"scanner": scanner, "sbom": sbom, + "vex": vex, "findings": norm}) + results.append({ + "hash": shas(blob), "mode": mode, + "run": i, "scanner": scanner, "sbom": sbom + }) +``` + +## Inputs +- 3–5 SBOMs (CycloneDX 1.6 / SPDX 3.0.1) + matching VEX docs covering affected/not_affected/fixed. +- Feeds bundle: vendor DBs (NVD, GHSA, OVAL) hashed and frozen. +- Policy: single normalization profile (e.g., prefer vendor scores, CVSS v3.1). + +## Metrics +- Determinism rate = identical_hash_runs / total_runs (20 per scanner/SBOM). +- Order-invariance failures (# distinct hashes between canonical vs shuffled). +- CVSS delta σ vs reference; VEX stability (σ_after ≤ σ_before). + +## Deliverables +- `bench/determinism/` with harness, hashed inputs, and `results.csv`. +- CI target `bench:determinism` producing determinism% and σ per scanner. + +## Links +- Source advisory: `docs/product-advisories/23-Nov-2025 - Benchmarking Determinism in Vulnerability Scoring.md` +- Sprint task: BENCH-DETERMINISM-401-057 (SPRINT_0401_0001_0001_reachability_evidence_chain.md) diff --git a/docs/implplan/AGENTS.md b/docs/implplan/AGENTS.md index 871fd9e37..10ae048cc 100644 --- a/docs/implplan/AGENTS.md +++ b/docs/implplan/AGENTS.md @@ -26,6 +26,14 @@ - Archival: completed tasks should flow to `docs/implplan/archived/tasks.md` as per sprint guidance. - Avoid external URLs unless already present; prefer relative doc links. +## Advisory Handling (must do for every new advisory) +- **Trigger:** any new/updated file in `docs/product-advisories/` (current or archived) automatically requires updates below—no chat approval. +- **Docs:** add/update a high-level page in `docs/` (vision/key-features/market) and a detailed page in the closest area (`docs/reachability/*`, `docs/market/*`, `docs/benchmarks/*`, `docs/modules//*`, etc.). Inline only short snippets; place runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic, offline-friendly) and link. +- **Sprints:** add Delivery Tracker rows in the relevant `SPRINT_*.md`, include doc paths, owners, deps; add an Execution Log line and risks/interlocks (schema/feed freeze, transparency caps) when needed. +- **De-dup:** check `docs/product-advisories/archived/`; mark “supersedes/extends ` if overlapping to avoid duplicate tasks. +- **Defaults:** hybrid reachability posture (graph DSSE required; edge-bundle optional), deterministic/frozen feeds, offline-ready benches. +- **Do not defer:** execute steps immediately, then report. + ## Cross-Module Coordination - Respect each module’s AGENTS.md when touching module-specific sprint entries; do not change module instructions from here. - If a required module AGENTS.md is missing/outdated, mark the related task BLOCKED in that module’s sprint and note it in Decisions & Risks here. diff --git a/docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md b/docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md index d84e6df1b..c3e73dd0f 100644 --- a/docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md +++ b/docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md @@ -85,6 +85,15 @@ | 50 | SCANNER-BUILDID-401-035 | TODO | Depends on scanner symbol work and fixtures. | Scanner Worker Guild (`src/Scanner/StellaOps.Scanner.Worker`, `docs/modules/scanner/architecture.md`) | Capture `.note.gnu.build-id` for ELF targets, thread into `SymbolID`/`code_id`, SBOM exports, runtime facts; add fixtures. | | 51 | SCANNER-INITROOT-401-036 | TODO | Requires graph writer updates from 1. | Scanner Worker Guild (`src/Scanner/StellaOps.Scanner.Worker`, `docs/modules/scanner/architecture.md`) | Model init sections as synthetic graph roots (phase=load) including `DT_NEEDED` deps; persist in evidence. | | 52 | QA-PORACLE-401-037 | TODO | Depends on reachability graph fixtures; add CI harness. | QA Guild · Scanner Worker Guild (`tests/reachability`, `docs/reachability/patch-oracles.md`) | Add patch-oracle fixtures and harness comparing graphs vs oracle, fail CI when expected functions/edges missing. | +| 53 | GRAPH-HYBRID-401-053 | TODO | Await graph schema (task 1) final hash; align with Attestor. | Scanner Worker Guild · Attestor Guild (`src/Scanner/StellaOps.Scanner.Worker`, `src/Attestor/StellaOps.Attestor`, `docs/reachability/hybrid-attestation.md`) | Implement mandatory graph-level DSSE for `richgraph-v1` with deterministic ordering → BLAKE3 graph hash → DSSE envelope → Rekor submit; expose CAS paths `cas://reachability/graphs/{hash}` and `.../{hash}.dsse`; add golden verification fixture. | +| 54 | EDGE-BUNDLE-401-054 | TODO | Depends on 53 and init/root handling (51). | Scanner Worker Guild · Attestor Guild (`src/Scanner/StellaOps.Scanner.Worker`, `src/Attestor/StellaOps.Attestor`) | Emit optional edge-bundle DSSE envelopes (≤512 edges) for runtime hits, init-array/TLS roots, contested/third-party edges; include `bundle_reason`, per-edge `reason`, `revoked?` flag; canonical sort before hashing; Rekor publish capped/configurable; CAS path `cas://reachability/edges/{graph_hash}/{bundle_id}[.dsse]`. | +| 55 | SIG-POL-HYBRID-401-055 | TODO | Needs edge-bundle schema from 54 and Unknowns rules. | Signals Guild · Policy Guild (`src/Signals/StellaOps.Signals`, `src/Policy/StellaOps.Policy.Engine`, `docs/reachability/evidence-schema.md`) | Ingest edge-bundle DSSEs, attach to `graph_hash`, enforce quarantine (`revoked=true`) before scoring, surface presence in APIs/CLI/UI explainers, and add regression tests for graph-only vs graph+bundle paths. | +| 56 | DOCS-HYBRID-401-056 | TODO | Dependent on 53–55 delivery; interim draft exists. | Docs Guild (`docs/reachability/hybrid-attestation.md`, `docs/modules/scanner/architecture.md`, `docs/modules/policy/architecture.md`, `docs/07_HIGH_LEVEL_ARCHITECTURE.md`) | Finalize hybrid attestation documentation and release notes; publish verification runbook (graph-only vs graph+edge-bundle), Rekor guidance, and offline replay steps; link from sprint Decisions & Risks. | +| 57 | BENCH-DETERMINISM-401-057 | TODO | Await feed-freeze hash + SBOM/VEX bundle list; align with Signals/Policy. | Bench Guild · Signals Guild · Policy Guild (`bench/determinism`, `docs/benchmarks/signals/`) | Implement cross-scanner determinism bench from 23-Nov advisory: shuffle SBOM/VEX, run 10x2 matrix per scanner, compute determinism rate & CVSS delta σ; add CI target `bench:determinism`, store hashed inputs/outputs, and publish summary CSV. | +| 58 | DATASET-REACH-PUB-401-058 | TODO | Needs schema alignment from tasks 1/17/55. | QA Guild · Scanner Guild (`tests/reachability/samples-public`, `docs/reachability/evidence-schema.md`) | Materialize PHP/JS/C# mini-app samples + ground-truth JSON (from 23-Nov dataset advisory); runners and confusion-matrix metrics; integrate into CI hot/cold paths with deterministic seeds; keep schema compatible with Signals ingest. | +| 59 | NATIVE-CALLGRAPH-INGEST-401-059 | TODO | Depends on 1 and native symbolizer readiness. | Scanner Guild (`src/Scanner/StellaOps.Scanner.CallGraph.Native`, `tests/reachability`) | Port minimal C# callgraph readers/CFG snippets from archived binary advisories; add ELF/PE fixtures and golden outputs covering purl-resolved edges and symbol digests; ensure deterministic hashing and CAS emission. | +| 60 | CORPUS-MERGE-401-060 | TODO | After 58 schema settled; tie to QA-CORPUS-401-031. | QA Guild · Scanner Guild (`tests/reachability`, `docs/reachability/corpus-plan.md`) | Merge archived multi-runtime corpus (Go/.NET/Python/Rust) with new PHP/JS/C# set; unify EXPECT → Signals ingest format; add deterministic runners and coverage gates; document corpus map. | +| 61 | DOCS-BENCH-401-061 | TODO | Blocks on outputs from 57–60. | Docs Guild (`docs/benchmarks/signals/bench-determinism.md`, `docs/reachability/corpus-plan.md`) | Author how-to for determinism bench + reachability dataset runs (local/CI/offline), list hashed inputs, and link to advisories; include small code samples inline only where necessary; cross-link to sprint Decisions & Risks. | ## Wave Coordination | Wave | Guild owners | Shared prerequisites | Status | Notes | @@ -98,6 +107,9 @@ - CAS hash/predicate choices must stay consistent across Scanner, Signals, Replay, and Policy (tasks 1, 11, 19, 24). - DSSE predicate catalog and Signer integration (tasks 12, 24, 34–36) gate VEX and provenance tasks. - UI/CLI explainers (tasks 15, 21, 47) depend on policy reachability outputs and graph schema stabilization. +- Hybrid reachability attestation decision: graph-level DSSE is mandatory; edge-bundle DSSE is optional/targeted (runtime/init/contested edges) with Rekor publish capped; see `docs/reachability/hybrid-attestation.md` and tasks 53–56. +- New datasets/benches (tasks 57–61) rely on schema freeze from tasks 1/55 and determinism guardrails; ensure feed-freeze hashes are published before CI wiring. +- Competitive/vision docs updated with reachability moat and vendor comparison; ensure sales/PMM references live in `docs/market/competitive-landscape.md` and `docs/reachability/lead.md`. ## Upcoming Checkpoints - Schedule go/no-go once Sprint 0400 readiness is confirmed (TBD, Planning). @@ -117,10 +129,18 @@ | R1 | Sprint 0400 and upstream runtime/replay prerequisites slip. | Delivery blocked; evidence chain cannot start. | Track readiness in checkpoints; hold start until record mode + Evidence Locker APIs land (Planning). | | R2 | CAS hash/predicate mismatch across modules. | Inconsistent artifacts, replay failures. | Align specs via tasks 1, 11, 19, 24; review before implementation (Platform Guild). | | R3 | Determinism gaps in fixtures/benchmarks. | Flaky reachability scoring and VEX proofs. | Prioritize QA tasks 16, 25, 46, 52; enforce deterministic ordering in tests (QA Guild). | +| R4 | Edge-bundle Rekor volume or bundle count spikes. | Rekor congestion/cost; slower pipelines; CAS bloat. | Cap Rekor publishes per graph (task 54), default to CAS-only for bulk bundles, monitor Signals ingest size; add CI perf guard after task 55. | +| R5 | Bench/dataset tasks start before feed-freeze and schema alignment. | Non-replayable results; wasted bench runs. | Block tasks 57–61 on published feed hashes + `richgraph-v1`/Unknowns schema; add gating checklist in task definitions. | +| R6 | Bench/dataset code not materialized (docs only). | Docs drift; no executable evidence for claims. | Tasks 57–60 must produce runnable harnesses/fixtures under `docs/benchmarks/**` or `tests/**`; Execution Log to confirm artifact paths. | ## Execution Log | Date (UTC) | Update | Owner | | --- | --- | --- | +| 2025-11-23 | Added R6 to enforce runnable bench/dataset artifacts; noted supersedes/extends text in moat/competitive docs. | Planning | +| 2025-11-23 | Added bench/dataset code-reference docs (`docs/benchmarks/signals/bench-determinism.md`, corpus plan update); updated tasks 57–61 links. | Planning | +| 2025-11-23 | Added competitive + reachability moat docs (`docs/market/competitive-landscape.md`, `docs/reachability/lead.md`) and linked sprint narrative to them. | Planning | +| 2025-11-23 | Added tasks 57–61 (determinism bench, public reachability dataset, native callgraph ingest, corpus merge, docs), logged R5, and noted schema/feed gating. | Planning | +| 2025-11-23 | Added hybrid attestation decision and tasks 53–56; aligned docs references. | Planning | | 2025-11-22 | Updated cross-references to new sprint filename in tasks-all and reachability docs; synced naming in bench playbook. | Planning | | 2025-11-22 | Normalized sprint to template, added dependencies/prereqs, Delivery Tracker numbering, interlocks, risks; renamed file for naming compliance. | Planning | | 2025-11-20 | Added tasks for purl-resolved edges, ELF build-id propagation, init-array roots, and patch-oracle QA harness; aligned docs references. | Planning | diff --git a/docs/implplan/SPRINT_0512_0001_0001_bench.md b/docs/implplan/SPRINT_0512_0001_0001_bench.md index b3d4f2e66..667f4903b 100644 --- a/docs/implplan/SPRINT_0512_0001_0001_bench.md +++ b/docs/implplan/SPRINT_0512_0001_0001_bench.md @@ -30,8 +30,9 @@ | 3 | BENCH-GRAPH-24-002 | BLOCKED | Waiting for 50k/100k graph fixture (SAMPLES-GRAPH-24-003) | Bench Guild · UI Guild | Implement UI interaction benchmarks (filter/zoom/table operations) citing p95 latency; integrate with perf dashboards. | | 4 | BENCH-IMPACT-16-001 | BLOCKED | PREP-BENCH-IMPACT-16-001-IMPACT-INDEX-DATASET | Bench Guild · Scheduler Team | ImpactIndex throughput bench (resolve 10k productKeys) + RAM profile. | | 5 | BENCH-POLICY-20-002 | BLOCKED | PREP-BENCH-POLICY-20-002-POLICY-DELTA-SAMPLE | Bench Guild · Policy Guild · Scheduler Guild | Add incremental run benchmark measuring delta evaluation vs full; capture SLA compliance. | -| 6 | BENCH-SIG-26-001 | BLOCKED | PREP-BENCH-SIG-26-001-REACHABILITY-SCHEMA-FIX | Bench Guild · Signals Guild | Develop benchmark for reachability scoring pipeline (facts/sec, latency, memory) using synthetic callgraphs/runtime batches. | +| 6 | BENCH-SIG-26-001 | BLOCKED | PREP-BENCH-SIG-26-001-REACHABILITY-SCHEMA-FIX | Bench Guild · Signals Guild | Develop benchmark for reachability scoring pipeline (facts/sec, latency, memory) using synthetic callgraphs/runtime batches. | | 7 | BENCH-SIG-26-002 | BLOCKED | PREP-BENCH-SIG-26-002-BLOCKED-ON-26-001-OUTPU | Bench Guild · Policy Guild | Measure policy evaluation overhead with reachability cache hot/cold; ensure ≤8 ms p95 added latency. | +| 8 | BENCH-DETERMINISM-401-057 | TODO | Feed-freeze hash + SBOM/VEX bundle list from Sprint 0401. | Bench Guild · Signals Guild · Policy Guild (`bench/determinism`, `docs/benchmarks/signals/bench-determinism.md`) | Run cross-scanner determinism bench from 23-Nov advisory; publish determinism% and CVSS delta σ; CI target `bench:determinism`; store hashed inputs/outputs. | ## Wave Coordination - Single wave; benches sequenced by dataset availability. No parallel wave gating beyond Delivery Tracker dependencies. diff --git a/docs/key-features.md b/docs/key-features.md index 92c78376e..19d0c0fa1 100644 --- a/docs/key-features.md +++ b/docs/key-features.md @@ -27,6 +27,16 @@ Each card is a fast read pairing the headline capability with the evidence that - **Evidence:** Quota tokens verify locally using bundled public keys, and Offline Update Kits include mirrored advisories, SBOM feeds, and VEX sources. - **Why it matters:** You stay within predictable limits, avoid surprise throttling, and operate entirely offline when needed. +## 6. Signed Reachability Proofs (Hybrid) +- **What it is:** Every reachability graph is sealed with a graph-level DSSE and optional edge-bundle DSSEs for runtime/init/contested edges; Rekor-backed when enabled. +- **Evidence:** CAS layout `cas://reachability/graphs/{hash}` + `{hash}.dsse`; edge bundles capped and sorted; quarantine/dispute uses per-edge revocation. See `docs/reachability/hybrid-attestation.md`. +- **Why it matters:** You can prove (or contest) exactly why a vuln is reachable, replay results offline, and avoid flooding transparency logs. + +## 7. Competitive Moats (2025-11 refresh) +- **What it is:** Deterministic replay, lattice VEX, sovereign crypto profiles, proof graph, and hybrid reachability attestations held as first-class product pillars. +- **Evidence:** `docs/market/competitive-landscape.md` distils a 15-vendor comparison; `03_VISION.md` lists moats; `docs/reachability/lead.md` details the reachability proof moat. +- **Why it matters:** Clear differentiation guides roadmap and sales; keeps us focused on replayable, sovereign, and explainable security. + ### Explore Further - Walk the first deployment in [quickstart.md](quickstart.md). - Dive into architectural flows in [high-level-architecture.md](high-level-architecture.md). diff --git a/docs/market/competitive-landscape.md b/docs/market/competitive-landscape.md new file mode 100644 index 000000000..9bd114236 --- /dev/null +++ b/docs/market/competitive-landscape.md @@ -0,0 +1,80 @@ +# Competitive Landscape (Nov 2025) + +Source: internal advisory “23-Nov-2025 - Stella Ops vs Competitors”. Supersedes/extends prior competitive notes (none published); treat this as canonical until a newer dated advisory arrives. This summary distils the 15-vendor comparison into actionable positioning notes and links back to the full matrix for sales/PMM. + +## Stella Ops moats (why we win) +- **Deterministic replay:** feed+rules snapshotting; graph/SBOM/VEX re-run bit-for-bit with manifest hashes. +- **Hybrid reachability attestations:** graph-level DSSE always; optional edge-bundle DSSE for runtime/init/contested edges; Rekor-backed with publish caps. +- **Lattice-based VEX engine:** merges advisories, runtime hits, reachability, waivers with explainable paths. +- **Crypto sovereignty:** FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class knobs. +- **Proof graph:** DSSE + transparency across SBOM, call-graph, VEX, replay manifests. + +## Top takeaways (sales-ready) +1. No competitor offers deterministic replay with frozen feeds; we do. +2. None sign reachability graphs; we sign graphs and (optionally) edges. +3. Sovereign crypto profiles (FIPS/eIDAS/GOST/SM/PQC) are unique to Stella Ops. +4. Lattice VEX + explainable paths is unmatched; others ship boolean VEX or none at all. +5. Offline/air-gap readiness with mirrored transparency is rare; we ship it by default. + +## Where others fall short (high level) +- **No deterministic replay:** none of the 15 provide hash-stable, replayable scans with frozen feeds. +- **No lattice/VEX merge:** VEX is absent or bolt-on; no trust algebra elsewhere. +- **Attestation gaps:** most rely on Cosign-only or have no DSSE/Rekor story; none sign reachability graphs. +- **Offline/sovereign:** weak or SaaS-only; no regional crypto options. + +## Snapshot table (condensed) +| Vendor | SBOM Gen | SBOM Ingest | Attest (DSSE) | Rekor | Offline | Primary gaps vs Stella | +| ------------------- | -------- | ----------- | ------------- | ----- | ------- | ---------------------- | +| Trivy | Yes | Yes | Cosign | Query | Strong | No replay, no lattice | +| Syft/Grype | Yes | Yes | Cosign-only | Indir | Medium | No replay, no lattice | +| Snyk | Yes | Limited | No | No | Weak | No attest/VEX/replay | +| Prisma | Yes | Limited | No | No | Strong | No attest/replay | +| AWS (Inspector/Signer)| Partial| Partial | Notary v2 | No | Weak | Closed, no replay | +| Google | Yes | Yes | Yes | Opt | Weak | No offline/lattice | +| GitHub | Yes | Partial | Yes | Yes | No | No replay/crypto opts | +| GitLab | Yes | Limited | Partial | No | Medium | No replay/lattice | +| Microsoft Defender | Partial | Partial | No | No | Weak | No attest/reachability | +| Anchore Enterprise | Yes | Yes | Some | No | Good | No sovereign crypto | +| JFrog Xray | Yes | Yes | No | No | Medium | No attest/lattice | +| Tenable | Partial | Limited | No | No | Weak | Not SBOM/VEX-focused | +| Qualys | Limited | Limited | No | No | Medium | No attest/lattice | +| Rezilion | Yes | Yes | No | No | Medium | Runtime-only; no DSSE | +| Chainguard | Yes | Yes | Yes | Yes | Medium | No replay/lattice | + +## How to use this doc +- Sales/PMM: pull talking points and the gap list when building battlecards. +- Product: map gaps to roadmap; keep replay/lattice/sovereign as primary differentiators. +- Engineering: ensure new features keep determinism + sovereign crypto front-and-center; link reachability attestations into proof graph. + +## Cross-links +- Vision: `docs/03_VISION.md` (Moats section) +- Architecture: `docs/07_HIGH_LEVEL_ARCHITECTURE.md` +- Reachability moat details: `docs/reachability/lead.md` +- Source advisory: `docs/product-advisories/23-Nov-2025 - Stella Ops vs Competitors.md` + +--- + +## Battlecard Appendix (snippet-ready) + +**One-liners** +- *Replay or it’s noise:* Only Stella Ops can re-run a scan bit-for-bit from frozen feeds. +- *Signed reachability, not guesses:* Graph DSSE always; optional edge DSSE for runtime/init edges. +- *Sovereign-first:* FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors are first-class toggles. +- *Trust algebra:* Lattice VEX merges advisories, reachability, runtime, waivers with explainable paths. + +**Proof points** +- Deterministic replay manifests; BLAKE3 graph hashes; DSSE + Rekor for graphs (edge bundles optional). +- Hybrid reachability: graph-level attestations plus capped edge-bundle attestations to avoid Rekor flood. +- Offline: transparency mirrors + sealed bundles keep verification working air-gapped. + +**Objection handlers** +- “We already sign SBOMs.” → Do you sign call-graphs and VEX? Do you replay scans bit-for-bit? We do. +- “Cosign/Rekor is enough.” → Without deterministic manifests + reachability proofs, you can’t audit why a vuln was reachable. +- “Our runtime traces show reachability.” → We combine runtime hits with signed static graphs and VEX lattice; evidence is replayable and quarantinable edge-by-edge. + +**CTA for reps** +- Demo: show `stella graph verify --graph ` with and without edge-bundle verification. +- Leave-behind: link `docs/reachability/lead.md` and this appendix. + +## Sources +- Full advisory: `docs/product-advisories/23-Nov-2025 - Stella Ops vs Competitors.md` diff --git a/docs/modules/devops/AGENTS.md b/docs/modules/devops/AGENTS.md index c1ee8175c..3c4b1ae30 100644 --- a/docs/modules/devops/AGENTS.md +++ b/docs/modules/devops/AGENTS.md @@ -1,7 +1,14 @@ # DevOps agent guide -## Mission -The DevOps module captures release, deployment, and migration playbooks that keep StellaOps deterministic across environments. +## Mission +The DevOps module captures release, deployment, and migration playbooks that keep StellaOps deterministic across environments. + +## Advisory Handling +- Any new/updated advisory triggers immediate doc + sprint updates (no approval). +- Update high-level + detailed docs; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link. +- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. +- Check archived advisories; mark supersedes/extends if overlapping. +- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after. ## Key docs - [Module README](./README.md) diff --git a/docs/modules/graph/AGENTS.md b/docs/modules/graph/AGENTS.md index 077464f31..1876052bc 100644 --- a/docs/modules/graph/AGENTS.md +++ b/docs/modules/graph/AGENTS.md @@ -3,6 +3,13 @@ ## Mission Graph module (upcoming) will power graph-indexed queries for SBOM relationships, lineage, and blast-radius analysis. +## Advisory Handling +- Any new/updated advisory triggers doc + sprint updates immediately. No approval. +- Update high-level + detailed docs; inline only short snippets; runnable/long code to `docs/benchmarks/**` or `tests/**` (deterministic/offline) with links. +- Add tasks and Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. +- Check archived advisories for overlap; mark supersedes/extends. +- Defaults: hybrid reachability posture, deterministic/frozen feeds; execute first, report after. + ## Key docs - [Module README](./README.md) - [Architecture](./architecture.md) diff --git a/docs/modules/platform/architecture-overview.md b/docs/modules/platform/architecture-overview.md index c262ddad4..e3f0dec72 100644 --- a/docs/modules/platform/architecture-overview.md +++ b/docs/modules/platform/architecture-overview.md @@ -69,6 +69,7 @@ Key boundaries: - **AOC border.** Everything inside the Ingestion subgraph writes only immutable raw facts plus link hints. Derived severity, consensus, and risk remain outside the border. - **Policy-only derivation.** Policy Engine materialises `effective_finding_*` collections and emits overlays; other services consume but never mutate them. - **Tenant enforcement.** Authority-issued DPoP scopes flow through Gateway to every service; raw stores and overlays include `tenant` strictly. +- **Hybrid reachability attestations.** Scanner/Attestor always publish graph-level DSSE for reachability graphs; optional edge-bundle DSSEs capture high-risk/runtime/init edges. Policy/Signals consume both, with graph DSSE as the minimum bar and edge bundles used for quarantine/dispute flows. --- diff --git a/docs/modules/policy/architecture.md b/docs/modules/policy/architecture.md index 44e106ec6..cbab199a7 100644 --- a/docs/modules/policy/architecture.md +++ b/docs/modules/policy/architecture.md @@ -20,6 +20,7 @@ The service operates strictly downstream of the **Aggregation-Only Contract (AOC - Materialise effective findings (`effective_finding_{policyId}`) with append-only history and produce explain traces. - Emit per-finding OpenVEX decisions anchored to reachability evidence, forward them to Signer/Attestor for DSSE/Rekor, and publish the resulting artifacts for bench/verification consumers. - Consume reachability lattice decisions (`ReachDecision`, `docs/reachability/lattice.md`) to drive confidence-based VEX gates (not_affected / under_investigation / affected) and record the policy hash used for each decision. +- Honor **hybrid reachability attestations**: graph-level DSSE is required input; when edge-bundle DSSEs exist, prefer their per-edge provenance for quarantine, dispute, and high-risk decisions. Quarantined edges (revoked in bundles or listed in Unknowns registry) must be excluded before VEX emission. - Operate incrementally: react to change streams (advisory/vex/SBOM deltas) with ≤ 5 min SLA. - Provide simulations with diff summaries for UI/CLI workflows without modifying state. - Enforce strict determinism guard (no wall-clock, RNG, network beyond allow-listed services) and RBAC + tenancy via Authority scopes. diff --git a/docs/modules/scanner/architecture.md b/docs/modules/scanner/architecture.md index 321e2920d..0ae0ffb7d 100644 --- a/docs/modules/scanner/architecture.md +++ b/docs/modules/scanner/architecture.md @@ -53,6 +53,8 @@ Analyzer assemblies and buildx generators are packaged as **restart-time plug-in - **Build-id capture**: read `.note.gnu.build-id` for every ELF, store hex build-id alongside soname/path, propagate into `SymbolID`/`code_id`, and expose it to SBOM + runtime joiners. If missing, fall back to file hash and mark source accordingly. - **PURL-resolved edges**: annotate call edges with the callee purl and `symbol_digest` so graphs merge with SBOM components. See `docs/reachability/purl-resolved-edges.md` for schema rules and acceptance tests. - **Unknowns emission**: when symbol → purl mapping or edge targets remain unresolved, emit structured Unknowns to Signals (see `docs/signals/unknowns-registry.md`) instead of dropping evidence. +- **Hybrid attestation**: emit **graph-level DSSE** for every `richgraph-v1` (mandatory) and optional **edge-bundle DSSE** (≤512 edges) for runtime/init-root/contested edges or third-party provenance. Publish graph DSSE digests to Rekor by default; edge-bundle Rekor publish is policy-driven. CAS layout: `cas://reachability/graphs/{blake3}` for graph body, `.../{blake3}.dsse` for envelope, and `cas://reachability/edges/{graph_hash}/{bundle_id}[.dsse]` for bundles. Deterministic ordering before hashing/signing is required. +- **Deterministic call-graph manifest**: capture analyzer versions, feed hashes, toolchain digests, and flags in a manifest stored alongside `richgraph-v1`; replaying with the same manifest MUST yield identical node/edge sets and hashes (see `docs/reachability/lead.md`). ### 1.1 Queue backbone (Redis / NATS) diff --git a/docs/modules/signer/AGENTS.md b/docs/modules/signer/AGENTS.md index 1cbd3dea8..0501f5b3e 100644 --- a/docs/modules/signer/AGENTS.md +++ b/docs/modules/signer/AGENTS.md @@ -3,6 +3,13 @@ ## Mission Signer validates callers, enforces Proof-of-Entitlement, and produces signed DSSE bundles for SBOMs, reports, and exports. +## Advisory Handling +- Any new/updated advisory triggers immediate doc + sprint updates; no approval. +- Update high-level + detailed docs; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link. +- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. +- Check archived advisories; mark supersedes/extends if overlapping. +- Defaults: hybrid reachability (graph DSSE required; edge-bundle optional), deterministic/frozen feeds; act first, report after. + ## Key docs - [Module README](./README.md) - [Architecture](./architecture.md) diff --git a/docs/modules/telemetry/AGENTS.md b/docs/modules/telemetry/AGENTS.md index af732c22e..e881d2124 100644 --- a/docs/modules/telemetry/AGENTS.md +++ b/docs/modules/telemetry/AGENTS.md @@ -3,6 +3,13 @@ ## Mission Telemetry module captures deployment and operations guidance for the shared observability stack (collectors, storage, dashboards). +## Advisory Handling +- Any new/updated advisory triggers immediate doc + sprint updates; no approval. +- Update high-level + detailed docs; inline only short snippets; place runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link. +- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. +- Check archived advisories; mark supersedes/extends if overlapping. +- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after. + ## Key docs - [Module README](./README.md) - [Architecture](./architecture.md) diff --git a/docs/modules/ui/AGENTS.md b/docs/modules/ui/AGENTS.md index 3fa15164e..71886ce7c 100644 --- a/docs/modules/ui/AGENTS.md +++ b/docs/modules/ui/AGENTS.md @@ -3,6 +3,12 @@ ## Mission The Console presents operator dashboards for scans, policies, VEX evidence, runtime posture, and admin workflows. +## Advisory Handling +- New/updated advisories require immediate doc + sprint updates (no approval): high-level + detailed docs; inline only short snippets; runnable/long code to `docs/benchmarks/**` or `tests/**` (deterministic/offline) with links. +- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. +- Check archived advisories for overlaps; mark supersedes/extends. +- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after. + ## Key docs - [Module README](./README.md) - [Architecture](./architecture.md) diff --git a/docs/modules/zastava/AGENTS.md b/docs/modules/zastava/AGENTS.md index abdfb3366..4cff64825 100644 --- a/docs/modules/zastava/AGENTS.md +++ b/docs/modules/zastava/AGENTS.md @@ -3,6 +3,13 @@ ## Mission Zastava monitors running workloads, verifies supply chain posture, and enforces runtime policy via Kubernetes admission webhooks. +## Advisory Handling +- Trigger: any new/updated advisory triggers doc + sprint updates; no approval required. +- Docs: update high-level + detailed pages; inline only small snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link. +- Sprints: add tasks + Execution Log in the relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply. +- De-dup: check archived advisories; mark supersedes/extends where overlapping. +- Defaults: hybrid reachability posture, deterministic/frozen feeds; execute immediately, then report. + ## Key docs - [Module README](./README.md) - [Architecture](./architecture.md) diff --git a/docs/reachability/corpus-plan.md b/docs/reachability/corpus-plan.md index f7037092d..9841ee210 100644 --- a/docs/reachability/corpus-plan.md +++ b/docs/reachability/corpus-plan.md @@ -3,6 +3,7 @@ Objective - Build a multi-runtime reachability corpus (Go/.NET/Python/Rust) with EXPECT.yaml ground truths and captured traces. - Make fixtures CI-consumable to validate reachability scoring and VEX proofs continuously. +- Add public mini-dataset cases (PHP/JavaScript/C#) from advisory 23-Nov-2025 for ingestion/bench reuse. Scope & deliverables - Fixture layout: `tests/reachability/corpus///` @@ -13,6 +14,17 @@ Scope & deliverables - `vex.openvex.json` — expected VEX statement. - CI integration: add corpus harness to `tests/reachability/StellaOps.Reachability.FixtureTests` to validate presence, schema, and determinism (hash manifest). - Offline posture: all artifacts deterministic, no external downloads; hashes recorded in manifest. +- Public mini-dataset layout (PHP/JS/C#) to be mirrored under `tests/reachability/samples-public/`: +``` +vuln-reach-dataset/ + schema/ground-truth.schema.json + runners/run_all.sh + samples/ + php/php-001-phar-deserialize/... + js/js-002-yaml-unsafe-load/... + csharp/cs-001-binaryformatter-deserialize/... +``` +Each sample ships: minimal app, lockfile, SBOM (CycloneDX JSON), VEX, ground truth (EXPECT/JSON), repro script. MVP slice (proposed) - Go: `go-ssh-CVE-2020-9283-keyexchange` diff --git a/docs/reachability/evidence-schema.md b/docs/reachability/evidence-schema.md index 43e6948e3..5870790ad 100644 --- a/docs/reachability/evidence-schema.md +++ b/docs/reachability/evidence-schema.md @@ -46,6 +46,16 @@ Purpose: define the canonical fields for reachability graph nodes/edges, runtime } ``` +## 2.5 Attestation levels (hybrid default) + +- **Graph DSSE (required):** one DSSE envelope over the canonical graph JSON (sorted arrays/keys) with `graph_hash` = BLAKE3 of body; Rekor publish always (or mirror when offline). +- **Edge-bundle DSSE (optional):** batches of ≤512 edges, emitted only for high-signal cases (`runtime`, `init_array`/TLS roots, contested/third-party edges). Each bundle carries `graph_hash`, `bundle_reason`, per-edge `reason`, `symbol_digest`, `purl`, `confidence`, and optional `revoked=true` for quarantine. Rekor publish is configurable; CAS storage is mandatory. +- CAS layout additions: + - Graph body: `cas://reachability/graphs/{blake3}` + - Graph DSSE: `cas://reachability/graphs/{blake3}.dsse` + - Edge bundle: `cas://reachability/edges/{graph_hash}/{bundle_id}` + `.dsse` +- Determinism: bundle ordering by `(bundle_reason, edge_id)`; arrays sorted before hashing. + ## 3. Runtime facts (Signals ingestion) Fields per NDJSON event: @@ -69,6 +79,7 @@ Unknowns must include `unknown_type`, `scope`, `provenance`, `confidence.p`, and - Graphs: `cas://reachability/graphs/{blake3}` (canonical JSON, sorted keys/arrays) - Runtime traces: `cas://reachability/runtime/{sha256}` - Unknowns evidence (optional large blobs): `cas://unknowns/{sha256}` +- Edge bundles: `cas://reachability/edges/{graph_hash}/{bundle_id}` (JSON + `.dsse`) Metadata for each CAS object: `{ schema: "richgraph-v1", analyzer: {name,version}, createdAtUtc, toolchain_digest }`. When analyzer metadata is supplied at ingest (Signals OpenAPI), persist it alongside parsed analyzer fields from the artifact. @@ -78,6 +89,8 @@ Metadata for each CAS object: `{ schema: "richgraph-v1", analyzer: {name,version - If `build_id` present, `symbol_id` and `code_id` must store it; if absent, record `build_id_source: "FileHash"`. - Evidence arrays sorted; confidence in [0,1]. - Roots must include load-time constructors when present. +- When `edge_bundles` are present, each edge in a bundle must also exist in the graph edge set; `revoked=true` bundles override graph edges for policy/scoring. +- Graph DSSE is mandatory per scan; edge-bundle DSSEs are optional but must reference `graph_hash` and `bundle_id`. ## 7. Acceptance checklist diff --git a/docs/reachability/hybrid-attestation.md b/docs/reachability/hybrid-attestation.md new file mode 100644 index 000000000..fa39cbca4 --- /dev/null +++ b/docs/reachability/hybrid-attestation.md @@ -0,0 +1,55 @@ +# Hybrid Reachability Attestation (Graph + Edge-Bundle) + +> Decision date: 2025-11-23 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild + +## 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. + +## 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. +- **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. + +## 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. 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. diff --git a/docs/reachability/lead.md b/docs/reachability/lead.md new file mode 100644 index 000000000..0f90a900e --- /dev/null +++ b/docs/reachability/lead.md @@ -0,0 +1,78 @@ +# Deterministic Reachability — Product Moat (Nov 2025) + +Source: internal advisory “23-Nov-2025 - Where Stella Ops Can Truly Lead”. Supersedes/extends archived binary reachability advisories (18-Nov-2025 - Binary-Reachability-Engine, Encoding Binary Reachability with PURL-Resolved Edges, CSharp-Binary-Analyzer). This page is the canonical, high-level articulation of our reachability moat for architects, PMM, and field teams. Detailed schemas live in `docs/reachability/evidence-schema.md` and `docs/reachability/hybrid-attestation.md`. + +## Why it matters +- Most scanners list every CVE; reachability asks whether vulnerable code is actually callable. +- Competitors infer paths and rarely sign evidence; we **prove** paths with deterministic graphs and attestations. +- Outcome targets: ≥40% fewer noisy vulns shown; ≥25% faster triage via explainable “why” paths. + +## Moat elements +1) **Deterministic call-graphs per artifact** + - Stable node IDs: `purl@version!build-id!symbol-signature` (or code offset when stripped). + - Stable edge IDs: `SHA256(nodeA||nodeB||tool-version||inputs-hash)`. + - Graph hash: BLAKE3 over canonical JSON; locked by manifest. +2) **Signed evidence** + - Graph-level DSSE for every scan (mandatory). + - Optional edge-bundle DSSE (≤512 edges) for runtime/init/contested edges; Rekor publish capped. See `docs/reachability/hybrid-attestation.md`. +3) **Explainability** + - Each finding carries call-chain + per-edge reason + VEX gate decision + layer attribution. +4) **Container layer provenance** + - Track file-to-layer mapping; show “introduced in layer X from base Y”. +5) **Replayability** + - Determinism manifest locks feeds, toolchain hashes, analyzer flags; replay yields identical graph and attestations. + +## Minimal architecture slice +- **Sbomer/Scanner**: emit SBOM + symbol maps + per-layer file index; capture Build-IDs. +- **Cartographer**: build deterministic call-graphs (language + native), output `EdgeList.jsonl` with stable IDs. +- **Attestor**: wrap graph (and edge bundles when emitted) into DSSE; log digests to Rekor/mirror. +- **Vexer/Policy**: evaluate lattice, produce OpenVEX with linked edge proofs. +- **Ledger**: retain manifests and DSSE; mirror to Rekor where allowed. + +## Practical spec (condensed) +- **Node fields**: `symbol_id`, `code_id`, `purl`, `build_id`, `symbol_digest`, `lang`, `evidence[]`. +- **Edge fields**: `from`, `to`, `kind` (direct|plt|runtime|init), `purl`, `symbol_digest`, `reason`, `confidence`, `evidence[]`. +- **Roots**: exports, entrypoints, **.init_array/.ctors/TLS callbacks**, plugin hooks. +- **Attestation layout**: + - Graph: `cas://reachability/graphs/{blake3}` + `{blake3}.dsse` (Rekor always). + - Edge bundle: `cas://reachability/edges/{graph_hash}/{bundle_id}[.dsse]` (Rekor optional, capped). + +### Example: Edge-bundle DSSE payload (abridged) +```json +{ + "graph_hash": "blake3:...", + "bundle_reason": "runtime-hit", + "edges": [{ + "edge_id": "sha256:...", + "from": "sym:...caller", + "to": "sym:...callee", + "reason": "plt", + "purl": "pkg:deb/openssl@3.0.2?arch=amd64", + "symbol_digest": "sha256:...", + "revoked": false + }] +} +``` + +### Field cheat sheet (for sprint readers) +- `graph_hash` — BLAKE3 of canonical graph JSON. +- `bundle_reason` — `runtime-hit | init-root | contested | third-party`. +- `edge_id` — sha256(from||to||reason||tool-version||inputs-hash). +- `revoked` — when true, policy/Signals must drop this edge before reachability scoring. +- `purl` + `symbol_digest` — bind edge to SBOM component and callee identity. + +## Quick wins (ship order) +1) Capture Build-IDs in Scanner and thread into `symbol_id`/`code_id`. +2) Emit Graph Determinism Manifest (feeds + toolchain hashes) per scan. +3) Turn on edge-bundle DSSE for runtime/init edges first; keep Rekor cap low. +4) Surface “why path” + layer attribution in CLI/UI explainers. + +## APIs (strawman) +- `POST /graph/edges: attest` — idempotent; same inputs → same edge IDs. +- `GET /findings/:id/proof` — returns call-chain + Rekor inclusion proofs. +- `GET /vex/:artifact` — streams OpenVEX with embedded proofs. + +## Links +- Advisory source: `docs/product-advisories/23-Nov-2025 - Where Stella Ops Can Truly Lead.md` +- Schemas: `docs/reachability/evidence-schema.md`, `docs/reachability/hybrid-attestation.md` +- Sprint tracking: `docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md` diff --git a/src/Cli/StellaOps.Cli/AGENTS.md b/src/Cli/StellaOps.Cli/AGENTS.md index b1648e732..2f629bf57 100644 --- a/src/Cli/StellaOps.Cli/AGENTS.md +++ b/src/Cli/StellaOps.Cli/AGENTS.md @@ -4,6 +4,14 @@ - Deliver an offline-capable command-line interface that drives StellaOps back-end operations: scanner distribution, scan execution, result uploads, and Concelier database lifecycle calls (init/resume/export). - Honour StellaOps principles of determinism, observability, and offline-first behaviour while providing a polished operator experience. +## Advisory Handling (inherit + enforce) +- Trigger: any new/updated advisory (`docs/product-advisories/`) requires immediate doc + sprint updates. No chat approval. +- Docs: add high-level + detailed updates; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link. +- Sprints: add Delivery Tracker rows and Execution Log entries in the relevant `SPRINT_*.md`; include doc paths and owners; add risks if feeds/schemas/transparency caps apply. +- De-dup: check archived advisories; mark supersedes/extends if overlapping. +- Defaults: hybrid reachability (graph DSSE required; edge-bundle optional), deterministic/frozen feeds. +- Do not defer: execute immediately, then report. + ## Role Charter | Role | Mandate | Collaboration | | --- | --- | --- |