diff --git a/docs/README.md b/docs/README.md index 846daab81..03dc4c4f2 100755 --- a/docs/README.md +++ b/docs/README.md @@ -68,7 +68,6 @@ This documentation set is intentionally consolidated and does not maintain compa | Understand the suite quickly | `overview.md` | | Capability cards | `key-features.md` | | Full capability matrix | `FEATURE_MATRIX.md` | -| Known documentation coverage gaps | `FEATURE_GAPS_REPORT.md` | | Product vision | `product/VISION.md` | | Roadmap (priorities + definition of "done") | `ROADMAP.md` | diff --git a/docs/product/VISION.md b/docs/product/VISION.md index c135b7c0f..46d2d3c7e 100755 --- a/docs/product/VISION.md +++ b/docs/product/VISION.md @@ -1,299 +1,223 @@ # Product Vision — Stella Ops Suite +*Evidence-grade release orchestration for containerized applications outside Kubernetes.* -> Stella Ops Suite isn't just another scanner or deployment tool—it's a different product category: **a centralized, auditable release control plane** that gates releases using reachability-aware security and produces verifiable evidence for every decision. - -## 1) Problem Statement & Goals - -We ship containers to non-Kubernetes targets (Docker hosts, Compose, ECS, Nomad). We need: - -- **Release governance** across environments (Dev → Stage → Prod) with approvals and audit trails. -- **Security as a gate, not a blocker** — integrate vulnerability decisions into promotion workflows. -- **Digest-based release identity** — immutable releases, not mutable tags. -- **Toolchain flexibility** — plug into any SCM, CI, registry, and secrets system. -- **Determinism & explainability** — release decisions can be replayed and justified. -- **Evidence packets** — every release decision links to concrete artifacts. -- **Non-Kubernetes first-class support** — Docker hosts, Compose, ECS, Nomad are not afterthoughts. -- **Pricing that doesn't punish automation** — no per-project, per-seat, or per-deployment taxes. - -**Non-goals:** Replacing CI systems, building Kubernetes deployments (use ArgoCD/Flux), or inventing new SBOM/attestation formats. +> Stella Ops Suite is not “a scanner” and not “another CD tool.” +> It is a **release control plane** that produces **verifiable evidence** for every promotion decision, and uses **reachability-aware security** as a first-class gate. --- -## 2) Golden Path (Release-Centric Flow) +## 1) Why this product exists -``` -Build → Scan → Create Release → Request Promotion → Gate Evaluation → Deploy → Evidence -``` +Most non-Kubernetes container estates ship using a patchwork: +- CI produces images, registries store them, scanners emit long CVE lists. +- Deployment happens via Compose/scripts/Ansible plus tribal knowledge approvals. +- Audit evidence is reconstructed from screenshots and spreadsheets. + +This fails in predictable ways: + +- Security noise overwhelms engineers (too many non-actionable CVEs). +- Release governance is informal (approvals are not cryptographically bound to artifacts). +- “Why was this approved / blocked?” is not replayable or defensible. +- Audits become manual, slow, and error-prone. + +**Stella’s premise:** in the AI economics era, code is cheap; trustworthy operations are expensive. +Stella’s job is to make *evidence-grade releases* routine, self-service, and hard to replicate. + +--- + +## 2) Target users and where we win + +### Who Stella is for +- Teams deploying containers **without Kubernetes** (Docker hosts, Docker Compose, ECS, Nomad, scripted targets). +- Small and mid organizations that need **practical, certifiable security** without a heavy platform team. +- Regulated or audit-exposed environments, including **offline/air-gapped** operations. + +### Where we intentionally win +- **Evidence-grade governance**: every promotion is backed by signed, exportable evidence. +- **Reachability-aware security**: prioritize what is actually exploitable, not what is merely present. +- **Deterministic replay**: reproduce past decisions bit-for-bit to answer auditors and incident reviews. +- **Non-Kubernetes first-class**: targets and workflows that are not an afterthought. + +### Non-goals +- Replacing CI systems (Jenkins/GitHub Actions/GitLab CI remain your build engine). +- Competing as a Kubernetes-first CD product (use Argo CD / Flux where Kubernetes is the estate). +- Inventing new SBOM, attestation, or VEX formats. + +--- + +## 3) The North Star: “Every release is provable” + +A **provable release** means: + +1. Every new artifact digest has evidence (SBOM + reachability + verdict) generated once and reused. +2. Every promotion decision records inputs, policy, approvals, and reasons. +3. Evidence is exportable, verifiable offline, and reproducible by replay. + +--- + +## 4) Golden path (Verified Release) + +Stella supports both “Verified” and “CD-only” modes, but it is designed to excel at Verified releases. + +### Verified release flow ```mermaid flowchart LR - A[CI Build] --> B[OCI Registry\nPush by digest] - B --> C[Stella Scan\nSBOM + Vuln Analysis] - C --> D[Create Release\nDigest bundle] - D --> E[Request Promotion\nDev → Stage → Prod] - E --> F[Gate Evaluation\nSecurity + Policy + Approval] - F --> G{Decision} - G -->|Allow| H[Deploy to Targets\nDocker/Compose/ECS/Nomad] - G -->|Deny| I[Block with Explanation] - H --> J[Evidence Packet\nSigned + Stored] + A[CI Build] --> B[Push to OCI Registry by digest] + B --> C[Deep Scan once per digest\nSBOM + reachability + findings] + C --> D[Create Release\nDigest bundle + provenance refs] + D --> E[Request Promotion\nDev -> Stage -> Prod] + E --> F[Gate Evaluation\nPolicy + security + approvals] + F --> G{Decision} + G -->|Allow| H[Deploy to targets\nCompose/Docker/ECS/Nomad/scripts] + G -->|Deny| I[Block with explainable reasons] + H --> J[Evidence Packet\nSigned + stored + exportable] ``` -### What Stella Ops Suite Does - -| Capability | Description | -|------------|-------------| -| **Release orchestration** | UI-driven promotion (Dev → Stage → Prod), approvals, policy gates, rollbacks; steps are hook-able with scripts | -| **Security decisioning as a gate** | Scan on build, evaluate on release, re-evaluate on CVE updates—without forcing re-scans | -| **OCI-digest-first releases** | A release is an immutable digest (or bundle of digests); track "what is deployed where" | -| **Toolchain-agnostic integrations** | Plug into any SCM, any CI, any registry, any secrets system | -| **Auditability + standards** | Evidence packets (exportable), SBOM/VEX/attestation support, deterministic replay | +### CD-only mode (supported, not optimized) +Stella can orchestrate deployments while bypassing evidence gates. This exists to avoid competing in a saturated “CD-only” market and to allow gradual adoption. However, the differentiator is **evidence-grade governance**. --- -## 3) Design Principles & Invariants +## 5) Product pillars (what we build) -These principles are **inviolable** and MUST be reflected in all code, UI, documentation, and audit artifacts. +### Pillar A — Release orchestration (control plane) +- Environment management and promotion workflows (Dev -> Stage -> Prod). +- Approvals, freeze windows, and separation-of-duties policies. +- Rollbacks and redeploys by immutable digest identity. +- “What is deployed where” inventory over time. -### Principle 1: Release Identity via Digest +### Pillar B — Security decisioning as a gate +- Scan on build, evaluate on release, re-evaluate on intel updates. +- Reachability-aware vulnerability prioritization (reduce noise; focus on exploitable paths). +- VEX-first decisioning and policy explainability (“why blocked?” traces). -``` -INVARIANT: A release is a set of OCI image digests (component → digest mapping), never tags. -``` +### Pillar C — Evidence & audit +- Signed evidence packets per decision: inputs, verdicts, approvals, deployment artifacts, logs. +- Exportable audit packs for auditors, incident reviews, and regulated reporting. +- Integrity guarantees (content-addressed artifacts + signatures + optional transparency logging). -- Tags are convenience inputs for resolution -- Tags are resolved to digests at release creation time -- All downstream operations (promotion, deployment, rollback) use digests -- Digest mismatch at pull time = deployment failure (tamper detection) +### Pillar D — Determinism and replay +- Deterministic scanning and policy evaluation with replay manifests. +- Reproduce prior decisions given the same manifest, feeds, and versioned engines. +- Deterministic identifiers and ordering; UTC timestamps; canonical hashing. -### Principle 2: Determinism and Evidence - -``` -INVARIANT: Every deployment/promotion produces an immutable evidence record. -``` - -Evidence record contains: -- **Who**: User identity (from Authority) -- **What**: Release bundle (digests), target environment, target hosts -- **Why**: Policy evaluation result, approval records, decision reasons -- **How**: Generated artifacts (compose files, scripts), execution logs -- **When**: Timestamps for request, decision, execution, completion - -### Principle 3: Pluggable Everything, Stable Core - -``` -INVARIANT: Integrations are plugins; the core orchestration engine is stable. -``` - -Plugins contribute: -- Configuration screens (UI) -- Connector logic (runtime) -- Step node types (workflow) -- Doctor checks (diagnostics) -- Agent types (deployment) - -Core engine provides: -- Workflow execution (DAG processing) -- State machine management -- Evidence generation -- Policy evaluation -- Credential brokering - -### Principle 4: No Feature Gating - -``` -INVARIANT: All plans include all features. Limits are only: -- Number of environments -- Number of new digests analyzed per day -- Fair use on deployments -``` - -### Principle 5: Offline-First Operation - -``` -INVARIANT: All core operations MUST work in air-gapped environments. -``` - -- No runtime calls to external APIs for core decisions -- Vulnerability data synced via mirror bundles -- Plugins may require connectivity; core does not -- Evidence packets exportable for external audit - -### Principle 6: Immutable Generated Artifacts - -``` -INVARIANT: Every deployment generates and stores immutable artifacts. -``` - -Generated artifacts: -- `compose.stella.lock.yml`: Pinned digests, resolved env refs -- `deploy.stella.script.dll`: Compiled C# script (or hash reference) -- `release.evidence.json`: Decision record -- `stella.version.json`: Version sticker placed on target +### Pillar E — Self-service operations (Doctor-first) +- Self-diagnostics (“Doctor”) to remove dependency on vendor support. +- Offline-first posture; explicit allowlists; strict validation; predictable failure modes. +- A product that can reach meaningful production adoption without a sales/support org. --- -## 4) Security Invariants (Scanning & Attestation) +## 6) Design principles and invariants (non-negotiable) -These invariants from our scanning heritage remain core to the security gate: +### Invariant 1 — Digest-first release identity +A release is a **bundle of OCI digests** (component -> digest mapping), never mutable tags. -1. **Artifact identity is content-addressed.** - - All identities are SHA-256 digests of immutable blobs. +- Tags may be accepted as inputs but must be resolved to digests at release creation time. +- Downstream operations (promotion, deployment, rollback) operate on digests. +- Digest mismatch at pull time is a hard failure (tamper signal). -2. **Every SBOM is signed.** - - SBOMs MUST be wrapped in **in-toto DSSE** attestations tied to the container digest. +### Invariant 2 — Evidence-first decisions +Every promotion/deployment emits an immutable evidence record. -3. **Provenance is attached, not implied.** - - Build metadata (who/where/how) MUST ride as attestations linked by digest. +Evidence must capture: +- Who: authenticated identity and authorization context +- What: release bundle, target environment(s), target selection +- Why: policy outcome, approval chain, decision reasons +- How: generated artifacts and execution traces +- When: deterministic timestamps and ordering -4. **Transparency FIRST mindset.** - - Signatures/attestations SHOULD be logged to **Rekor** and store inclusion proofs. +### Invariant 3 — Deterministic replay +Given the recorded manifest (inputs + versions), Stella must reproduce: +- scan outputs, +- policy outcomes, +- gate reasons, +- and decision records. -5. **Determinism & replay.** - - Scans MUST be reproducible given: input digests, scanner version, DB snapshot, and config. +### Invariant 4 — Offline-first operation +Core decisions must not require external network access. +External feeds are mirrored; verification and replay must work offline. -6. **Explainability.** - - Findings MUST show the *why*: package → file path → call-stack / entrypoint (when available). +### Invariant 5 — Pluggable edges, stable core +Integrations and target types are plugins. The orchestration and evidence core remains stable. -7. **Exploitability over enumeration.** - - Risk MUST be communicated via **VEX** (OpenVEX), including **under_investigation** where appropriate. +Plugins may provide: +- connector logic (SCM/CI/registry/secrets), +- workflow step types, +- target/agent types, +- Doctor checks. -8. **Air-gap friendly.** - - Mirrors for vuln DBs and containers; all verification MUST work without public egress. +### Invariant 6 — No “feature gating” +Capabilities are not tier-gated. +Commercial limits (when relevant) apply only to **scale units** such as: +- environments (governance boundaries), +- new digests deep-scanned per month (evidence generation), +- fair-use constraints on exceptional bandwidth/support consumption. --- -## 5) Adopted Standards +## 7) Security and evidence invariants (carryover from scanning heritage) -| Domain | Standard | Stella Pin | Notes | -|--------|----------|------------|-------| -| **SBOM** | CycloneDX | **1.7** | JSON or XML; 1.6 ingest supported | -| **Attestation** | in-toto | **Statement v1** | Predicates per use case | -| **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 | +1. Artifact identity is content-addressed (SHA-256 digests). +2. SBOMs and key evidence artifacts are signed (in-toto DSSE envelopes). +3. Provenance is attached via attestations, not implied via tags or CI logs. +4. Explainability is required: findings must connect to packages/paths/symbols when available. +5. Exploitability over enumeration: VEX and reachability drive actionability. +6. Air-gap posture is first-class: mirrors, offline kits, and offline verification flows. --- -## 6) Competitive Positioning +## 8) Competitive positioning (category definition) -### Why Stella Wins (One Line Each) +### What we are not +- **Not a pure scanner**: scanners find issues; Stella governs releases with evidence. +- **Not a generic CD tool**: CD tools deploy; Stella is a release authority with proof. -- **CI/CD tools** (Actions/Jenkins/GitLab CI): great at running pipelines, weak at being a central release authority with audit-grade evidence. -- **CD orchestrators** (Octopus/Harness/Spinnaker): strong promotions, but security is bolt-on and pricing scales poorly. -- **Registries** (Harbor/JFrog): can store and scan, but don't provide release governance. -- **Scanners/CNAPP** (Trivy/Snyk/Aqua): scan well, but don't provide release orchestration. +### Where alternatives typically stop +- Scanners: produce findings, but do not produce release-level evidence chains. +- CD tools: provide deployments, but security is bolt-on and audit evidence is manual. +- Registries: store artifacts, but are not a governance and decision system. -### Core Differentiators (Moats) - -1. **Non-Kubernetes Specialization** — Docker hosts, Compose, ECS, Nomad are first-class, not afterthoughts. - -2. **Signed Reachability** — Every reachability graph is sealed with DSSE; optional edge-bundle attestations for runtime/init/contested paths. - -3. **Deterministic Replay** — Scans and release decisions run bit-for-bit identical from frozen feeds and manifests. - -4. **Evidence-Linked Decisions** — Every gate evaluation produces a signed decision record with evidence refs. - -5. **Sovereign + Offline Operation** — FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class toggles. - -6. **Cost Model** — No per-seat, per-project, or per-deployment tax. Limits are environments + new digests/day. +### Stella’s moat +- Digest-first release identity + signed evidence chain + deterministic replay +- Reachability-aware decisioning bound to promotion workflows +- Offline-first and sovereign crypto posture +- Self-service operability (Doctor-first) designed for small teams --- -## 7) Release Orchestration Architecture (Planned) +## 9) Roadmap framing (outcome-driven) -### New Themes +This vision is delivered in phases, but the category remains consistent: -| Theme | Purpose | Key Modules | -|-------|---------|-------------| -| **INTHUB** | Integration hub | Integration Manager, Connection Profiles, Connector Runtime | -| **ENVMGR** | Environment management | Environment Manager, Target Registry, Agent Manager | -| **RELMAN** | Release management | Component Registry, Version Manager, Release Manager | -| **WORKFL** | Workflow engine | Workflow Designer, Workflow Engine, Step Executor | -| **PROMOT** | Promotion and approval | Promotion Manager, Approval Gateway, Decision Engine | -| **DEPLOY** | Deployment execution | Deploy Orchestrator, Target Executor, Artifact Generator | -| **AGENTS** | Deployment agents | Agent Core, Docker/Compose/ECS/Nomad agents | -| **PROGDL** | Progressive delivery | A/B Manager, Traffic Router, Canary Controller | -| **RELEVI** | Release evidence | Evidence Collector, Sticker Writer, Audit Exporter | -| **PLUGIN** | Plugin infrastructure | Plugin Registry, Plugin Loader, Plugin SDK | - -### Key Data Entities - -- **Environment**: Dev/Stage/Prod with freeze windows, approval policies -- **Target**: Deployment destination (Docker host, Compose host, ECS service, Nomad job) -- **Agent**: Deployment executor with capabilities and heartbeat -- **Component**: Logical service mapped to image repository -- **Release**: Bundle of component digests with semantic version -- **Promotion**: Request to move release between environments -- **Workflow**: DAG of steps for deployment execution -- **Evidence Packet**: Signed bundle of decision inputs and outputs +1) **Evidence foundation**: deep scan, policy, determinism, evidence export, Doctor maturity +2) **Release control plane**: environments, promotions, approvals, decision records +3) **Deployment execution**: non-Kubernetes targets, rollback, artifacts, verification checks +4) **Progressive delivery**: canary/A-B/blue-green where practical for non-K8s estates +5) **Ecosystem depth**: integrations/connectors, plugin surface hardening, docs, ops kits --- -## 8) Existing Capabilities (Operational) +## 10) Glossary (canonical terms) -These themes power the security gate within release orchestration: - -| Theme | Purpose | Key Modules | -|-------|---------|-------------| -| **INGEST** | Advisory ingestion | Concelier, Advisory-AI | -| **VEXOPS** | VEX document handling | Excititor, VEX Lens, VEX Hub | -| **REASON** | Policy and decisioning | Policy Engine, OPA Runtime | -| **SCANENG** | Scanning and SBOM | Scanner, SBOM Service, Reachability | -| **EVIDENCE** | Evidence and attestation | Evidence Locker, Attestor, Export Center | -| **RUNTIME** | Runtime signals | Signals, Graph, Zastava | -| **JOBCTRL** | Job orchestration | Scheduler, Orchestrator, TaskRunner | -| **OBSERVE** | Observability | Notifier, Telemetry | -| **REPLAY** | Deterministic replay | Replay Engine | -| **DEVEXP** | Developer experience | CLI, Web UI, SDK | +- **Environment**: governance boundary (policy + config + approvals + targets) +- **Release**: immutable bundle of digests (component -> digest) +- **Promotion**: moving a release between environments +- **Gate**: policy check that blocks/allows promotion +- **Evidence packet**: signed bundle of decision inputs/outputs suitable for export and verification +- **Deterministic replay**: re-running a decision with the same manifest to reproduce outputs --- -## 9) Pricing Model - -**Principle:** Pay for scale, not for features or automation. - -| Plan | Price | Environments | New Digests/Day | Notes | -|------|-------|--------------|-----------------|-------| -| **Free** | $0/month | 3 | 333 | Full features, unlimited deployments (fair use) | -| **Pro** | $699/month | 33 | 3,333 | Same features | -| **Enterprise** | $1,999/month | Unlimited | Unlimited | Fair use on mirroring/audit bandwidth | - ---- - -## 10) Implementation Roadmap (Planned) - -| Phase | Focus | Key Deliverables | -|-------|-------|------------------| -| **Phase 1** | Foundation | Environment management, integration hub, release bundles | -| **Phase 2** | Workflow Engine | DAG execution, step registry, workflow templates | -| **Phase 3** | Promotion & Decision | Approval gateway, security gates, decision records | -| **Phase 4** | Deployment Execution | Docker/Compose agents, artifact generation, rollback | -| **Phase 5** | UI & Polish | Release dashboard, promotion UI, environment management | -| **Phase 6** | Progressive Delivery | A/B releases, canary, traffic routing | -| **Phase 7** | Extended Targets | ECS, Nomad, SSH/WinRM agentless | -| **Phase 8** | Plugin Ecosystem | Full plugin system, marketplace | - ---- - -## 11) Change Log +## Change log | Version | Date | Note | -|---------|------|------| -| v2.0 | 09-Jan-2026 | Major revision: pivot to release control plane; scanning becomes gate | +|---|---:|---| +| v3.0 | 2026-01-17 | Reframed as evidence-grade release control plane; added Doctor-first and CD-only framing; removed pricing specifics. | +| v2.0 | 2026-01-09 | Pivot to release control plane; scanning becomes gate. | | v1.4 | 29-Oct-2025 | Initial principles, golden path, policy examples, JSON skeletons | | v1.3 | 12-Jul-2025 | Expanded ecosystem pillar, added metrics/integrations | | v1.2 | 11-Jul-2025 | Restructured to link with WHY; merged principles | | v1.1 | 11-Jul-2025 | Original OSS-only vision | | v1.0 | 09-Jul-2025 | First public draft | - ---- - -## References - -- [Overview](../overview.md) — 2-minute product summary -- [Architecture Overview](../ARCHITECTURE_OVERVIEW.md) — High-level architecture -- [Release Orchestrator Architecture](../modules/release-orchestrator/architecture.md) — Detailed orchestrator design -- [Competitive Landscape](competitive-landscape.md) — Vendor comparison -- [Roadmap](../ROADMAP.md) — Implementation priorities