audit-pipeline.yaml

import { z } from 'zod';

export const AuditEventSchema = z.object({
  eventId: z.string().uuid(),
  timestamp: z.string().datetime(),
  actor: z.object({
    id: z.string(),
    type: z.enum(['user', 'service', 'admin', 'system']),
    session: z.string().optional(),
    ip: z.string().ip()
  }),
  action: z.string().min(1),
  resource: z.object({
    type: z.string(),
    id: z.string(),
    tenant: z.string().optional()
  }),
  context: z.record(z.unknown()).optional(),
  outcome: z.enum(['success', 'failure', 'partial']),
  integrity: z.object({
    prevHash: z.string(),
    currentHash: z.string()
  })
});

export type AuditEvent = z.infer<typeof AuditEventSchema>;

import pino from 'pino';
import crypto from 'crypto';
import { AuditEvent, A

uditEventSchema } from './audit-schema';

const logger = pino({ transport: { target: 'pino/file', options: { destination: '/var/log/audit/audit.log', mkdir: true } }, formatters: { level: (label) => ({ level: label.toUpperCase() }) } });

export class AuditLogger { private lastHash: string = crypto.randomBytes(32).toString('hex');

async emit(event: Omit<AuditEvent, 'integrity'>): Promise<void> { const validated = AuditEventSchema.omit({ integrity: true }).parse(event);

const payload = JSON.stringify({ ...validated, eventId: crypto.randomUUID() });
const currentHash = crypto.createHmac('sha256', process.env.AUDIT_SECRET!)
  .update(`${this.lastHash}${payload}`)
  .digest('hex');

const auditEvent: AuditEvent = {
  ...validated,
  integrity: { prevHash: this.lastHash, currentHash }
};

this.lastHash = currentHash;
logger.info(auditEvent);

} }

### Step 3: Architectural Decisions & Rationale
- **Append-Only Storage:** Audit logs must never support UPDATE or DELETE. Use object storage with WORM (Write Once Read Many) policies or append-only databases. This eliminates retroactive tampering at the infrastructure layer.
- **Cryptographic Chaining:** Each event hashes its payload combined with the previous event’s hash. Breaking the chain requires recomputing all subsequent hashes, which is detectable during verification.
- **Separation of Duties:** Application code emits events to a local buffer or message queue. A dedicated audit service consumes, validates, chains, and writes to storage. This prevents application crashes from corrupting the log stream and isolates security controls.
- **Key Rotation & HMAC:** Use environment-scoped secrets for HMAC generation. Rotate keys quarterly and maintain a key registry for historical verification. Never store secrets in code or version control.
- **Context Enrichment at Ingestion:** Do not trust application-provided context. Enrich events with verified identity tokens, tenant IDs, and geographic metadata at the audit service boundary.

### Step 4: Secure Transport & Verification
Use mTLS between services and the audit pipeline. Implement a verification script to validate chain integrity during audits:

```typescript
export async function verifyChain(logFile: string, secret: string): Promise<boolean> {
  const lines = require('fs').readFileSync(logFile, 'utf-8').split('\n').filter(Boolean);
  let expectedPrev = lines[0].integrity.prevHash;
  
  for (const line of lines) {
    const payload = JSON.stringify({ ...line, integrity: undefined });
    const computed = crypto.createHmac('sha256', secret)
      .update(`${expectedPrev}${payload}`)
      .digest('hex');
    
    if (computed !== line.integrity.currentHash) return false;
    expectedPrev = line.integrity.currentHash;
  }
  return true;
}

Pitfall Guide

1. Logging PII, Secrets, or Tokens in Audit Trails Audit logs become high-value targets. Logging passwords, session tokens, or PII violates GDPR/CCPA and creates compliance liabilities. Sanitize payloads before emission. Use tokenization for sensitive identifiers.

2. Inconsistent or Mutable Schemas Schema drift breaks correlation and verification. Without strict validation, downstream parsers fail during investigations. Enforce schemas at ingestion, not storage. Reject non-conforming events with explicit error codes.

3. Missing Cryptographic Integrity Timestamps and sequence numbers are trivial to forge. Without HMAC chaining or digital signatures, auditors cannot prove event sequence. Implement cryptographic chaining from day one. Store verification keys separately from logs.

4. Mixing Audit Logs with Debug/Error Logs Operational logs contain stack traces, internal state, and noisy metrics. Audit logs require clean, normalized events. Shared pipelines cause schema pollution, retention conflicts, and access control leaks. Physically and logically separate audit streams.

5. Ignoring Clock Synchronization & Timezone Standardization Distributed systems drift. Inconsistent timestamps break forensic reconstruction. Use NTP/chrony across all nodes. Store all timestamps in UTC. Include timezone metadata only for display, never for ordering.

6. Over-Logging Noise vs Under-Logging Critical Paths Logging every HTTP request creates storage bloat and masks security events. Logging only authentication misses privilege escalation. Define a minimum audit surface: authentication, authorization, data access, configuration changes, and administrative actions. Use sampling for high-frequency non-critical events.

7. Inadequate Retention & Archival Lifecycle Compliance requires specific retention windows (e.g., 7 years for financial data, 3 years for general audit). Storing everything hot increases cost and attack surface. Implement tiered storage: hot (30 days), warm (1 year), cold archive (compliance retention). Automate deletion with cryptographic proof of destruction.

Best Practices from Production:

• Validate schemas at the edge, not the sink.
• Use idempotent event IDs to prevent duplication during retries.
• Implement rate limiting on audit emission to prevent log injection DoS.
• Maintain a separate verification service that runs daily chain audits.
• Document the audit surface per service and review quarterly with security.

Production Bundle

Action Checklist

• Define minimum audit surface: authentication, authorization, data access, config changes, admin actions
• Implement strict Zod/JSON schema validation at ingestion boundary
• Enable HMAC-SHA256 cryptographic chaining with environment-scoped secrets
• Route audit logs to append-only storage with WORM policies
• Separate audit pipeline from operational logging infrastructure
• Enforce UTC timestamps and NTP synchronization across all nodes
• Configure tiered retention: hot (30d), warm (1y), cold archive (compliance)
• Deploy daily chain verification job and alert on integrity failures

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Cloud-native SaaS (multi-tenant)	Event-driven audit service with Kafka + S3 WORM	Decouples emission from storage, scales horizontally, supports tenant isolation	Medium upfront, low long-term via tiered archival
Regulated financial/healthcare	On-prem append-only database + HSM-backed key rotation	Meets strict compliance mandates, provides air-gapped verification, satisfies audit trails	High infrastructure, reduces compliance penalty risk
Internal enterprise tool	Structured Pino logger + centralized ELK with hash verification	Low overhead, integrates with existing observability stack, sufficient for internal audits	Low cost, acceptable for non-public-facing systems

Configuration Template

# audit-pipeline.yaml
schema:
  version: "2.1"
  required_fields: [eventId, timestamp, actor.id, action, resource.type, outcome]
  sensitive_fields: [actor.ip, context.token] # auto-redact before storage

integrity:
  algorithm: "hmac-sha256"
  key_rotation_days: 90
  chain_verification_cron: "0 2 * * *"

storage:
  hot:
    type: "elasticsearch"
    retention_days: 30
    index_pattern: "audit-hot-{yyyy.MM.dd}"
  warm:
    type: "s3"
    retention_days: 365
    lifecycle: "transition_to_glacier"
  cold:
    type: "s3-glacier"
    retention_days: 2555
    compliance_hold: true

access:
  rbac:
    - role: "auditor"
      permissions: ["read", "verify_chain"]
    - role: "devops"
      permissions: ["read_metrics"]
    - role: "app_service"
      permissions: ["write_only"]
  mtls:
    enabled: true
    cert_rotation_days: 365

Quick Start Guide

1. Install dependencies: npm i pino zod crypto
2. Create schema & logger: Copy the AuditEventSchema and AuditLogger class into src/audit/. Set AUDIT_SECRET in environment.
3. Attach middleware: Import AuditLogger in your Express/Fastify app. Call auditLogger.emit() after authentication and authorization checks.
4. Verify chain: Run node verify-chain.js /var/log/audit/audit.log to confirm integrity. Schedule via cron or CI pipeline.

Deploy, monitor emission latency, and validate chain verification daily. Audit logging is not a feature. It is forensic infrastructure. Build it with cryptographic certainty, not convenience.