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

refactor README.md for clarity and structure; enhance product descriptions and operational details

Browse Source
This commit is contained in:
master
2026-01-16 00:25:09 +02:00
parent a927d924e3
commit 0ec8db6374
1 changed files with 81 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
docs/README.md
View File

@@ -1,121 +1,130 @@
# Stella Ops Suite Documentation
**Stella Ops Suite** is a centralized, auditable release control plane for **non‑Kubernetes** container estates. It orchestrates environment promotions, gates releases using reachability-aware security and policy, and produces verifiable evidence for every decision.
**Stella Ops Suite** is a centralized, auditable **release control plane** for **non-Kubernetes container estates**. It orchestrates environment promotions, gates releases using reachability-aware security and policy, and produces **verifiable evidence** for every decision.
The platform combines:
- **Release orchestration** — UI-driven promotion (Dev -> Stage -> Prod), approvals, policy gates, rollbacks, and step-graph execution (sequential/parallel) with per-step logs
- **Security decisioning as a gate** — scan on build, evaluate on release, re-evaluate on vulnerability intel updates
- **OCI-digest-first releases** — immutable digest-based release identity with authoritative "what is deployed where" tracking
- **Toolchain-agnostic integrations** — plug into any SCM, CI, registry, secrets system, and host access method via plugins
- **Auditability + standards** — evidence packets, SBOM/VEX/attestation support, deterministic replay and explainable decisions
Stella is designed for teams who deploy containers via **Docker/Compose, hosts/VMs, and scripted automation** and need **certifiable security + auditable releases** without building a bespoke governance pipeline.
---
## Verified vs Unverified Releases
## What Stella delivers
Stella supports two operational modes:
### Evidence-grade release governance (outside Kubernetes)
- **Environment promotions** (Dev -> Stage -> Prod) with explicit policy, approvals, and change control.
- **Digest-first release identity**: deployments are tracked by immutable OCI digests so "what is deployed where" is unambiguous.
- **Deterministic decision records**: every gate decision is explainable ("why blocked?") and replayable.
- **Verified releases (recommended):** promotions require Stella evidence for each new digest (SBOM + reachability + policy decision record + approvals where configured). Intended for certifiable security and audit-grade releases.
- **Unverified releases (CD-only):** orchestration is allowed with evidence gates bypassed. Still tracked and logged, but not intended for security certification.
### Reachability-aware security decisioning
- **Deep scanning** produces SBOM + findings + reachability and hybrid reachability evidence.
- **VEX-first decisioning** with consensus and conflict handling across issuers (SBOM/VEX are part of the evidence chain, not a side export).
- **Policy-as-code** with deterministic evaluation and traceable outcomes.
This documentation emphasizes the **verified release** path as the primary product value.
### Verifiability, attestability, and audit export
- **Evidence packets / decision capsules**: hashable, immutable bundles that capture inputs, verdicts, and approvals.
- **Attestations** (DSSE/in-toto, predicates for SBOM/VEX/verdict/reachability; optional Sigstore flows where configured).
- **Audit exports** for compliance review, incident response, and forensic reconstruction.
### Offline-first, sovereign operation
- Built for **air-gapped** and restricted environments: local databases, offline kits/snapshots, and deterministic replay.
- **Regional crypto profiles** (eIDAS/FIPS/GOST/SM and related plugin architecture) to avoid compliance lock-in.
### Toolchain-agnostic integrations
- Integrates with common SCM/CI/registries/secrets managers through **connectors and plugins**.
- Works alongside existing pipelines: scan-on-build, gate-on-promotion, re-evaluate on advisory updates.
---
## Licensing model (documentation-level summary)
## Core differentiators (the "why Stella" set)
Stella Ops Suite uses **no feature gating** across plans. Licensing limits apply only to:
These concepts appear throughout the docs and are the suite's anchor points:
- **Environments**
- **New digests deep-scanned per month** (evidence-grade analysis of previously unseen OCI digests)
- **Signed, replayable risk verdicts**: decisions can be re-run deterministically from the same evidence.
- **Decision capsules**: evidence is packaged for audit, not scattered across logs and screenshots.
- **Reachability with portable proofs**: exploitability is evidenced, not asserted.
- **Smart-diff / semantic risk delta**: focus on what materially changed between releases.
- **Unknowns as first-class state**: uncertainty is tracked and budgeted, not hidden.
- **Non-Kubernetes-first**: orchestration and evidence for Compose/hosts/agentless targets as a primary use case.
- **Digest-first release identity**: immutable artifacts, immutable accountability.
**Deployment targets are not licensed** (unlimited targets; fair use may apply only under abusive automation patterns).
(See your offer/pricing document if present in the repo; commonly stored under `docs/product/`.)
For exhaustive capability detail (including planned items), use the Feature Matrix referenced below.
---
## Two Levels of Documentation
## Two levels of documentation
- **High-level (canonical):** curated guides in `docs/*.md`.
- **Detailed (reference):** deep dives under `docs/**` (module dossiers, architecture notes, API contracts/samples, runbooks, schemas). Entry point: `docs/technical/README.md`.
- **Detailed (reference):** deep dives under `docs/**` (module dossiers, architecture notes, API contracts/samples, runbooks, schemas).
Entry point: `docs/technical/README.md`.
This documentation set is internal and does not keep compatibility stubs for old paths. Content is consolidated to reduce duplication and outdated pages.
This documentation set is intentionally consolidated and does not maintain compatibility stubs for old paths.
---
## Start Here
## Start here
### Product Understanding
### Product understanding
| Goal | Open this |
| --- | --- |
| Understand the product in 2 minutes | [overview.md](overview.md) |
| Browse capabilities | [key-features.md](key-features.md) |
| Feature matrix | [FEATURE_MATRIX.md](FEATURE_MATRIX.md) |
| Product vision | [product/VISION.md](product/VISION.md) |
| Roadmap (priorities + definition of "done") | [ROADMAP.md](ROADMAP.md) |
| Verified release model (concepts + evidence) | [VERIFIED_RELEASES.md](VERIFIED_RELEASES.md) |
| 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` |
### Getting Started
### Getting started
| Goal | Open this |
| --- | --- |
| First run (minimal install) | [quickstart.md](quickstart.md) |
| Run a first scan (CLI) | [quickstart.md](quickstart.md) |
| Run a first verified promotion (Dev -> Stage -> Prod) | [RELEASE_PROCESS.md](releases/RELEASE_PROCESS.md) |
| Ingest advisories (Concelier + CLI) | [CONCELIER_CLI_QUICKSTART.md](CONCELIER_CLI_QUICKSTART.md) |
| Console (Web UI) operator guide | [UI_GUIDE.md](UI_GUIDE.md) |
| Doctor / self-service diagnostics | [DOCTOR_GUIDE.md](doctor/README.md) |
| Offline / air-gap operations | [OFFLINE_KIT.md](OFFLINE_KIT.md) |
| First run and basic workflows | `quickstart.md` |
| Ingest advisories (Concelier + CLI) | `CONCELIER_CLI_QUICKSTART.md` |
| Console (Web UI) operator guide | `UI_GUIDE.md` |
| Offline / air-gap operations | `OFFLINE_KIT.md` |
### Architecture
| Goal | Open this |
| --- | --- |
| Architecture: high-level overview | [ARCHITECTURE_OVERVIEW.md](ARCHITECTURE_OVERVIEW.md) |
| Architecture: full reference map | [ARCHITECTURE_REFERENCE.md](ARCHITECTURE_REFERENCE.md) |
| Architecture: user flows (UML) | [technical/architecture/user-flows.md](technical/architecture/user-flows.md) |
| Architecture: module matrix | [technical/architecture/module-matrix.md](technical/architecture/module-matrix.md) |
| Architecture: data flows | [technical/architecture/data-flows.md](technical/architecture/data-flows.md) |
| Architecture: schema mapping | [technical/architecture/schema-mapping.md](technical/architecture/schema-mapping.md) |
| Release Orchestrator architecture | [modules/release-orchestrator/architecture.md](modules/release-orchestrator/architecture.md) |
| Evidence and attestations | [modules/evidence/README.md](modules/evidence/README.md) |
| Architecture: high-level overview | `ARCHITECTURE_OVERVIEW.md` |
| Architecture: full reference map | `ARCHITECTURE_REFERENCE.md` |
| Architecture: user flows (UML) | `technical/architecture/user-flows.md` |
| Architecture: module matrix | `technical/architecture/module-matrix.md` |
| Architecture: data flows | `technical/architecture/data-flows.md` |
| Architecture: schema mapping | `technical/architecture/schema-mapping.md` |
| Release Orchestration dossier | `modules/release-orchestrator/architecture.md` |
### Development & Operations
### Development and operations
| Goal | Open this |
| --- | --- |
| Engineering rules (determinism, security, docs discipline) | [code-of-conduct/CODE_OF_CONDUCT.md](code-of-conduct/CODE_OF_CONDUCT.md) |
| Testing standards and evidence expectations | [code-of-conduct/TESTING_PRACTICES.md](code-of-conduct/TESTING_PRACTICES.md) |
| Develop plugins/connectors | [PLUGIN_SDK_GUIDE.md](PLUGIN_SDK_GUIDE.md) |
| Security deployment hardening | [SECURITY_HARDENING_GUIDE.md](SECURITY_HARDENING_GUIDE.md) |
| VEX consensus and issuer trust | [VEX_CONSENSUS_GUIDE.md](VEX_CONSENSUS_GUIDE.md) |
| Vulnerability Explorer guide | [VULNERABILITY_EXPLORER_GUIDE.md](VULNERABILITY_EXPLORER_GUIDE.md) |
| Develop plugins/connectors | `PLUGIN_SDK_GUIDE.md` |
| Security deployment hardening | `SECURITY_HARDENING_GUIDE.md` |
| VEX consensus and issuer trust | `VEX_CONSENSUS_GUIDE.md` |
| Vulnerability Explorer guide | `VULNERABILITY_EXPLORER_GUIDE.md` |
| Engineering standards (for implementers) | `code-of-conduct/CODE_OF_CONDUCT.md` |
| Testing standards (for QA/automation) | `code-of-conduct/TESTING_PRACTICES.md` |
---
## Detailed Indexes
## Detailed indexes
- **Technical index (everything):** [docs/technical/README.md](/docs/technical/)
- **End-to-end workflow flows:** [docs/flows/](/docs/flows/)
- **Module dossiers:** [docs/modules/](/docs/modules/)
- **API contracts and samples:** [docs/api/](/docs/api/)
- **Architecture notes / ADRs:** [docs/technical/architecture/](/docs/technical/architecture/), [docs/technical/adr/](/docs/technical/adr/)
- **Operations and deployment:** [docs/operations/](/docs/operations/)
- **Air-gap workflows:** [docs/modules/airgap/guides/](/docs/modules/airgap/guides/)
- **Security deep dives:** [docs/security/](/docs/security/)
- **Benchmarks and fixtures:** [docs/benchmarks/](/docs/benchmarks/), [docs/assets/](/docs/assets/)
- **Product advisories:** [docs/product/advisories/](/docs/product/advisories/)
- Technical index (everything): `docs/technical/README.md`
- End-to-end workflow flows: `docs/flows/`
- Module dossiers: `docs/modules/`
- API contracts and samples: `docs/api/`
- Architecture notes / ADRs: `docs/technical/architecture/`, `docs/technical/adr/`
- Operations and deployment: `docs/operations/`
- Air-gap workflows: `docs/modules/airgap/guides/`
- Security deep dives: `docs/security/`
- Benchmarks and fixtures: `docs/benchmarks/`, `docs/assets/`
- Product advisories: `docs/product/advisories/`
---
## Design Principles
## Design principles (non-negotiable)
- **Offline-first**: core operations work in air-gapped environments
- **Deterministic replay**: same inputs yield same outputs (stable ordering, canonical hashing)
- **Evidence-linked decisions**: every verified release decision links to concrete evidence artifacts
- **Digest-first release identity**: releases are immutable OCI digests, not mutable tags
- **Pluggable everything**: integrations are plugins; core orchestration is stable
- **No feature gating**: all plans include all features; licensing limits are environments + new digests deep-scanned per month; deployment targets are not licensed
- **Offline-first:** core operations must work in restricted/air-gapped environments.
- **Deterministic replay:** same inputs yield the same outputs (stable ordering, canonical hashing).
- **Evidence-linked decisions:** every decision links to concrete evidence artifacts.
- **Digest-first identity:** releases are immutable OCI digests, not mutable tags.
- **Pluggable integrations:** connectors and steps are extensible; the core evidence chain stays stable.