Findings Ledger — Air-Gap Provenance Extensions (LEDGER-AIRGAP-56/57/58)

Scope: How ledger events capture mirror bundle provenance, staleness metrics, evidence snapshots, and sealed-mode timeline events for air-gapped deployments.

1. Requirements recap

LEDGER-AIRGAP-56-001: Record mirror bundle metadata (bundle_id, merkle_root, time_anchor, source_region) whenever advisories/VEX/policies are imported offline. Tie import provenance to each affected ledger event.
LEDGER-AIRGAP-56-002: Surface staleness metrics and enforce risk-critical export blocks when imported data exceeds freshness SLAs; emit remediation guidance.
LEDGER-AIRGAP-57-001: Link findings evidence snapshots (portable bundles) so cross-enclave verification can attest to the same ledger hash.
LEDGER-AIRGAP-58-001: Emit sealed-mode timeline events describing bundle impacts (new findings, remediation deltas) for Console and Notify.

2. Schema additions

Entity	Field	Type	Notes
`ledger_events.event_body`	`airgap.bundle`	object	`{ "bundleId", "merkleRoot", "timeAnchor", "sourceRegion", "importedAt", "importOperator" }` recorded on import events.
`ledger_events.event_body`	`airgap.evidenceSnapshot`	object	`{ "bundleUri", "dsseDigest", "expiresAt" }` for findings evidence bundles.
`ledger_projection`	`airgap.stalenessSeconds`	integer	Age of newest data feeding the finding projection.
`ledger_projection`	`airgap.bundleId`	string	Last bundle influencing the projection row.
`timeline_events` (new view)	`airgapImpact`	object	Materials needed for LEDGER-AIRGAP-58-001 timeline feed (finding counts, severity deltas).

Canonical JSON must sort object keys (bundleId, importOperator, …) to keep hashes deterministic.

3. Import workflow

Mirror bundle validation: AirGap controller verifies bundle signature/manifest before ingest; saves metadata for ledger enrichment.
Event enrichment: The importer populates airgap.bundle fields on each event produced from the bundle. bundleId equals manifest digest (SHA-256). merkleRoot is the bundle’s manifest Merkle root; timeAnchor is the authoritative timestamp from the bundle.
Anchoring: Merkle batching includes bundle metadata; anchor references in ledger_merkle_roots.anchor_reference use format airgap::<bundleId> when not externally anchored.
Projection staleness: Projector updates airgap.stalenessSeconds comparing current time with bundle.timeAnchor per artifact scope; CLI + Console read the value to display freshness indicators.
API surface: POST /internal/ledger/airgap-import records bundle provenance (returns ledgerEventId, chainId, sequence) and persists the same metadata into airgap_imports for audit.

4. Staleness enforcement

Config option AirGapPolicies:FreshnessThresholdSeconds (default 604800 = 7 days) sets allowable age.
Export workflows check airgap.stalenessSeconds; when over threshold the service raises ERR_AIRGAP_STALE and supplies remediation message referencing the last bundle (bundleId, timeAnchor, importOperator).
Metrics (ledger_airgap_staleness_seconds) track distribution per tenant for dashboards.

5. Evidence snapshots

Evidence bundles (airgap.evidenceSnapshot) reference portable DSSE packages stored in Evidence Locker (bundleUri like file://offline/evidence/<bundleId>.tar).
CLI command stella ledger evidence link attaches evidence snapshots to findings after bundle generation; ledger event records both DSSE digest and expiration.
Timeline entries and Console detail views display “Evidence snapshot available” with download instructions suited for sealed environments.

6. Timeline events (LEDGER-AIRGAP-58-001)

New derived view timeline_airgap_impacts emits JSON objects such as:

{
  "tenant": "tenant-a",
  "bundleId": "bundle-sha256:…",
  "newFindings": 42,
  "resolvedFindings": 18,
  "criticalDelta": +5,
  "timeAnchor": "2025-10-30T11:00:00Z",
  "sealedMode": true
}

Console + Notify subscribe to ledger.airgap.timeline events to show sealed-mode summaries.

7. Offline kit considerations

Include bundle provenance schema, staleness policy config, CLI scripts (stella airgap bundle import, stella ledger evidence link), and sample manifests.
Provide validation script scripts/ledger/validate-airgap-bundle.sh verifying manifest signatures, timestamps, and ledger enrichment before ingest.
Document sealed-mode toggles ensuring no external egress occurs when importing bundles.

Draft 2025-11-13 for LEDGER-AIRGAP-56/57/58 planning.