Audit Logs

Phase 14 · Document 06 · Security, Privacy and Governance Prev: 05 — Policy and Guardrails · Up: Phase 14 Index

Table of Contents

1. Why This Matters
2. Core Concept
3. Mental Model
4. Hitchhiker's Guide
5. Warmup Readings
6. Deep Readings and External References
7. Key Terms
8. Important Facts
9. Observations from Real Systems
10. Common Misconceptions
11. Engineering Decision Framework
12. Hands-On Lab
13. Verification Questions
14. Takeaways
15. Artifact Checklist

1. Why This Matters

When something goes wrong — an injection succeeds, an agent takes a destructive action, a tenant sees another's data, a user disputes a decision, a regulator asks "who accessed this record?" — the audit log is the only thing that lets you answer. Without it you can't detect an attack, investigate an incident, prove compliance, or even reconstruct what your non-deterministic system did. Audit logging is where security, privacy, and governance converge into evidence: it's how you detect the threats from docs 01–05, how you prove the privacy controls from 02 actually ran, and the foundation regulators and enterprise buyers demand in 07. But LLM logging has a built-in tension: the most useful thing to log (the full prompt/response) is also the most privacy-dangerous (it's full of PII, 02). This doc is how to log enough to be safe and accountable — without becoming the breach.

2. Core Concept

Plain-English primer: a tamper-evident record of who did what, when

An audit log is a durable, append-only record of consequential events: who (actor/tenant), did what (action), to what (resource), when (timestamp), from where (context), and what happened (outcome). It's distinct from debug logs (developer diagnostics, ephemeral) — audit logs are security/compliance artifacts that must be trustworthy (you can rely on them in an investigation or audit) and often retained for years.

AUDIT EVENT = { who (actor + tenant_id) , what (action) , resource , when (ts) , where (ip/session) , outcome (allow/deny/error) , correlation_id }
   append-only · tamper-evident · access-controlled · PII-safe · retained per policy
DISTINCT FROM debug/telemetry logs (diagnostics, short-lived, may be noisy)

What to log in an LLM system (the consequential events)

• Every model interaction (metadata): request id, tenant/user, model, token counts, latency, cost, timestamp — for usage, cost, and incident reconstruction (Phase 7.08/Phase 8.06).
• Every tool/agent action: which tool, arguments (sanitized), authorization decision, result, and especially any state-changing/irreversible action (Phase 10.05/Phase 10.08).
• Every guardrail/policy decision: what was blocked/redacted/allowed and why — proves your safety layer ran (05).
• Access to sensitive data: who retrieved which documents/records (RAG access, Phase 9) — required for "who accessed X?" (04).
• Auth & admin events: logins, permission changes, key rotation/issuance (03), config changes.
• Security events: detected injection attempts, rate-limit hits, anomalies, denied actions.

The defining property: trustworthy and tamper-evident

An audit log is only useful if it can't be quietly altered or deleted:

• Append-only / immutable — no updates or deletes; corrections are new events. Use WORM storage, append-only tables, or a log service that enforces it.
• Tamper-evident — hash chaining (each entry includes the prior entry's hash) or signing, so any alteration is detectable.
• Access-controlled — only authorized roles can read audit logs (they contain sensitive info); reads themselves may be audited.
• Time-synced — reliable timestamps (NTP) so sequences are reconstructable.
• Retained per policy — long enough for compliance (often years, 07), but balanced against privacy (don't keep PII-laden content forever, 02).

The privacy tension: log accountability, not PII content

This is the LLM-specific crux. The full prompt/response is the most useful debugging artifact and the most dangerous privacy liability:

• Default to metadata, not content — log that a request happened (ids, counts, decision), not necessarily what was in it.
• Scrub/redact PII before any content lands in logs (02); never log secrets/keys (03).
• Separate stores — keep high-PII content (if you must retain it for debugging/eval) in a separate, short-retention, access-controlled store, distinct from the long-lived audit trail.
• Honor erasure — if content logs contain personal data, they're in scope for deletion requests (02).
• Tag with tenant_id so logs are isolated and one tenant's data never surfaces in another's view (04).

Traceability: correlation IDs and end-to-end traces

A single user action fans out into many calls (retrieval, multiple model calls, tool calls). A correlation/request ID propagated across all of them lets you reconstruct the full chain of what happened — essential for debugging non-determinism and for incident forensics. This is the audit-grade extension of agent/LLM observability and tracing (Phase 10.08/Phase 7.08): observability answers "is it healthy/fast?"; the audit trail answers "who did what, and can I prove it?"

Incident response: logs are the substrate

When (not if) you're probed or breached, the audit log drives the IR loop: detect (alerts on anomalies/denied actions/spend spikes) → investigate (reconstruct via correlation ID) → contain (revoke keys [03], disable a tenant/tool) → remediate → report (regulators/customers within legal deadlines, 07). Have an IR plan before you need it; the log is what makes every step possible. Assume breach — design logs to support the investigation you hope never to run.

3. Mental Model

   AUDIT LOG = durable, append-only, tamper-evident record of CONSEQUENTIAL events: WHO(actor+tenant) · WHAT(action) · RESOURCE · WHEN · WHERE · OUTCOME · correlation_id
   ≠ debug/telemetry logs (diagnostics, short-lived). Audit = security/compliance EVIDENCE, retained for years.

   LOG (in an LLM system): model interactions (METADATA) · TOOL/agent actions (esp. irreversible [10.05]) · GUARDRAIL/policy decisions [05] ·
                            sensitive-data ACCESS (who retrieved what [04/9]) · auth/admin/key events [03] · security events (injection/rate-limit/anomaly)

   ★ TRUSTWORTHY: APPEND-ONLY/immutable · TAMPER-EVIDENT (hash-chain/sign) · ACCESS-CONTROLLED · time-synced · retained per policy [07]
   ★ PRIVACY TENSION: full prompt/response = most useful + most dangerous (PII [02])
       → default to METADATA not content · SCRUB PII / never log secrets [02/03] · SEPARATE short-retention store for content ·
         honor ERASURE · tag tenant_id [04]

   TRACEABILITY: correlation/request ID across retrieval→model→tool calls → reconstruct the chain (audit-grade observability [10.08/7.08])
       observability = "healthy/fast?" · AUDIT = "who did what, provably?"
   INCIDENT RESPONSE loop (logs are the substrate): DETECT(alerts) → INVESTIGATE(correlation id) → CONTAIN(revoke [03]/disable) → REMEDIATE → REPORT [07]. Assume breach.

Mnemonic: log who-did-what-when for every consequential action in an append-only, tamper-evident, access-controlled trail — but log accountability, not PII content (scrub, separate, short-retain); thread a correlation ID so you can reconstruct the chain; and treat the audit log as the substrate for detection, investigation, and proof.

4. Hitchhiker's Guide

What to look for first: are consequential actions logged (tool calls, data access, guardrail decisions, auth/key events) in a tamper-evident, access-controlled trail — and is PII kept out of it? Those two (completeness + privacy-safety) define a good audit log.

What to ignore at first: logging full prompt/response content everywhere. Start with metadata + decisions + correlation IDs; add scrubbed content selectively in a separate short-retention store only where you truly need it.

What misleads beginners:

• Confusing debug logs with audit logs. Audit logs must be trustworthy, immutable, retained — not best-effort diagnostics.
• Logging full prompts/responses verbatim. That's a PII/secret breach in your logs — scrub, default to metadata (02/03).
• Mutable logs. If logs can be edited/deleted, they're worthless in an investigation — append-only + tamper-evident.
• No correlation ID. You can't reconstruct a multi-call chain — propagate a request ID.
• No alerting. A log nobody watches doesn't detect anything — alert on anomalies/denied actions/spend spikes.
• Keeping PII-laden logs forever. Violates retention/erasure (02) and grows breach blast radius.

How experts reason: they log every consequential event (actions, access, decisions, auth) with a correlation ID, in an append-only, tamper-evident, access-controlled store retained per compliance (07), while keeping PII/secrets out (metadata-first, scrub, separate short-retention content store), tag tenant_id (04), alert on anomalies, and maintain an IR plan the log is built to support. They separate audit (provable accountability) from observability (health/perf).

What matters in production: completeness (every consequential action), trustworthiness (immutable/tamper-evident), privacy-safety (no PII/secrets), traceability (correlation IDs), detection (alerting), and retention that satisfies compliance without hoarding PII.

How to debug/verify: can you reconstruct a given user action end-to-end from logs? Can you answer "who accessed record X?" Are logs immutable (try to alter one)? Grep logs for PII/keys (should be none). Do alerts fire on a simulated anomaly? Does retention match policy?

Questions to ask: are consequential actions logged with who/what/when/outcome? immutable + tamper-evident + access-controlled? PII/secrets kept out? correlation IDs for reconstruction? tenant-tagged? alerting + IR plan? retention per compliance?

What silently fails you: missing action/access logs (can't investigate), mutable logs (can't trust), PII/secrets in logs (breach), no correlation IDs (can't reconstruct), no alerting (can't detect), and infinite PII retention.

5. Warmup Readings

6. Deep Readings and External References

7. Key Terms

8. Important Facts

• The audit log is how you detect attacks, investigate incidents, and prove compliance — security, privacy, and governance converge into evidence here.
• Audit logs ≠ debug logs — audit logs must be trustworthy (reliable in an investigation/audit) and are often retained for years (07).
• Log consequential events: model interactions (metadata), tool/agent actions (esp. irreversible, Phase 10.05), guardrail decisions (05), sensitive-data access (04), auth/key events (03), security events.
• Audit logs must be append-only/immutable, tamper-evident (hash-chain/sign), access-controlled, time-synced, and retained per policy.
• Privacy tension: log accountability, not PII content — default to metadata, scrub PII, never log secrets, keep content in a separate short-retention store, honor erasure (02/03).
• Propagate a correlation ID across retrieval→model→tool calls to reconstruct the chain (Phase 10.08).
• Observability answers "healthy/fast?"; the audit trail answers "who did what, provably?" (Phase 7.08).
• Logs are the substrate of incident response (detect→investigate→contain→remediate→report) — have an IR plan and assume breach.

9. Observations from Real Systems

• "Who accessed this record?" is a routine compliance/customer question — teams without per-access audit logs (esp. for RAG document retrieval) can't answer it and fail audits (04/07).
• PII discovered in logs is a common self-inflicted breach — verbatim prompt logging in the observability stack; the fix is metadata-first + scrubbing (02).
• Immutable audit stores (CloudTrail-style, hash-chained) are the norm where logs must hold up in an investigation — mutable logs get challenged.
• Correlation IDs / OpenTelemetry traces are how teams debug non-deterministic agent chains and reconstruct incidents (Phase 10.08).
• The teams that survive incidents are the ones who logged tool actions + guardrail decisions and had an IR plan ready — detection and reconstruction beat scrambling after the fact.

10. Common Misconceptions

11. Engineering Decision Framework

AUDIT LOGGING FOR AN LLM APP:
 1. DEFINE consequential events: tool/agent actions (esp. irreversible [10.05]), data access [04/9], guardrail decisions [05],
    auth/key events [03], security events, model-interaction metadata.
 2. SCHEMA per event: who(actor+tenant_id) · what · resource · when · where · outcome · correlation_id.
 3. TRUSTWORTHY store: append-only/immutable + tamper-evident (hash-chain/sign) + access-controlled + time-synced.
 4. PRIVACY: metadata-FIRST (not content); scrub PII; NEVER log secrets [02/03]; content (if needed) → separate short-retention store; honor erasure.
 5. TRACEABILITY: propagate a correlation ID across retrieval→model→tool calls [10.08].
 6. DETECT: alert on anomalies, denied actions, spend spikes [7.09]; tag tenant_id [04].
 7. RETENTION: long for audit/compliance [07], short for PII content [02] — split them.
 8. IR PLAN: detect→investigate(correlation id)→contain(revoke [03]/disable)→remediate→report [07]. Assume breach.

12. Hands-On Lab

Goal

Build a PII-safe, tamper-evident audit log for an LLM app that records consequential actions with correlation IDs, and use it to reconstruct an incident and answer "who accessed what?"

Prerequisites

• An LLM app with at least one tool and a RAG retrieval step; a datastore for logs; a PII scrubber (02).

Steps

1. Define events + schema: decide what's consequential (tool calls, doc access, guardrail decisions, auth) and a schema (who/what/resource/when/where/outcome/correlation_id).
2. Instrument: emit an audit event for each — metadata-first, scrubbing any content and never logging secrets (03); tag tenant_id (04).
3. Correlation ID: generate one per user request and propagate it through retrieval → model call(s) → tool call(s).
4. Tamper-evidence: store append-only and hash-chain entries (each includes the prior hash); show that altering an entry breaks the chain.
5. Reconstruct: given a correlation ID, reconstruct the full chain of what happened; and answer "who accessed document D?" from the access events.
6. Detect + IR: add an alert on a simulated anomaly (e.g., a denied destructive action or a spend spike) and write a short IR runbook (detect→investigate→contain→report).

Expected output

A PII-safe, append-only, hash-chained audit log capturing consequential actions with correlation IDs, a demonstrated incident reconstruction, a "who accessed X?" query, a tamper-detection demo, and an IR runbook.

Debugging tips

• Grep the log for emails/keys — found any? Your scrubbing/metadata-first is incomplete (02).
• If you can edit an entry without breaking the chain, your tamper-evidence isn't wired.

Extension task

Add OpenTelemetry trace/span IDs and compare audit logging vs observability tracing (Phase 10.08); split audit (long retention) from content (short retention) stores.

Production extension

Ship audit events to an immutable store (e.g., CloudTrail-style/WORM), wire alerting on denied actions/anomalies, enforce access control + retention per compliance (07), and centralize at the gateway (Phase 8.09).

What to measure

Coverage of consequential actions, PII/secrets in logs (target 0), tamper-detection works, reconstruction success, alert firing, retention adherence.

Deliverables

• A PII-safe, append-only, tamper-evident audit log with a defined schema.
• Correlation-ID propagation + an incident reconstruction + a "who accessed X?" answer.
• An alert on an anomaly + a short IR runbook.

13. Verification Questions

Basic

1. How does an audit log differ from a debug log?
2. What fields define an audit event?
3. Why must audit logs be append-only and tamper-evident?

Applied 4. What's the privacy tension in LLM logging and how do you resolve it? 5. What is a correlation ID and why is it essential?

Debugging 6. You find emails and an API key in your logs. What went wrong and how do you fix it? 7. A regulator asks "who accessed patient record X?" — what must your logs support?

System design 8. Design an audit-logging system for a multi-tenant LLM agent (events, schema, immutability, privacy, IR).

Startup / product 9. Why are audit logs both a compliance requirement and an incident-response necessity?

14. Takeaways

1. The audit log is how you detect, investigate, and prove — security/privacy/governance converge into evidence here.
2. Log every consequential action (tool calls, data access, guardrail decisions, auth) in an append-only, tamper-evident, access-controlled trail (Phase 10.05/05).
3. Log accountability, not PII content — metadata-first, scrub PII, never log secrets, separate short-retention content (02/03).
4. Propagate correlation IDs to reconstruct multi-call chains — audit answers "who did what, provably?" vs observability's "healthy/fast?" (Phase 10.08).
5. Logs are the substrate of incident response — alert, have an IR plan, assume breach, retain per compliance (07).

15. Artifact Checklist

• A defined audit-event schema (who/what/resource/when/where/outcome/correlation_id).
• Append-only + tamper-evident (hash-chained/signed), access-controlled storage.
• PII-safe logging (metadata-first, scrubbed, no secrets) + tenant tagging.
• Correlation-ID propagation enabling chain reconstruction + "who accessed X?".
• Alerting on anomalies + an IR runbook + a retention split (audit vs content).

Up: Phase 14 Index · Next: 07 — Compliance Readiness