name: audit-backend description: >- Implement audit logging and audit trails for .NET backend applications. Covers entity change tracking, user action logging, audit middleware, tamper-proof audit storage, and compliance patterns. Use when: adding audit trails to data changes, logging user actions, implementing compliance requirements (GDPR, SOC2, HIPAA), or reviewing audit coverage. argument-hint: 'Describe the audit requirement: entity tracking, action logging, compliance, or review.'

Audit Logging (.NET)

When to Use

• Adding audit trails for entity create/update/delete operations
• Logging user actions (login, permission changes, data access)
• Implementing compliance audit requirements (GDPR, SOC2, HIPAA)
• Reviewing existing audit coverage for gaps
• Adding tamper-proof audit storage

Official Documentation

• EF Core Interceptors
• EF Core Change Tracker

Key Principles

• Audit is separate from logging — audit events are business-critical records, not debug logs.
• Immutable and append-only — audit records must never be updated or deleted.
• Who, What, When, Where — every audit entry captures the actor, action, timestamp, and target.
• Sensitive data handling — store what changed but redact PII where required.
• Async and non-blocking — audit writes must not slow down the primary operation.

Procedure

1. Define the AuditEntry domain model (see audit model sample)
2. Implement an EF Core SaveChangesInterceptor for automatic entity tracking
3. Add an audit middleware for HTTP request-level actions
4. Store audit records in a dedicated, append-only table
5. Include the actor (user ID), action type, entity type, entity ID, timestamp, and changes
6. Redact sensitive fields (passwords, tokens, PII) before persisting
7. Add retention policies and archival for compliance

Audit Entry Structure

Constraints

• NEVER update or delete audit records
• ALWAYS capture the acting user from the authentication context
• ALWAYS use UTC timestamps
• ALWAYS redact sensitive fields before persisting
• NEVER let audit failures break the primary operation (use try/catch)