ScadaBridge/docs/plans/2026-06-16-m5-audit-hardening-design.md

M5 — Audit Hardening (T3–T8) — Design

Status: Approved (awaiting plan). Worktree/branch: worktree-m5-audit-hardening off main (e77e209). Source: Phase-2 milestone M5 from docs/plans/2026-06-15-stillpending-completion-design.md.

Goal

Harden the centralized Audit Log with six independent, ready-to-build items. Two items originally listed under M5 — T1 hash-chain tamper evidence and T2 Parquet export — remain deferred to v1.x (per CLAUDE.md's audit design decisions); their stubs (CLI verify-chain no-op, export 501) stay unchanged.

Scope (in)

T3 per-channel retention · T4 ParentExecutionId tag-cascade · T5 historical backfill (reframed) · T6 per-node stuck KPIs · T7 structured response-capture increments · T8 CLI audit tree.

Scope (out / deferred to v1.x)

T1 hash-chain (no Hash/PrevHash columns, no real verify-chain), T2 Parquet export (the 501 gate stays). Reversing those deferrals is a separate decision.

---

Items

T8 — CLI audit tree (smallest; reuses existing server walk + UI)

The recursive execution-tree walk (IAuditLogRepository.GetExecutionTreeAsync, backed by IX_AuditLog_ParentExecution) and the Blazor ExecutionTreePage already exist; only an HTTP projection + CLI surface are missing.

• Server: add GET /api/audit/tree?executionId=… in AuditEndpoints.MapAuditAPI → repo.GetExecutionTreeAsync → serialize ExecutionTreeNode[].
• CLI: add audit tree --execution-id <guid> [--format table|json] in AuditCommands + an AuditTreeHelpers renderer (indented ASCII tree for table; raw nodes for json), mirroring AuditQueryHelpers/AuditExportHelpers.
• No schema change. Tests: endpoint returns the tree; CLI renders a multi-level tree + handles not-found.

T6 — Per-node stuck-count KPIs

KPIs are per-site today; SourceNode is on the Notification and SiteCalls rows but not aggregated.

• Add ComputePerNodeKpisAsync (group by SourceNode) parallel to the existing ComputePerSiteKpisAsync in NotificationOutboxRepository and SiteCallAuditRepository.
• New PerNode…KpiRequest/Response message pair per actor; register in each actor's Receive<>.
• Surface a per-node breakdown on the existing KPI tiles (AuditKpiTiles/SiteCallKpiTiles) — additive, behind the existing tiles.
• Tests: repository grouping returns correct per-node counts (stuck/parked/ queue-depth); message round-trip.

T7 — Structured response-capture increments (no schema change)

• (a) Inbound request headers → captured into the existing Extra JSON in AuditWriteMiddleware.EmitInboundAudit, passed through the existing header redactor (auth headers redacted by default).
• (b) AuditInboundCeilingHits counter on AuditCentralHealthSnapshot (alongside the existing failure counters), incremented when an inbound row truncates (request or response hits InboundMaxBytes). Surfaced via the health snapshot.
• (c) Per-method opt-out of body capture: a SkipBodyCapture flag on PerTargetRedactionOverride, checked in the capture pipeline so a noisy/ sensitive method can suppress body capture (headers + metadata still recorded).
• Tests: request headers land in Extra and are redacted; ceiling-hit increments the counter; opt-out suppresses body but keeps the row.

T4 — ParentExecutionId tag-cascade (touches the actor model — high-risk)

Completes the execution tree beyond the inbound-API→routed-script case.

• Alarm on-trigger: thread a Guid? parentExecutionId through AlarmActor.SpawnAlarmExecutionActor → AlarmExecutionActor → ScriptRuntimeContext, so an alarm-triggered script chains to its firing context (the alarm's own execution id where one exists; otherwise a root).
• Nested CallScript/CallShared: in ScriptRuntimeContext, pass the current run's ExecutionId (not the inherited _parentExecutionId) as the child invocation's ParentExecutionId, so A → CallScript(B) records B's parent as A — a true multi-level tree.
• Timer/expression-trigger top-level runs stay roots (no spawner) — unchanged.
• Tests: alarm-triggered script row carries the expected parent; a 2-level nested CallScript produces a chain A→B→C walkable by GetExecutionTreeAsync.
• Risk: serialized actor state + correlation plumbing; covered by targeted SiteRuntime actor tests + a tree-walk integration assertion.

T3 — Per-channel retention overrides (one design wrinkle, resolved)

Retention is a single global RetentionDays; the purge actor switches out whole month partitions by OccurredAtUtc (channel-blind).

• Add PerChannelRetentionDays (Dictionary<string,int>, keyed by channel / Action name) to AuditLogOptions, validated like the global value; a channel override may only be shorter than the global window (longer is meaningless under month-partition switch-out, which is governed by the largest retention).
• Mechanism (resolved): after the coarse global partition purge, the purge actor runs a bounded row-level delete for channels whose override is shorter than global (DELETE … WHERE Action=@channel AND OccurredAtUtc<@thr, batched). This runs from the purge/maintenance path, not the writer role — the append-only invariant binds the writer/ingest role, not maintenance. The M2.10 CI grep-guard is widened to allow the purge actor's single audited deletion call site (an allow-list entry, not a blanket exemption).
• Tests: a channel with a shorter override is purged earlier than the global; channels without an override follow the global; the guard still rejects UPDATE/DELETE everywhere except the sanctioned purge site.

T5 — Historical backfill (reframed per the computed-column reality)

• SourceNode is a physical nullable column. For truly historical rows the node-of-origin is unknowable, so the backfill sets a configurable sentinel (default "unknown") on NULL rows via a one-shot maintenance command (run from the purge/maintenance path), rather than guessing a node.
• ExecutionId/ParentExecutionId are persisted computed columns derived from DetailsJson; backfilling them means mutating the JSON, which append-only forbids. These are documented as a runbook limitation (pre-feature rows stay NULL) — no code.
• Tests: the SourceNode backfill sets the sentinel only on NULL rows within a bounded range and is idempotent; documentation note added.

---

Cross-cutting

• Shared seams: AuditLogOptions (T3, T7), AuditEndpoints.MapAuditAPI (T8), AuditCommands (T8), AuditCentralHealthSnapshot (T6, T7), IAuditLogRepository/the KPI repositories (T6), the purge/maintenance role (T3, T5). No AuditLog schema change in M5 (T1/T2 deferred).
• Append-only: the only new deletion is T3's purge-role channel delete + T5's purge-role sentinel UPDATE — both maintenance-path, both reflected in the CI guard's allow-list. Writer/ingest paths stay INSERT-only.

Testing strategy

Per-item unit + targeted integration tests (above). T4 additionally gets a tree-walk integration assertion. Full-solution build + targeted suites at the integration step. No new infra dependency (Parquet deferred).

Sequencing

Independent items, parallelizable by disjoint area:

• Wave A (parallel): T8 (CLI+endpoint), T6 (KPI repos+actors+tiles), T7 (middleware+health+redaction-override) — disjoint projects.
• Wave B (parallel): T4 (SiteRuntime actors — high-risk), T3 (AuditLog options+purge actor+CI guard), T5 (purge-path backfill command + runbook).
• Wave C: integration verification + docs (Component-AuditLog/-CLI, CLAUDE.md KPI/retention notes, runbook).

Risks

• T4 actor-model correlation (serialized state) — targeted tests + tree-walk assertion.
• T3 append-only tension — resolved via maintenance-role delete + CI-guard allow-list; verify the guard still blocks all other DELETE/UPDATE.
• T5 node-of-origin unknowable — sentinel + documented limitation (no false precision).