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:
@@ -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);
|
||||
Reference in New Issue
Block a user