Audit Logging

The Problem

Regulated industries (healthcare, finance, government) and security-conscious applications need a complete, tamper-proof record of who did what, when, and from where. Audit logs answer questions like “Who accessed this patient record?”, “Who changed the billing amount?”, and “What admin actions were taken during the incident?” Unlike application logs (for debugging), audit logs are legal records that may be subpoenaed. They must be immutable, complete, queryable, and retained for years — while adding minimal latency to the operations being audited.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

Tamper-Proof Hash Chain

Audit logs must be tamper-proof — if someone modifies a historical entry, it should be detectable.

Hash chain implementation:

1. For each audit event, compute: hash = SHA-256(event_id + actor + action + resource + timestamp + previous_hash)
2. Store the hash alongside the event
3. The first event in the chain uses a known seed value for previous_hash
4. To verify integrity: recompute hashes from the beginning and compare with stored hashes

Verification: Run a daily integrity check job that walks the entire chain and verifies each hash. Any break in the chain indicates tampering. Alert the security team immediately.

Anchoring: Periodically publish the latest hash to an external system (a public blockchain, a separate write-once storage, or a third-party timestamping service). This prevents an attacker who gains database access from rewriting the entire chain.

Performance: SHA-256 hashing is fast (~1 microsecond per entry). The chain verification job processes millions of entries per minute. Run incrementally — only verify entries since the last check.

Alternative: Use a Merkle tree instead of a linear chain. Allows efficient proof that a specific entry exists in the log without verifying the entire chain. More complex but better for selective verification.

What to Audit

Not every operation needs auditing. Focus on security-relevant and compliance-required events.

Always audit:

• Authentication events: login, logout, failed login attempts, password changes, MFA enrollment
• Authorization changes: role assignments, permission grants/revocations
• Data access: reads of sensitive data (PII, financial records, health data)
• Data modifications: creates, updates, deletes of business-critical records
• Administrative actions: user management, configuration changes, feature flag toggles
• API key and token management: creation, rotation, revocation

Consider auditing:

• Search queries on sensitive data (who searched for patient records?)
• Export operations (who downloaded the customer list?)
• Impersonation/admin access (admin viewed user’s account)
• Billing and payment operations

Skip (use application logs instead):

• Read-only access to non-sensitive data
• Health checks and monitoring requests
• Static asset requests
• Internal service-to-service communication (unless accessing sensitive data)

Structured format: Every audit entry should include: WHO (actor ID, actor type, IP, session), WHAT (action, resource type, resource ID), WHEN (timestamp, timezone), WHERE (IP, user agent, geolocation), and OUTCOME (success/failure, error details).

Retention and Compliance

Different regulations have different retention requirements:

• SOX (Sarbanes-Oxley): 7 years for financial audit trails
• HIPAA: 6 years for access logs to protected health information
• GDPR: Retain only as long as necessary (conflict with long retention!)
• PCI DSS: 1 year minimum, 3 months immediately accessible
• SOC 2: No specific retention, but auditors expect 12+ months

GDPR tension: GDPR requires data minimization — don’t keep data longer than necessary. But audit logs may contain PII (user names, emails, IP addresses). Solutions:

• Anonymize/pseudonymize PII in audit logs after the active period
• Keep audit logs but redact PII fields after the retention window
• Document the legal basis for retaining audit logs (legitimate interest, legal obligation)

Tiered storage:

• Hot (0-90 days): Fast queryable store (PostgreSQL, Elasticsearch). Full detail.
• Warm (90 days - 1 year): Compressed storage (S3 Standard). Queryable with some delay.
• Cold (1-7+ years): Archive storage (S3 Glacier). Retrieved on demand for audits.

Immutability enforcement: Use write-once storage (S3 Object Lock, WORM-compliant storage) for cold archives. Even database administrators cannot modify or delete archived audit logs. This is required for SOX compliance.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Audit Logging

You are an expert software architect and teacher. I want to understand audit logging as a practical system design capability. (Append-only event stores, tamper-proof records, and compliance-ready activity trails).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

Regulated industries (healthcare, finance, government) and security-conscious applications need a complete, tamper-proof record of who did what, when, and from where. Audit logs answer questions like "Who accessed this patient record?", "Who changed the billing amount?", and "What admin actions were taken during the incident?" Unlike application logs (for debugging), audit logs are legal records that may be subpoenaed. They must be immutable, complete, queryable, and retained for years — while adding minimal latency to the operations being audited.

## Architectural Approaches

<ApproachList>
<Approach
  name="Application-Level Audit Middleware"
  pros={[
    'Rich context — captures business-level semantics (not just SQL)',
    'Can include request context (IP, user agent, session)',
    'Flexible — audit only what matters, skip noisy operations',
    'Works with any database and framework',
  ]}
  cons={[
    'Must be added to every relevant code path — easy to miss',
    'Application bugs can cause missing or incorrect audit entries',
    'Developers must remember to add audit logging to new features',
    'Bypassed by direct database access',
  ]}
>
Intercept operations at the application layer and emit structured audit events. Middleware on API routes captures the actor, action, resource, and outcome. Events are written to a dedicated audit log store asynchronously to avoid impacting request latency.
</Approach>
<Appro...

[Full prompt copied to clipboard]