docs consolidation

2026-01-07 10:23:21 +02:00
parent 4789027317
commit 044cf0923c
515 changed files with 5460 additions and 5292 deletions
--- a/docs/product/VISION.md
+++ b/docs/product/VISION.md
@@ -0,0 +1,409 @@
+#  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:
+- **Authenticity & integrity** of build artifacts and metadata.
+- **Provenance** attached to artifacts, not platforms.
+- **Transparency** to detect tampering and retroactive edits.
+- **Determinism & explainability** so scanner judgments can be replayed and justified.
+- **Actionability** to separate theoretical from exploitable risk (VEX).
+- **Minimal trust** across multi‑tenant and third‑party boundaries.
+
+**Non‑goals:** Building a new package manager, inventing new SBOM/attestation formats, or depending on closed standards.
+
+---
+
+## 2) Golden Path (Minimal End‑to‑End Flow)
+
+```mermaid
+flowchart LR
+    A[Source / Image / Rootfs] --> B[SBOM Producer\nCycloneDX 1.7]
+    B --> C[Signer\nin‑toto Attestation + DSSE]
+    C --> D[Transparency\nSigstore Rekor - optional but RECOMMENDED]
+    D --> E[Durable Storage\nSBOMs, Attestations, Proofs]
+    E --> F[Scanner\nPkg analyzers + Entry‑trace + Layer cache]
+    F --> G[VEX Authoring\nOpenVEX + SPDX 3.0.1 relationships]
+    G --> H[Policy Gate\nOPA/Rego: allow/deny + waivers]
+    H --> I[Artifacts Store\nReports, SARIF, VEX, Audit log]
+````
+
+**Adopted standards (pinned for interoperability):**
+
+* **SBOM:** CycloneDX **1.7** (JSON/XML; 1.6 accepted for ingest)
+* **Attestation & signing:** **in‑toto Attestations** (Statement + Predicate) in **DSSE** envelopes
+* **Transparency:** **Sigstore Rekor** (inclusion proofs, monitoring)
+* **Exploitability:** **OpenVEX** (statuses & justifications)
+* **Modeling & interop:** **SPDX 3.0.1** (relationships / VEX modeling)
+* **Findings interchange (optional):** SARIF for analyzer output
+
+> Pinnings are *policy*, not claims about “latest”. We may update pins via normal change control.
+
+---
+
+## 3) Security Invariants (What MUST Always Hold)
+
+1. **Artifact identity is content‑addressed.**
+
+   * All identities are SHA‑256 digests of immutable blobs (images, SBOMs, attestations).
+2. **Every SBOM is signed.**
+
+   * SBOMs MUST be wrapped in **in‑toto DSSE** attestations tied to the container digest.
+3. **Provenance is attached, not implied.**
+
+   * Build metadata (who/where/how) MUST ride as attestations linked by digest.
+4. **Transparency FIRST mindset.**
+
+   * Signatures/attestations SHOULD be logged to **Rekor** and store inclusion proofs.
+5. **Determinism & replay.**
+
+   * Scans MUST be reproducible given: input digests, scanner version, DB snapshot, and config.
+6. **Explainability.**
+
+   * Findings MUST show the *why*: package → file path → call‑stack / entrypoint (when available).
+7. **Exploitability over enumeration.**
+
+   * Risk MUST be communicated via **VEX** (OpenVEX), including **under_investigation** where appropriate.
+8. **Least privilege & minimal trust.**
+
+   * Build keys are short‑lived; scanners run on ephemeral, least‑privileged workers.
+9. **Air‑gap friendly.**
+
+   * Mirrors for vuln DBs and containers; all verification MUST work without public egress.
+10. **No hidden blockers.**
+
+* Policy gates MUST be code‑reviewable (e.g., Rego) and auditable; waivers are attestations, not emails.
+
+---
+
+## 4) Trust Boundaries & Roles
+
+<!-- ```mermaid
+flowchart TB
+    subgraph DevTenant[Dev Tenant]
+      SRC[Source Code]
+      CI[CI Runner]
+    end
+    subgraph SecPlatform[Security Platform]
+      SB[SBOM Service]
+      AT[Attestation Service]
+      TR[Transparency Client]
+      SCN[Scanner Pool]
+      POL[Policy Gate]
+      ST[Artifacts Store]
+    end
+    subgraph External[External/3rd‑party]
+      REG[Container Registry]
+      REK[Rekor]
+    end
+
+    SRC --> CI
+    CI -->|image digest| REG
+    REG -->|pull by digest| SB
+    SB --> AT --> TR --> REK
+    AT --> ST
+    REK --> ST
+    ST --> SCN --> POL --> ST
+
+``` -->
+
+* **Build/CI:** Holds signing capability (short‑lived keys or keyless signing).
+* **Registry:** Source of truth for image bytes; access via digest only.
+* **Scanner Pool:** Ephemeral nodes; content‑addressed caches; no shared mutable state.
+* **Artifacts Store:** Immutable, WORM‑like storage for SBOMs, attestations, proofs, SARIF, VEX.
+
+---
+
+## 5) Data & Evidence We Persist
+
+| Artifact             | MUST Persist                         | Why                          |
+| -------------------- | ------------------------------------ | ---------------------------- |
+| SBOM (CycloneDX 1.7) | Raw file + DSSE attestation          | Reproducibility, audit       |
+| in‑toto Statement    | Full JSON                            | Traceability                 |
+| Rekor entry          | UUID + inclusion proof               | Tamper‑evidence              |
+| Scanner output       | SARIF + raw notes                    | Triage & tooling interop     |
+| VEX                  | OpenVEX + links to findings          | Noise reduction & compliance |
+| Policy decisions     | Input set + decision + rule versions | Governance & forensics       |
+
+Retention follows our Compliance policy; default **≥ 18 months**.
+
+---
+
+## 6) Scanner Requirements (Determinism & Explainability)
+
+* **Inputs pinned:** image digest(s), SBOM(s), scanner version, vuln DB snapshot date, config hash.
+* **Explainability:** show file paths, package coords (e.g., purl), and—when possible—**entry‑trace/call‑stack** from executable entrypoints to vulnerable symbol(s).
+* **Caching:** content‑addressed per‑layer & per‑ecosystem caches; warming does not change decisions.
+* **Unknowns:** output **under_investigation** where exploitability is not yet known; roll into VEX.
+* **Interchange:** emit **SARIF** for IDE and pipeline consumption (optional but recommended).
+
+---
+
+## 7) Policy Gate (OPA/Rego) — Examples
+
+> Gate runs after scan + VEX merge. It treats VEX as first‑class input.
+
+### 7.1 Deny unreconciled criticals that are exploitable
+
+```rego
+package stella.policy
+
+default allow := false
+
+exploitable(v) {
+  v.severity == "CRITICAL"
+  v.exploitability == "affected"
+}
+
+allow {
+  not exploitable_some
+}
+
+exploitable_some {
+  some v in input.findings
+  exploitable(v)
+  not waived(v.id)
+}
+
+waived(id) {
+  some w in input.vex
+  w.vuln_id == id
+  w.status == "not_affected"
+  w.justification != ""
+}
+```
+
+### 7.2 Require Rekor inclusion for attestations
+
+```rego
+package stella.policy
+
+violation[msg] {
+  some a in input.attestations
+  not a.rekor.inclusion_proof
+  msg := sprintf("Attestation %s lacks Rekor inclusion proof", [a.id])
+}
+```
+
+---
+
+## 8) Version Pins & Compatibility
+
+| Domain       | Standard       | Stella Pin       | Notes                                            |
+| ------------ | -------------- | ---------------- | ------------------------------------------------ |
+| SBOM         | CycloneDX      | **1.7**          | JSON or XML accepted; 1.6 ingest supported       |
+| Attestation  | in‑toto        | **Statement v1** | Predicates per use case (e.g., sbom, provenance) |
+| Envelope     | DSSE           | **v1**           | Canonical JSON payloads                          |
+| Transparency | Sigstore Rekor | **API stable**   | Inclusion proof stored alongside artifacts       |
+| VEX          | OpenVEX        | **spec current** | Map to SPDX 3.0.1 relationships as needed        |
+| Interop      | SPDX           | **3.0.1**        | Use for modeling & cross‑ecosystem exchange      |
+| Findings     | SARIF          | **2.1.0**        | Optional but recommended                         |
+
+---
+
+## 9) Minimal CLI Playbook (Illustrative)
+
+> Commands below are illustrative; wire them into CI with short‑lived credentials.
+
+```bash
+# 1) Produce SBOM (CycloneDX 1.7) from image digest
+syft registry:5000/myimg@sha256:... -o cyclonedx-json > sbom.cdx.json
+
+# 2) Create in‑toto DSSE attestation bound to the image digest
+cosign attest --predicate sbom.cdx.json \
+  --type https://stella-ops.org/attestations/sbom/1 \
+  --key env://COSIGN_KEY \
+  registry:5000/myimg@sha256:...
+
+# 3) (Optional but recommended) Rekor transparency
+cosign sign --key env://COSIGN_KEY registry:5000/myimg@sha256:...
+cosign verify-attestation --type ... --certificate-oidc-issuer https://token.actions... registry:5000/myimg@sha256:... > rekor-proof.json
+
+# 4) Scan (pinned DB snapshot)
+stella-scan --image registry:5000/myimg@sha256:... \
+  --sbom sbom.cdx.json \
+  --db-snapshot 2025-10-01 \
+  --out findings.sarif
+
+# 5) Emit VEX
+stella-vex --from findings.sarif --policy vex-policy.yaml --out vex.json
+
+# 6) Gate
+opa eval -i gate-input.json -d policy/ -f pretty "data.stella.policy.allow"
+```
+
+---
+
+## 10) JSON Skeletons (Copy‑Ready)
+
+### 10.1 in‑toto Statement (DSSE payload)
+
+```json
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    {
+      "name": "registry:5000/myimg",
+      "digest": { "sha256": "IMAGE_DIGEST_SHA256" }
+    }
+  ],
+  "predicateType": "https://stella-ops.org/attestations/sbom/1",
+  "predicate": {
+    "sbomFormat": "CycloneDX",
+    "sbomVersion": "1.7",
+    "mediaType": "application/vnd.cyclonedx+json",
+    "location": "sha256:SBOM_BLOB_SHA256"
+  }
+}
+```
+
+### 10.2 DSSE Envelope (wrapping the Statement)
+
+```json
+{
+  "payloadType": "application/vnd.in-toto+json",
+  "payload": "BASE64URL_OF_CANONICAL_STATEMENT_JSON",
+  "signatures": [
+    {
+      "keyid": "KEY_ID_OR_CERT_ID",
+      "sig": "BASE64URL_SIGNATURE"
+    }
+  ]
+}
+```
+
+### 10.3 OpenVEX (compact)
+
+```json
+{
+  "@context": "https://openvex.dev/ns/v0.2.0",
+  "author": "Stella Ops Security",
+  "timestamp": "2025-10-29T00:00:00Z",
+  "statements": [
+    {
+      "vulnerability": "CVE-2025-0001",
+      "products": ["pkg:purl/example@1.2.3?arch=amd64"],
+      "status": "under_investigation",
+      "justification": "analysis_ongoing",
+      "timestamp": "2025-10-29T00:00:00Z"
+    }
+  ]
+}
+```
+
+---
+
+## 11) Handling “Unknowns” & Noise
+
+* Use **OpenVEX** statuses: `affected`, `not_affected`, `fixed`, `under_investigation`.
+* Prefer **justifications** over free‑text.
+* Time‑bound **waivers** are modeled as VEX with `not_affected` + justification or `affected` + compensating controls.
+* Dashboards MUST surface counts separately for `under_investigation` so risk is visible.
+
+---
+
+## 12) Operational Guidance
+
+**Key management**
+
+* Use **ephemeral OIDC** or short‑lived keys (HSM/KMS bound).
+* Rotate signer identities at least quarterly; no shared long‑term keys in CI.
+
+**Caching & performance**
+
+* Layer caches keyed by digest + analyzer version.
+* Pre‑warm vuln DB snapshots; mirror into air‑gapped envs.
+
+**Multi‑tenancy**
+
+* Strict tenant isolation for storage and compute.
+* Rate‑limit and bound memory/CPU per scan job.
+
+**Auditing**
+
+* Every decision is a record: inputs, versions, rule commit, actor, result.
+* Preserve Rekor inclusion proofs with the attestation record.
+
+---
+
+## 13) Exceptions Process (Break‑glass)
+
+1. Open a tracked exception with: artifact digest, CVE(s), business justification, expiry.
+2. Generate VEX entry reflecting the exception (`not_affected` with justification or `affected` with compensating controls).
+3. Merge into policy inputs; **policy MUST read VEX**, not tickets.
+4. Re‑review before expiry; exceptions cannot auto‑renew.
+
+---
+
+## 14) Threat Model (Abbreviated)
+
+* **Tampering**: modified SBOMs/attestations → mitigated by DSSE + Rekor + WORM storage.
+* **Confused deputy**: scanning a different image → mitigated by digest‑only pulls and subject digests in attestations.
+* **TOCTOU / re‑tagging**: registry tags drift → mitigated by digest pinning everywhere.
+* **Scanner poisoning**: unpinned DBs → mitigated by snapshotting and recording version/date.
+* **Key compromise**: long‑lived CI keys → mitigated by OIDC keyless or short‑lived KMS keys.
+
+---
+
+## 15) Implementation Checklist
+
+* [ ] SBOM producer emits CycloneDX 1.7; bound to image digest.
+* [ ] in‑toto+DSSE signing wired in CI; Rekor logging enabled.
+* [ ] Durable artifact store with WORM semantics.
+* [ ] Scanner produces explainable findings; SARIF optional.
+* [ ] OpenVEX emitted and archived; linked to findings & image.
+* [ ] Policy gate enforced; waivers modeled as VEX; decisions logged.
+* [ ] Air‑gap mirrors for registry and vuln DBs.
+* [ ] Runbooks for key rotation, Rekor outage, and database rollback.
+
+---
+
+## 16) Glossary
+
+* **SBOM**: Software Bill of Materials describing packages/components within an artifact.
+* **Attestation**: Signed statement binding facts (predicate) to a subject (artifact) using in‑toto.
+* **DSSE**: Envelope that signs the canonical payload detached from transport.
+* **Transparency Log**: Append‑only log (e.g., Rekor) giving inclusion and temporal proofs.
+* **VEX**: Vulnerability Exploitability eXchange expressing exploitability status & justification.
+
+---
+
+## 9) Moats
+
+<!-- TODO: Review for separate approval - updated moats section -->
+**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. 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, 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/product/competitive-landscape.md` for vendor comparison and talking points.
+
+---
+
+
+## 8 · Change Log
+
+| Version | Date        | Note (high‑level)                                                                                     |
+| ------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| v1.4    | 29-Oct-2025 | Initial principles, golden path, policy examples, and JSON skeletons.                                    |
+| v1.4    | 14‑Jul‑2025 | First public revision reflecting quarterly roadmap & KPI baseline.                                    |
+| v1.3    | 12‑Jul‑2025 | Expanded ecosystem pillar, added metrics/integrations, refined non-goals, community persona/feedback. |
+| v1.2    | 11‑Jul‑2025 | Restructured to link with WHY; merged principles into Strategic Pillars; added review §7              |
+| v1.1    | 11‑Jul‑2025 | Original OSS‑only vision                                                                              |
+| v1.0    | 09‑Jul‑2025 | First public draft                                                                                    |
+
+*(End of Product Vision v1.3)*