diff --git a/docs/03_VISION.md b/docs/03_VISION.md index 2b167647f..7c855dd61 100755 --- a/docs/03_VISION.md +++ b/docs/03_VISION.md @@ -1,5 +1,7 @@ #  3 · Product Vision — **Stella Ops** +> Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + ## 1) Problem Statement & Goals We ship containers. We need: @@ -369,11 +371,24 @@ opa eval -i gate-input.json -d policy/ -f pretty "data.stella.policy.allow" --- ## 9) Moats + + +**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. +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. + +**Decision Capsules:** Every scan result is sealed in a Decision Capsule—a content-addressed bundle containing exact SBOM, vuln feed snapshots, reachability evidence, policy version, derived VEX, and signatures. Auditors can re-run any capsule bit-for-bit to verify the outcome. + +**Additional moat details:** - **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. +- **Hybrid reachability attestations:** Graph-level DSSE always; selective edge-bundle DSSE for runtime/init/contested edges with Rekor caps. Both static call-graph edges and runtime-derived edges can be attested. +- **Lattice VEX engine (Evidence-Linked):** Trust algebra across advisories, runtime, reachability, waivers; explainable paths with proof-linked decisions. Unlike yes/no approaches, explicit "Unknown" state handling ensures incomplete data never leads to false safety. - **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. +- **Proof graph:** DSSE + Rekor spanning SBOM, call-graph, VEX, Decision Capsules, replay manifests for chain-of-custody evidence. +- **VEX Propagation:** Generate vulnerability status attestations downstream consumers can automatically trust and ingest—scalable VEX sharing across the supply chain. See also: `docs/market/competitive-landscape.md` for vendor comparison and talking points. diff --git a/docs/README.md b/docs/README.md index c75f89fe3..a827c6910 100755 --- a/docs/README.md +++ b/docs/README.md @@ -1,52 +1,59 @@ -# Stella Ops +# Stella Ops -> Stella Ops is the sovereign, SBOM‑first security platform that proves every container decision with deterministic scans, explainable policy verdicts, and offline‑ready provenance. +> Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. -- **Sovereign by design** – bring your own trust roots, vulnerability advisory sources, VEX sources, regional crypto, and Offline Update Kits that never phone home. -- **Deterministic + replayable** – every scan can be reproduced bit‑for‑bit with DSSE + OpenVEX evidence. -- **Actionable signal** – lattice logic ranks exploitability, and the policy engine lets you tailor VEX handling, muting, and expiration rules for your environment. + +Stella Ops delivers **four capabilities no competitor offers together**: -**Proof points:** SBOM dependency and vulnerability dependency cartographing work, deterministic replay manifests, lattice policy UI with OpenVEX, and post‑quantum trust packs ready for regulated sectors. +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. Auditors and incident responders can re-run historical findings and trust the results weren't tampered with. +3. **Explainable Policy (Lattice VEX)** – The lattice engine merges SBOM data, advisories, VEX statements, and waivers into a single verdict with human-readable justifications. Explicit "Unknown" state handling ensures incomplete data never leads to false safety. +4. **Sovereign + Offline Operation** – FIPS, eIDAS, GOST, SM, or PQC profiles are first-class toggles. Offline Kits and regional crypto profiles keep every decision inside your perimeter—air-gapped verification works by default. + +**Proof points:** Decision Capsules (sealed evidence bundles), SBOM cartographing, deterministic replay manifests, lattice policy UI with OpenVEX, evidence-linked VEX decisions, and post‑quantum trust packs ready for regulated sectors. ## Choose Your Path | If you want to… | Open this | Read time | |-----------------|-----------|-----------| -| Understand the promise and pain we solve | `overview.md` | ≈ 2 min | -| Run a first scan and see the CLI | `quickstart.md` | ≈ 5 min | -| Browse key capabilities at a glance | `key-features.md` | ≈ 3 min | -| Check architecture, road to production, or evaluate fit | See “Dig deeper” below | ≤ 30 min curated set | +| Understand the promise and pain we solve | `overview.md` | ≈ 2 min | +| Run a first scan and see the CLI | `quickstart.md` | ≈ 5 min | +| Browse key capabilities at a glance | `key-features.md` | ≈ 3 min | +| Check architecture, road to production, or evaluate fit | See "Dig deeper" below | ≤ 30 min curated set | ## Explore the Essentials -1. **Value in context** – [Overview](overview.md) compresses the “Why” + “What” stories and shows how Stella Ops stands apart. +1. **Value in context** – [Overview](overview.md) compresses the "Why" + "What" stories and shows how Stella Ops stands apart. 2. **Try it fast** – [Quickstart](quickstart.md) walks through fetching the signed bundles, configuring `.env`, and verifying the first scan. -3. **Feature confidence** – [Key Features](key-features.md) gives five capability cards covering Delta SBOM, VEX-first policy, Sovereign crypto, Deterministic replay, and Transparent quotas. +3. **Feature confidence** – [Key Features](key-features.md) gives nine capability cards covering Decision Capsules, Delta SBOM, VEX-first policy, Sovereign crypto, Deterministic replay, and more. 4. **Up-next checkpoints** – [Evaluation checklist](evaluate/checklist.md) helps teams plan Day-0 to Day-30 adoption milestones. 5. **Be dev-ready** – [Developer Quickstart](onboarding/dev-quickstart.md) (29-Nov-2025 advisory) walks through the core repos, determinism tests, attestations, and starter issues for a mid-level .NET engineer. -## Key capabilities that define Stella Ops +## Key capabilities that define Stella Ops + | Capability | What ships | Why it matters | |------------|------------|----------------| +| **Decision Capsules** | Every scan result is sealed in a content-addressed bundle containing SBOM, vuln feed snapshots, reachability evidence, policy version, derived VEX, and signatures. | Auditors can re-run any capsule bit-for-bit to verify the outcome—audit-grade evidence bundles. | | **Deterministic Δ‑SBOM & replay bundles** | Layer-aware cache + replay manifests keep scans reproducible even months later. | Auditors can re-run any verdict with identical inputs, proving integrity without SaaS dependencies. | | **Pristine advisory mirrors** | OSV, GHSA, NVD, CNVD, CNNVD, ENISA, JVN, BDU, etc. are mirrored as immutable, per-source snapshots—never merged. | Policy (via `scanner.*` / `SCANNER__*`) can trust, down-rank, or ignore sources without rewriting upstream data. | -| **Lattice VEX engine** | OpenVEX, waivers, mitigations, and configs flow through deterministic lattice logic. | Every block/allow decision is explainable, replayable, and environment-specific. | -| **Context fabric** | Static reachability now, optional runtime/eBPF probes at GA so build + runtime signals share one verdict. | Prioritisation spans first-party code, base images, and live telemetry. | +| **Lattice VEX engine (Evidence-Linked)** | OpenVEX, waivers, mitigations, and configs flow through deterministic lattice logic with proof-linked decisions. | Every block/allow decision is explainable, replayable, evidence-linked, and environment-specific. Explicit "Unknown" state handling ensures incomplete data never leads to false safety. | +| **Hybrid Reachability** | Static call-graph analysis + optional runtime/eBPF probes; both edge types can be attested with DSSE. | Build + runtime signals share one verdict; prioritisation spans first-party code, base images, and live telemetry. | | **Transparency log + trust credits** | Cosign/DSSE bundles push to a Rekor-compatible log; the trust-credit ledger records who accepted a risk. | Compliance teams get provenance plus accountable ownership trails. | | **Sovereign crypto profiles** | Swap in FIPS, eIDAS, GOST, SM, or PQ-ready providers without code changes. | Meets regional crypto rules while keeping attestations verifiable. | | **Offline-first operations** | Offline Kit packages the pristine feeds, plug-ins, and configs; import CLI verifies everything locally. | Air-gapped clouds get the same security posture as connected sites. | +| **VEX Propagation** | Generate vulnerability status attestations your downstream consumers can automatically trust and ingest. | Scalable VEX sharing across the supply chain—competitors export VEX formats; Stella provides a unified proof model that can be verified independently. | | **Enterprise readiness** | Transparent quotas, LDAP/AD SSO, restart-time plug-in SDK, generous free tier. | Large teams keep their workflows without surrendering control to SaaS platforms. | -## Where Stella Ops differs from incumbents +## Where Stella Ops differs from incumbents -| Vendor | Where they stop | Stella Ops difference | +| Vendor | Where they stop | Stella Ops difference | |--------|-----------------|-----------------------| -| **Trivy / Syft** | SBOM generation as a CLI add-on; policy left to other products. | SBOM + VEX are the system of record with deterministic replay and signed evidence. | -| **Snyk Container** | Static reachability bounded to first-party code. | Lattice links code, base images, cluster policies, and optional runtime probes so the entire stack shares one score. | -| **JFrog Xray** | Contextual scoring lives behind a closed service. | Policies, DSSE bundles, and transparency logs are open, auditable, and portable. | -| **Docker Scout** | Provenance remains inside Docker’s ecosystem. | Any OCI provenance is ingested, signed with your crypto profile, and replayed offline. | -| **Wiz / runtime sensors** | Runtime telemetry is separate from build-time SBOM/VEX evidence. | Optional runtime probes feed the same deterministic lattice so build- and run-time context stay consistent. | +| **Trivy / Syft** | SBOM generation as a CLI add-on; policy left to other products. | SBOM + VEX are the system of record with deterministic replay, Decision Capsules, and signed evidence. | +| **Snyk Container** | Static reachability bounded to first-party code. | Hybrid reachability links code, base images, cluster policies, and optional runtime probes so the entire stack shares one score. | +| **JFrog Xray** | Contextual scoring lives behind a closed service. | Policies, DSSE bundles, Decision Capsules, and transparency logs are open, auditable, and portable. | +| **Docker Scout** | Provenance remains inside Docker's ecosystem. | Any OCI provenance is ingested, signed with your crypto profile, and replayed offline with full evidence. | +| **Wiz / runtime sensors** | Runtime telemetry is separate from build-time SBOM/VEX evidence. | Optional runtime probes feed the same deterministic lattice so build- and run-time context stay consistent; all evidence sealed in Decision Capsules. | ## Dig Deeper (curated reading) @@ -63,4 +70,4 @@ Need more? The full documentation tree – ADRs, per‑module operations, schema > **Configuration note:** Feature exposure stays governed by `StellaOps.Scanner.WebService` (`scanner.*` / `SCANNER__*`) settings. See [modules/scanner/architecture.md](modules/scanner/architecture.md) and [modules/scanner/design/surface-env.md](modules/scanner/design/surface-env.md) for the authoritative schema; the docs remain pristine while configuration decides what surfaces for each deployment. -© 2025 Stella Ops contributors – AGPL‑3.0‑or‑later +© 2025 Stella Ops contributors – AGPL‑3.0‑or‑later diff --git a/docs/key-features.md b/docs/key-features.md index 5dc3349ed..41aa90bbf 100644 --- a/docs/key-features.md +++ b/docs/key-features.md @@ -1,41 +1,49 @@ # Key Features – Capability Cards -Each card is a fast read pairing the headline capability with the evidence that backs it and why it matters day to day. +> Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + +Each card below pairs the headline capability with the evidence that backs it and why it matters day to day. + + +## 0. Decision Capsules — Audit-Grade Evidence Bundles (2025-12) +- **What it is:** Every scan result is sealed in a **Decision Capsule**—a content-addressed bundle containing all inputs, outputs, and evidence needed to reproduce and verify the vulnerability decision. +- **Evidence:** Each capsule includes: exact SBOM (and source provenance if available), exact vuln feed snapshots (or IDs to frozen snapshots), reachability evidence (static artifacts + runtime traces if any), policy version + lattice rules, derived VEX statements, and signatures over all of the above. +- **Why it matters:** Auditors can re-run any capsule bit-for-bit to verify the outcome. This is the heart of audit-grade assurance—every decision becomes a provable, replayable fact. ## 1. Delta SBOM Engine - **What it is:** Layer-aware ingestion keeps the SBOM catalog content-addressed; rescans only fetch new layers and update dependency/vulnerability cartographs. - **Evidence:** Deterministic Replay Manifest (SRM) captures the exact analyzer inputs/outputs per layer. - **Why it matters:** Warm scans drop below one second, so CI/CD pipelines stay fast even under the free-tier quota. -## 2. Lattice Policy + OpenVEX -- **What it is:** Policy engine merges SBOM, advisories, VEX, and waivers through lattice logic that prioritises exploitability. -- **Evidence:** OpenVEX is treated as first-class input; the policy UI renders explain traces, while custom rule packs let teams automate muting, expirations, and non-VEX alert logic. -- **Why it matters:** Teams can distinguish exploitable risk from noise, tune the experience beyond VEX statements, and prove why a deployment was blocked or allowed. +## 2. Lattice Policy + OpenVEX (Evidence-Linked) +- **What it is:** Policy engine merges SBOM, advisories, VEX, and waivers through lattice logic that prioritises exploitability. Every VEX assertion includes pointers to an internal evidence graph. +- **Evidence:** OpenVEX is treated as first-class input; the policy UI renders explain traces with proof-linked decisions. Custom rule packs let teams automate muting, expirations, and non-VEX alert logic. +- **Why it matters:** Teams can distinguish exploitable risk from noise, tune the experience beyond VEX statements, and prove why a deployment was blocked or allowed. Unlike simplistic yes/no approaches, the lattice model explicitly handles an "Unknown" state, ensuring incomplete data doesn't lead to false safety. ## 3. Sovereign Crypto Profiles - **What it is:** Bring-your-own trust bundles that switch signing algorithms (FIPS, eIDAS, GOST, SM) without code changes. - **Evidence:** Crypto profiles travel with Offline Update Kits and post-quantum trust packs, keeping signatures verifiable in regulated sectors. - **Why it matters:** You meet regional crypto requirements while keeping provenance attestations consistent across tenants. -## 4. Deterministic Replay & Evidence Bundles -- **What it is:** Every scan produces a DSSE + SRM bundle that can be replayed with `stella replay`. +## 4. Deterministic Replay & Evidence Bundles — The Heart of Audit-Grade Assurance +- **What it is:** Every scan produces a DSSE + SRM bundle that can be replayed with `stella replay srm.yaml`. - **Evidence:** Replay manifests capture analyzer versions, lattice state, and attestations in content-addressed storage for audit trails. -- **Why it matters:** Auditors and incident responders can re-run a historical scan and trust the findings were not tampered with. +- **Why it matters:** A CVE found 6 months ago can be re-verified today by running `stella replay srm.yaml`, yielding an identical result—an audit trail no other scanner provides. This is why Stella decisions survive auditors, regulators, and supply-chain propagation. ## 5. Transparent Quotas & Offline Operations - **What it is:** Redis-backed counters surface `{{ quota_token }}` scans/day via headers, UI banners, and `/quota` API; Offline Update Kits mirror feeds. - **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. +## 6. Signed Reachability Proofs — Hybrid Static + Runtime Attestations +- **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. Both static call-graph edges and runtime-derived edges can be attested—true hybrid reachability. - **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. +- **Why it matters:** You can prove (or contest) exactly why a vuln is reachable, replay results offline, and avoid flooding transparency logs. Hybrid analysis combining static call-graph analysis with runtime process tracing provides confidence across build and runtime contexts. -## 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. +## 7. Competitive Moats — Four Capabilities (2025-12 refresh) +- **What it is:** Four capabilities no competitor offers together: (1) Signed Reachability, (2) Deterministic Replay, (3) Explainable Policy (Lattice VEX), (4) Sovereign + Offline Operation. Plus Decision Capsules for audit-grade evidence bundles. - **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. +- **Why it matters:** Clear differentiation guides roadmap and sales; keeps us focused on replayable, sovereign, evidence-linked, and explainable security. ## 8. Deterministic Task Packs (2025-11) - **What it is:** TaskRunner executes declarative Task Packs with plan-hash binding, approvals, sealed-mode enforcement, and DSSE evidence bundles. diff --git a/docs/marketing/decision-capsules.md b/docs/marketing/decision-capsules.md new file mode 100644 index 000000000..c4deaeb9a --- /dev/null +++ b/docs/marketing/decision-capsules.md @@ -0,0 +1,170 @@ +# Decision Capsules — Audit-Grade Evidence Bundles + +> Status: Marketing Bridge Document · December 2025 +> Audience: Technical buyers, security architects, compliance teams + + + +## Executive Summary + +Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + +**Decision Capsules** are the mechanism that makes this possible: content-addressed bundles that seal every scan result with all inputs, outputs, and evidence needed to reproduce and verify vulnerability decisions. This is the heart of audit-grade assurance—every decision becomes a provable, replayable fact. + +**Key message**: "Prove every fix, audit every finding." + +--- + +## What is a Decision Capsule? + +A Decision Capsule is a signed, immutable bundle containing: + +| Component | Description | Purpose | +|-----------|-------------|---------| +| **Exact SBOM** | The precise software bill of materials used for the scan | Reproducibility | +| **Vuln feed snapshots** | Frozen advisory data (NVD, OSV, GHSA, etc.) at scan time | Consistency | +| **Reachability evidence** | Static call-graph artifacts + runtime traces | Proof of analysis | +| **Policy version** | Lattice rules and threshold configuration | Explainability | +| **Derived VEX** | The vulnerability status decision with justification | Outcome | +| **DSSE signatures** | Cryptographic signatures over all contents | Integrity | + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Decision Capsule │ +├─────────────────────────────────────────────────────────────┤ +│ ┌─────────┐ ┌─────────────┐ ┌──────────────────┐ │ +│ │ SBOM │ │ Vuln Feeds │ │ Reachability │ │ +│ │ (exact) │ │ (snapshots) │ │ Evidence │ │ +│ └─────────┘ └─────────────┘ └──────────────────┘ │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │ +│ │ Policy Ver │ │ Derived VEX │ │ DSSE Signatures │ │ +│ │ + Lattice │ │ + Justify. │ │ (integrity) │ │ +│ └─────────────┘ └─────────────┘ └──────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Why Decision Capsules Matter + +### For Security Teams +- **Reproduce any finding**: Re-run a scan from 6 months ago with identical results +- **Trust the evidence**: Every decision has cryptographic proof +- **Explain to stakeholders**: Clear justification for every block/allow decision + +### For Compliance Teams +- **Audit-ready artifacts**: Evidence bundles meet regulatory requirements +- **Chain of custody**: Full provenance from scan to decision +- **Tamper-evident**: Any modification breaks the signature + +### For Developers +- **No "works on my machine"**: Reproducible results across environments +- **Fast debugging**: Trace exactly why a vulnerability was flagged +- **CI/CD integration**: Capsules fit into existing pipelines + +--- + +## Competitive Differentiation + +| Capability | Stella Ops | Competitors | +|------------|------------|-------------| +| **Sealed evidence** | Decision Capsules with DSSE signatures | Scan reports (mutable) | +| **Reproducibility** | Bit-for-bit replay from frozen feeds | "Re-scan" with current data | +| **Evidence linking** | Every VEX decision has proof pointers | VEX statements without proof | +| **Offline verification** | Full verification without network | Requires SaaS connection | + +**Battlecard one-liner**: "Prove every fix, audit every finding—Decision Capsules seal evidence so you can replay scans bit-for-bit." + +--- + +## Technical Details + +### Capsule Format + +```yaml +apiVersion: capsule.stellaops.dev/v1 +metadata: + id: "cap-2025-12-11-abc123" + timestamp: "2025-12-11T14:30:00Z" + scan_id: "scan-xyz789" +inputs: + sbom: + format: "cyclonedx@1.6" + digest: "sha256:..." + feeds: + - name: "nvd" + snapshot: "2025-12-11" + digest: "sha256:..." + - name: "osv" + snapshot: "2025-12-11" + digest: "sha256:..." + policy: + version: "corp-policy@2025-12-01" + digest: "sha256:..." + reachability: + graph_hash: "blake3:..." + edge_bundles: ["bundle:001", "bundle:002"] +outputs: + vex: + format: "openvex" + digest: "sha256:..." + findings: + digest: "sha256:..." +signatures: + - scheme: "DSSE" + profile: "FIPS-140-3" + signer: "build-ca@corp" +``` + +### CLI Commands + +```bash +# Create a capsule during scan +stella scan --image reg/app@sha256:... --capsule-out capsule.yaml + +# Replay a capsule +stella replay capsule.yaml --assert-digest sha256:... + +# Verify capsule integrity +stella capsule verify capsule.yaml + +# Extract evidence for audit +stella capsule export capsule.yaml --format audit-bundle +``` + +--- + +## Integration with Four Capabilities + +Decision Capsules connect all four capabilities: + +1. **Signed Reachability** → Reachability evidence sealed in capsule +2. **Deterministic Replay** → Capsule enables bit-for-bit replay +3. **Explainable Policy** → Policy version + derived VEX in capsule +4. **Sovereign Offline** → Capsule verifiable without network + +--- + +## Customer Scenarios + +### Scenario 1: Regulatory Audit +"Show me the evidence for this CVE decision from 6 months ago." +→ Replay the Decision Capsule, get identical results, provide the signed evidence bundle. + +### Scenario 2: Incident Response +"This vulnerability was marked not_affected—prove it." +→ Extract the reachability evidence from the capsule showing the vulnerable code path is not reachable. + +### Scenario 3: Supply Chain Attestation +"Provide proof that this image was scanned and passed policy." +→ Share the Decision Capsule; downstream consumers can verify the signature independently. + +--- + +## Related Documentation + +- `docs/key-features.md` — Feature overview +- `docs/03_VISION.md` — Product vision and moats +- `docs/reachability/lattice.md` — Reachability scoring +- `docs/vex/consensus-overview.md` — VEX consensus engine diff --git a/docs/marketing/evidence-linked-vex.md b/docs/marketing/evidence-linked-vex.md new file mode 100644 index 000000000..9caaec192 --- /dev/null +++ b/docs/marketing/evidence-linked-vex.md @@ -0,0 +1,228 @@ +# Evidence-Linked VEX — Proof-Backed Vulnerability Decisions + +> Status: Marketing Bridge Document · December 2025 +> Audience: Technical buyers, security architects, compliance teams + + + +## Executive Summary + +Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + +**Evidence-Linked VEX** is how those decisions are structured: every vulnerability status assertion includes pointers to the underlying proof. Unlike traditional VEX that simply states "not_affected" without explanation, Stella Ops provides a complete evidence graph connecting the decision to its inputs. + +**Key message**: "VEX you can prove." + +--- + +## What is Evidence-Linked VEX? + +Every VEX decision in Stella Ops links to an **evidence graph** containing: + +| Evidence Type | Description | Link Format | +|---------------|-------------|-------------| +| **SBOM match** | Component identity confirmation | `sbom_hash`, `purl` | +| **Vuln snapshot** | Exact advisory data at decision time | `advisory_snapshot_id` | +| **Reachability proof** | Static/runtime analysis artifacts | `reach_decision_id`, `graph_hash` | +| **Runtime observation** | Process traces, method hits | `runtime_trace_id` | +| **Mitigation evidence** | WAF rules, config flags, patches | `mitigation_id` | + +``` +┌────────────────────────────────────────────────────────────┐ +│ VEX Decision: NOT_AFFECTED │ +├────────────────────────────────────────────────────────────┤ +│ │ +│ "CVE-2025-1234 does not affect pkg:nuget/Example@1.2.3" │ +│ │ +│ Evidence Graph: │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ SBOM Match │───▶│ Vuln Record │───▶│ Reach Proof │ │ +│ │ sha256:abc │ │ nvd-snap-01 │ │ graph:xyz │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ Runtime Obs │ │ +│ │ trace:456 │ │ +│ └─────────────┘ │ +└────────────────────────────────────────────────────────────┘ +``` + +--- + +## Why Evidence-Linked VEX Matters + +### The Problem with Traditional VEX + +Traditional VEX statements are **assertions without proof**: + +```json +{ + "vulnerability": "CVE-2025-1234", + "status": "not_affected", + "justification": "vulnerable_code_not_present" +} +``` + +Questions this doesn't answer: +- How do you know the vulnerable code isn't present? +- What analysis was performed? +- Can this decision be independently verified? +- What happens when the advisory changes? + +### The Evidence-Linked Solution + +Stella Ops VEX includes **proof pointers**: + +```json +{ + "vulnerability": "CVE-2025-1234", + "status": "not_affected", + "justification": "vulnerable_code_not_present", + "evidence_refs": { + "sbom": "sha256:abc123...", + "advisory_snapshot": "nvd-2025-12-01", + "reachability": { + "decision_id": "reach:xyz789", + "graph_hash": "blake3:...", + "score": 22, + "state": "POSSIBLE" + }, + "mitigations": ["mit:waf-rule-123"] + }, + "replay_bundle": "capsule:2025-12-11-abc" +} +``` + +This enables: +- **Independent verification**: Anyone can follow the proof chain +- **Deterministic replay**: Re-run the exact analysis +- **Audit compliance**: Evidence meets regulatory requirements + +--- + +## Explicit "Unknown" State Handling + +A key differentiator: Stella Ops explicitly handles **incomplete data**. + +| Traditional Approach | Stella Ops Approach | +|---------------------|---------------------| +| Binary: affected/not_affected | Three states: affected/not_affected/under_investigation | +| Missing data → assume safe | Missing data → mark "Unknown" | +| False negatives possible | Incomplete data surfaced explicitly | + +**Why this matters**: Incomplete data never leads to false safety. If reachability analysis is inconclusive, the decision stays `under_investigation` until sufficient evidence is gathered. + +--- + +## Competitive Differentiation + +| Capability | Stella Ops | Competitors | +|------------|------------|-------------| +| **VEX output** | Evidence-linked with proof graph | Simple VEX statements | +| **Verification** | Independent proof chain verification | Trust the vendor | +| **Unknown handling** | Explicit `under_investigation` state | Binary yes/no | +| **Replay** | Bit-for-bit from Decision Capsules | Not possible | + +**Battlecard one-liner**: "Competitors export VEX formats; Stella provides VEX you can prove." + +--- + +## Evidence Graph Structure + +### Full Evidence Chain + +``` +Component (PURL) + │ + ├──▶ SBOM Document + │ └── digest: sha256:... + │ + ├──▶ Vulnerability Record + │ ├── source: NVD + │ ├── snapshot_id: nvd-2025-12-01 + │ └── digest: sha256:... + │ + ├──▶ Reachability Analysis + │ ├── static_graph: blake3:... + │ ├── runtime_traces: [trace:001, trace:002] + │ ├── score: 22 (POSSIBLE) + │ └── evidence: [edge:abc, edge:def] + │ + ├──▶ Mitigations + │ ├── waf_rule: rule:xyz + │ └── config_flag: flag:disabled + │ + └──▶ Policy Decision + ├── version: corp-policy@2025-12-01 + ├── digest: sha256:... + └── threshold: score < 25 → not_affected +``` + +### Evidence Types + +| Evidence Kind | Confidence Impact | Source | +|---------------|-------------------|--------| +| `StaticCallEdge` | +30 base score | IL/bytecode analysis | +| `RuntimeMethodHit` | +60 base score | EventPipe/JFR | +| `UserInputSource` | +80 base score | Taint analysis | +| `WafRulePresent` | -20 mitigation | WAF connector | +| `PatchLevel` | -40 mitigation | Patch diff | + +--- + +## VEX Propagation + +Evidence-Linked VEX enables **scalable supply chain sharing**: + +1. **Generate**: Create evidence-linked VEX from scan results +2. **Sign**: Apply DSSE signatures with your trust root +3. **Share**: Propagate to downstream consumers +4. **Verify**: Consumers verify independently using proof pointers + +```bash +# Generate evidence-linked VEX +stella vex generate --scan scan-123 --format openvex --include-evidence + +# Export for downstream +stella vex export --decisions "decision:abc123" --bundle evidence-bundle.tar + +# Downstream verification +stella vex verify evidence-bundle.tar --trust-root downstream-ca +``` + +--- + +## Integration with Four Capabilities + +Evidence-Linked VEX connects to the four capabilities: + +1. **Signed Reachability** → Reachability proof in evidence graph +2. **Deterministic Replay** → Evidence reproducible via Decision Capsules +3. **Explainable Policy** → Policy version and thresholds traced +4. **Sovereign Offline** → Evidence verifiable without network + +--- + +## Customer Scenarios + +### Scenario 1: Vendor VEX Verification +"The vendor says this CVE doesn't affect us—can we trust it?" +→ Check their evidence graph; verify the reachability analysis matches your deployment. + +### Scenario 2: Compliance Audit +"Prove this CVE was properly analyzed." +→ Show the evidence chain from SBOM → advisory → reachability → decision. + +### Scenario 3: Supply Chain Propagation +"Pass our VEX decisions to downstream consumers." +→ Export evidence-linked VEX; consumers can independently verify. + +--- + +## Related Documentation + +- `docs/vex/consensus-overview.md` — VEX consensus engine +- `docs/reachability/lattice.md` — Reachability scoring model +- `docs/marketing/decision-capsules.md` — Decision Capsules overview +- `docs/marketing/hybrid-reachability.md` — Hybrid analysis diff --git a/docs/marketing/hybrid-reachability.md b/docs/marketing/hybrid-reachability.md new file mode 100644 index 000000000..2d567a9e1 --- /dev/null +++ b/docs/marketing/hybrid-reachability.md @@ -0,0 +1,239 @@ +# Hybrid Reachability — Static + Runtime Analysis + +> Status: Marketing Bridge Document · December 2025 +> Audience: Technical buyers, security architects, compliance teams + + + +## Executive Summary + +Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + +**Hybrid Reachability** is how we achieve accurate impact analysis: combining static call-graph analysis with runtime process tracing to determine whether vulnerable code is actually reachable. Both edge types are separately attestable with DSSE signatures, providing true hybrid analysis with cryptographic proof. + +**Key message**: "True hybrid reachability—static and runtime signals share one verdict." + +--- + +## What is Hybrid Reachability? + +Traditional reachability analysis uses either: +- **Static analysis**: Examines code without executing it (call graphs, data flow) +- **Runtime analysis**: Observes actual execution (method hits, stack traces) + +Stella Ops uses **both** and reconciles them into a unified reachability decision: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Hybrid Reachability │ +├────────────────────────┬────────────────────────────────────┤ +│ Static Analysis │ Runtime Analysis │ +├────────────────────────┼────────────────────────────────────┤ +│ • IL/bytecode walkers │ • .NET EventPipe │ +│ • ASP.NET routing │ • JVM JFR │ +│ • Call-graph edges │ • Node inspector │ +│ • Entry-point prox. │ • Go/Rust probes │ +├────────────────────────┴────────────────────────────────────┤ +│ │ +│ Lattice Engine │ +│ ┌─────────────────────────────────────┐ │ +│ │ Merge signals → Score → VEX status │ │ +│ └─────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────┐ │ +│ │ DSSE Attestation (Graph + Edges) │ │ +│ └─────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Why Hybrid Matters + +### Limitations of Static-Only Analysis + +| Issue | Description | Impact | +|-------|-------------|--------| +| **Over-reporting** | Reports paths that never execute | Alert fatigue | +| **Dynamic dispatch** | Misses reflection, DI, runtime binding | False negatives | +| **Framework magic** | ASP.NET/Spring routing not fully modeled | Incomplete coverage | +| **Configuration** | Doesn't account for runtime config | Context-blind | + +### Limitations of Runtime-Only Analysis + +| Issue | Description | Impact | +|-------|-------------|--------| +| **Coverage gaps** | Only sees executed paths | Misses rare paths | +| **Environment-specific** | Results vary by test coverage | Non-deterministic | +| **No proactive detection** | Requires traffic to observe | Reactive, not preventive | +| **Attack surface** | May miss dormant vulnerabilities | Security risk | + +### Hybrid Solution + +| Signal Type | Strength | Weakness | Hybrid Benefit | +|-------------|----------|----------|----------------| +| Static | Comprehensive coverage | Over-reports | Runtime filters false positives | +| Runtime | Ground truth | Incomplete | Static catches unexercised paths | + +**Result**: Higher confidence with lower false positive/negative rates. + +--- + +## Reachability Lattice + +Stella Ops uses a **confidence lattice** with explicit states: + +``` +UNOBSERVED (0–9) + < POSSIBLE (10–29) + < STATIC_PATH (30–59) + < DYNAMIC_SEEN (60–79) + < DYNAMIC_USER_TAINTED (80–99) + < EXPLOIT_CONSTRAINTS_REMOVED (100) +``` + +| State | Evidence Required | VEX Mapping | +|-------|-------------------|-------------| +| UNOBSERVED | None | under_investigation | +| POSSIBLE | Lockfile-only | under_investigation | +| STATIC_PATH | Static call-graph edge | under_investigation | +| DYNAMIC_SEEN | Runtime method hit | affected | +| DYNAMIC_USER_TAINTED | User input reaches vuln | affected | +| EXPLOIT_CONSTRAINTS_REMOVED | Full exploit chain | affected | + +**Key feature**: The `under_investigation` state explicitly handles incomplete data—Stella never marks something "safe" without sufficient evidence. + +--- + +## Attestation Model + +Both static and runtime edges are attestable: + +### Graph-Level Attestation (Required) + +```yaml +level: 0 +payload: richgraph-v1 +signature: DSSE +storage: cas://reachability/graphs/{blake3} +rekor: always +``` + +### Edge-Bundle Attestation (Selective) + +```yaml +level: 1 +payload: edge-bundle (≤512 edges) +criteria: + - source: runtime + - source: init_array/constructors + - status: contested/quarantined +signature: DSSE +storage: cas://reachability/edges/{graph_hash}/{bundle_id} +rekor: configurable +``` + +This enables: +- **Prove specific paths**: Attest individual runtime-observed edges +- **Dispute resolution**: Quarantine/revoke specific edges +- **Offline verification**: Verify without network access + +--- + +## Competitive Differentiation + +| Capability | Stella Ops | Competitors | +|------------|------------|-------------| +| **Analysis type** | Hybrid (static + runtime) | Usually one or the other | +| **Attestation** | DSSE for both edge types | None or graph-only | +| **Unknown handling** | Explicit `under_investigation` | Binary yes/no | +| **Edge-level proof** | Selective edge-bundle DSSE | Not available | + +**Battlecard one-liner**: "Static analysis sees code paths; runtime sees execution. Stella sees both—and proves it." + +--- + +## Signal Sources + +### Static Analysis Signals + +| Signal | Source | Evidence Kind | +|--------|--------|---------------| +| Call-graph edges | Roslyn/IL walkers | `StaticCallEdge` | +| Entry-point proximity | Framework routing models | `StaticEntryPointProximity` | +| Package declarations | Lockfile/manifest | `StaticPackageDeclaredOnly` | + +### Runtime Analysis Signals + +| Signal | Source | Evidence Kind | +|--------|--------|---------------| +| Method hits | .NET EventPipe | `RuntimeMethodHit` | +| Stack samples | JVM JFR | `RuntimeStackSample` | +| HTTP routes | ASP.NET/Spring routing | `RuntimeHttpRouteHit` | +| User input | Taint analysis | `UserInputSource` | + +### Mitigation Signals + +| Signal | Source | Effect | +|--------|--------|--------| +| WAF rules | WAF connectors | Score reduction | +| Config flags | Config snapshot | Score reduction | +| Network isolation | Container policy | Score reduction | + +--- + +## Integration with Four Capabilities + +Hybrid Reachability is **Capability #1** of four: + +1. **Signed Reachability** ← This document +2. **Deterministic Replay** → Reachability evidence in Decision Capsules +3. **Explainable Policy** → Reachability feeds the lattice VEX engine +4. **Sovereign Offline** → All analysis verifiable without network + +--- + +## Customer Scenarios + +### Scenario 1: False Positive Reduction +"We're drowning in vulnerability alerts." +→ Hybrid analysis shows 70% of reported CVEs have no reachable path; focus on the 30% that matter. + +### Scenario 2: Runtime Validation +"Static analysis says this is reachable—is it really?" +→ Runtime probes observed 0 hits over 30 days; downgrade to `under_investigation`. + +### Scenario 3: Audit Proof +"Prove the vulnerable code path is not reachable." +→ Show the signed reachability graph with static call-graph (no path) + runtime traces (no hits). + +### Scenario 4: Contested Edge +"We disagree with this reachability finding." +→ Mark the edge as disputed; policy excludes it; recompute reachability; surface the delta. + +--- + +## CLI Integration + +```bash +# Scan with hybrid reachability +stella scan --image reg/app@sha256:... --reachability hybrid + +# Verify reachability graph +stella graph verify --graph blake3:abc123 + +# Show reachability decision for a CVE +stella reach show --cve CVE-2025-1234 --component pkg:nuget/Example@1.2.3 + +# Export edge bundles for audit +stella reach export --graph blake3:abc123 --bundles-only +``` + +--- + +## Related Documentation + +- `docs/reachability/hybrid-attestation.md` — Attestation technical details +- `docs/reachability/lattice.md` — Scoring model +- `docs/marketing/decision-capsules.md` — Decision Capsules overview +- `docs/marketing/evidence-linked-vex.md` — Evidence-linked VEX diff --git a/docs/moat.md b/docs/moat.md index e810b8c26..c07353c39 100644 --- a/docs/moat.md +++ b/docs/moat.md @@ -1,13 +1,23 @@ -# StellaOps Moat Track — Spec Outline v0.3 +# StellaOps Moat Track — Spec Outline v0.4 + +> Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + + +**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. Decision Capsules seal all evidence for audit-grade reproducibility. +3. **Explainable Policy (Lattice VEX)** – The lattice engine merges SBOM data, advisories, VEX statements, and waivers into a single verdict with human-readable justifications. Evidence-linked VEX decisions with explicit "Unknown" state handling. +4. **Sovereign + Offline Operation** – FIPS, eIDAS, GOST, SM, or PQC profiles are first-class toggles. Offline Kits and regional crypto profiles keep every decision inside your perimeter. **Scope of this doc:** -(1) Deterministic Replayable Scans (SRM), (2) Policy Engine & Lattice UI, (3) Sovereign Readiness (CryptoProfile + RootPack), (4) Attestation Observability Graph (AOG), (5) Procurement‑Grade Trust Statement, (6) Third‑Party Proof Channel, (7) Zastava differential SBOM + AI scheduler. +(1) Decision Capsules, (2) Deterministic Replayable Scans (SRM), (3) Policy Engine & Lattice UI, (4) Sovereign Readiness (CryptoProfile + RootPack), (5) Attestation Observability Graph (AOG), (6) Procurement‑Grade Trust Statement, (7) Third‑Party Proof Channel, (8) Zastava differential SBOM + AI scheduler. Cross‑cutting principles: offline‑first, cryptographic determinism, evidence‑bound decisions, regional crypto compliance, minimal operational friction. --- -## 0) Shared Concepts (applies to all 7) +## 0) Shared Concepts (applies to all 8) * **Artifact identity:** digest-first (OCI image digest, file sha256). * **Canonicalization:** all structured payloads (SBOM, SRM, Trust Statement JSON, VEX) are normalized via Canonical JSON (RFC‑8785‑like) prior to hashing/signing. diff --git a/docs/reachability/hybrid-attestation.md b/docs/reachability/hybrid-attestation.md index fa39cbca4..b154695f9 100644 --- a/docs/reachability/hybrid-attestation.md +++ b/docs/reachability/hybrid-attestation.md @@ -1,10 +1,25 @@ # Hybrid Reachability Attestation (Graph + Edge-Bundle) -> Decision date: 2025-11-23 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild +> Decision date: 2025-12-11 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild + + +## 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** @@ -24,6 +39,7 @@ - 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). @@ -35,7 +51,7 @@ - **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. + - 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. @@ -43,13 +59,32 @@ - **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. Open decisions (tracked in Sprint 0401 tasks 53–56) +## 7. 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. diff --git a/docs/reachability/lattice.md b/docs/reachability/lattice.md index 549cc2244..3db57adf9 100644 --- a/docs/reachability/lattice.md +++ b/docs/reachability/lattice.md @@ -1,15 +1,20 @@ # Reachability Lattice & Scoring Model -> **Status:** Draft – mirrors the November 2025 advisory on confidence-based reachability. +> **Status:** Draft – mirrors the December 2025 advisory on confidence-based reachability. > **Owners:** Scanner Guild · Policy Guild · Signals Guild. +> Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + This document defines the confidence lattice, evidence types, mitigation scoring, and policy gates used to turn static/runtime signals into reproducible reachability decisions and VEX statuses. --- ## 1. Overview -Classic “reachable: true/false” answers are too brittle. Stella Ops models reachability as an **ordered lattice** with explicit states and scores. Each analyzer/runtime probe emits `Evidence` documents; mitigations add `Mitigation` entries. The lattice engine joins both inputs into a `ReachDecision`: + +**Key differentiator:** Unlike simplistic yes/no reachability approaches, the Stella Ops lattice model explicitly handles an **"Unknown"** (under_investigation) state, ensuring incomplete data doesn't lead to false safety. Every VEX decision is evidence-linked with proof pointers to the underlying reachability evidence. + +Classic "reachable: true/false" answers are too brittle. Stella Ops models reachability as an **ordered lattice** with explicit states and scores. Each analyzer/runtime probe emits `Evidence` documents; mitigations add `Mitigation` entries. The lattice engine joins both inputs into a `ReachDecision`: ``` UNOBSERVED (0–9) @@ -75,10 +80,10 @@ public sealed record ReachDecision( | Evidence class | Base score contribution | |--------------------------|-------------------------| -| Static path (call graph) | ≥ 30 | -| Runtime hit | ≥ 60 | -| User-tainted flow | ≥ 80 | -| “Constraints removed” | = 100 | +| Static path (call graph) | ≥ 30 | +| Runtime hit | ≥ 60 | +| User-tainted flow | ≥ 80 | +| "Constraints removed" | = 100 | | Lockfile-only evidence | 10 (if no other signals)| Mitigations subtract up to 40 points (configurable): @@ -106,11 +111,11 @@ Default thresholds (edit in `reachability.policy.yml`): VEX mapping: -* **not_affected**: score ≤ 25 or mitigations dominate (score reduced below threshold). -* **affected**: score ≥ 60 (dynamic evidence without sufficient mitigation). -* **under_investigation**: everything between. +* **not_affected**: score ≤ 25 or mitigations dominate (score reduced below threshold). +* **affected**: score ≥ 60 (dynamic evidence without sufficient mitigation). +* **under_investigation**: everything between. **This explicit "Unknown" state is a key differentiator**—incomplete data never leads to false safety. -Each decision records `reachability.policy.version`, analyzer versions, policy hash, and config snapshot so downstream verifiers can replay the exact logic. +Each decision records `reachability.policy.version`, analyzer versions, policy hash, and config snapshot so downstream verifiers can replay the exact logic. All decisions are sealed in Decision Capsules for audit-grade reproducibility. --- @@ -125,7 +130,7 @@ Each decision records `reachability.policy.version`, analyzer versions, policy h | Mitigations | WAF connectors, patch diff, kill switches | `MitigationKind.*` via `Mitigation` records | | Trust | Vendor VEX statements, manual overrides | `VendorVexNotAffected/Affected`, `ManualOverride` | -Each evidence object **must** log `Source`, timestamps, and references (function IDs, config hashes) so auditors can trace it in the event graph. +Each evidence object **must** log `Source`, timestamps, and references (function IDs, config hashes) so auditors can trace it in the event graph. This enables **evidence-linked VEX decisions** where every assertion includes pointers to the underlying proof. --- @@ -185,7 +190,20 @@ See `src/Scanner/StellaOps.Scanner.WebService/Reachability/Runtime/DotNetRuntime --- -## 9. Roadmap +## 9. Hybrid Reachability + + +Stella Ops combines **static call-graph analysis** with **runtime process tracing** for true hybrid reachability: + +- **Static analysis** provides call-graph edges from IL/bytecode analysis, framework routing models, and entry-point proximity calculations. +- **Runtime analysis** provides observed method hits, stack samples, and HTTP route hits from live or shadow traffic. +- **Hybrid reconciliation** merges both signal types, with each edge type attestable via DSSE. See `docs/reachability/hybrid-attestation.md` for the attestation model. + +This hybrid approach ensures that both build-time and run-time context contribute to the same verdict, avoiding the blind spots of purely static or purely runtime analysis. + +--- + +## 10. Roadmap | Task | Description | |------|-------------| @@ -195,4 +213,3 @@ See `src/Scanner/StellaOps.Scanner.WebService/Reachability/Runtime/DotNetRuntime | `REACH-POLICY-402-026` | Expose reachability gates in Policy DSL & CLI (edit/lint/test). | Keep this doc updated as the lattice evolves or new signals/mitigations are added. -*** End Patch diff --git a/docs/vex/consensus-overview.md b/docs/vex/consensus-overview.md index 3909d2f55..6b46686fb 100644 --- a/docs/vex/consensus-overview.md +++ b/docs/vex/consensus-overview.md @@ -1,15 +1,203 @@ -# VEX Consensus Overview — Draft Skeleton (2025-12-05 UTC) +# VEX Consensus Overview — Evidence-Linked Decisions -Status: draft placeholder. Inputs pending: PLVL0102 schema snapshot, issuer directory details. +> Status: Updated 2025-12-11 · Owners: Policy Guild, Scanner Guild, Signals Guild + +> Stella Ops isn't just another scanner—it's a different product category: **deterministic, evidence-linked vulnerability decisions** that survive auditors, regulators, and supply-chain propagation. + + + +## Context: Four Capabilities + +The VEX Consensus Engine supports **Explainable Policy (Lattice VEX)**—one of four capabilities no competitor offers together: + +1. **Signed Reachability** – Every reachability graph is sealed with DSSE. +2. **Deterministic Replay** – Scans run bit-for-bit identical from frozen feeds. +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. + +All decisions are sealed in **Decision Capsules** for audit-grade reproducibility. + +--- ## Purpose -- Explain why consensus exists and what assurances it provides (AOC scope). + +The VEX Consensus Engine merges multiple evidence sources into a single, reproducible vulnerability status for each component-vulnerability pair. Unlike simple VEX aggregation that picks the "most authoritative" statement, Stella Ops applies **lattice logic** to combine all inputs deterministically. + +**Key differentiators:** +- **Evidence-linked decisions**: Every VEX assertion includes pointers to the underlying proof +- **Explicit "Unknown" state**: Incomplete data is surfaced as `under_investigation`, never as false safety +- **Deterministic consensus**: Given the same inputs, the engine produces identical outputs +- **Human-readable justifications**: Every decision comes with an explainable trace + +--- ## Inputs -- Evidence sources (attestations, SBOM edges) — to be confirmed. + +The consensus engine ingests evidence from multiple sources: + +| Source Type | Description | Evidence Link | +|-------------|-------------|---------------| +| **SBOM data** | Component identities (PURLs), dependency relationships, layer provenance | `sbom_hash`, `layer_digest` | +| **Advisory feeds** | OSV, GHSA, NVD, CNVD, CNNVD, ENISA, JVN, BDU, vendor feeds | `advisory_snapshot_id`, `feed_hash` | +| **Reachability evidence** | Static call-graph analysis, runtime traces, entry-point proximity | `reach_decision_id`, `graph_hash` | +| **VEX statements** | Vendor VEX, internal VEX, third-party VEX | `vex_statement_id`, `issuer_id` | +| **Waivers/Mitigations** | Temporary exceptions, compensating controls | `waiver_id`, `mitigation_id` | +| **Policy rules** | Lattice configuration, threshold settings | `policy_version`, `policy_hash` | + +Each input is content-addressed and timestamped, enabling full traceability. + +--- + +## Lattice Logic + +The consensus engine applies a **partial order** over vulnerability states: + +``` +UNKNOWN (under_investigation) + < NOT_AFFECTED + < AFFECTED + < FIXED +``` + +Cross-product with confidence levels: +- **High confidence**: Strong evidence from multiple sources +- **Medium confidence**: Partial evidence or single authoritative source +- **Low confidence**: Weak evidence, pending investigation + +**Merge semantics:** +- Monotonic joins: states can only progress "up" the lattice +- Conflict resolution: prioritized by source trust level and evidence strength +- "Unknown" preserved: if any critical input is missing, the decision stays `under_investigation` + +See `docs/reachability/lattice.md` for the full scoring model. + +--- ## Outputs -- Decision artifacts; confidence/threshold handling. + +### Decision Artifact + +Each consensus decision produces: + +```json +{ + "vulnerability": "CVE-2025-1234", + "component": "pkg:nuget/Example@1.2.3", + "status": "not_affected|under_investigation|affected|fixed", + "confidence": "high|medium|low", + "justification": "component_not_present|vulnerable_code_not_present|inline_mitigations_already_exist|...", + "evidence_refs": { + "sbom": "sha256:...", + "advisory_snapshot": "nvd-2025-12-01", + "reachability": "reach:abc123", + "vex_statements": ["vex:vendor-redhat-001", "vex:internal-002"], + "mitigations": ["mit:waf-rule-xyz"] + }, + "policy_version": "corp-policy@2025-12-01", + "policy_hash": "sha256:...", + "timestamp": "2025-12-11T00:00:00Z", + "status_notes": "Reachability score 22 (Possible) with WAF rule mitigation.", + "action_statement": "Monitor config ABC", + "impact_statement": "Runtime probes observed 0 hits; static call graph absent." +} +``` + +### Evidence Graph + +Every decision artifact links to an **evidence graph** containing: +- SBOM component hash / PURL match +- Vulnerability record snapshot ID +- Reachability proof artifact (if applicable) +- Runtime observation proof (if available) +- Mitigation evidence + +This enables **proof-linked VEX**—auditors can trace any decision back to its inputs. + +--- + +## Decision Capsules Integration + +Consensus decisions are sealed into **Decision Capsules** along with: +- Exact SBOM used +- Exact vuln feed snapshots +- Reachability evidence (static + runtime) +- Policy version + lattice rules +- Derived VEX statements +- DSSE signatures over all of the above + +Capsules enable: +- Bit-for-bit replay: `stella replay capsule.yaml` +- Offline verification: No network required +- Audit-grade evidence: Every decision is provable + +--- + +## Threshold and Confidence Handling + +| Confidence Level | Criteria | Default Action | +|------------------|----------|----------------| +| High | Multiple corroborating sources, strong reachability evidence | Auto-apply decision | +| Medium | Single authoritative source or partial reachability evidence | Apply with advisory flag | +| Low | Weak evidence, conflicting sources | Mark `under_investigation` | + +Policy rules can override these defaults per environment. + +--- + +## VEX Propagation + +Once consensus is reached, Stella Ops can generate **downstream VEX statements** for consumers: + +- **OpenVEX format**: Standard VEX for interoperability +- **CSAF VEX**: For CSAF-compliant ecosystems +- **Custom formats**: Via export templates + +Downstream consumers can automatically trust and ingest these VEX statements because they include: +- Proof pointers to the evidence graph +- Signatures from trusted issuers +- Replay bundle references + +**Key differentiator**: Competitors export VEX formats; Stella provides a unified proof model that can be verified independently. + +--- + +## API Integration + +```bash +# Evaluate consensus for a component-vuln pair +POST /v1/vex/consensus/evaluate +{ + "component": "pkg:nuget/Example@1.2.3", + "vulnerabilities": ["CVE-2025-1234"], + "policy": "corp-policy@2025-12-01" +} + +# Get consensus decision with evidence +GET /v1/vex/consensus/{decision_id}?include_evidence=true + +# Export VEX for downstream propagation +POST /v1/vex/export +{ + "format": "openvex|csaf", + "decisions": ["decision:abc123"] +} +``` + +--- ## Open TODOs -- Fill concrete schema references and examples once PLVL0102 arrives. + +- [ ] PLVL0102 schema integration (pending schema finalization) +- [ ] Issuer directory details for third-party VEX sources +- [ ] CSAF VEX export template +- [ ] CLI commands for consensus querying + +--- + +## Related Documentation + +- `docs/reachability/lattice.md` — Reachability scoring model +- `docs/vex/consensus-algorithm.md` — Algorithm details +- `docs/vex/consensus-api.md` — API reference +- `docs/vex/aggregation.md` — VEX aggregation rules +- `docs/vex/issuer-directory.md` — Trusted VEX issuers