37cba83708
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
3.7 KiB
3.7 KiB
Findings Ledger — FL1–FL10 Remediation (LEDGER-GAPS-121-009)
Source advisory: docs/product-advisories/archived/27-Nov-2025-superseded/28-Nov-2025 - Findings Ledger and Immutable Audit Trail.md
Created: 2025-12-02 · Owner: Findings Ledger Guild
Gap closure map
| ID | Gap summary | Remediation artefact(s) | Evidence / notes |
|---|---|---|---|
| FL1 | Versioned ledger event schema (canonical JSON + hashes) | docs/modules/findings-ledger/schema-catalog.md §1; updated docs/modules/findings-ledger/schema.md canonical rules |
Canonical envelope v1.0.0 stamped; hash derivation pinned to sha256(canonicalJson) + sha256(eventHash-sequence). |
| FL2 | Projection schema versions + cycle hash determinism | schema-catalog.md §2; schema.md §4 |
Projection v1.0.0 with cycle-hash recipe and required fields; rebuild checksum guard in harness. |
| FL3 | Export schema (canonical/compact) + filter hash versioning | schema-catalog.md §3; golden fixtures under src/Findings/StellaOps.Findings.Ledger/fixtures/golden/ |
Canonical export shape tagged export.v1.canonical; compact tagged export.v1.compact; fixtures hashed. |
| FL4 | Merkle + external anchor policy (Rekor/offline) | docs/modules/findings-ledger/merkle-anchor-policy.md |
Anchoring cadence (1k/15m), Rekor/air-gap policy, anchor ref format, DSSE anchoring manifest. |
| FL5 | Tenant isolation + redaction manifest for exports/logs | docs/modules/findings-ledger/tenant-isolation-redaction.md; manifest: docs/modules/findings-ledger/redaction-manifest.yaml |
Per-tenant partitions, export field redaction (comments, actor ids), signed manifest checksum. |
| FL6 | DSSE + policy hash linkage for exports and attestations | docs/modules/findings-ledger/dsse-policy-linkage.md; harness DSSE placeholder includes policyHash |
Describes payloadType + bindings to policy digest and export hashlist. |
| FL7 | Deterministic export fixtures (golden) | fixtures/golden/*.ndjson (findings, vex, advisories, sboms) |
Each includes filtersHash, cycleHash, policyVersion; hashes logged in manifest. |
| FL8 | Offline verifier script for bundles/exports | tools/LedgerReplayHarness/scripts/verify_export.py |
Pure-Python, no deps; validates ordering, recomputes SHA-256 and optional expected hash file. |
| FL9 | Replay/rebuild checksum guard | Harness update: tools/LedgerReplayHarness/Program.cs (--expected-checksum) |
Computes event-stream and projection checksums; fails on mismatch; emitted in report. |
| FL10 | Quotas/backpressure metrics and alerts | Metrics update: Observability/LedgerMetrics.cs; doc: observability.md §2/§4 |
New counters ledger_backpressure_applied_total, gauge ledger_quota_remaining, alert guidance. |
How to verify
- Run
dotnet run --project tools/LedgerReplayHarness -- --fixture <path> --connection <conn> --tenant <tenant> --report out/report.json --metrics out/metrics.json --expected-checksum <baseline-checksums.json>(use a file produced by a known-good run; template:docs/modules/findings-ledger/replay-checksums.sample.json). - Validate exports:
python tools/LedgerReplayHarness/scripts/verify_export.py --input fixtures/golden/findings-canonical.ndjson --schema export.v1.canonical. - Check manifest hashes:
sha256sum docs/modules/findings-ledger/redaction-manifest.yaml fixtures/golden/*.ndjson.
Follow-ons
- Keep lightweight test stub
HarnessRunner(unit-only) to avoid heavy harness bootstrap during fast tests; revisit once harness logic is extracted into a reusable library. - Integrate Rekor anchor publishing toggle into Helm/Compose overlays (tracked separately).
- Mirror golden fixtures into Offline Kit once export pipeline emits real data.