congiuluc/audit-backend-python

Audit Logging (Python FastAPI)

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

• SQLAlchemy Events
• SQLAlchemy ORM Events
• FastAPI Middleware

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 Pydantic/SQLAlchemy model (see audit model sample)
2. Implement SQLAlchemy after_insert, after_update, after_delete event listeners
3. Add a FastAPI middleware for HTTP request-level action auditing
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

| Field | Type | Description | |-------|------|-------------| | id | str | Unique audit entry ID (UUID) | | timestamp | datetime | When the action occurred (UTC) | | user_id | str | Who performed the action | | action | str | CREATE, UPDATE, DELETE, ACCESS, LOGIN, etc. | | entity_type | str | The type of entity affected | | entity_id | str | The ID of the entity affected | | changes | str \| None | JSON diff of old/new values (for updates) | | ip_address | str \| None | Client IP address | | correlation_id | str \| None | Request correlation ID |

Constraints

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