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,51 @@
|
||||
using ZB.MOM.WW.Configuration;
|
||||
|
||||
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
|
||||
|
||||
/// <summary>
|
||||
/// Options for the central <see cref="AuditLogHashChainService"/> (section
|
||||
/// <c>AuditLog:HashChain</c>) — hash-chain tamper evidence for the AuditLog
|
||||
/// (audit roadmap T1, alog.md §11.4, ScadaBridge#41).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Default OFF</b> (alog.md §11.4: "Default off … to avoid operational burden"). When
|
||||
/// enabled, both central nodes run the job; the SQL application lock means only one of
|
||||
/// them chains at a time, so a dual-active pair still produces one gap-free chain per month.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Enabling it on an existing database chains the historical backlog oldest month first,
|
||||
/// <see cref="BatchSize"/> × <see cref="MaxBatchesPerTick"/> rows per tick, so the first
|
||||
/// ticks run long. Rows chained late are only protected from the moment they are chained.
|
||||
/// Run <c>audit backfill-source-node</c> BEFORE enabling: a chained row's SourceNode is frozen.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class AuditLogHashChainOptions
|
||||
{
|
||||
/// <summary>Whether the chaining job runs (default false).</summary>
|
||||
public bool Enabled { get; set; }
|
||||
|
||||
/// <summary>Seconds between chaining ticks (default 60).</summary>
|
||||
public int IntervalSeconds { get; set; } = 60;
|
||||
|
||||
/// <summary>Rows linked per transaction (default 1000).</summary>
|
||||
public int BatchSize { get; set; } = 1000;
|
||||
|
||||
/// <summary>Upper bound on batches per tick so a backlog yields between ticks (default 100).</summary>
|
||||
public int MaxBatchesPerTick { get; set; } = 100;
|
||||
}
|
||||
|
||||
/// <summary>Validates <see cref="AuditLogHashChainOptions"/> at host startup.</summary>
|
||||
public sealed class AuditLogHashChainOptionsValidator : OptionsValidatorBase<AuditLogHashChainOptions>
|
||||
{
|
||||
/// <inheritdoc />
|
||||
protected override void Validate(ValidationBuilder builder, AuditLogHashChainOptions options)
|
||||
{
|
||||
builder.RequireThat(options.IntervalSeconds > 0,
|
||||
$"AuditLog:HashChain:{nameof(AuditLogHashChainOptions.IntervalSeconds)} ({options.IntervalSeconds}) must be > 0.");
|
||||
builder.RequireThat(options.BatchSize is > 0 and <= 10_000,
|
||||
$"AuditLog:HashChain:{nameof(AuditLogHashChainOptions.BatchSize)} ({options.BatchSize}) must be between 1 and 10000.");
|
||||
builder.RequireThat(options.MaxBatchesPerTick > 0,
|
||||
$"AuditLog:HashChain:{nameof(AuditLogHashChainOptions.MaxBatchesPerTick)} ({options.MaxBatchesPerTick}) must be > 0.");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user