stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
55464f84984ae579eca18456874ba5ccac6ccf29
git.stella-ops.org/docs/03_VISION.md
Vladimir Moushkov 55464f8498
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
up
2025-10-29 19:24:20 +02:00

14 KiB
Executable File
Raw Blame History

 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)

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

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.

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

{
  "_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)

{
  "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)

{
  "@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)