feat(audit)!: remove the AuditLog hash chain, head export and two-login maintenance hardening
Owner decision 2026-11-15, at IT security's request, pending a family-wide general solution. Removed: the chaining service, hasher, verifier, chain head/tombstone entities and store, the #139 chain-start cutoff, AuditLog:HashChain (incl. ChainBacklog and HeadExport with its File/Syslog sinks and export service), the audit-chain-head-export health check, the VerifyAuditChain / VerifyAuditChainHeads management commands and the `audit verify-chain` / `audit verify-heads` CLI commands, and the two-login plumbing (AuditLog:MaintenanceConnectionString, AuditMaintenanceContext, the keyed audit-maintenance repository/archive). Purge, archive, retention, partition roll-forward and backfill-source-node all run on the runtime connection again, as before #107. Parquet archive (#42) kept, chain-free: format v2 (ten stored columns, no tombstone file, manifest without chain state), the switch guard is the row count only (51003 gone), verify = data-file size, SHA-256 and row count, and superseded-stale cleanup proves coverage by EventId. Format-v1 archives still list, verify and are cleaned up (their tombstone file too). Migration RemoveAuditLogHashChain drops the chain indexes, the scadabridge_audit_chainer role (members first), both chain tables, ChainSeq/RowHash and the purger's AuditMaintenanceGrants grants; writer/purger roles stay. Down restores them. Every chain-column reference is EXEC-deferred for the idempotent script (#126); FlipAuditLogClusteredKey's two chain index statements get the same deferral, behaviour unchanged, so re-running the idempotent script on a migrated database works. The partition-switch staging table adds the chain columns only when the live table has them, so the new binary purges either schema. Deploy gate: old binaries map the chain columns, so the migration ships with the new binaries, both centrals stopped. A leftover AuditLog:HashChain section or MaintenanceConnectionString (DEV/QA still carry AuditLog__HashChain__Enabled=true) is ignored with one startup warning (RetiredAuditSettingsWarning). Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
This commit is contained in:
@@ -1,11 +0,0 @@
|
||||
namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
|
||||
|
||||
/// <summary>DI keys for the AuditLog maintenance-login registrations (ScadaBridge#107/#113).</summary>
|
||||
public static class AuditLogServiceKeys
|
||||
{
|
||||
/// <summary>
|
||||
/// Key of the maintenance-login <see cref="IAuditLogRepository"/> / <c>IAuditLogArchive</c>:
|
||||
/// the connection from <c>AuditLog:MaintenanceConnectionString</c>, or the runtime connection when unset.
|
||||
/// </summary>
|
||||
public const string Maintenance = "audit-maintenance";
|
||||
}
|
||||
@@ -1,28 +0,0 @@
|
||||
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);
|
||||
}
|
||||
@@ -10,16 +10,10 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Archive before purge.</b> <see cref="ArchivePartitionAsync"/> writes the partition's
|
||||
/// rows (with their hash-chain columns), the month's chain head and its per-channel purge
|
||||
/// tombstones; <see cref="PurgeArchivedPartitionAsync"/> then switches the partition out
|
||||
/// inside a guard that refuses to drop it if the partition gained or lost a row, or its
|
||||
/// chain advanced, since the archive was written. A partition is therefore never purged
|
||||
/// without an archive that holds exactly the rows the purge drops.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Hash chain.</b> The switch records each month's chain end as the checkpoint anchor
|
||||
/// (ScadaBridge#41); the archive records the same chain end, so <see cref="VerifyAsync"/>
|
||||
/// can recompute the archived chain and tie its end to the anchor still in the database.
|
||||
/// rows; <see cref="PurgeArchivedPartitionAsync"/> then switches the partition out inside a
|
||||
/// guard that refuses to drop it if the partition gained or lost a row since the archive was
|
||||
/// written. A partition is therefore never purged without an archive that holds exactly the
|
||||
/// rows the purge drops.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public interface IAuditLogArchive
|
||||
@@ -58,8 +52,7 @@ public interface IAuditLogArchive
|
||||
Task<IReadOnlyList<AuditArchiveManifest>> ListAsync(CancellationToken ct = default);
|
||||
|
||||
/// <summary>
|
||||
/// Verifies one archive: file integrity against the manifest, the hash chain recomputed
|
||||
/// over the archived rows, and the chain end against the database's checkpoint anchor.
|
||||
/// Verifies one archive: data-file integrity (size, SHA-256, row count) against the manifest.
|
||||
/// </summary>
|
||||
/// <param name="name">The archive name (as <see cref="ListAsync"/> reports it).</param>
|
||||
/// <param name="ct">Cancellation token.</param>
|
||||
@@ -70,7 +63,7 @@ public interface IAuditLogArchive
|
||||
/// <summary>
|
||||
/// Archive cleanup (ScadaBridge#109): deletes superseded stale archives a retried purge left
|
||||
/// behind (when <c>AuditLog:Archive:DeleteSupersededStaleArchives</c>), and archives past
|
||||
/// <c>AuditLog:Archive:RetentionDays</c> (0 = never). Only ever deletes the three files of a
|
||||
/// <c>AuditLog:Archive:RetentionDays</c> (0 = never). Only ever deletes the files of a
|
||||
/// well-formed archive inside the configured directory, manifest first.
|
||||
/// </summary>
|
||||
/// <param name="dryRun">Report only; delete nothing.</param>
|
||||
@@ -81,7 +74,7 @@ public interface IAuditLogArchive
|
||||
|
||||
/// <summary>
|
||||
/// Thrown by <see cref="IAuditLogArchive.PurgeArchivedPartitionAsync"/> when the partition
|
||||
/// gained or lost rows, or its hash chain advanced, after the archive was written. Nothing
|
||||
/// gained or lost rows after the archive was written. Nothing
|
||||
/// is purged; the next purge tick writes a fresh archive.
|
||||
/// </summary>
|
||||
public sealed class AuditArchiveStaleException : Exception
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
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>
|
||||
/// <remarks>
|
||||
/// <b>Chain start (ScadaBridge#139).</b> On a pristine database (nothing ever chained) and
|
||||
/// with <paramref name="chainBacklog"/> false, the first pass records a chain-start anchor
|
||||
/// at the database's current UTC time; from then on only rows dated at or after it are
|
||||
/// chained, whatever either node passes later. With <paramref name="chainBacklog"/> true on
|
||||
/// that first pass, no anchor is written and every row is chained, oldest month first. A
|
||||
/// database that already has a chain and no anchor keeps chaining every row.
|
||||
/// </remarks>
|
||||
/// <param name="batchSize">Maximum rows to chain in this pass.</param>
|
||||
/// <param name="chainBacklog">
|
||||
/// Only consulted on a pristine database: true chains the historical backlog instead of
|
||||
/// starting the chain now.
|
||||
/// </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, bool chainBacklog = false, 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);
|
||||
}
|
||||
@@ -158,11 +158,6 @@ 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>
|
||||
|
||||
@@ -25,23 +25,6 @@ public record QueryAuditLogCommand(
|
||||
/// <param name="TotalCount">Total number of rows matching the filters (unpaged).</param>
|
||||
public record AuditLogQueryResult(IReadOnlyList<AuditLogEntry> Entries, int TotalCount);
|
||||
|
||||
/// <summary>
|
||||
/// Verifies the central AuditLog hash chain for one UTC calendar month (audit roadmap T1,
|
||||
/// ScadaBridge#41). Read-only; gated on the OperationalAudit roles and refused for a
|
||||
/// site-scoped caller, because a month's chain spans every site.
|
||||
/// </summary>
|
||||
/// <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
|
||||
@@ -50,9 +33,8 @@ public record VerifyAuditChainHeadsCommand(IReadOnlyList<AuditChainHeadRecord> R
|
||||
public record ListAuditArchivesCommand;
|
||||
|
||||
/// <summary>
|
||||
/// Verifies one AuditLog Parquet archive (ScadaBridge#42): file integrity against its
|
||||
/// manifest, the hash chain recomputed over the archived rows, and the chain end against the
|
||||
/// checkpoint anchor the partition purge left. Read-only; same gate as
|
||||
/// Verifies one AuditLog Parquet archive (ScadaBridge#42): data-file integrity against its
|
||||
/// manifest (size, SHA-256, row count). Read-only; same gate as
|
||||
/// <see cref="ListAuditArchivesCommand"/>.
|
||||
/// </summary>
|
||||
/// <param name="Name">The archive name, as <c>audit archive list</c> reports it.</param>
|
||||
|
||||
@@ -11,8 +11,7 @@ public enum AuditArchiveStatus
|
||||
/// <summary>
|
||||
/// The archive files are durable but the partition switch that should follow has not
|
||||
/// been confirmed: either it failed (the archive went stale and a later tick wrote a
|
||||
/// fresh one) or the node stopped between the switch and the manifest update. Verify
|
||||
/// tells the two apart: only the second one's chain end matches the database anchor.
|
||||
/// fresh one) or the node stopped between the switch and the manifest update.
|
||||
/// </summary>
|
||||
Archived,
|
||||
|
||||
@@ -20,48 +19,25 @@ public enum AuditArchiveStatus
|
||||
Purged,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// One chain partition (UTC calendar month) as it stood when its rows were archived: the
|
||||
/// chain head and the checkpoint anchor an earlier partition purge had left, so the archived
|
||||
/// rows can be re-verified with <c>AuditChainVerifier</c> long after the database dropped them.
|
||||
/// </summary>
|
||||
/// <param name="Partition">The chain partition, <c>YYYY-MM</c>.</param>
|
||||
/// <param name="LastSeq">The head's last sequence number at archive time.</param>
|
||||
/// <param name="LastHash">The head's last hash at archive time (lowercase hex).</param>
|
||||
/// <param name="PriorPurgedThroughSeq">The checkpoint anchor an earlier purge of this month left, or null.</param>
|
||||
/// <param name="PriorPurgedThroughHash">The hash at <paramref name="PriorPurgedThroughSeq"/> (lowercase hex), or null.</param>
|
||||
/// <param name="TombstoneCount">Per-channel purge tombstones of this month carried in the archive.</param>
|
||||
public sealed record AuditArchiveChainState(
|
||||
string Partition,
|
||||
long LastSeq,
|
||||
string LastHash,
|
||||
long? PriorPurgedThroughSeq,
|
||||
string? PriorPurgedThroughHash,
|
||||
long TombstoneCount);
|
||||
|
||||
/// <summary>
|
||||
/// The JSON manifest written beside every AuditLog Parquet archive (ScadaBridge#42). It is
|
||||
/// written LAST, so its presence is the commit marker for the archive's two Parquet files.
|
||||
/// written LAST, so its presence is the commit marker for the archive's Parquet data file.
|
||||
/// A format-v1 manifest (written while the audit hash chain existed, before 2026-11-15) also
|
||||
/// carries chain and tombstone fields; they are ignored when it is read.
|
||||
/// </summary>
|
||||
/// <param name="FormatVersion">Manifest/file layout version (currently 1).</param>
|
||||
/// <param name="Name">Archive name, <c>auditlog-YYYY-MM-yyyyMMddTHHmmssfffZ</c>; the file stem of all three files.</param>
|
||||
/// <param name="FormatVersion">Manifest/file layout version (currently 2; 1 = written with the hash chain).</param>
|
||||
/// <param name="Name">Archive name, <c>auditlog-YYYY-MM-yyyyMMddTHHmmssfffZ</c>; the file stem of the archive's files.</param>
|
||||
/// <param name="PartitionBoundaryUtc">The <c>pf_AuditLog_Month</c> lower boundary of the archived partition.</param>
|
||||
/// <param name="Partition">The archived partition, <c>YYYY-MM</c>.</param>
|
||||
/// <param name="ArchivedAtUtc">When the archive was written.</param>
|
||||
/// <param name="Status">Whether the partition switch that follows the archive has been confirmed.</param>
|
||||
/// <param name="PurgedAtUtc">When the partition switch completed, or null.</param>
|
||||
/// <param name="RowCount">Rows in the data file.</param>
|
||||
/// <param name="ChainedRowCount">Rows that carried a ChainSeq/RowHash.</param>
|
||||
/// <param name="UnchainedRowCount">Rows the chaining job had not reached (not covered by the chain).</param>
|
||||
/// <param name="MinOccurredAtUtc">Earliest OccurredAtUtc in the data file, or null when empty.</param>
|
||||
/// <param name="MaxOccurredAtUtc">Latest OccurredAtUtc in the data file, or null when empty.</param>
|
||||
/// <param name="DataFile">Data file name, relative to the manifest's directory.</param>
|
||||
/// <param name="DataSha256">SHA-256 of the data file (lowercase hex).</param>
|
||||
/// <param name="DataBytes">Size of the data file in bytes.</param>
|
||||
/// <param name="TombstoneFile">Tombstone file name, relative to the manifest's directory.</param>
|
||||
/// <param name="TombstoneSha256">SHA-256 of the tombstone file (lowercase hex).</param>
|
||||
/// <param name="TombstoneCount">Tombstones in the tombstone file.</param>
|
||||
/// <param name="Chains">One entry per chain partition that had a head when the rows were archived.</param>
|
||||
public sealed record AuditArchiveManifest(
|
||||
int FormatVersion,
|
||||
string Name,
|
||||
@@ -71,66 +47,23 @@ public sealed record AuditArchiveManifest(
|
||||
AuditArchiveStatus Status,
|
||||
DateTime? PurgedAtUtc,
|
||||
long RowCount,
|
||||
long ChainedRowCount,
|
||||
long UnchainedRowCount,
|
||||
DateTime? MinOccurredAtUtc,
|
||||
DateTime? MaxOccurredAtUtc,
|
||||
string DataFile,
|
||||
string DataSha256,
|
||||
long DataBytes,
|
||||
string TombstoneFile,
|
||||
string TombstoneSha256,
|
||||
long TombstoneCount,
|
||||
IReadOnlyList<AuditArchiveChainState> Chains);
|
||||
long DataBytes);
|
||||
|
||||
/// <summary>
|
||||
/// How an archive's recorded chain end relates to the checkpoint anchor the partition purge
|
||||
/// left on the database's chain head.
|
||||
/// </summary>
|
||||
[JsonConverter(typeof(JsonStringEnumConverter<AuditArchiveAnchorStatus>))]
|
||||
public enum AuditArchiveAnchorStatus
|
||||
{
|
||||
/// <summary>The database anchor is exactly the archive's chain end (sequence and hash).</summary>
|
||||
Matches,
|
||||
|
||||
/// <summary>
|
||||
/// The database anchor is past the archive's chain end: rows that arrived late for this
|
||||
/// month were chained and purged (and archived) again afterwards.
|
||||
/// </summary>
|
||||
Superseded,
|
||||
|
||||
/// <summary>The partition has not been purged: the archive's rows are still in <c>dbo.AuditLog</c>.</summary>
|
||||
NotPurged,
|
||||
|
||||
/// <summary>
|
||||
/// The anchor disagrees with the archive (an earlier sequence number, a different hash, or
|
||||
/// no chain head at all): the archive or the head was altered.
|
||||
/// </summary>
|
||||
Mismatch,
|
||||
}
|
||||
|
||||
/// <summary>Verification of one chain partition inside an archive.</summary>
|
||||
/// <param name="Chain">The chain recomputed over the archived rows, the archived head and tombstones.</param>
|
||||
/// <param name="Anchor">How the archived chain end relates to the database's checkpoint anchor.</param>
|
||||
/// <param name="AnchorDetail">Human-readable explanation of <paramref name="Anchor"/>.</param>
|
||||
public sealed record AuditArchiveChainVerification(
|
||||
AuditChainVerificationResult Chain,
|
||||
AuditArchiveAnchorStatus Anchor,
|
||||
string AnchorDetail);
|
||||
|
||||
/// <summary>
|
||||
/// Result of <c>audit archive verify</c> (ScadaBridge#42): the archive files match their
|
||||
/// manifest, every archived chain recomputes to the archived head, and each chain end is the
|
||||
/// anchor the partition purge left in the database.
|
||||
/// Result of <c>audit archive verify</c> (ScadaBridge#42): the data file matches its manifest
|
||||
/// (size, SHA-256 and row count).
|
||||
/// </summary>
|
||||
/// <param name="Name">The archive verified.</param>
|
||||
/// <param name="Partition">The archived partition, <c>YYYY-MM</c>.</param>
|
||||
/// <param name="ManifestStatus">The manifest's lifecycle status.</param>
|
||||
/// <param name="Verified">True when the files are intact, no chain is broken and no anchor mismatches.</param>
|
||||
/// <param name="FilesIntact">True when both files' size and SHA-256 and the row/tombstone counts match the manifest.</param>
|
||||
/// <param name="Verified">True when the data file is intact.</param>
|
||||
/// <param name="FilesIntact">True when the data file's size, SHA-256 and row count match the manifest.</param>
|
||||
/// <param name="FileProblem">Why <paramref name="FilesIntact"/> is false, or null.</param>
|
||||
/// <param name="RowsRead">Rows read from the data file.</param>
|
||||
/// <param name="Chains">Per chain partition verification.</param>
|
||||
public sealed record AuditArchiveVerificationResult(
|
||||
string Name,
|
||||
string Partition,
|
||||
@@ -138,8 +71,7 @@ public sealed record AuditArchiveVerificationResult(
|
||||
bool Verified,
|
||||
bool FilesIntact,
|
||||
string? FileProblem,
|
||||
long RowsRead,
|
||||
IReadOnlyList<AuditArchiveChainVerification> Chains);
|
||||
long RowsRead);
|
||||
|
||||
/// <summary>Result of <c>audit archive list</c> (ScadaBridge#42).</summary>
|
||||
/// <param name="Enabled">Whether the retention purge is archiving partitions (<c>AuditLog:Archive:Enabled</c>).</param>
|
||||
@@ -159,8 +91,7 @@ public enum AuditArchiveCleanupAction
|
||||
/// <summary>
|
||||
/// Deleted as a superseded stale archive: status <c>Archived</c> (its partition switch never
|
||||
/// completed — a retried purge), and a LATER, verified, <c>Purged</c> archive of the same
|
||||
/// partition provably holds every row it holds (same chain through its chain end, every
|
||||
/// unchained row present by EventId).
|
||||
/// partition provably holds every row it holds (every row present by EventId).
|
||||
/// </summary>
|
||||
DeletedSuperseded,
|
||||
|
||||
@@ -172,7 +103,7 @@ public enum AuditArchiveCleanupAction
|
||||
|
||||
/// <summary>
|
||||
/// Deleted as an orphan of an interrupted archive write (ScadaBridge#114): a temp file of the
|
||||
/// archive writer (<c>*.parquet.tmp</c>, <c>*.tombstones.parquet.tmp</c>, <c>*.manifest.json.tmp</c>)
|
||||
/// archive writer (<c>*.parquet.tmp</c>, <c>*.manifest.json.tmp</c>, or a format-v1 <c>*.tombstones.parquet.tmp</c>)
|
||||
/// or a data file whose <c>.manifest.json</c> was never written, older than the safe age.
|
||||
/// </summary>
|
||||
DeletedOrphan,
|
||||
|
||||
@@ -1,126 +0,0 @@
|
||||
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);
|
||||
@@ -1,126 +0,0 @@
|
||||
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>
|
||||
/// A chained row is dated before the chain cutoff (ScadaBridge#139). Rows before the cutoff
|
||||
/// are never chained, so the row's <c>OccurredAtUtc</c> was moved back (to hide it among the
|
||||
/// unprotected pre-cutoff rows) or the cutoff itself was moved forward.
|
||||
/// </summary>
|
||||
ChainedBeforeCutoff,
|
||||
|
||||
/// <summary>
|
||||
/// The chain-start (cutoff) anchor is inconsistent (ScadaBridge#139): its stored hash does not
|
||||
/// match its cutoff, it sits in the wrong month, or more than one anchor exists. The cutoff
|
||||
/// that decides which rows are in scope cannot be trusted.
|
||||
/// </summary>
|
||||
CutoffAnchorInvalid,
|
||||
}
|
||||
|
||||
/// <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, at or after the chain cutoff, that 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 yet.
|
||||
/// </param>
|
||||
/// <param name="FirstBreak">The first break, or null when <see cref="Status"/> is not <see cref="AuditChainStatus.Broken"/>.</param>
|
||||
/// <param name="PreCutoffRows">
|
||||
/// Rows in the month dated before the chain cutoff (ScadaBridge#139). They are out of scope by
|
||||
/// design — the chain covers only rows written from its first enablement on — so they are
|
||||
/// never chained and never a break. Zero when the chain has no cutoff.
|
||||
/// </param>
|
||||
/// <param name="ChainFromUtc">
|
||||
/// The chain cutoff: the instant the chain was first enabled without backlog chaining. Null
|
||||
/// when the chain covers the whole table (legacy / <c>ChainBacklog</c> enablement).
|
||||
/// </param>
|
||||
public sealed record AuditChainVerificationResult(
|
||||
string Partition,
|
||||
AuditChainStatus Status,
|
||||
long RowsVerified,
|
||||
long TombstonesApplied,
|
||||
long? PurgedThroughSeq,
|
||||
long? HeadSeq,
|
||||
long UnchainedRows,
|
||||
AuditChainBreak? FirstBreak,
|
||||
long PreCutoffRows = 0,
|
||||
DateTime? ChainFromUtc = null);
|
||||
|
||||
/// <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