/oath

Audit Trail Design Reference

Core Principles

1. Immutability: Audit logs must be append-only; no modification or deletion
2. Completeness: Every security-relevant action must be logged
3. Integrity: Tamper detection mechanisms must be in place
4. Availability: Logs must be accessible for the required retention period
5. Timeliness: Events must be logged at or near real-time (NTP sync required)

Audit Event Schema

interface AuditEvent {
  // Identity
  eventId: string;          // UUID v7 (time-ordered)
  timestamp: string;        // ISO 8601 with timezone

  // Actor
  actorId: string;          // User ID or system identity
  actorType: 'user' | 'service' | 'system' | 'admin';
  actorIp?: string;         // Source IP (if applicable)
  sessionId?: string;       // Session identifier

  // Action
  action: string;           // Verb: 'create' | 'read' | 'update' | 'delete' | 'login' | 'logout' | 'export' | 'grant' | 'revoke'
  resource: string;         // Target resource type
  resourceId: string;       // Target resource identifier

  // Context
  outcome: 'success' | 'failure' | 'denied';
  reason?: string;          // Failure/denial reason
  metadata?: Record<string, unknown>; // Additional context (no PII/secrets)

  // Integrity
  previousHash?: string;    // Hash chain for tamper detection
  eventHash: string;        // SHA-256 of event payload
}

Framework-Specific Logging Requirements

PCI-DSS Req 10 Specifics

Must log:

• All individual user access to cardholder data (10.2.1)
• All actions by admin/root (10.2.2)
• Access to all audit trails (10.2.3)
• Invalid logical access attempts (10.2.4)
• Use of identification and authentication mechanisms (10.2.5)
• Initialization, stopping, or pausing of audit logs (10.2.6)
• Creation and deletion of system-level objects (10.2.7)

Implementation Patterns

Append-Only Log Store

Application -> Audit Middleware -> Message Queue -> Immutable Store
                                                     |
                                                     v
                                              Integrity Verifier
                                                     |
                                                     v
                                              SIEM / Analytics

Recommended stores:

• AWS CloudTrail + S3 (Object Lock) + CloudWatch
• Azure Monitor + Immutable Blob Storage
• GCP Cloud Audit Logs + Cloud Storage (retention lock)
• Self-hosted: Append-only PostgreSQL (BEFORE DELETE trigger blocks deletion) + external backup

Hash Chain Pattern

Event[n].hash = SHA-256(Event[n].payload + Event[n-1].hash)

• Genesis event uses a known seed
• Periodic hash checkpoints stored in separate system
• Verification: replay chain from genesis, compare intermediate hashes
• Break in chain indicates tampering

Log Integrity Monitoring

Evidence Collection for Auditors

Anti-Patterns