stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

save progress

Browse Source
This commit is contained in:
StellaOps Bot
2026-01-03 12:41:57 +02:00
parent 83c37243e0
commit d486d41a48
48 changed files with 7174 additions and 1086 deletions
Download Patch File Download Diff File Expand all files Collapse all files

353
docs/key-features.md
View File

@@ -1,93 +1,302 @@
# Key Features – Capability Cards
> 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.
> **Core Thesis:** Stella Ops isn't a scanner that outputs findings. It's a platform that outputs **attestable decisions that can be replayed**. That difference survives auditors, regulators, and supply-chain propagation.
---
## At a Glance
| What Competitors Do | What Stella Ops Does |
|--------------------|---------------------|
| Output findings | Output decisions with proof chains |
| VEX as suppression file | VEX as logical claim system (K4 lattice) |
| Reachability as badge | Reachability as signed proof |
| "+3 CVEs" reports | "Exploitability dropped 41%" semantic deltas |
| Hide unknowns | Surface and score unknowns |
| Online-first | Offline-first with full parity |
---
Each card below pairs the headline capability with the evidence that backs it and why it matters day to day.
<!-- TODO: Review for separate approval - added Decision Capsules as feature 0 -->
## 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.
- **UX surface:** Vulnerability triage is built around VEX-first decisions and one-click immutable audit bundles; see `docs/ux/TRIAGE_UX_GUIDE.md`.
- **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.
## 0. Decision Capsules — Audit-Grade Evidence Bundles
**The core moat capability.** Every scan result is sealed in a **Decision Capsule**—a content-addressed bundle containing everything needed to reproduce and verify the vulnerability decision.
| Component | What's Included |
|-----------|----------------|
| **Inputs** | Exact SBOM, frozen feed snapshots (with Merkle roots), policy version, lattice rules |
| **Evidence** | Reachability proofs (static + runtime), VEX statements, binary fingerprints |
| **Outputs** | Verdicts, risk scores, remediation paths |
| **Signatures** | DSSE envelopes over all of the above |
**Why it matters:** Six months from now, an auditor can run `stella replay srm.yaml --assert-digest <sha>` and get *identical* results. This is what "audit-grade assurance" actually means.
**No competitor offers this.** Trivy, Grype, Snyk—none can replay a past scan bit-for-bit because they don't freeze feeds or produce deterministic manifests.
## 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 (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.
**Performance without sacrificing determinism.** Layer-aware ingestion keeps the SBOM catalog content-addressed; rescans only fetch new layers.
- **Speed:** Warm scans < 1 second; CI/CD pipelines stay fast
- **Determinism:** Replay Manifest (SRM) captures exact analyzer inputs/outputs per layer
- **Evidence:** Binary crosswalk via Build-ID mapping; `bin:{sha256}` fallbacks for stripped binaries
**Modules:** `Scanner`, `SbomService`, `BinaryIndex`
---
## 2. Lattice Policy + OpenVEX (K4 Logic)
**VEX as a logical claim system, not a suppression file.** The policy engine uses **Belnap K4 four-valued logic** (Unknown, True, False, Conflict) to merge SBOM, advisories, VEX, and waivers.
| What Competitors Do | What Stella Does |
|--------------------|------------------|
| VEX filters findings (boolean) | VEX is logical claims with trust weighting |
| Conflicts hidden | Conflicts are explicit state (⊤) |
| "Vendor says not_affected" = done | Vendor + runtime + reachability merged; conflicts surfaced |
| Unknown = assume safe | Unknown = first-class state with risk implications |
**Why it matters:** When vendor says "not_affected" but your runtime shows the function was called, you have a *conflict*—not a false positive. The lattice preserves this for policy resolution.
**Modules:** `VexLens`, `TrustLatticeEngine`, `Excititor` (110+ tests passing)
---
## 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 — 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:** 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.
**Regional compliance without code changes.** FIPS, eIDAS, GOST, SM, and PQC (post-quantum) profiles are configuration toggles, not recompiles.
## 5. Transparent Quotas & Offline Operations
- **What it is:** Valkey-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.
- **Platform Service aggregation:** The Console UI consumes health, quotas, onboarding, preferences, and search via the Platform Service aggregator (`docs/modules/platform/platform-service.md`) instead of fanning out to every module.
- **Why it matters:** You stay within predictable limits, avoid surprise throttling, and operate entirely offline when needed.
| Profile | Algorithms | Use Case |
|---------|-----------|----------|
| **FIPS-140-3** | ECDSA P-256, RSA-PSS | US federal requirements |
| **eIDAS** | ETSI TS 119 312 | EU qualified signatures |
| **GOST-2012** | GOST R 34.10-2012 | Russian Federation |
| **SM2** | GM/T 0003.2-2012 | People's Republic of China |
| **PQC** | Dilithium, Falcon | Post-quantum readiness |
## 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. Hybrid analysis combining static call-graph analysis with runtime process tracing provides confidence across build and runtime contexts.
**Why it matters:** Multi-signature DSSE envelopes (sign with FIPS *and* GOST) for cross-jurisdiction compliance. No competitor offers this.
## 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, evidence-linked, and explainable security.
**Modules:** `Cryptography`, `CryptoProfile`, `RootPack`
## 8. Semantic Smart-Diff (2025-12)
- **What it is:** Diff security meaning, not just artifacts. Compare reachability graphs, policy outcomes, and trust weights between releases.
- **Evidence:** Drift detection in `src/Scanner/__Libraries/StellaOps.Scanner.ReachabilityDrift/`; DSSE-attested drift results.
- **Why it matters:** Outputs "This release reduces exploitability by 41% despite +2 CVEs" — no competitor quantifies semantic security deltas.
---
## 9. Unknowns as First-Class State (2025-12)
- **What it is:** Explicit modeling of Unknown-Reachable and Unknown-Unreachable states with risk scoring implications.
- **Evidence:** Unknowns Registry in Signals; `unknowns_pressure` factor in scoring; UI chips for unknowns.
- **Why it matters:** Uncertainty is risk. We don't hide it — we surface and score it. Critical for air-gapped and zero-day scenarios.
## 4. Deterministic Replay
## 10. Call-Path Reachability Proofs (2025-12)
- **What it is:** Three-layer reachability: static call graph + binary resolution + runtime gating. All three must align for exploitability.
- **Evidence:** Vulnerability surfaces in `src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/`; confidence tiers (Confirmed/Likely/Present/Unreachable).
- **Why it matters:** Makes false positives *structurally impossible*, not heuristically reduced. Path witnesses are DSSE-signed.
**The audit-grade guarantee.** Every scan produces a DSSE + SRM bundle that can be replayed with `stella replay srm.yaml`.
## 12. Trust Algebra and Lattice Engine (2025-12)
- **What it is:** A deterministic claim resolution engine using **Belnap K4 four-valued logic** (Unknown, True, False, Conflict) to aggregate heterogeneous security assertions (VEX, SBOM, reachability, provenance) into signed, replayable verdicts.
- **Evidence:** Implementation in `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/`; 110 unit+integration tests; normalizers for CycloneDX, OpenVEX, and CSAF VEX formats; ECMA-424 disposition output (resolved, exploitable, in_triage, etc.).
- **Technical primitives:**
- **K4 Lattice**: Conflict-preserving knowledge aggregation with join/meet/order operations
- **Security Atoms**: Six orthogonal propositions (PRESENT, APPLIES, REACHABLE, MITIGATED, FIXED, MISATTRIBUTED)
- **Trust Labels**: Four-tuple (AssuranceLevel, AuthorityScope, FreshnessClass, EvidenceClass) for issuer credibility
- **Disposition Selection**: Priority-based rules that detect conflicts before auto-dismissal
- **Proof Bundles**: Content-addressed audit trail with decision trace
- **Why it matters:** Unlike naive VEX precedence (vendor > distro > scanner), the lattice engine:
- Preserves conflicts as explicit state (⊤) rather than hiding them
- Reports critical unknowns (PRESENT, APPLIES, REACHABLE) separately from ancillary ones
- Produces deterministic, explainable dispositions that survive audit
- Makes "what we don't know" visible and policy-addressable
```bash
# Six months later, prove what you knew
stella replay srm.yaml --assert-digest sha256:abc123...
# Output: PASS - identical result
```
## 11. 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.
- **Evidence:** `docs/task-packs/spec.md` and `docs/task-packs/registry.md`; architecture contract in `docs/modules/taskrunner/architecture.md`; runbook in `docs/task-packs/runbook.md`.
- **Why it matters:** Security teams get auditable, air-gap-friendly automation with human approvals and provable provenance, reusing the same workflows online or offline.
**What's frozen:**
- Feed snapshots (NVD, KEV, EPSS, distro advisories) with content hashes
- Analyzer versions and configs
- Policy rules and lattice state
- Random seeds for deterministic ordering
## 13. Evidence-Grade Testing and Deterministic Gates (2025-12)
- **What it is:** A model-driven test taxonomy and CI lanes that make determinism, offline behavior, and contract stability continuously provable.
- **Evidence:** `docs/testing/testing-strategy-models.md` and the catalog in `docs/testing/TEST_CATALOG.yml` define required test types per module; `docs/19_TEST_SUITE_OVERVIEW.md` lists the gated lanes.
- **Why it matters:** Regression-proof audits and predictable CI gates ensure that evidence, not assumptions, drives releases.
**Why it matters:** This is what "audit-grade" actually means. Not "we logged it" but "you can re-run it."
### Explore Further
- Walk the first deployment in [quickstart.md](quickstart.md).
- Dive into architectural flows in [`40_ARCHITECTURE_OVERVIEW.md`](40_ARCHITECTURE_OVERVIEW.md).
- Need detailed matrices? The legacy [feature matrix](04_FEATURE_MATRIX.md) and [vision](03_VISION.md) remain available for deep dives.
---
## 5. Offline Operations (Air-Gap Parity)
**Full functionality without network.** Offline Update Kits bundle everything needed for air-gapped operation.
| Component | Online | Offline |
|-----------|--------|---------|
| Feed updates | Live | Sealed bundle with Merkle roots |
| Crypto verification | OCSP/CRL | Embedded revocation lists |
| Transparency logging | Rekor | Local transparency mirror |
| Trust roots | Live TSL | RootPack bundles |
**Why it matters:** Air-gapped environments get *identical* results to connected, not degraded. Competitors offer partial offline (cached feeds) but not epistemic parity (sealed, reproducible knowledge state).
**Modules:** `AirGap.Controller`, `TrustStore`, `EgressPolicy`
---
## 6. Signed Reachability Proofs
**Proof of exploitability, not just a badge.** Every reachability graph is sealed with DSSE; optional edge-bundle attestations for contested paths.
| Layer | What It Proves | Attestation |
|-------|---------------|-------------|
| **Static** | Call graph says function is reachable | Graph-level DSSE |
| **Binary** | Compiled binary contains the symbol | Build-ID mapping |
| **Runtime** | Process actually executed the code path | Edge-bundle DSSE (optional) |
**Why it matters:** Not "potentially reachable" but "here's the exact call path from `main()` to `vulnerable_function()`." You can quarantine or dispute individual edges, not just all-or-nothing.
**No competitor signs reachability graphs.** They claim reachability; we *prove* it.
**Modules:** `ReachGraph`, `PathWitnessBuilder`, `CompositeGateDetector`
---
## 7. Semantic Smart-Diff
**Diff security meaning, not CVE counts.** Compare reachability graphs, policy outcomes, and trust weights between releases.
```
Before: 5 critical CVEs (3 reachable)
After: 7 critical CVEs (1 reachable)
Smart-Diff output: "Exploitability DECREASED by 67% despite +2 CVEs"
```
**What's compared:**
- Reachability graph deltas
- VEX state changes
- Policy outcome changes
- Trust weight shifts
**Why it matters:** "+3 CVEs" tells you nothing. "Reachable attack surface dropped by half" tells you everything.
**Modules:** `MaterialRiskChangeDetector`, `RiskStateSnapshot`, `Scanner.ReachabilityDrift`
---
## 8. Unknowns as First-Class State
**Uncertainty is risk—we surface and score it.** Explicit modeling of what we *don't* know, with policy implications.
| Band | Meaning | Policy Action |
|------|---------|---------------|
| **HOT** | High uncertainty + exploit pressure | Immediate investigation |
| **WARM** | Moderate uncertainty | Scheduled review |
| **COLD** | Low uncertainty | Decay toward resolution |
| **RESOLVED** | Uncertainty eliminated | No action |
**Why it matters:** Competitors hide unknowns (assume safe). We track them with decay algorithms, blast-radius containment, and policy budgets ("fail if unknowns > N").
**Modules:** `UnknownStateLedger`, `Policy`, `Signals`
---
## 9. Three-Layer Reachability Proofs
**Structural false positive elimination.** All three layers must align for exploitability to be confirmed.
```
Layer 1 (Static): Call graph shows path from entrypoint → vulnerable function
Layer 2 (Binary): Compiled binary contains the symbol with matching offset
Layer 3 (Runtime): eBPF probe confirms function was actually executed
```
**Confidence tiers:**
- **Confirmed** — All three layers agree
- **Likely** — Static + binary agree; no runtime data
- **Present** — Package present; no reachability evidence
- **Unreachable** — Static analysis proves no path exists
**Why it matters:** False positives become *structurally impossible*, not heuristically reduced.
**Modules:** `Scanner.VulnSurfaces`, `PathWitnessBuilder`
---
## 10. Competitive Moats Summary
**Four capabilities no competitor offers together:**
| # | Capability | Why It's Hard to Copy |
|---|-----------|----------------------|
| 1 | **Signed Reachability** | Requires three-layer instrumentation + cryptographic binding |
| 2 | **Deterministic Replay** | Requires content-addressed evidence + feed snapshotting |
| 3 | **K4 Lattice VEX** | Requires rethinking VEX from suppression to claims |
| 4 | **Sovereign Offline** | Requires pluggable crypto + offline trust roots |
**Reference:** `docs/market/competitive-landscape.md`, `docs/market/moat-strategy-summary.md`
---
## 11. Trust Algebra Engine (K4 Lattice)
**Formal conflict resolution, not naive precedence.** The lattice engine uses Belnap K4 four-valued logic to aggregate heterogeneous security assertions.
| State | Meaning | Example |
|-------|---------|---------|
| **Unknown (⊥)** | No information | New package, no VEX yet |
| **True (T)** | Positive assertion | "This CVE affects this package" |
| **False (F)** | Negative assertion | "This CVE does not affect this package" |
| **Conflict (⊤)** | Contradictory assertions | Vendor says not_affected; runtime says called |
**Security Atoms (six orthogonal propositions):**
- PRESENT, APPLIES, REACHABLE, MITIGATED, FIXED, MISATTRIBUTED
**Why it matters:** Unlike naive precedence (vendor > distro > scanner), we:
- Preserve conflicts as explicit state, not hidden
- Track critical unknowns separately from ancillary ones
- Produce deterministic, explainable dispositions
**Modules:** `TrustLatticeEngine`, `Policy` (110+ tests passing)
---
## 12. Deterministic Task Packs
**Auditable automation.** TaskRunner executes declarative Task Packs with plan-hash binding, approvals, and DSSE evidence bundles.
- **Plan-hash binding:** Task pack execution is tied to specific plan versions
- **Approval gates:** Human sign-off required before execution
- **Sealed mode:** Air-gap compatible execution
- **Evidence bundles:** DSSE-signed results for audit trails
**Why it matters:** Same workflows online or offline, with provable provenance.
**Reference:** `docs/task-packs/spec.md`, `docs/modules/taskrunner/architecture.md`
---
## 13. Evidence-Grade Testing
**Determinism as a continuous guarantee.** CI lanes that make reproducibility continuously provable.
| Test Type | What It Proves |
|----------|---------------|
| **Determinism tests** | Same inputs → same outputs |
| **Offline parity tests** | Air-gapped = connected results |
| **Contract stability tests** | APIs don't break |
| **Golden fixture tests** | Historical scans still replay |
**Why it matters:** Regression-proof audits. Evidence, not assumptions, drives releases.
**Reference:** `docs/testing/testing-strategy-models.md`, `docs/19_TEST_SUITE_OVERVIEW.md`
---
## Quick Reference
### Key Commands
```bash
# Determinism proof
stella scan --image <img> --srm-out a.yaml
stella scan --image <img> --srm-out b.yaml
diff a.yaml b.yaml # Identical
# Replay proof
stella replay srm.yaml --assert-digest <sha>
# Reachability proof
stella graph show --cve CVE-XXXX-YYYY --artifact <digest>
# VEX evaluation
stella vex evaluate --artifact <digest>
# Offline scan
stella rootpack import bundle.tar.gz
stella scan --offline --image <digest>
```
### Key Documents
- **Competitive Landscape**: `docs/market/competitive-landscape.md`
- **Moat Strategy**: `docs/market/moat-strategy-summary.md`
- **Proof Architecture**: `docs/modules/platform/proof-driven-moats-architecture.md`
- **Vision**: `docs/03_VISION.md`
- **Architecture Overview**: `docs/40_ARCHITECTURE_OVERVIEW.md`
- **Quickstart**: `docs/quickstart.md`