Table of Contents

Class SecurityAuditor

Namespace
Excalibur.Data.ElasticSearch.Security
Assembly
Excalibur.Data.ElasticSearch.dll

Production implementation of comprehensive security auditing for Elasticsearch operations with GDPR, SOC2, and HIPAA compliance, tamper-proof logging, real-time threat detection, and automated incident response capabilities.

public sealed class SecurityAuditor : IElasticsearchSecurityAuditor, IElasticsearchSecurityAuditorCore, IElasticsearchSecurityAuditorRecording, IElasticsearchSecurityAuditorEvents, IElasticsearchSecurityAuditorReporting, IElasticsearchSecurityAuditorMaintenance, IDisposable, IAsyncDisposable
Inheritance
SecurityAuditor
Implements
Inherited Members

Remarks

Facade that delegates to focused service classes following SRP:

  • Excalibur.Data.ElasticSearch.Security.SecurityAuditWriter — event recording (authentication, data access, config changes, incidents)
  • Excalibur.Data.ElasticSearch.Security.SecurityAuditQueryService — reporting and search (audit reports, compliance reports, event search)
  • Excalibur.Data.ElasticSearch.Security.SecurityAuditMaintenanceService — integrity validation and archival

Owns shared infrastructure: event processing queues, timers, index initialization, and disposal.

Constructors

SecurityAuditor(ElasticsearchClient, IOptions<AuditOptions>, IOptions<SecurityMonitoringOptions>, IAuditIntegrityStrategy, ITelemetrySanitizer?, TimeProvider, ILogger<SecurityAuditor>)

Initializes a new instance of the SecurityAuditor class with an explicit audit integrity strategy. This is the dependency-injection entry point.

public SecurityAuditor(ElasticsearchClient elasticsearchClient, IOptions<AuditOptions> auditOptions, IOptions<SecurityMonitoringOptions> monitoringOptions, IAuditIntegrityStrategy integrityStrategy, ITelemetrySanitizer? sanitizer, TimeProvider timeProvider, ILogger<SecurityAuditor> logger)

Parameters

elasticsearchClient ElasticsearchClient

The Elasticsearch client for audit log storage.

auditOptions IOptions<AuditOptions>

The audit configuration options.

monitoringOptions IOptions<SecurityMonitoringOptions>

The security monitoring configuration options.

integrityStrategy IAuditIntegrityStrategy

The shared keyed-MAC audit integrity strategy.

sanitizer ITelemetrySanitizer

The sanitizer used to mask PII on audit events before enqueue; when null and MaskPiiInAuditEvents is enabled, construction fails closed.

timeProvider TimeProvider

The time source driving the compliance-report and audit-queue-drain schedules.

logger ILogger<SecurityAuditor>

The logger for operational events.

Exceptions

ArgumentNullException

Thrown when required dependencies are null.

SecurityAuditor(ElasticsearchClient, IOptions<AuditOptions>, IOptions<SecurityMonitoringOptions>, ILogger<SecurityAuditor>)

Initializes a new instance of the SecurityAuditor class.

public SecurityAuditor(ElasticsearchClient elasticsearchClient, IOptions<AuditOptions> auditOptions, IOptions<SecurityMonitoringOptions> monitoringOptions, ILogger<SecurityAuditor> logger)

Parameters

elasticsearchClient ElasticsearchClient

The Elasticsearch client for audit log storage.

auditOptions IOptions<AuditOptions>

The audit configuration options.

monitoringOptions IOptions<SecurityMonitoringOptions>

The security monitoring configuration options.

logger ILogger<SecurityAuditor>

The logger for operational events.

Exceptions

ArgumentNullException

Thrown when required dependencies are null.

Properties

Configuration

Gets the audit configuration settings currently in use.

public AuditOptions Configuration { get; }

Property Value

AuditOptions

The current audit configuration settings.

IntegrityProtectionEnabled

Gets a value indicating whether audit log integrity protection is enabled.

public bool IntegrityProtectionEnabled { get; }

Property Value

bool

True if audit logs are cryptographically protected, false otherwise.

SupportedComplianceFrameworks

Gets the supported compliance frameworks for reporting.

public IReadOnlyCollection<ComplianceFramework> SupportedComplianceFrameworks { get; }

Property Value

IReadOnlyCollection<ComplianceFramework>

A collection of compliance frameworks supported by this auditor.

Methods

ArchiveAuditEventsAsync(AuditArchiveRequest, CancellationToken)

Archives old audit events according to retention policies and compliance requirements.

public Task<AuditArchiveResult> ArchiveAuditEventsAsync(AuditArchiveRequest archiveRequest, CancellationToken cancellationToken)

Parameters

archiveRequest AuditArchiveRequest

The archive request with retention criteria.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<AuditArchiveResult>

A task that represents the asynchronous operation. The task result contains the archive operation result including the number of events archived and any errors encountered.

Exceptions

SecurityException

Thrown when audit archiving fails due to security constraints.

ArgumentNullException

Thrown when the archive request is null.

ArchiveAuditEventsAsync(DateTimeOffset, string, CancellationToken)

Archives audit events before the cutoff date to the specified location.

public Task<AuditArchiveResult> ArchiveAuditEventsAsync(DateTimeOffset cutoffDate, string archiveLocation, CancellationToken cancellationToken)

Parameters

cutoffDate DateTimeOffset
archiveLocation string
cancellationToken CancellationToken

Returns

Task<AuditArchiveResult>

AuditSecurityActivityAsync(SecurityActivityEvent, CancellationToken)

Audits a security activity event for compliance and monitoring purposes.

public Task AuditSecurityActivityAsync(SecurityActivityEvent activityEvent, CancellationToken cancellationToken)

Parameters

activityEvent SecurityActivityEvent

The security activity event to audit.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task

A task representing the asynchronous audit operation.

Dispose()

Releases all resources used by the SecurityAuditor.

public void Dispose()

DisposeAsync()

Asynchronously releases resources, ensuring tracked timer callbacks have completed.

public ValueTask DisposeAsync()

Returns

ValueTask

GenerateAuditReportAsync(AuditReportRequest, CancellationToken)

Generates a comprehensive security audit report for the specified time period.

public Task<SecurityAuditReport> GenerateAuditReportAsync(AuditReportRequest reportRequest, CancellationToken cancellationToken)

Parameters

reportRequest AuditReportRequest

The audit report generation request with filters and parameters.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<SecurityAuditReport>

A task that represents the asynchronous operation. The task result contains the generated audit report with security events and compliance information.

Exceptions

SecurityException

Thrown when report generation fails due to security constraints.

ArgumentNullException

Thrown when the report request is null.

GenerateAuditReportAsync(DateTimeOffset, DateTimeOffset, AuditReportType, CancellationToken)

Generates a comprehensive audit report for the specified time period.

public Task<AuditReport> GenerateAuditReportAsync(DateTimeOffset startTime, DateTimeOffset endTime, AuditReportType reportType, CancellationToken cancellationToken)

Parameters

startTime DateTimeOffset
endTime DateTimeOffset
reportType AuditReportType
cancellationToken CancellationToken

Returns

Task<AuditReport>

GenerateComplianceReportAsync(ComplianceFramework, DateTimeOffset, DateTimeOffset, CancellationToken)

Generates a compliance report for the specified framework and time period.

public Task<ComplianceReport> GenerateComplianceReportAsync(ComplianceFramework framework, DateTimeOffset startTime, DateTimeOffset endTime, CancellationToken cancellationToken)

Parameters

framework ComplianceFramework
startTime DateTimeOffset
endTime DateTimeOffset
cancellationToken CancellationToken

Returns

Task<ComplianceReport>

GenerateComplianceReportAsync(ComplianceReportRequest, CancellationToken)

Generates a compliance report for specific regulatory frameworks.

public Task<ComplianceReport> GenerateComplianceReportAsync(ComplianceReportRequest complianceRequest, CancellationToken cancellationToken)

Parameters

complianceRequest ComplianceReportRequest

The compliance report generation request with framework specifications.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<ComplianceReport>

A task that represents the asynchronous operation. The task result contains the generated compliance report formatted according to the specified regulatory requirements.

Exceptions

SecurityException

Thrown when compliance report generation fails due to security constraints.

ArgumentNullException

Thrown when the compliance request is null.

RecordAuthenticationEventAsync(AuthenticationEvent, CancellationToken)

Records an authentication event for security monitoring and compliance purposes.

public Task<bool> RecordAuthenticationEventAsync(AuthenticationEvent authenticationEvent, CancellationToken cancellationToken)

Parameters

authenticationEvent AuthenticationEvent

The authentication event details to record.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if the event was successfully recorded, false otherwise.

Exceptions

SecurityException

Thrown when audit recording fails due to security constraints.

ArgumentNullException

Thrown when the authentication event is null.

RecordConfigurationChangeAsync(ConfigurationChangeEvent, CancellationToken)

Records a security configuration change for compliance and change tracking purposes.

public Task<bool> RecordConfigurationChangeAsync(ConfigurationChangeEvent configurationEvent, CancellationToken cancellationToken)

Parameters

configurationEvent ConfigurationChangeEvent

The configuration change event details to record.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if the event was successfully recorded, false otherwise.

Exceptions

SecurityException

Thrown when audit recording fails due to security constraints.

ArgumentNullException

Thrown when the configuration event is null.

RecordDataAccessEventAsync(DataAccessEvent, CancellationToken)

Records a data access event for monitoring data usage patterns and detecting anomalies.

public Task<bool> RecordDataAccessEventAsync(DataAccessEvent dataAccessEvent, CancellationToken cancellationToken)

Parameters

dataAccessEvent DataAccessEvent

The data access event details to record.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if the event was successfully recorded, false otherwise.

Exceptions

SecurityException

Thrown when audit recording fails due to security constraints.

ArgumentNullException

Thrown when the data access event is null.

RecordSecurityEventAsync(ElasticsearchSecurityEvent, CancellationToken)

Records a general security event for compliance and monitoring purposes.

public Task<bool> RecordSecurityEventAsync(ElasticsearchSecurityEvent securityEvent, CancellationToken cancellationToken)

Parameters

securityEvent ElasticsearchSecurityEvent
cancellationToken CancellationToken

Returns

Task<bool>

RecordSecurityIncidentAsync(SecurityIncident, CancellationToken)

Records a security incident or violation for immediate attention and investigation.

public Task<bool> RecordSecurityIncidentAsync(SecurityIncident securityIncident, CancellationToken cancellationToken)

Parameters

securityIncident SecurityIncident

The security incident details to record.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true if the incident was successfully recorded, false otherwise.

Exceptions

SecurityException

Thrown when audit recording fails due to security constraints.

ArgumentNullException

Thrown when the security incident is null.

SearchAuditEventsAsync(AuditSearchCriteria, CancellationToken)

Searches audit events based on internal search criteria.

public Task<IEnumerable<SecurityAuditEvent>> SearchAuditEventsAsync(AuditSearchCriteria searchCriteria, CancellationToken cancellationToken)

Parameters

searchCriteria AuditSearchCriteria
cancellationToken CancellationToken

Returns

Task<IEnumerable<SecurityAuditEvent>>

SearchAuditEventsAsync(AuditSearchRequest, CancellationToken)

Searches audit events based on specified criteria for investigation and analysis.

public Task<AuditSearchResult> SearchAuditEventsAsync(AuditSearchRequest searchRequest, CancellationToken cancellationToken)

Parameters

searchRequest AuditSearchRequest

The audit search request with filters and criteria.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<AuditSearchResult>

A task that represents the asynchronous operation. The task result contains the matching audit events and search result metadata.

Exceptions

SecurityException

Thrown when audit search fails due to security constraints.

ArgumentNullException

Thrown when the search request is null.

ValidateAuditIntegrityAsync(AuditIntegrityRequest, CancellationToken)

Validates the integrity of audit logs to detect tampering or corruption.

public Task<AuditIntegrityResult> ValidateAuditIntegrityAsync(AuditIntegrityRequest validationRequest, CancellationToken cancellationToken)

Parameters

validationRequest AuditIntegrityRequest

The integrity validation request with parameters.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<AuditIntegrityResult>

A task that represents the asynchronous operation. The task result contains the integrity validation result indicating whether audit logs are intact and trustworthy.

Exceptions

SecurityException

Thrown when integrity validation fails due to security constraints.

ArgumentNullException

Thrown when the validation request is null.

ValidateAuditIntegrityAsync(DateTimeOffset, DateTimeOffset, CancellationToken)

Validates the integrity of audit logs for the specified time period.

public Task<AuditLogIntegrityResult> ValidateAuditIntegrityAsync(DateTimeOffset startTime, DateTimeOffset endTime, CancellationToken cancellationToken)

Parameters

startTime DateTimeOffset
endTime DateTimeOffset
cancellationToken CancellationToken

Returns

Task<AuditLogIntegrityResult>

Events

AuditArchiveCompleted

Occurs when audit log archiving is completed.

public event EventHandler<AuditArchiveCompletedEventArgs>? AuditArchiveCompleted

Event Type

EventHandler<AuditArchiveCompletedEventArgs>

ComplianceViolationDetected

Raised when a compliance violation is detected.

public event EventHandler<ComplianceViolationEventArgs>? ComplianceViolationDetected

Event Type

EventHandler<ComplianceViolationEventArgs>

IntegrityViolationDetected

Occurs when audit log integrity validation fails.

public event EventHandler<AuditIntegrityViolationEventArgs>? IntegrityViolationDetected

Event Type

EventHandler<AuditIntegrityViolationEventArgs>

SecurityEventRecorded

Occurs when a security event is successfully recorded.

public event EventHandler<SecurityEventRecordedEventArgs>? SecurityEventRecorded

Event Type

EventHandler<SecurityEventRecordedEventArgs>