Table of Contents

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

startDate DateTimeOffset

The start of the verification period.

endDate DateTimeOffset

The 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

eventsVerified long

The 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.

startDate DateTimeOffset

The start of the verification period.

endDate DateTimeOffset

The end of the verification period.

isHashChained bool

Whether the store's write path chained the records that were verified.

Returns

AuditIntegrityResult

A result whose Outcome is Verified.

Exceptions

ArgumentOutOfRangeException

Thrown when eventsVerified is 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

eventsVerified long

The number of events examined. Must be greater than zero.

startDate DateTimeOffset

The start of the verification period.

endDate DateTimeOffset

The end of the verification period.

firstViolationEventId string

The identifier of the earliest failing event.

violationDescription string

A description of the earliest failure.

compromisedChainCount int

The number of the store's chaining units that failed. Must be greater than zero.

isHashChained bool

Whether the store's write path chained the records that were verified.

Returns

AuditIntegrityResult

A result whose Outcome is ViolationsDetected.

Exceptions

ArgumentOutOfRangeException

Thrown when eventsVerified is negative or compromisedChainCount is 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 firstViolationEventId or violationDescription is null, empty, or whitespace. A reported violation must identify and describe itself.