Build a Compliance Audit Trail with AI

The Problem

Your application handles sensitive financial data, and your compliance auditor just flagged a critical gap: there is no audit trail for who accessed what data and when. The application logs show HTTP requests, but they do not capture business-level events like "user exported all customer records" or "admin changed billing plan for account X."

When the auditor asks "can you prove that only authorized users accessed PII in the last 90 days?" -- you cannot answer. The access logs show that someone hit GET /customers/export, but not who made the request, not which fields they pulled, and not whether they were authorized to do so. That is a finding that can block SOC 2 certification entirely.

Building a proper audit trail means instrumenting dozens of endpoints, designing a tamper-evident storage scheme, and creating query interfaces for auditors who do not write SQL. The team estimated six weeks of engineering time. The auditor is coming back in three.

The Solution

Using the coding-agent, security-audit, and data-analysis skills, the agent designs a tamper-evident audit event schema, instruments 34 endpoints with middleware and decorators, builds integrity verification with chained SHA-256 checksums, and generates auditor-facing query endpoints and downloadable reports -- all in a single session.

Step-by-Step Walkthrough

Step 1: Define Audit Requirements

Start by telling the agent what needs to be tracked and why:

We're a fintech startup preparing for SOC 2 Type II. We need an audit trail for:
- All authentication events (login, logout, failed attempts, password changes)
- PII access (viewing, exporting, or modifying customer data)
- Admin actions (role changes, account modifications, config updates)
- Data exports and bulk operations

Our stack: Express API, Postgres, React frontend. Show me how to build this.

Step 2: Design the Audit Event Schema

Every audit event needs to answer four questions: who did it, what did they do, what resource did they touch, and what was the outcome. The schema captures all four in a single structured record:

{
  "eventId": "uuid-v4",
  "timestamp": "2026-02-17T14:23:01.445Z",
  "actor": {
    "userId": "usr_a1b2c3",
    "email": "dani@company.com",
    "role": "admin",
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0..."
  },
  "action": "customer.pii.export",
  "resource": {
    "type": "customer",
    "id": "cust_x7y8z9",
    "name": "Acme Corp"
  },
  "details": {
    "fields_accessed": ["name", "email", "phone", "billing_address"],
    "export_format": "csv",
    "record_count": 1
  },
  "result": "success",
  "checksum": "sha256:a1b2c3..."
}

The storage design is critical for compliance. The audit table is append-only in Postgres -- the application role has INSERT permission only, no UPDATE or DELETE. Row-level security enforces this at the database level, not just the application level. Even if the application code has a bug, the database will not allow audit records to be modified. Retention is set to 7 years, configurable per compliance framework.

Step 3: Generate Audit Middleware and Infrastructure

The core infrastructure lives in five files:

src/audit/
  audit-logger.ts        # Core logging function with checksum generation
  middleware.ts           # Express middleware for automatic capture
  decorators.ts          # @Audited() decorator for service methods
  events.ts              # Typed event catalog (47 event types)
  integrity.ts           # Checksum chain verification

The design uses two capture strategies that work together:

Automatic capture via Express middleware logs all state-changing requests (POST, PUT, DELETE) without any code changes to existing routes. Drop it in, and every mutation is recorded.

Explicit capture via the @Audited() decorator handles business-logic events that do not map cleanly to HTTP requests -- like a background job that processes a data export, or a cron task that purges expired records. These events need to be audited too, and middleware alone cannot catch them.

Tamper detection works through chained SHA-256 checksums: each event includes a hash of the previous event, creating a blockchain-like chain. Modifying or deleting any record breaks the chain, and the integrity checker detects the break in seconds. This is what separates a compliance-grade audit trail from a regular log table.

PII detection is automatic -- any event that touches fields marked as PII in the schema gets flagged, making it trivial to generate the PII access reports auditors always ask for.

Step 4: Instrument Critical Endpoints

With the infrastructure in place, instrumentation covers 34 endpoints across 6 route files:

Authentication (8 event types):

Customer PII (14 event types):

Admin Actions (12 event types):

Every event captures the actor, resource, result, and relevant details. PII updates include before/after snapshots so the auditor can see exactly what changed, when, and by whom. Failed authentication attempts record the IP address and user agent for security analysis.

Step 5: Build Auditor-Facing Query Interface

Auditors do not want to write SQL. They need clean endpoints and downloadable reports they can drop into their compliance binder:

Query endpoints:

• GET /audit/events?actor=usr_123&from=2026-01-01&to=2026-02-01 -- all actions by a specific user
• GET /audit/events?action=customer.pii.*&resource=cust_456 -- all PII access for a specific customer
• GET /audit/integrity-check?from=2026-01-01 -- verifies the entire checksum chain is unbroken

Generated reports (PDF):

• PII Access Report -- who accessed what PII, when, from which IP address
• Failed Auth Report -- failed login attempts with IP addresses and frequency patterns (useful for detecting brute-force attempts)
• Admin Actions Report -- all privilege escalations and configuration changes
• Integrity Report -- mathematical proof that no audit records have been tampered with

The integrity report is the one auditors care about most. It walks the checksum chain from the first event to the last and confirms every link is intact. If someone had modified or deleted a record, the chain would break at that point -- and the report would flag exactly where.

Real-World Example

Nadia is the engineering lead at a 15-person fintech team preparing for their first SOC 2 Type II audit. The auditor's preliminary assessment flagged "insufficient audit trail" as a critical finding that could block certification. The team estimated six weeks to build what the auditor described. They had three weeks before the follow-up visit.

The agent designs a tamper-evident event schema, generates middleware and decorators, and instruments 34 endpoints in a single session. The integrity verification system uses chained SHA-256 checksums -- modifying or deleting any audit record breaks the chain and gets flagged immediately.

When the auditor returns, Nadia demonstrates real-time audit queries: "Show me all PII access by admin users in Q1." The query returns in under a second with structured results -- who accessed which customer records, what fields they viewed, and from what IP. She hands over a clean integrity report proving no audit records have been tampered with since the system went live. The finding is resolved, and they pass the audit. What was estimated as a six-week project shipped in days, with the kind of tamper-evidence that most companies at their stage do not have.