feat(audit): off-box chain-head export, verify-heads, maintenance login (ScadaBridge#107)

Item 1 (owner decision: no signing). AuditLog:HashChain:HeadExport (default
off): both centrals periodically read every month's chain head (LastSeq,
LastHash, purge anchor, chained rows, tombstones; one snapshot under the
chain lock SHARED) and append the changed heads to a sink the DB login cannot
write - File (append-only JSONL per node per day, local or UNC) or Syslog
(RFC 5424 over UDP / TCP octet counting). `audit verify-heads --path` reads
those records back (file or syslog-collector lines) and the new
VerifyAuditChainHeads command checks each against the database: Matches /
Extended / Purged, or Mismatch / Regressed / MissingHead / MissingLink /
CountMismatch (exit 3). AuditChainHeadStoreTests forges a chain with the
production hasher: verify-chain says Intact, verify-heads says Mismatch.

Item 3. AuditLog:MaintenanceConnectionString (${secret:}-capable, unset =
today's single login) runs the chain job, chain verify / head export, the
partition switch-out + archive and the per-channel purge on
AuditMaintenanceContext (keyed audit-maintenance repository/archive, purge
actor prefers them). AuditMaintenanceLoginTests runs the hardened setup on
SQL Server: writer (datareader/datawriter/audit_writer) ingests and is
refused chaining and deleting; the chainer+purger login does the full cycle.
Two-login grants documented in Component-AuditLog.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 23:16:05 -05:00
parent 5e7d5389d4
commit c4d7ec9b96
40 changed files with 2769 additions and 43 deletions
@@ -0,0 +1,87 @@
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>Where exported chain heads go.</summary>
public enum AuditChainHeadSinkKind
{
/// <summary>Append-only JSON-lines files in a directory (local or UNC).</summary>
File,
/// <summary>RFC 5424 syslog over UDP or TCP.</summary>
Syslog,
}
/// <summary>Syslog transport.</summary>
public enum AuditSyslogProtocol
{
/// <summary>One datagram per record (RFC 5426).</summary>
Udp,
/// <summary>Octet-counted frames on one TCP connection per export (RFC 6587).</summary>
Tcp,
}
/// <summary>
/// Off-box export of the AuditLog hash-chain heads (section <c>AuditLog:HashChain:HeadExport</c>,
/// ScadaBridge#107 item 1). <b>Default OFF.</b> Every <see cref="IntervalMinutes"/> both central
/// nodes read each month's chain head (month, last sequence + hash, partition-purge anchor,
/// chained-row and tombstone counts) and append the heads that changed since their previous
/// export to a sink the database login cannot write. <c>audit verify-heads</c> later compares
/// those records with the database: a chain someone rewrote and re-hashed inside SQL Server no
/// longer carries the hash that was exported.
/// </summary>
public sealed class AuditChainHeadExportOptions
{
/// <summary>Whether the export runs (default false).</summary>
public bool Enabled { get; set; }
/// <summary>Minutes between exports (default 60).</summary>
public int IntervalMinutes { get; set; } = 60;
/// <summary>
/// Re-export unchanged heads every tick too (default false: only heads whose sequence,
/// anchor or counts moved since this node's previous export, plus every head on the first
/// tick after start).
/// </summary>
public bool ExportUnchanged { get; set; }
/// <summary>Which sink (default <see cref="AuditChainHeadSinkKind.File"/>).</summary>
public AuditChainHeadSinkKind Sink { get; set; } = AuditChainHeadSinkKind.File;
/// <summary>File sink settings.</summary>
public AuditChainHeadFileSinkOptions File { get; set; } = new();
/// <summary>Syslog sink settings.</summary>
public AuditChainHeadSyslogSinkOptions Syslog { get; set; } = new();
}
/// <summary>File sink: <c>{Directory}/{yyyy}/audit-chain-heads-{yyyy-MM-dd}-{node}.jsonl</c>, opened for append only.</summary>
public sealed class AuditChainHeadFileSinkOptions
{
/// <summary>
/// Absolute directory (local path or UNC share). Give the service account create + append
/// rights only; the SQL Server login has no access to it by construction.
/// </summary>
public string? Directory { get; set; }
}
/// <summary>Syslog sink (RFC 5424).</summary>
public sealed class AuditChainHeadSyslogSinkOptions
{
/// <summary>Collector host name or address.</summary>
public string? Host { get; set; }
/// <summary>Collector port (default 514).</summary>
public int Port { get; set; } = 514;
/// <summary>Transport (default UDP).</summary>
public AuditSyslogProtocol Protocol { get; set; } = AuditSyslogProtocol.Udp;
/// <summary>Syslog facility 0–23 (default 13, "log audit").</summary>
public int Facility { get; set; } = 13;
/// <summary>APP-NAME field (default <c>scadabridge</c>).</summary>
public string AppName { get; set; } = "scadabridge";
/// <summary>Send/connect timeout in seconds (default 10).</summary>
public int TimeoutSeconds { get; set; } = 10;
}