git.stella-ops.org/docs/03_VISION.md

#  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.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

<!-- ```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.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.

---

## 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/market/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)*