stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Vladimir Moushkov
2025-10-29 19:24:20 +02:00
parent 3154c67978
commit 55464f8498
41 changed files with 2134 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

384
docs/03_VISION.md
View File

@@ -1,95 +1,379 @@
#  3 · Product Vision — **Stella Ops**
*(v1.3 — 12 Jul 2025 · supersedes v1.2; expanded with ecosystem integration, refined metrics, and alignment to emerging trends)*
## 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.
---
##  0 Preamble
## 2) Golden Path (Minimal End‑to‑End Flow)
This Vision builds on the purpose and gap analysis defined in **01 WHY**.
It paints a three‑year “north‑star” picture of success for the open‑source project and sets the measurable guard‑rails that every roadmap item must serve, while fostering ecosystem growth and adaptability to trends like SBOM mandates, AI‑assisted security **and transparent usage quotas**.
```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.
---
##  1 North‑Star Vision Statement (2027)
## 3) Security Invariants (What MUST Always Hold)
> *By mid‑2027, Stella Ops is the fastest, most‑trusted self‑hosted SBOM scanner. Developers expect vulnerability feedback in **five seconds or less**—even while the free tier enforces a transparent **{{ quota_token }} scans/day** limit with graceful waiting. The project thrives on a vibrant plug‑in marketplace, weekly community releases, transparent governance, and seamless integrations with major CI/CD ecosystems—while never breaking the five‑second promise.*
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.
---
##  2 Outcomes & Success Metrics
## 4) Trust Boundaries & Roles
| KPI (community‑centric) | Baseline Jul 2025 | Target Q2‑2026 | North‑Star 2027 |
| -------------------------------- | ----------------- | -------------- | --------------- |
| ⭐ Gitea / GitHub stars | 0 | 4 000 | 10 000 |
| Weekly active Docker pulls | 0 | 1 500 | 4 000 |
| P95 SBOM scan time (alpine) | 5 s | **≤ 5 s** | **≤ 4 s** |
| Free‑tier scan satisfaction* | n/a | ≥ 90 % | ≥ 95 % |
| First‑time‑contributor PRs / qtr | 0 | 15 | 30 |
<!-- ```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
\*Measured via anonymous telemetry *opt‑in only*: ratio of successful scans to `429 QuotaExceeded` errors.
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.
---
##  3 Strategic Pillars
## 5) Data & Evidence We Persist
1. **Speed First** – preserve the sub‑5 s P95 wall‑time; any feature that hurts it must ship behind a toggle or plug‑in. **Quota throttling must apply a soft 5 s delay first, so “speed first” remains true even at the limit.**
2. **Offline‑by‑Design** – every byte required to scan ships in public images; Internet access is optional.
3. **Modular Forever** – capabilities land as hot‑load plug‑ins; the monolith can split without rewrites.
4. **Community Ownership** – ADRs and governance decisions live in public; new maintainers elected by meritocracy.
5. **Zero‑Surprise Upgrades & Limits** – SemVer discipline; `main` is always installable; minor upgrades never break CI YAML **and free‑tier limits are clearly documented, with early UI warnings.**
6. **Ecosystem Harmony** – Prioritise integrations with popular OSS tools (e.g., Trivy extensions, BuildKit hooks) to lower adoption barriers.
| 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**.
---
##  4 Road‑map Themes (18‑24 months)
## 6) Scanner Requirements (Determinism & Explainability)
| Horizon | Theme | Example EPIC |
| ------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Q3‑2025** (3 mo) | **Core Stability & UX** | One‑command installer; dark‑mode UI; baseline SBOM scanning; **Free‑tier Quota Service ({{ quota_token }} scans/day, early banner, wait‑wall).** |
| 6–12 mo | *Extensibility* | Scan‑service micro‑split PoC; community plugin marketplace beta. |
| 12–18 mo | *Ecosystem* | Community plug‑in marketplace launch; integrations with Syft and Harbor. |
| 18–24 mo | *Resilience & Scale* | Redis Cluster auto‑sharding; AI‑assisted triage plugin framework. |
*(Granular decomposition lives in 25_LEDGER.md.)
* **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).
---
##  5 Stakeholder Personas & Benefits
## 7) Policy Gate (OPA/Rego) — Examples
| Persona | Core Benefit |
| --------------------- | ---------------------------------------------------------------- |
| Solo OSS maintainer | Laptop scans in **≤ 5 s**; zero cloud reliance. |
| CI Platform Engineer | Single‑binary backend + Redis; stable YAML integrations. |
| Security Auditor | AGPL code, traceable CVE sources, reproducible benchmarks. |
| Community Contributor | Plugin hooks and good‑first issues; merit‑based maintainer path. |
| Budget‑conscious Lead | Clear **{{ quota_token }} scans/day** allowance before upgrades are required. |
> Gate runs after scan + VEX merge. It treats VEX as first‑class input.
(See **01 WHY §3** for detailed pain‑points & evidence.)
### 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])
}
```
---
##  6 Non‑Goals (2025‑2027)
## 8) Version Pins & Compatibility
* Multi‑tenant SaaS offering.
* Automated “fix PR” generation.
* Proprietary compliance certifications (left to downstream distros).
* Windows **container** scanning (agents only).
| 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 |
---
##  7 Review & Change Process
## 9) Minimal CLI Playbook (Illustrative)
* **Cadence:** product owner leads a public Vision review every **2 sprints (≈ 1 quarter)**.
* **Amendments:** material changes require PR labelled `type:vision` + two maintainer approvals.
* **Versioning:** bump patch for typo, minor for KPI tweak, major if North‑Star statement shifts.
* **Community Feedback:** Open GitHub Discussions for input; incorporate top‑voted suggestions quarterly.
> 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 |