384 lines
14 KiB
Markdown
Executable File
384 lines
14 KiB
Markdown
Executable File
# 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
|
||
|
||
<!-- ```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.
|
||
|
||
---
|
||
|
||
|
||
## 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)*
|