HIPAA Audit Logging: What to Capture in Every Record

What HIPAA actually says

Here is the full text of § 164.312(b):

That is it. Record and examine activity. HIPAA deliberately does not specify fields or formats because the rule is meant to be technology-neutral — it applies equally to EHR systems, telehealth apps, clinical trial databases, and paper logs scanned into PDFs.

What HIPAA does not spell out, OCR enforcement actions have made clear over 20+ years of case law. When OCR investigators ask for audit logs, they test three things:

If your audit log cannot answer these three questions for any event from the last six years, you fail. That is true regardless of how many logs you have or how sophisticated your pipeline is. The violations we documented in the $130M+ OCR enforcement series include at least four where the primary finding was inadequate audit logging — not absent logging, inadequate.

The 7 fields every audit log must capture

These are the fields OCR expects. The first four are non-negotiable — a log missing any of these is considered incomplete. Fields 5-7 are strongly recommended and required for any app handling non-trivial PHI volume.

3 mistakes that fail real audits

The schema that passes

Here is the SQLAlchemy model we ship in every HIPAA project generated by VertiComply. It maps directly to the seven fields above and is enforced at the ORM layer so developers cannot accidentally skip a field.

# backend/compliance/hipaa_audit.py
from sqlalchemy import Column, Integer, String, DateTime, Text, Boolean, Index
from datetime import datetime
from database import Base

class AuditLog(Base):
    """HIPAA § 164.312(b) — Audit Controls."""
    __tablename__ = "audit_log"

    id             = Column(Integer, primary_key=True)
    user_id        = Column(String(64), nullable=False, index=True)
    user_role      = Column(String(32), nullable=False)
    action         = Column(String(16), nullable=False)   # READ|CREATE|UPDATE|DELETE|EXPORT
    resource_type  = Column(String(64), nullable=False)   # e.g. "patient", "prescription"
    resource_id    = Column(String(64), nullable=False)   # opaque ID only
    timestamp      = Column(DateTime, nullable=False,
                            default=datetime.utcnow, index=True)
    source_ip      = Column(String(45))                   # IPv4/IPv6
    user_agent     = Column(String(256))
    status_code    = Column(Integer)
    success        = Column(Boolean, nullable=False, default=True)
    purpose        = Column(String(32))                   # treatment|payment|operations|break_glass
    request_id     = Column(String(64), index=True)
    prev_hash      = Column(String(64))                   # for tamper-evident chain
    row_hash       = Column(String(64))

    # Composite index for the most common audit query:
    # "show me everything user X did to resource Y"
    __table_args__ = (
        Index("ix_audit_user_resource",
              "user_id", "resource_type", "resource_id", "timestamp"),
    )

Three things make this schema pass an OCR review that most hand-written schemas fail:

Retention and immutability

Minimum retention: 6 years from creation (or from “date when last in effect” for policy logs). This comes from § 164.316(b)(2)(i), not from § 164.312(b). The audit control rule says “record,” the documentation rule says “retain for 6 years.” You need both.

State overrides: California extends this to 7 years for medical records; several states require 10 years for records of pediatric patients (typically 7 years past the patient's 18th birthday, whichever is longer). For most apps, picking 10 years as your retention target covers every state.

Middleware pattern: write once, capture everywhere

Hand-writing an audit log call in every request handler is how fields get forgotten. The reliable pattern is a middleware that runs on every request and writes the audit row automatically, with the handler only needing to tag the event with its resource_id.

# backend/compliance/hipaa_audit.py (continued)
import logging
from starlette.middleware.base import BaseHTTPMiddleware

logger = logging.getLogger(__name__)

class HIPAAAuditMiddleware(BaseHTTPMiddleware):
    """Writes an audit log row for every authenticated HTTP request."""

    async def dispatch(self, request, call_next):
        response = await call_next(request)

        # Skip non-PHI paths (health, static assets, docs)
        if _is_non_phi_path(request.url.path):
            return response

        user = getattr(request.state, "user", None)
        if not user:
            return response  # Unauthenticated reqs handled by auth middleware

        try:
            entry = AuditLog(
                user_id     = str(user.id),
                user_role   = getattr(user, "role", "unknown"),
                action      = _action_from_method(request.method),
                resource_type = _resource_from_path(request.url.path),
                resource_id = getattr(request.state, "resource_id", "?"),
                source_ip   = request.client.host if request.client else None,
                user_agent  = request.headers.get("user-agent", "")[:256],
                status_code = response.status_code,
                success     = 200 <= response.status_code < 400,
                purpose     = getattr(request.state, "purpose", "operations"),
                request_id  = request.headers.get("x-request-id"),
            )
            # Hash chain — omitted for brevity; see full impl in our repo
            _write_audit(entry)
        except Exception as e:
            logger.warning("Audit write failed (non-blocking): %s", e)

        return response

Route handlers only need to set request.state.resource_id when they know it (usually after parsing the URL or loading the record). The middleware does everything else.

The 2026 shift: testable audit controls

The most important change in healthcare compliance this year is not a new regulation — it is a shift in how regulators evaluate existing ones. The 2026 HIPAA Security Rule update reframes the Audit Controls standard from “document your intent” to “prove technical enforcement.”

In practical terms: having a written policy that says “we log all PHI access” is no longer enough. Auditors now expect automated tests that verify the logging pipeline is actually capturing events — with sample queries, synthetic test data, and live verification against the running system.

This is exactly what we built into the VertiComply generation pipeline. Every HIPAA project ships with a /api/compliance-status endpoint and the builder verifies — via a live HTTP call against the running Docker container — that HIPAAAuditMiddleware is registered before the build passes. If you want the full architecture, our writeup on runtime compliance verification covers the six assertions we run on every build.

Audit-ready checklist

Run through this before your next audit, after your next refactor, or before shipping anything that touches PHI.

Related reading

Frequently asked questions