From 47af424c2e9d14b3423dd1be45c851afb0fad6d8 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Mon, 9 Nov 2026 15:27:48 -0500 Subject: [PATCH] docs(audit-log): list all audit channels and their kinds, incl. Cluster and ScriptTrace (ScadaBridge#102 item 5) Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV --- docs/components/AuditLog.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/components/AuditLog.md b/docs/components/AuditLog.md index f9d6bd33..a16893a0 100644 --- a/docs/components/AuditLog.md +++ b/docs/components/AuditLog.md @@ -18,7 +18,22 @@ The same DI entry point, `ServiceCollectionExtensions.AddAuditLog`, registers th ### Script trust boundary -The audited scope is the script trust boundary, not framework traffic. The four channels are modelled by the `AuditChannel` enum (`ApiOutbound`, `DbOutbound`, `Notification`, `ApiInbound`), and the specific action by `AuditKind` (for example `ApiCall`, `DbWriteCached`, `NotifySend`, `InboundRequest`). Every row is built through `ScadaBridgeAuditEventFactory.Create`, which maps the domain vocabulary onto the canonical record: `Channel`/`Kind`/`Status` become `Action`/`Category`/`Outcome` plus a `DetailsJson` extension bag carrying every other domain field. +The audited scope is the script trust boundary, not framework traffic, plus a small set of operator-initiated central acts. Channels are modelled by the `AuditChannel` enum and the specific action by `AuditKind`. Every row is built through `ScadaBridgeAuditEventFactory.Create`, which maps the domain vocabulary onto the canonical record: `Channel`/`Kind`/`Status` become `Action`/`Category`/`Outcome` plus a `DetailsJson` extension bag carrying every other domain field. + +The channels and the kinds each one carries (derived from `AuditChannel.cs` / `AuditKind.cs` and the emitting call sites): + +| Channel | Kinds | What it records | +|---|---|---| +| `ApiOutbound` | `ApiCall`, `ApiCallCached`, `CachedSubmit`, `CachedResolve` | Script calls to external systems; cached variants emit several rows per operation. | +| `DbOutbound` | `DbWrite`, `DbWriteCached`, `CachedSubmit`, `CachedResolve` | Script database writes. | +| `Notification` | `NotifySend`, `NotifyDeliver` | Notification submit and delivery. | +| `ApiInbound` | `InboundRequest`, `InboundAuthFailure` | Inbound API requests and auth failures. | +| `SecuredWrite` | `SecuredWriteSubmit`, `SecuredWriteApprove`, `SecuredWriteReject`, `SecuredWriteExecute`, `SecuredWriteExpire` | Two-person secured-write lifecycle; `Expire` is a system-emitted TTL lapse. | +| `Cluster` | `ManualFailover` | An administrator's manual failover of the central pair (Health page); one row per invocation, written before the Leave is issued. | +| `ScriptTrace` | `RouteCall`, `ScriptRun`, `AttributeWrite`, `AttributeWait`, `ScriptLog` | Flow Debugger trace rows. `RouteCall` is always-on; the others are emitted only for traced executions. `ScriptLog` is folded into its owning step by the Flow Debugger and is never a node. | +| `Security` | `CertTrust`, `CertTrustRemove` | Operator trust decisions for OPC UA server certificates (Gitea #43). | + +`ReconciliationAbandoned` (a permanently-lost reconciliation-pull row, emitted once by `SiteAuditReconciliationActor`) is a synthetic row that reuses the channel of the row that was lost (falling back to `ApiOutbound`), so it appears under whichever channel above lost the data. ### Canonical `AuditEvent` and `DetailsJson`