feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
- Introduced a new VEX compact fixture for testing purposes. - Implemented `verify_export.py` script to validate Findings Ledger exports, ensuring deterministic ordering and applying redaction manifests. - Added a lightweight stub `HarnessRunner` for unit tests to validate ledger hashing expectations. - Documented tasks related to the Mirror Creator. - Created models for entropy signals and implemented the `EntropyPenaltyCalculator` to compute penalties based on scanner outputs. - Developed unit tests for `EntropyPenaltyCalculator` to ensure correct penalty calculations and handling of edge cases. - Added tests for symbol ID normalization in the reachability scanner. - Enhanced console status service with comprehensive unit tests for connection handling and error recovery. - Included Cosign tool version 2.6.0 with checksums for various platforms.
This commit is contained in:
50
docs/modules/findings-ledger/merkle-anchor-policy.md
Normal file
50
docs/modules/findings-ledger/merkle-anchor-policy.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Merkle & External Anchor Policy (FL4)
|
||||
|
||||
**Audience:** Findings Ledger Guild · DevOps · Compliance
|
||||
**Applies to:** `src/Findings/StellaOps.Findings.Ledger` (Merkle worker, anchoring jobs)
|
||||
|
||||
## Anchoring cadence
|
||||
- **Batch size:** 1,000 events or **15 minutes**, whichever is first (`LedgerServiceOptions:Merkle.BatchSize/WindowDuration`).
|
||||
- **Tree:** flat Merkle over `merkle_leaf_hash` (see `schema-catalog.md` §1). Root hashed with SHA-256; no salt.
|
||||
- **Partitions:** per-tenant batching only; no cross-tenant mixing.
|
||||
- **Ordering:** leaves ordered by `(sequence_no, recorded_at)`. Any deviation is a failure.
|
||||
|
||||
## Anchor references
|
||||
- `ledger_merkle_roots.anchor_reference` formats:
|
||||
- `rekor::<uuid>` when pushed to Rekor.
|
||||
- `airgap::<bundleId>` when sealed in offline bundle.
|
||||
- `none` (empty) for internal-only anchors.
|
||||
- External publication is optional but **must** include DSSE envelope with payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.stella-ledger-anchor+json",
|
||||
"payload": {
|
||||
"tenant": "<tenant>",
|
||||
"rootHash": "<sha256>",
|
||||
"leafCount": 1000,
|
||||
"windowStart": "2025-12-02T00:00:00Z",
|
||||
"windowEnd": "2025-12-02T00:15:00Z",
|
||||
"policyHash": "<policyVersion>",
|
||||
"schemaVersion": "ledger.event.v1"
|
||||
},
|
||||
"signatures": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Determinism & recovery
|
||||
- Anchor worker enforces stable ordering; replay harness recomputes Merkle roots and fails when root mismatch (FL9 guard).
|
||||
- Root hash + DSSE signature are stored alongside export bundles for offline verification.
|
||||
- External anchors **never** include tenant-identifying data beyond tenant id already present in ledger tables.
|
||||
|
||||
## Air-gap posture
|
||||
- Rekor publication optional; when disabled, anchors are sealed inside offline bundles with `anchor_reference=airgap::<bundleId>`.
|
||||
- Anchor manifest is bundled in Offline Kit under `offline/ledger/anchors/<tenant>/<anchorId>.json`.
|
||||
- No outbound network calls when `ExternalAnchoring:Enabled=false`.
|
||||
|
||||
## Monitoring
|
||||
- Metrics: `ledger_merkle_anchor_duration_seconds`, `ledger_merkle_anchor_failures_total`, `ledger_backpressure_applied_total{reason="anchoring"}`, `ledger_quota_remaining{kind="ingest"}`.
|
||||
- Alerts: see `observability.md` (AnchorFailure + new Backpressure alert).
|
||||
|
||||
## Change control
|
||||
- Any change to batch size/window or hash recipe requires bumping `ledger.event` schema minor version and updating `schema-catalog.md`.
|
||||
Reference in New Issue
Block a user