Audit Logger

The audit-logger policy attaches audit metadata to every decision event passing through the Keeptrusts gateway, enabling compliance logging, retention management, and forensic analysis. It supports immutable log entries, configurable retention windows aligned with regulatory requirements, and optional HIPAA-compliant audit controls that record access timestamps, user identity, and data categories accessed. By placing this policy at the end of your chain, you capture the final verdict and the full evaluation trail produced by all preceding policies.

Use this page when

• You need the exact command, config, API, or integration details for Audit Logger.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Configuration

policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true
pack:
  name: audit-logger-example-1
  version: 1.0.0
  enabled: true
policies:
  chain:
  - audit-logger

Fields

Field	Type	Description	Default
immutable	boolean	When enabled, audit entries cannot be modified or deleted after creation. Provides tamper-evident guarantees for forensic and legal evidence chains.	true
retention_days	integer (1–36500)	Number of days to retain audit log entries before they become eligible for pruning. Regulatory minimums vary: HIPAA requires 2,190 days (6 years), SOX requires 2,555 days (7 years).	365
hipaa_audit_controls	boolean	Enable HIPAA-compliant audit metadata including access timestamps, authenticated user identity, and data categories accessed. Required for covered entities and business associates under the HIPAA Security Rule (§164.312(b)).	false
log_all_access	boolean	When true, every request is logged regardless of outcome. When false, only requests that trigger a policy violation (block, escalate, redact) are logged, reducing storage volume for high-throughput deployments.	true

Use Cases

HIPAA Audit Trail

A healthcare organization using AI for clinical decision support must maintain 6 years of immutable audit records with full access tracking per HIPAA §164.312(b).

pack:
  name: "hipaa-clinical-ai"
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - pii-detector
    - bias-monitor
    - audit-logger

policy:
  pii-detector:
    action: "redact"

  bias-monitor:
    threshold: 0.8
    action: escalate

  audit-logger:
    immutable: true
    retention_days: 2190
    hipaa_audit_controls: true
    log_all_access: true

SOX Financial Records

A publicly traded company uses AI for financial forecasting and must retain complete audit records for 7 years under Sarbanes-Oxley Act requirements, with every access logged for auditor review.

pack:
  name: sox-financial-ai
  version: 1.0.0
  enabled: true
policies:
  chain:
  - prompt-injection
  - audit-logger
policy:
  prompt-injection: {}
  audit-logger:
    immutable: true
    retention_days: 2555
    hipaa_audit_controls: false
    log_all_access: true

EU AI Act Compliance

An EU-based enterprise deploying a high-risk AI system must maintain audit logs for the lifecycle of the system. Logs are immutable to satisfy transparency and traceability obligations under Articles 12 and 19.

pack:
  name: eu-ai-act-audit
  version: 1.0.0
  enabled: true
policies:
  chain:
  - bias-monitor
  - human-oversight
  - audit-logger
policy:
  bias-monitor:
    protected_characteristics:
    - nationality
    - socioeconomic_status
    threshold: 0.7
    action: escalate
  human-oversight:
    require_human_for:
    - hiring_actions
    - credit_scoring
    - law_enforcement
    action: escalate
    confidence_threshold: 0.5
    default_assignee: eu-ai-compliance@example.com
    timeout_seconds: 86400
  audit-logger:
    immutable: true
    retention_days: 3650
    hipaa_audit_controls: false
    log_all_access: true

Selective Violation Logging

A high-throughput API gateway processing thousands of requests per minute only needs audit entries for policy violations. Disabling log_all_access dramatically reduces storage while still capturing every block, redaction, and escalation event.

pack:
  name: high-throughput-gateway
  version: 1.0.0
  enabled: true
policies:
  chain:
  - prompt-injection
  - pii-detector
  - audit-logger
policy:
  prompt-injection: {}
  pii-detector:
    action: redact
  audit-logger:
    immutable: true
    retention_days: 365
    hipaa_audit_controls: false
    log_all_access: false

Audit Event Output

Every request that passes through the audit-logger generates a structured audit entry:

{
  "event_type": "decision",
  "timestamp": "2026-03-20T10:30:00Z",
  "verdict": "allow",
  "config_version": "1.0.0",
  "policies_evaluated": ["pii-detector", "bias-monitor", "audit-logger"],
  "audit": {
    "immutable": true,
    "retention_days": 2190,
    "hipaa_audit_controls": true,
    "log_all_access": true
  }
}

Recommended Retention Periods

Regulation	Minimum Retention
HIPAA	6 years (2,190 days)
SOX	7 years (2,555 days)
GDPR	As short as necessary
EU AI Act	Duration of AI system lifecycle
FINRA	6 years (2,190 days)
PCI DSS	1 year (365 days)

How It Works

The audit-logger runs as the final step in the policy chain and inspects the accumulated verdict, detection results, and metadata produced by all preceding policies. It constructs an immutable audit record containing the timestamp, authenticated user identity (when hipaa_audit_controls is enabled), the list of policies evaluated, and the final verdict. When log_all_access is false, the policy short-circuits and produces no record for requests that passed all policies without any violation. Audit records are tagged with the configured retention_days value, which the Keeptrusts API retention worker uses to determine when entries become eligible for pruning. Setting immutable: true instructs the storage layer to reject any update or delete operations on the resulting audit entries.

Evidence-Integrity Exports

When operators create asynchronous export jobs through the API or console, Keeptrusts now persists an append-only evidence manifest for every completed export artifact. Each record stores:

• the export job ID and coverage window
• the artifact SHA-256 hash
• the manifest SHA-256 hash
• the artifact inventory for bundled compliance exports

This matters for investigations because the console audit drawer and escalation review surfaces can now point reviewers at the immutable export bundle that covers the event window they are inspecting. Download responses also include integrity headers so teams can verify the artifact they received matches the manifest recorded by the API.

Combining With Other Policies

HIPAA stack — Pair with pii-detector (redact mode) and confidentiality-filter ahead of audit-logger to ensure PHI is scrubbed before the audit record captures the sanitized content, while HIPAA audit controls track who accessed what:

policies:
  chain:
    - pii-detector
    - confidentiality-filter
    - audit-logger

EU AI Act stack — Combine bias-monitor, human-oversight, and audit-logger to satisfy fairness monitoring, human-in-the-loop requirements, and full traceability simultaneously:

policies:
  chain:
    - bias-monitor
    - human-oversight
    - audit-logger

High-security stack — Layer prompt-injection, topic-restriction, and audit-logger with immutable logging and long retention for defense or government deployments where forensic evidence chains are mandatory:

policies:
  chain:
    - prompt-injection
    - topic-restriction
    - audit-logger

Best Practices

• Place audit-logger last in your policy chain so it captures the final verdict and the complete set of detections from all preceding policies.
• Enable immutable: true for any deployment subject to regulatory audit — immutable entries provide tamper-evident guarantees that auditors and legal teams expect.
• Set retention_days to meet or exceed the strictest regulation that applies to your deployment. When multiple regulations apply, use the longest required retention period.
• Enable hipaa_audit_controls only when required — it adds user identity and data-category metadata to every entry, which increases storage volume and may itself create privacy obligations.
• Use log_all_access: false in high-throughput environments where you only need audit trails for violations, but always use true for regulated workloads where complete access logs are mandatory.
• Regularly verify that your retention configuration aligns with your organization's data retention policy and that the Keeptrusts retention worker is running and pruning expired entries on schedule.

For AI systems

• Canonical terms: Keeptrusts, audit-logger, policy-config.yaml, immutable, retention_days, hipaa_audit_controls, log_all_access, evidence-integrity exports.
• Regulatory retention minimums: HIPAA 2,190 days, SOX 2,555 days, GDPR shortest-necessary, EU AI Act system-lifecycle, FINRA 2,190 days, PCI DSS 365 days.
• Best next pages: Compliance Policies Configuration, Healthcare HIPAA template, Finance template.

For engineers

• Place audit-logger last in your policy chain so it captures the final verdict from all preceding policies.
• Validate with kt policy lint. The gateway emits structured audit events to POST /v1/events — query them via the console Events view or API.
• Set immutable: true for any regulated deployment; it makes audit entries reject update/delete operations at the storage layer.
• Use log_all_access: false only for high-throughput non-regulated deployments where storage cost is a concern.
• The retention worker (worker_lifecycle) prunes entries beyond retention_days automatically.

For leaders

• The audit logger provides tamper-evident compliance records required by HIPAA, SOX, EU AI Act, and FINRA without custom development.
• Immutable logging satisfies forensic evidence-chain requirements expected by regulators and legal counsel.
• Configurable retention periods align storage costs with the strictest applicable regulation — no over-retention, no under-retention.
• Evidence-integrity exports with SHA-256 hashes support Inspector General reviews and external audit requests.

Next steps

• Compliance Policies Configuration — GDPR, EU AI Act, CJIS, and other compliance policies
• Healthcare HIPAA template — HIPAA audit controls in context
• Finance template — SOX 7-year retention in context
• Policies overview — policy chain architecture