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,28 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
/// <summary>
/// Reads the AuditLog hash-chain heads for off-box export and checks exported heads against
/// the database chain (ScadaBridge#107 item 1 — the external anchor of the #41 chain).
/// </summary>
public interface IAuditChainHeadStore
{
/// <summary>
/// Reads every month's chain head with its live chained-row and tombstone counts, in one
/// consistent snapshot (under the chain lock SHARED, so no chaining pass or purge is half-way).
/// </summary>
/// <param name="ct">Cancellation token.</param>
/// <returns>One snapshot per month that has a head, oldest first.</returns>
Task<IReadOnlyList<AuditChainHeadSnapshot>> ReadHeadsAsync(CancellationToken ct = default);
/// <summary>
/// Checks exported head records against the database: for each distinct exported head, does
/// the database still carry the exported hash at the exported sequence?
/// </summary>
/// <param name="records">Exported records (duplicates are collapsed).</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The per-record verdicts.</returns>
Task<AuditChainHeadVerificationResult> VerifyExportedHeadsAsync(
IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct = default);
}
@@ -1,4 +1,5 @@
using ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
@@ -32,6 +33,15 @@ public record AuditLogQueryResult(IReadOnlyList<AuditLogEntry> Entries, int Tota
/// <param name="Month">The month to verify, <c>YYYY-MM</c>.</param>
public record VerifyAuditChainCommand(string Month);
/// <summary>
/// Checks AuditLog chain heads exported off-box (<c>AuditLog:HashChain:HeadExport</c>,
/// ScadaBridge#107 item 1) against the database chain: does the database still carry each
/// exported hash at its exported sequence? Read-only; same gate as
/// <see cref="VerifyAuditChainCommand"/>. The CLI reads the records from the export files.
/// </summary>
/// <param name="Records">The exported head records (at most 50,000; duplicates are collapsed).</param>
public record VerifyAuditChainHeadsCommand(IReadOnlyList<AuditChainHeadRecord> Records);
/// <summary>
/// Lists the AuditLog Parquet cold archives under the configured archive directory (audit
/// roadmap T2, ScadaBridge#42). Read-only; OperationalAudit roles, refused for a site-scoped
@@ -0,0 +1,126 @@
using System.Text.Json.Serialization;
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
/// <summary>
/// One month's AuditLog hash-chain head as exported off-box (ScadaBridge#107 item 1). The
/// export is the external anchor the in-database chain lacks: a principal able to rewrite rows,
/// recompute every later link and update <c>AuditLogChainHead</c> produces a chain that
/// <c>verify-chain</c> accepts, but cannot change a head hash that already left the box.
/// </summary>
/// <remarks>
/// Serialised as one JSON object per line (camelCase) by both export sinks; the
/// <c>audit verify-heads</c> CLI reads those lines back and the server compares them with the
/// database. Hashes are lowercase hex. The format is versioned by <see cref="V"/>.
/// </remarks>
/// <param name="V">Record format version (1).</param>
/// <param name="Month">Chain partition, the UTC calendar month <c>YYYY-MM</c>.</param>
/// <param name="LastSeq">The head's last sequence number — links written for the month so far.</param>
/// <param name="LastHash">The head's last link hash (hex).</param>
/// <param name="PurgedThroughSeq">The partition-purge checkpoint anchor's sequence, or null.</param>
/// <param name="PurgedThroughHash">The anchor's hash (hex), or null.</param>
/// <param name="ChainedRows">Chained rows of the month still in <c>dbo.AuditLog</c> at export time.</param>
/// <param name="Tombstones">Per-channel purge tombstones of the month at export time.</param>
/// <param name="HeadUpdatedAtUtc">When the head row was last advanced.</param>
/// <param name="ExportedAtUtc">When this record was exported.</param>
/// <param name="Node">The central node that exported it.</param>
public sealed record AuditChainHeadRecord(
int V,
string Month,
long LastSeq,
string LastHash,
long? PurgedThroughSeq,
string? PurgedThroughHash,
long ChainedRows,
long Tombstones,
DateTime HeadUpdatedAtUtc,
DateTime ExportedAtUtc,
string? Node)
{
/// <summary>The current record format version.</summary>
public const int CurrentVersion = 1;
}
/// <summary>Outcome of comparing one exported head with the database chain.</summary>
[JsonConverter(typeof(JsonStringEnumConverter<AuditChainHeadStatus>))]
public enum AuditChainHeadStatus
{
/// <summary>The database head is exactly the exported head (same sequence, same hash, same row + tombstone count).</summary>
Matches,
/// <summary>The chain has grown since the export and the link at the exported sequence still carries the exported hash.</summary>
Extended,
/// <summary>
/// The link at the exported sequence was removed by a monthly partition purge (it is at or
/// before the checkpoint anchor and not the anchor itself), so the database cannot confirm
/// it; verify the month's Parquet archive instead (<c>audit archive verify</c>).
/// </summary>
Purged,
/// <summary>The link at the exported sequence carries a different hash: the chain was rewritten.</summary>
Mismatch,
/// <summary>The database head's sequence is BELOW the exported one: links were removed and the head rolled back.</summary>
Regressed,
/// <summary>The month's head row is gone although links had been exported for it.</summary>
MissingHead,
/// <summary>No row, tombstone or anchor carries the exported sequence any more: a chained row was deleted outside the purge paths.</summary>
MissingLink,
/// <summary>
/// Same head as exported, no partition purge since, but chained rows + tombstones differ
/// from the exported counts: a chained row was removed or its link cleared.
/// </summary>
CountMismatch,
}
/// <summary>One exported head checked against the database.</summary>
/// <param name="Month">Chain partition (<c>YYYY-MM</c>).</param>
/// <param name="ExportedSeq">The exported head's sequence.</param>
/// <param name="ExportedAtUtc">When it was exported.</param>
/// <param name="Node">Which node exported it.</param>
/// <param name="Status">The verdict.</param>
/// <param name="DatabaseSeq">The database head's current sequence, or null when it has none.</param>
/// <param name="Detail">Human-readable explanation.</param>
public sealed record AuditChainHeadCheck(
string Month,
long ExportedSeq,
DateTime ExportedAtUtc,
string? Node,
AuditChainHeadStatus Status,
long? DatabaseSeq,
string Detail)
{
/// <summary>True for the verdicts that are tamper evidence.</summary>
[JsonIgnore]
public bool IsFailure => Status is AuditChainHeadStatus.Mismatch or AuditChainHeadStatus.Regressed
or AuditChainHeadStatus.MissingHead or AuditChainHeadStatus.MissingLink or AuditChainHeadStatus.CountMismatch;
}
/// <summary>Result of <c>audit verify-heads</c>.</summary>
/// <param name="Verified">True when no check is a failure.</param>
/// <param name="RecordsChecked">Distinct exported heads checked.</param>
/// <param name="Checks">Every check, failures first, then by month and sequence.</param>
public sealed record AuditChainHeadVerificationResult(bool Verified, int RecordsChecked, IReadOnlyList<AuditChainHeadCheck> Checks);
/// <summary>The database's current chain head for a month, as read for export.</summary>
/// <param name="Month">First instant of the month (UTC).</param>
/// <param name="LastSeq">Head sequence.</param>
/// <param name="LastHash">Head hash.</param>
/// <param name="PurgedThroughSeq">Checkpoint anchor sequence, or null.</param>
/// <param name="PurgedThroughHash">Checkpoint anchor hash, or null.</param>
/// <param name="ChainedRows">Chained rows of the month still present.</param>
/// <param name="Tombstones">Tombstones of the month.</param>
/// <param name="UpdatedAtUtc">When the head row was last advanced.</param>
public sealed record AuditChainHeadSnapshot(
DateTime Month,
long LastSeq,
byte[] LastHash,
long? PurgedThroughSeq,
byte[]? PurgedThroughHash,
long ChainedRows,
long Tombstones,
DateTime UpdatedAtUtc);