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

docs consolidation work

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-25 18:48:11 +02:00
parent 2a06f780cf
commit 82a49f6743
102 changed files with 3550 additions and 1679 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/modules/export-center/README.md
View File

@@ -1,7 +1,7 @@
# StellaOps Export Center
Export Center packages reproducible evidence bundles (JSON, Trivy DB, mirror) with provenance metadata and optional signing for offline or mirrored deployments.
# StellaOps Export Center
Export Center packages reproducible evidence bundles (JSON, Trivy DB, mirror) with provenance metadata and optional signing for offline or mirrored deployments.
## Latest updates (2025-11-30)
- Sprint tracker `docs/implplan/SPRINT_0320_0001_0001_docs_modules_export_center.md` and module `TASKS.md` added to mirror status.
- Observability runbook stub + dashboard placeholder added under `operations/` (offline import).
@@ -12,7 +12,7 @@ Export Center packages reproducible evidence bundles (JSON, Trivy DB, mirror) wi
- Assemble manifests, provenance documents, and cosign signatures.
- Stream bundles via HTTP/OCI and stage them for Offline Kit uses.
- Expose CLI/API surfaces for automation.
## Key components
- `StellaOps.ExportCenter.WebService` planner.
- `StellaOps.ExportCenter.Worker` bundle builder.
@@ -44,5 +44,31 @@ Export Center packages reproducible evidence bundles (JSON, Trivy DB, mirror) wi
- DOCS-EXPORT-35-001 … DOCS-EXPORT-37-002 in ../../TASKS.md.
- EXPORT-ATTEST-75-002 cross-team deliverable.
## Epic alignment
- **Epic 10 – Export Center:** deliver canonical JSON, Trivy DB, and mirror bundle workflows with provenance, signatures, and offline parity.
## Epic alignment
- **Epic 10 – Export Center:** deliver canonical JSON, Trivy DB, and mirror bundle workflows with provenance, signatures, and offline parity.
## Implementation Status
### Delivery Phases
- **Phase 1 – JSON & mirror foundations:** Stand up service + worker, deliver canonical JSON and mirror profiles, seed schema migrations, publish manifest/provenance formats
- **Phase 2 – Trivy adapters & distribution:** Implement Trivy DB/Java DB adapters, wire OCI/object storage distribution, expose policy snapshot embedding + verification
- **Phase 3 – Delta, encryption, scheduling:** Release mirror deltas, bundle encryption, advanced scheduling/automation, resumable downloads, CLI/Console verification workflows
### Acceptance Criteria
- Operators can create, monitor, and download exports; verification succeeds against manifest + provenance
- Trivy bundles import cleanly; mirror bundles run in Offline Kit reference environment (full + delta)
- Policy snapshot runs reproduce deterministic decisions with embedded policyVersion + inputsHash
- Tenant scoping and RBAC block unauthorized actions; encryption-enabled bundles lock data to recipient keys
- Metrics and dashboards reflect live runs; alerts trigger on sustained failure rates
- Retried runs remain idempotent with matching manifests, hashes, and distribution artefacts
### Key Risks & Mitigations
- **Schema drift:** Versioned adapters with compatibility gates, CI integration tests, fail-fast with actionable errors
- **Bundle bloat:** zstd compression, sharding, delta exports, OCI dedupe
- **Data leakage:** Strict schema allowlists, tenancy filters, redaction enforcement, encryption options
- **Non-determinism:** Embed policy snapshots, enforce deterministic ordering, include content hashes in manifest
### Recent Updates
- Sprint tracker and module TASKS.md added to mirror status
- Observability runbook stub + dashboard placeholder added under operations/
- Bundle/profile/offline manifest guidance reaffirmed

71
docs/modules/export-center/implementation_plan.md
View File

@@ -1,71 +0,0 @@
# Implementation plan — Export Center
## Delivery phases
- **Phase 1 – JSON & mirror foundations**
Stand up the Export Center service + worker, deliver canonical JSON (`json:raw`, `json:policy`) and `mirror:full` profiles as download-only bundles, seed schema migrations, and publish manifest/provenance formats.
- **Phase 2 – Trivy adapters & distribution**
Implement Trivy DB / Java DB adapters, wire OCI/object storage distribution paths, and expose policy snapshot embedding + verification tooling.
- **Phase 3 – Delta, encryption, scheduling**
Release mirror deltas, bundle encryption, advanced scheduling/automation, resumable downloads, and CLI/Console verification workflows.
## Component work breakdown
- **Service & worker**
- Define migrations for `export_profiles`, `export_runs`, `export_inputs`, `export_distributions`.
- Implement planner, adapter host, signing/attestation layer, distribution engines, and deterministic manifests.
- Enforce tenant quotas, concurrency controls, and audit logging for create/cancel/distribute events.
- **Adapters**
- JSON adapters: canonical JSONL writers, redaction guardrails, compression (zstd).
- Trivy adapters: field mapping, schema compatibility gating, validation suite.
- Mirror adapters: filesystem/OCI layout, delta computation, optional encryption with manifest updates.
- **Integrations**
- Findings Ledger streaming APIs for advisories, VEX, SBOMs, findings.
- Policy Engine deterministic snapshot endpoint; VEX Lens consensus snapshot.
- Export Center telemetry surfaced through Observability stack.
- **Surfaces**
- Console: profiles CRUD, run wizard, run detail + verification panel, distribution dashboards.
- CLI: `stella export profile|run|download|verify` with resumable downloads and signature verification.
- **Security / RBAC**
- Scope enforcement per tenant, role matrix coverage, encryption key rotation tests, redaction filters.
- **Docs & ops**
- Author module dossier (overview, architecture, profiles, API, CLI, mirror bundles, Trivy adapter, provenance & signing).
- Produce runbooks (`docs/operations/export-runbook.md`) and hardening guidance (`docs/security/export-hardening.md`).
## Documentation deliverables
- `docs/modules/export-center/overview.md` — responsibilities, profiles, surfaces.
- `docs/modules/export-center/architecture.md` — service topology, adapters, manifests, distribution flow.
- `docs/modules/export-center/profiles.md`, `trivy-adapter.md`, `mirror-bundles.md`, `provenance-and-signing.md`, `api.md`, `cli.md` — keep aligned with shipped features.
- Cross-link Orchestrator, Policy, VEX Lens, CLI, and Offline Kit docs whenever exports become dependencies.
## Acceptance criteria
- Operators can create, monitor, and download an export; `cosign verify` (and CLI verify) succeeds against manifest + provenance, mapping back to source artifacts.
- Trivy bundles import cleanly into Trivy across supported versions; mirror bundles run in Offline Kit reference environment (full + delta).
- Policy snapshot runs reproduce deterministic decisions and include embedded `policyVersion` + `inputsHash`.
- Tenant scoping and RBAC block unauthorized actions; encryption-enabled bundles lock data to recipient keys.
- Metrics (`exporter_run_duration_seconds`, `exporter_bundle_bytes_total`, `exporter_run_failures_total`) and dashboards reflect live runs; alerts trigger on sustained failure rates.
- Retried runs remain idempotent: manifests, hashes, and distribution artefacts match across identical inputs.
## Risks & mitigations
- **Schema drift (Trivy / policy):** versioned adapters with compatibility gates, CI integration tests, fail-fast with actionable errors.
- **Bundle bloat:** zstd compression, sharding, delta exports, OCI dedupe.
- **Data leakage:** strict schema allowlists, tenancy filters, redaction enforcement, encryption options.
- **Non-determinism:** embed policy snapshots, enforce deterministic ordering, include content hashes in manifest.
- **Operational slowness:** streaming downloads with range support, resumable CLI, concurrency limits, retry policies for workers.
## Test strategy
- **Unit:** adapter mapping, manifest hashing, signing/attestation, delta computation, encryption round-trips.
- **Integration:** end-to-end runs for every profile, verification workflows, OCI push/pull, resume/abort scenarios.
- **Compatibility:** matrix tests for Trivy versions, mirror bundle import in Offline Kit sample environment.
- **Security:** tenant fuzzing, RBAC coverage, redaction/PII filters, key rotation.
- **Performance & chaos:** stress exports with large datasets, simulate worker/API failures mid-run, confirm deterministic recovery.
## Definition of done
- Service, worker, and adapters deployed with telemetry & alerting.
- CLI & Console workflows published, Offline Kit instructions updated.
- Documentation set listed above refreshed; imposed rule statements appended where required.
- CI pipelines include schema validation, profile verification, and determinism checks.
- ./TASKS.md + ../../TASKS.md reflect current status for in-flight stories.
## Sprint alignment (2025-11-30)
- Docs sprint: `docs/implplan/SPRINT_0320_0001_0001_docs_modules_export_center.md`; statuses mirrored in `docs/modules/export-center/TASKS.md`.
- Observability evidence stub lives in `operations/observability.md` with Grafana placeholder under `operations/dashboards/`.
- Bundle/profile/offline manifest guidance maintained in `devportal-offline*.md`, `mirror-bundles.md`, and `provenance-and-signing.md`; update sprint/TASKS if these change.