Class AuditIntegrityResult
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Represents the result of an audit log integrity verification.
public sealed record AuditIntegrityResult : IEquatable<AuditIntegrityResult>
- Inheritance
-
AuditIntegrityResult
- Implements
- Inherited Members
Remarks
Audit logs are hash-chained for tamper detection. Regular integrity verification should be performed as part of ongoing compliance monitoring.
Read Outcome to interpret the result. It carries three states, because verification has three: the chain was checked and held, the chain was checked and did not hold, or there was nothing in the window to check. The third case establishes nothing and must not be reported as a pass. A verification that examined no events is not evidence that the audit log is intact.
Instances are produced only by Verified(long, DateTimeOffset, DateTimeOffset, bool), ViolationsDetected(long, DateTimeOffset, DateTimeOffset, string, string, int, bool), and NoEventsInScope(DateTimeOffset, DateTimeOffset). Those three cover every representable result, and each rejects the arguments that would describe an impossible one, notably a claim of successful verification over zero events, which no caller can construct.
Properties
CompromisedChainCount
Gets the number of the store's chaining units that failed verification.
public int CompromisedChainCount { get; }
Property Value
- int
The count of compromised chains, or zero unless Outcome is ViolationsDetected.
Remarks
A chaining unit is the grouping the store's write path chains over, and each compromised unit counts once however many of its records are affected: once a chain breaks, the records after the break are unverifiable rather than independently sound, so counting them would report the consequences of a single break as separate findings. When IsHashChained is false the store chains nothing and each record is its own unit, so this is a count of records that failed content verification. Read it together with IsHashChained, which says which of the two it is.
EndDate
Gets the end of the verification period.
public DateTimeOffset EndDate { get; }
Property Value
- DateTimeOffset
The inclusive end of the window that was examined.
EventsVerified
Gets the total number of events examined.
public long EventsVerified { get; }
Property Value
- long
The number of audit events read and checked. Always zero when Outcome is NoEventsInScope, and always greater than zero otherwise.
FirstViolationEventId
Gets the first event ID with an integrity violation.
public string? FirstViolationEventId { get; }
Property Value
- string
The identifier of the earliest failing event, or null unless Outcome is ViolationsDetected.
IsHashChained
Gets a value indicating whether the store's write path hash-chained the records that were verified.
public bool IsHashChained { get; }
Property Value
- bool
true when the records were chained, so deletion, insertion and reordering were tested; otherwise false, meaning only each record's own content integrity was tested and deletion, insertion and reordering were not.
Remarks
This is what makes CompromisedChainCount readable. Without it the same field carries two different units depending on a store setting the reader cannot see.
Outcome
Gets what the verification established.
public AuditIntegrityOutcome Outcome { get; }
Property Value
- AuditIntegrityOutcome
Verified when every event in the window was examined and the chain held; ViolationsDetected when at least one event failed; NoEventsInScope when the window contained no events at all.
StartDate
Gets the start of the verification period.
public DateTimeOffset StartDate { get; }
Property Value
- DateTimeOffset
The inclusive start of the window that was examined.
VerifiedAt
Gets the timestamp when verification was performed.
public DateTimeOffset VerifiedAt { get; }
Property Value
- DateTimeOffset
The instant the verification ran.
ViolationDescription
Gets a description of the integrity violation.
public string? ViolationDescription { get; }
Property Value
- string
A description of the earliest failure, or null unless Outcome is ViolationsDetected.
Methods
NoEventsInScope(DateTimeOffset, DateTimeOffset)
Creates a result recording that the window contained no audit events, so integrity was not exercised.
public static AuditIntegrityResult NoEventsInScope(DateTimeOffset startDate, DateTimeOffset endDate)
Parameters
startDateDateTimeOffsetThe start of the verification period.
endDateDateTimeOffsetThe end of the verification period.
Returns
- AuditIntegrityResult
A result whose Outcome is NoEventsInScope and whose EventsVerified is zero.
Remarks
This is not a pass. Callers producing compliance evidence must report it as an unexamined window rather than as a successful verification.
Verified(long, DateTimeOffset, DateTimeOffset, bool)
Creates a result recording that every event in the window was examined and the hash chain held.
public static AuditIntegrityResult Verified(long eventsVerified, DateTimeOffset startDate, DateTimeOffset endDate, bool isHashChained)
Parameters
eventsVerifiedlongThe number of events examined. May be zero: a violation can be found in a record that lies OUTSIDE the examined range. The right-edge pin verifies the record immediately following the range, and it fails precisely when records have been deleted from the end — a range truncated to nothing still has a successor to check, so the count examined is zero and the finding is real.
startDateDateTimeOffsetThe start of the verification period.
endDateDateTimeOffsetThe end of the verification period.
isHashChainedboolWhether the store's write path chained the records that were verified.
Returns
Exceptions
- ArgumentOutOfRangeException
Thrown when
eventsVerifiedis less than one. Verification that examined no events establishes nothing and cannot be reported as a successful verification; use NoEventsInScope(DateTimeOffset, DateTimeOffset) for an empty window.
ViolationsDetected(long, DateTimeOffset, DateTimeOffset, string, string, int, bool)
Creates a result recording that at least one event in the window failed verification.
public static AuditIntegrityResult ViolationsDetected(long eventsVerified, DateTimeOffset startDate, DateTimeOffset endDate, string firstViolationEventId, string violationDescription, int compromisedChainCount, bool isHashChained)
Parameters
eventsVerifiedlongThe number of events examined. Must be greater than zero.
startDateDateTimeOffsetThe start of the verification period.
endDateDateTimeOffsetThe end of the verification period.
firstViolationEventIdstringThe identifier of the earliest failing event.
violationDescriptionstringA description of the earliest failure.
compromisedChainCountintThe number of the store's chaining units that failed. Must be greater than zero.
isHashChainedboolWhether the store's write path chained the records that were verified.
Returns
- AuditIntegrityResult
A result whose Outcome is ViolationsDetected.
Exceptions
- ArgumentOutOfRangeException
Thrown when
eventsVerifiedis negative orcompromisedChainCountis less than one. A reported violation always compromises at least one of the store's chaining units, but it need not have examined anything: the record whose link is broken may be the one just outside the range, which is the case a truncated tail produces and the case this detection exists for.- ArgumentException
Thrown when
firstViolationEventIdorviolationDescriptionis null, empty, or whitespace. A reported violation must identify and describe itself.