stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
108d1c64b323808d6085fca05818fc581c6b003a
git.stella-ops.org/docs/modules/findings-ledger/merkle-anchor-policy.md
StellaOps Bot 47168fec38 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.
2025-12-02 21:08:01 +02:00

2.3 KiB
Raw Blame History

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:
{
  "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.