df66ce10c3
Closes SPRINT_20260423_001 — all 3 tasks DONE, sprint archived. Extends
the scalar persisted-settings model (7efa424fe) with an artifact-
reference storage layer for the complex OCI OpenVEX connector, which
carries image subscription lists + cosign keys + TUF roots that don't
fit the flat values/clearKeys shape.
OCI-CFG-001 — Storage model:
- New vex.provider_artifact_refs table via embedded migration
009_vex_provider_artifact_refs.sql (auto-applied per §2.7). Columns:
artifact_id (UUID PK), provider_id, tenant_id, mime_type, size_bytes,
sha256, payload bytea, staged_at, staged_by. RLS via
current_setting('app.tenant_id', TRUE); size_bytes CHECK >= 0.
- Upload / list / meta / delete API under /excititor/providers/{id}/
artifacts. Multipart upload returns { artifactId, sha256, ... };
meta never returns payload. Scopes: read=vex.read, write=vex.admin.
- VexProviderArtifactMaterializer: scoped session writes artifacts to
%TMP%/stella-excititor-artifacts/<guid>/<artifactId>.bin with
chmod 0700/0600 on POSIX; Dispose cleans up the scratch root.
IDisposable + IAsyncDisposable, idempotent cleanup.
- PostgresVexProviderArtifactStore uses raw Npgsql for bytea I/O
(bypasses EF compiled-model cache + change tracking); EF entity
ProviderArtifactRefRow added for future EF-consumer completeness.
OCI-CFG-002 — Config wiring:
- VexProviderConfigurationFieldDefinition.FieldShape extended:
scalar | list<string> | artifactRef | list<artifactRef>.
- list<string> encoded as newline-or-JSON text; artifactRef stored as
the artifact UUID. Snapshot exposes FieldShape for clients.
- OCI-specific blocked sub-codes (all inside PROVIDER_CONFIG_INVALID /
_REQUIRED envelope): PROVIDER_CONFIG_MISSING_IMAGE_SUBSCRIPTIONS,
_INVALID_IMAGE_REFERENCE, _MISSING_COSIGN_KEY, _MISSING_COSIGN_ISSUER,
_MISSING_COSIGN_SUBJECT, _MISSING_TUF_ROOT, _INVALID_COSIGN_MODE,
_HTTP_REGISTRY_BLOCKED.
- Readiness reuses OciOpenVexAttestationConnectorOptions validator.
OCI-CFG-003 — CLI + Web:
- CLI `stella vex providers configure` flags: --image (repeatable),
--upload-artifact <key>=@<path> (repeatable), --clear-artifact,
--list-artifacts, --host-path-compat (CLI-only compatibility mode).
- New subcommand `stella vex providers artifacts <provider>` lists
staged artifacts.
- OciOpenVexConfigurationComponent (Angular standalone): image-
subscription list editor, artifact slots with file upload + staged
meta, scalar fields for cosign mode/issuer/subject/registry auth/
offline bundle, staged-artifact table with delete. Conditionally
rendered in vex-provider-catalog when provider.id == 'excititor:
oci-openvex'.
- docs/modules/excititor/operations/provider-credentials.md §5 OCI
OpenVEX rewritten with 4 canonical setup flows: keyless, keypair,
TUF+offline, private-registry.
Tests: targeted xUnit via scripts/test-targeted-xunit.ps1:
- VexProviderConfigurationServiceTests — 8/8 (regression)
- VexProviderOciOpenVexTests — 13/13 (OCI schema + sub-codes + artifact
service size/quota/tenant-isolation + materializer tempfile lifecycle)
Worker-side wiring of VexProviderArtifactMaterializationSession into
DefaultVexProviderRunner (before cosign/TUF validation) is a natural
follow-up — the resolver + API + store exist; a future sprint ties
the runner into the session lifecycle when the first end-to-end OCI
provider scan lands.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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 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.
Product framing reference: docs/product/release-with-confidence-product-card.md
What Stella delivers
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.
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.
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.
Core differentiators (the "why Stella" set)
These concepts appear throughout the docs and are the suite's anchor points:
- 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.
For exhaustive capability detail (including planned items), use the Feature Matrix referenced below.
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.
This documentation set is intentionally consolidated and does not maintain compatibility stubs for old paths.
Start here
Product understanding
| Goal | Open this |
|---|---|
| Understand the suite quickly | overview.md |
| Product operating card | product/release-with-confidence-product-card.md |
| Capability cards | key-features.md |
| Full capability matrix | FEATURE_MATRIX.md |
| Product vision | product/VISION.md |
Getting started
| Goal | Open this |
|---|---|
| First run and basic workflows | quickstart.md |
| Installation guide | INSTALL_GUIDE.md |
| Runtime data assets (ML models, JDK, certs) | ../devops/runtime-assets/README.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: canonical system overview | 07_HIGH_LEVEL_ARCHITECTURE.md |
| Architecture: platform overview dossier | modules/platform/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-jobengine/architecture.md |
| Telemetry federation architecture | modules/telemetry/federation-architecture.md |
| Telemetry federation runbook | runbooks/federated-telemetry-operations.md |
| Telemetry federation contracts | contracts/federated-consent-v1.md, contracts/federated-telemetry-v1.md |
Development and operations
| Goal | Open this |
|---|---|
| Develop plugins/connectors | PLUGIN_SDK_GUIDE.md |
| Console UI traversal map | qa/console-ui-traversal-map.md |
| Console UI QA strategy | qa/console-ui-qa-strategy.md |
| Security deployment hardening | SECURITY_HARDENING_GUIDE.md |
| VEX consensus and issuer trust | VEX_CONSENSUS_GUIDE.md |
| Vulnerability Explorer guide | modules/vuln-explorer/VULNERABILITY_EXPLORER_GUIDE.md |
| SBOM determinism guide | sboms/DETERMINISM.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
- 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/ - Hybrid diff patching blueprint:
docs/hybrid-diff-patching.md
License and notices
- Project license (BUSL-1.1 + Additional Use Grant):
../LICENSE - Third-party notices:
../NOTICE.md - Legal and licensing index:
docs/legal/README.md - Full dependency inventory:
docs/legal/THIRD-PARTY-DEPENDENCIES.md - Compatibility guidance:
docs/legal/LICENSE-COMPATIBILITY.md - Cryptography compliance:
docs/legal/crypto-compliance-review.md
Design principles (non-negotiable)
- 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.