> ## Documentation Index
> Fetch the complete documentation index at: https://trust.denialbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit logging

> Every PHI action, every authentication event — logged with 7-year retention.

<Info>
  HIPAA requires a detailed audit trail of PHI access. Denialbase logs at two levels — a dedicated HIPAA audit log and a security event log — with 7-year retention (exceeds the 6-year HIPAA minimum).
</Info>

## HIPAA audit log

Every action that accesses, modifies, creates, exports, or discloses PHI is recorded in a structured log.

### What's captured

| Field      | Example                                                        |
| ---------- | -------------------------------------------------------------- |
| Event type | `access`, `create`, `update`, `delete`, `export`, `disclosure` |
| Actor      | User ID, role, authentication method                           |
| Resource   | Model name + ID (e.g. `OverturnableDenial#1234`)               |
| Action     | HTTP method + route, or internal service call                  |
| Result     | Success / failure / authorization denied                       |
| Metadata   | IP address, user agent, request ID                             |
| Timestamp  | ISO 8601 UTC, millisecond precision                            |

<Warning>
  We log **event metadata**, not the PHI itself. A log entry records that user X viewed denial Y — not the contents of that denial. This prevents the audit log from becoming another copy of the PHI that needs equivalent protection.
</Warning>

### Where it lives

* Stored in the `hipaa_audit_logs` table in our primary PostgreSQL database.
* Forwarded to GCP Cloud Logging for long-term retention and SIEM integration.
* Retention: **7 years** (2555 days), enforced by a scheduled cleanup job.
* Access to the audit log is itself audit-logged.

### When it fires

* Every controller action on a PHI-bearing model.
* Every document download (EOB, appeal letter, medical record).
* Every export (JSON, CSV, PDF).
* Every admin or support action that views customer data.
* Every failed authorization attempt on a PHI resource.

## Security audit log

A separate log captures authentication and account-lifecycle events that do not involve PHI.

### What's captured

* Login success and failure (with reason: wrong password, unknown user, expired, etc.)
* Account lockout and unlock events
* Password changes
* 2FA enrollment, removal, and use
* Passkey registration and deletion
* Admin actions (role changes, user deletions, data exports)
* Session termination

### Retention

Same 7-year retention policy applies.

## Access to logs

* **Customer access** — covered-entity admins can view their own organization's HIPAA audit log via the admin panel; exports available on request.
* **Internal access** — Denialbase engineering access to logs is role-gated and itself audit-logged. All production log reads are recorded.
* **Regulator access** — in the event of a HIPAA breach investigation, we can produce the full audit trail filtered by date range, actor, or resource, under a signed request.

## Integrity controls

* Log entries are write-once — our application does not expose update or delete operations against the `hipaa_audit_logs` table.
* Database roles for the runtime service account do not include `UPDATE` or `DELETE` privileges on the audit log tables.
* Cloud Logging sink provides a tamper-evident archive independent of the application database.
* Planned: cryptographic chain-of-custody (hash-chained entries) as part of the scoped-delegation work, Q3 2026.

## Alerting

The following events trigger GCP Monitoring alerts in near-real-time:

| Alert                               | Trigger                       | Severity      |
| ----------------------------------- | ----------------------------- | ------------- |
| High failed-login rate              | >20 failures in 5 minutes     | Critical      |
| Account lockout                     | Any lockout event             | Warning       |
| Bulk data export                    | Any export                    | Informational |
| Admin action outside business hours | Role change, deletion, export | Informational |

*See [Incident response](/trust/incident-response) for what happens when an alert fires.*