#  3 · Product Vision — **Stella Ops** ## 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.6] 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.6** (JSON/XML) * **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 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.6) | 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.6** | JSON or XML accepted; JSON preferred | | 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.6) 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.6", "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.6; 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. --- ## 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)*