feat(audit): SHA-256 hash chain over the central AuditLog (ScadaBridge#41)
Audit roadmap T1 (alog.md §11.4): one chain per UTC calendar month of OccurredAtUtc. Each chained row carries ChainSeq (gap-free within its month) and RowHash = SHA-256(prev.RowHash || canonical(row)); the v1 canonical form (AuditChainHasher) is pinned by a known-answer vector computed independently. - Migration AddAuditLogHashChain: nullable ChainSeq/RowHash on dbo.AuditLog (metadata-only add), AuditLogChainHead (per-month chain end + partition-purge checkpoint anchor), AuditLogChainTombstone, two partition-aligned filtered indexes, scadabridge_audit_chainer role with a column-level UPDATE grant. Production script docs/plans/sql/AddAuditLogHashChain.sql. - AuditLogHashChain chains unchained rows oldest month first under an exclusive sp_getapplock (zero timeout, so a dual-active central pair still yields one chain), with an optimistic head check and a ChainSeq IS NULL row-count check that roll a pass back instead of leaving a gap. The ingest path is untouched. - Purges keep the chain verifiable: the partition switch records the month's checkpoint anchor and drops its tombstones; the per-channel DELETE writes a tombstone per chained row in the same transaction (OUTPUT INTO). Both, and the SourceNode backfill, hold the chain lock; the backfill skips chained rows. The switch staging table gains the two new columns. - AuditChainVerifier reports the first break (partition, ChainSeq, EventId, kind) for edited, deleted, reordered rows and tail truncation. - AuditLogHashChainService (central, default OFF via AuditLog:HashChain). Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
@@ -0,0 +1,46 @@
|
||||
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
|
||||
|
||||
namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
|
||||
|
||||
/// <summary>
|
||||
/// Hash-chain tamper evidence for the central <c>AuditLog</c> table (audit roadmap T1,
|
||||
/// alog.md §11.4, ScadaBridge#41).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// One chain per <b>partition</b> = UTC calendar month of <c>OccurredAtUtc</c> (the same
|
||||
/// month the <c>ps_AuditLog_Month</c> scheme partitions on). Each chained row carries a
|
||||
/// <c>ChainSeq</c> (1, 2, 3 … within its month) and
|
||||
/// <c>RowHash = SHA-256(prev.RowHash || canonical(row))</c>, where <c>prev</c> is the row
|
||||
/// at <c>ChainSeq - 1</c> (32 zero bytes for the first). The canonical serialisation
|
||||
/// covers every writable column plus the month and sequence number.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Rows are linked by a <b>chaining job</b>, not by the hot-path writers: two central
|
||||
/// nodes and the site-ingest path all INSERT concurrently, so a write-time chain would
|
||||
/// need a global serialisation point on every audit write. The job serialises itself
|
||||
/// with an exclusive SQL Server application lock, so even a dual-active central pair
|
||||
/// produces one gap-free chain per month.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public interface IAuditLogHashChain
|
||||
{
|
||||
/// <summary>
|
||||
/// Links up to <paramref name="batchSize"/> unchained rows (oldest
|
||||
/// <c>OccurredAtUtc</c> first) onto the end of their month's chain, in one transaction.
|
||||
/// Returns immediately with <see cref="AuditChainBatchResult.LockBusy"/> set when another
|
||||
/// chainer holds the chain lock.
|
||||
/// </summary>
|
||||
/// <param name="batchSize">Maximum rows to chain in this pass.</param>
|
||||
/// <param name="ct">Cancellation token.</param>
|
||||
/// <returns>How many rows were chained, and whether the lock was busy.</returns>
|
||||
Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, CancellationToken ct = default);
|
||||
|
||||
/// <summary>
|
||||
/// Verifies one month's chain end to end and reports the first break.
|
||||
/// </summary>
|
||||
/// <param name="monthStartUtc">The first instant of the month (UTC, day 1, midnight).</param>
|
||||
/// <param name="ct">Cancellation token.</param>
|
||||
/// <returns>The verification result.</returns>
|
||||
Task<AuditChainVerificationResult> VerifyMonthAsync(DateTime monthStartUtc, CancellationToken ct = default);
|
||||
}
|
||||
@@ -155,6 +155,11 @@ public interface IAuditLogRepository
|
||||
/// <c>OccurredAtUtc</c> is strictly older than <paramref name="threshold"/>, in
|
||||
/// bounded batches of <paramref name="batchSize"/> rows, looping until no further
|
||||
/// rows match. Returns the total number of rows deleted across all batches.
|
||||
/// <para>
|
||||
/// Hash chain (ScadaBridge#41): every CHAINED row the DELETE removes leaves a
|
||||
/// <c>dbo.AuditLogChainTombstone</c> (month, ChainSeq, RowHash) written in the same
|
||||
/// transaction, under the exclusive chain lock, so the month's chain still verifies.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
|
||||
|
||||
/// <summary>
|
||||
/// Overall outcome of verifying one month's AuditLog hash chain (audit roadmap T1,
|
||||
/// ScadaBridge#41).
|
||||
/// </summary>
|
||||
[JsonConverter(typeof(JsonStringEnumConverter<AuditChainStatus>))]
|
||||
public enum AuditChainStatus
|
||||
{
|
||||
/// <summary>Every chained row, tombstone and the chain head agree.</summary>
|
||||
Intact,
|
||||
|
||||
/// <summary>The chain is broken; <see cref="AuditChainVerificationResult.FirstBreak"/> names where.</summary>
|
||||
Broken,
|
||||
|
||||
/// <summary>The month has no chained rows and no chain head — nothing to verify yet.</summary>
|
||||
NotChained,
|
||||
}
|
||||
|
||||
/// <summary>How the first chain break manifested.</summary>
|
||||
[JsonConverter(typeof(JsonStringEnumConverter<AuditChainBreakKind>))]
|
||||
public enum AuditChainBreakKind
|
||||
{
|
||||
/// <summary>
|
||||
/// A row's recomputed hash differs from its stored <c>RowHash</c>: the row's content
|
||||
/// was edited, or rows were reordered (their <c>ChainSeq</c> values swapped).
|
||||
/// </summary>
|
||||
HashMismatch,
|
||||
|
||||
/// <summary>
|
||||
/// A sequence number is absent and no purge tombstone covers it: a chained row was
|
||||
/// deleted outside the sanctioned purge path, or its <c>ChainSeq</c> was cleared.
|
||||
/// </summary>
|
||||
MissingRow,
|
||||
|
||||
/// <summary>Two rows carry the same <c>ChainSeq</c>.</summary>
|
||||
DuplicateSequence,
|
||||
|
||||
/// <summary>A chained row carries a <c>ChainSeq</c> but no <c>RowHash</c> (or vice versa).</summary>
|
||||
IncompleteLink,
|
||||
|
||||
/// <summary>
|
||||
/// The chain ends before (or after) the sequence/hash the chain head records: rows were
|
||||
/// deleted from the tail, or the head itself was altered.
|
||||
/// </summary>
|
||||
HeadMismatch,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The first point at which a month's chain fails verification.
|
||||
/// </summary>
|
||||
/// <param name="Partition">The chain partition — the UTC calendar month, formatted <c>YYYY-MM</c>.</param>
|
||||
/// <param name="ChainSeq">The sequence number at which the break was detected.</param>
|
||||
/// <param name="EventId">
|
||||
/// The <c>EventId</c> of the row at (or, for <see cref="AuditChainBreakKind.MissingRow"/>,
|
||||
/// immediately after) the break; null when no row is present there (tail truncation).
|
||||
/// </param>
|
||||
/// <param name="Kind">How the break manifested.</param>
|
||||
/// <param name="Detail">Human-readable explanation.</param>
|
||||
public sealed record AuditChainBreak(
|
||||
string Partition,
|
||||
long ChainSeq,
|
||||
Guid? EventId,
|
||||
AuditChainBreakKind Kind,
|
||||
string Detail);
|
||||
|
||||
/// <summary>
|
||||
/// Result of <c>audit verify-chain --month YYYY-MM</c>: whether the month's AuditLog hash
|
||||
/// chain is intact, and if not, the first break.
|
||||
/// </summary>
|
||||
/// <param name="Partition">The chain partition verified (<c>YYYY-MM</c>).</param>
|
||||
/// <param name="Status">Overall outcome.</param>
|
||||
/// <param name="RowsVerified">Chained rows whose hash was recomputed and matched before the first break (or in total when intact).</param>
|
||||
/// <param name="TombstonesApplied">Sequence numbers bridged by a sanctioned purge tombstone (per-channel retention).</param>
|
||||
/// <param name="PurgedThroughSeq">
|
||||
/// The checkpoint anchor left by a monthly partition purge: the last sequence number the
|
||||
/// purge removed. Verification starts immediately after it. Null when the month was never purged.
|
||||
/// </param>
|
||||
/// <param name="HeadSeq">The last sequence number the chain head records, or null when the month has no head.</param>
|
||||
/// <param name="UnchainedRows">
|
||||
/// Rows in the month the chaining job has not reached yet (written since the last tick, or
|
||||
/// written while chaining was disabled). They are not covered by the chain.
|
||||
/// </param>
|
||||
/// <param name="FirstBreak">The first break, or null when <see cref="Status"/> is not <see cref="AuditChainStatus.Broken"/>.</param>
|
||||
public sealed record AuditChainVerificationResult(
|
||||
string Partition,
|
||||
AuditChainStatus Status,
|
||||
long RowsVerified,
|
||||
long TombstonesApplied,
|
||||
long? PurgedThroughSeq,
|
||||
long? HeadSeq,
|
||||
long UnchainedRows,
|
||||
AuditChainBreak? FirstBreak);
|
||||
|
||||
/// <summary>Outcome of one chaining pass over unchained AuditLog rows.</summary>
|
||||
/// <param name="RowsChained">Rows linked into a chain by this pass.</param>
|
||||
/// <param name="LockBusy">True when another chainer (the peer central node) held the chain lock, so this pass did nothing.</param>
|
||||
public sealed record AuditChainBatchResult(int RowsChained, bool LockBusy);
|
||||
Reference in New Issue
Block a user