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

22
docs/modules/findings-ledger/README.md
View File

@@ -14,3 +14,25 @@ Immutable, append-only event ledger for tracking vulnerability findings, policy
- Schema catalog (events/projections/exports): `schema-catalog.md`
- Merkle & external anchor policy: `merkle-anchor-policy.md`
- Tenant isolation & redaction manifest: `tenant-isolation-redaction.md`
## Implementation Status
### Delivery Phases
- **Phase 1 – Observability baselines:** Instrument writer/projector with metrics, structured logs, OTLP exporters, Grafana dashboards + alert rules
- **Phase 2 – Determinism harness:** Finalize NDJSON fixtures for ≥5M findings/tenant, implement replay harness CLI, add CI pipeline jobs
- **Phase 3 – Deployment & backup collateral:** Integrate ledger service into Compose/Helm, automate PostgreSQL migrations, document backup cadence
- **Phase 4 – Provenance & air-gap extensions:** Ingest orchestrator run export metadata, extend ledger events for bundle provenance, store attestation pointers
### Key Dependencies
- AdvisoryAI Sprint 110.A completion (raw findings parity)
- Observability schema approval to unblock Phase 1 instrumentation
- QA lab capacity for 5M replay checkpoint
- DevOps review of Compose/Helm overlays
- Orchestrator export schema freeze for provenance linkage
### Acceptance Criteria
- Metrics/logging/tracing implementation merged with dashboards exported
- Harness CLI + fixtures + signed reports committed
- Compose/Helm overlays + backup/restore runbooks validated
- Air-gap provenance fields documented + implemented
- Sprint tracker and release notes updated after each phase

45
docs/modules/findings-ledger/implementation_plan.md
View File

@@ -1,45 +0,0 @@
# Implementation Plan — Findings Ledger (Sprint 120)
## Phase 1 – Observability baselines (LEDGER-29-007)
- Instrument writer/projector with metrics listed in `observability.md` (`ledger_write_latency_seconds`, `ledger_events_total`, `ledger_projection_lag_seconds`, etc.).
- Emit structured logs (Serilog JSON) including chain/sequence/hash metadata.
- Wire OTLP exporters, ensure `/metrics` endpoint exposes histogram buckets with exemplars.
- Publish Grafana dashboards + alert rules (Policy SLO pack).
- Deliver doc updates + sample Grafana JSON in repo (`docs/observability/dashboards/findings-ledger/`).
## Phase 2 – Determinism harness (LEDGER-29-008)
- Finalize NDJSON fixtures for ≥5 M findings/tenant (per tenant/test scenario).
- Implement `tools/LedgerReplayHarness` CLI as specified in `replay-harness.md`.
- Add GitHub/Gitea pipeline job(s) running nightly (1 M) + weekly (5 M) harness plus DSSE signing.
- Capture CPU/memory/latency metrics and commit signed reports for validation.
- Provide runbook for QA + Ops to rerun harness in their environments.
## Phase 3 – Deployment & backup collateral (LEDGER-29-009)
- Integrate ledger service into Compose (`docker-compose.prod.yaml`) and Helm values.
- Automate PostgreSQL migrations (DatabaseMigrator invocation pre-start).
- Document backup cadence (pg_dump + WAL archiving) and projection rebuild process (call harness).
- Ensure Offline Kit packaging pulls binaries, migrations, harness, and default dashboards.
## Phase 4 – Provenance & air-gap extensions
- LEDGER-34-101: ingest orchestrator run export metadata, index by artifact hash, expose audit endpoint.
- LEDGER-AIRGAP-56/57/58: extend ledger events to capture bundle provenance, staleness metrics, timeline events.
- LEDGER-ATTEST-73-001: store attestation pointers (DSSE IDs, Rekor metadata) for explainability.
- For each extension, update schema doc + workflow inference doc to describe newly recorded fields and tenant-safe defaults.
## Dependencies & sequencing
1. AdvisoryAI Sprint 110.A completion (raw findings parity).
2. Observability schema approval (Nov 15) to unblock Phase 1 instrumentation.
3. QA lab capacity for 5 M replay (Nov 18 checkpoint).
4. DevOps review of Compose/Helm overlays (Nov 20).
5. Orchestrator export schema freeze (Nov 25) for provenance linkage.
## Deliverables checklist
- [ ] Metrics/logging/tracing implementation merged, dashboards exported.
- [ ] Harness CLI + fixtures + signed reports committed.
- [ ] Compose/Helm overlays + backup/restore runbooks validated.
- [ ] Air-gap provenance fields documented + implemented.
- [ ] Sprint tracker and release notes updated after each phase.
---
*Draft: 2025-11-13. Update when sequencing or dependencies change.*