feat(audit): persist OPC UA certificate-trust decisions to the central audit log (ScadaBridge#43)

New AuditChannel.Security with AuditKind.CertTrust / CertTrustRemove (appended, ordinals stable).
Both central entry points - the management actor handlers and the Central UI CertManagementService -
write a best-effort ICentralAuditWriter row after the site outcome is known (Delivered when all
reachable site nodes acked, Failed otherwise, incl. relay timeouts), naming actor, site, thumbprint
and connection. Shared builder: CertTrustAuditEvents.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 15:17:03 -05:00
parent f98369a786
commit f5eed5e8fd
10 changed files with 322 additions and 22 deletions
@@ -12,6 +12,11 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
// singleton (active node only). For trust/remove it broadcasts the
// corresponding per-node internal message to the per-node CertStoreActor on
// EVERY site cluster node; for list it answers from the local node.
//
// The decision itself IS recorded centrally (Gitea #43): both central entry points (the
// management actor and the Central UI CertManagementService) write an AuditChannel.Security
// AuditLog row (AuditKind.CertTrust / CertTrustRemove) naming the actor, site and thumbprint,
// with Delivered/Failed per the aggregate site outcome. Only the certificate itself stays site-local.
// ─────────────────────────────────────────────────────────────────────────────
/// <summary>
@@ -0,0 +1,46 @@
using System.Text.Json;
using ZB.MOM.WW.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
/// <summary>
/// Builds the central <see cref="AuditEvent"/> recording an OPC UA server-certificate trust
/// decision (Gitea #43). The trusted-peer PKI store is site-local and each decision is already
/// broadcast to both site nodes; this is the central, queryable record of WHO made the decision.
/// Shared by the two central entry points (the management actor and the Central UI service) so
/// both emit the identical row shape.
/// </summary>
public static class CertTrustAuditEvents
{
/// <summary>Builds the audit row for a trust or remove decision after its outcome is known.</summary>
/// <param name="remove">True for a trust removal, false for a trust grant.</param>
/// <param name="actor">The authenticated user who made the decision.</param>
/// <param name="siteIdentifier">The site whose PKI stores were targeted.</param>
/// <param name="thumbprint">The certificate thumbprint.</param>
/// <param name="connectionName">The data connection the certificate was captured from (trust only).</param>
/// <param name="result">The aggregate site outcome, or null when the relay threw before an outcome.</param>
/// <param name="exceptionMessage">The relay failure message when <paramref name="result"/> is null.</param>
/// <returns>The audit event, ready for <c>ICentralAuditWriter.WriteAsync</c>.</returns>
public static AuditEvent Create(
bool remove,
string actor,
string siteIdentifier,
string thumbprint,
string? connectionName,
CertTrustResult? result,
string? exceptionMessage = null)
{
var succeeded = result?.Success == true;
return ScadaBridgeAuditEventFactory.Create(
channel: AuditChannel.Security,
kind: remove ? AuditKind.CertTrustRemove : AuditKind.CertTrust,
status: succeeded ? AuditStatus.Delivered : AuditStatus.Failed,
actor: actor,
target: $"{siteIdentifier}/{thumbprint}",
sourceSiteId: siteIdentifier,
errorMessage: succeeded ? null : (result?.Error ?? exceptionMessage ?? "Unknown error."),
extra: JsonSerializer.Serialize(new { thumbprint, siteIdentifier, connectionName }));
}
}
@@ -29,5 +29,12 @@ public enum AuditChannel
/// (plus the always-on <see cref="AuditKind.RouteCall"/>). Appended last so stored
/// ordinals of existing channels never move.
/// </summary>
ScriptTrace
ScriptTrace,
/// <summary>
/// Operator-initiated security-trust decisions made through the central management surface
/// (UI, CLI, HTTP Management API) — currently OPC UA server-certificate trust and removal.
/// Appended last so stored ordinals of existing channels never move. (Gitea #43)
/// </summary>
Security
}
@@ -64,5 +64,19 @@ public enum AuditKind
AttributeWait,
/// <summary>One log line a traced script (or the runtime on its behalf) wrote; folded into its owning step by the Flow Debugger, never a node (design 2026-09-09 D1).</summary>
ScriptLog
ScriptLog,
/// <summary>
/// An administrator trusted an OPC UA server certificate for a site's data connection
/// (<see cref="AuditChannel.Security"/>). One row per decision, written after the site
/// reports the outcome: <see cref="AuditStatus.Delivered"/> when every reachable site node
/// acked, <see cref="AuditStatus.Failed"/> otherwise (Gitea #43).
/// </summary>
CertTrust,
/// <summary>
/// An administrator removed trust for an OPC UA server certificate at a site
/// (<see cref="AuditChannel.Security"/>); same status semantics as <see cref="CertTrust"/> (Gitea #43).
/// </summary>
CertTrustRemove
}