Audit Logging Configuration

Configure audit logging backends including file, local database, Cerbos Hub, and Kafka for tracking access decisions and API calls

Cerbos audit logging captures detailed records of authorization decisions and API access for compliance, debugging, and analytics.

Overview

Audit logs provide visibility into:

• Access Logs: API requests and responses
• Decision Logs: Policy evaluation results for CheckResources and PlanResources calls

Supported backends:

• file: Write logs to local files with rotation
• local: Store logs in embedded BadgerDB database
• hub: Send logs to Cerbos Hub
• kafka: Stream logs to Kafka topics

Basic Configuration

audit.enabled · boolean · default: "false"

Enable or disable audit logging globally.

audit.backend · string · default: "local"

Audit backend to use: file, local, hub, or kafka.

audit.accessLogsEnabled · boolean · default: "true"

Enable logging of API access events.

audit.decisionLogsEnabled · boolean · default: "true"

Enable logging of policy decision events.

audit:
  enabled: true
  backend: file
  accessLogsEnabled: true
  decisionLogsEnabled: true

Metadata Filtering

Control which gRPC metadata (headers) are included in audit logs.

audit.includeMetadataKeys · string[]

List of metadata keys to include in logs. If empty, all metadata is included.

audit.excludeMetadataKeys · string[]

List of metadata keys to exclude from logs. Takes precedence over includeMetadataKeys.

audit:
  enabled: true
  includeMetadataKeys:
    - "content-type"
    - "user-agent"
  excludeMetadataKeys:
    - "authorization"
    - "cookie"

Always exclude sensitive headers like authorization to prevent credential leakage in logs.

Decision Log Filters

Reduce log volume by filtering decision logs based on outcomes.

CheckResources Filters

audit.decisionLogFilters.checkResources.ignoreAllowAll · boolean · default: "false"

Ignore decisions where all actions are allowed (no EFFECT_DENY).

audit:
  enabled: true
  decisionLogFilters:
    checkResources:
      ignoreAllowAll: true  # Only log denials

PlanResources Filters

audit.decisionLogFilters.planResources.ignoreAll · boolean · default: "false"

Ignore all plan responses. Takes precedence over other filters.

audit.decisionLogFilters.planResources.ignoreAlwaysAllow · boolean · default: "false"

Ignore ALWAYS_ALLOWED plan responses.

audit:
  enabled: true
  decisionLogFilters:
    planResources:
      ignoreAlwaysAllow: true  # Only log conditional or denied plans

File Backend

Write audit logs to local files with automatic rotation.

audit.file.path · string · default: "stdout" · required

Path to the log file. Special values: stdout, stderr.

audit.file.additionalPaths · string[]

Additional paths to mirror log output. Use with caution due to performance impact.

Log Rotation

audit.file.logRotation.maxFileSizeMB · integer

Maximum size of individual log files in megabytes before rotation.

audit.file.logRotation.maxFileAgeDays · integer

Maximum age in days of old log files before deletion.

audit.file.logRotation.maxFileCount · integer

Maximum number of rotated files to retain.

audit:
  enabled: true
  backend: file
  file:
    path: /var/log/cerbos/audit.log
    logRotation:
      maxFileSizeMB: 100
      maxFileAgeDays: 30
      maxFileCount: 10

Writing to stdout

audit:
  enabled: true
  backend: file
  file:
    path: stdout

Writing to stdout is useful for container environments where logs are collected by external systems.

Local Backend

Store audit logs in an embedded BadgerDB database for querying via Admin API.

audit.local.storagePath · string · required

Directory path to store the BadgerDB database.

audit.local.retentionPeriod · duration · default: "168h"

How long to retain audit records. Min: 1h, Max: 720h (30 days).

Advanced Settings

audit.local.advanced.bufferSize · integer · default: "16"

Number of records to buffer before writing.

audit.local.advanced.maxBatchSize · integer · default: "16"

Maximum number of records to write in a single batch.

audit.local.advanced.flushInterval · duration · default: "30s"

Interval to flush buffered records. Min: 1s.

audit.local.advanced.gcInterval · duration · default: "15m"

Interval to run garbage collection for expired records.

audit:
  enabled: true
  backend: local
  local:
    storagePath: /var/cerbos/audit
    retentionPeriod: 168h  # 7 days
    advanced:
      bufferSize: 256
      maxBatchSize: 32
      flushInterval: 10s
      gcInterval: 30m

Local backend enables querying audit logs via the Admin API’s audit log endpoints.

Cerbos Hub Backend

Send audit logs to Cerbos Hub for centralized management and analytics.

audit.hub.storagePath · string · required

Local storage path for buffering logs before sending to Hub.

audit.hub.retentionPeriod · duration · default: "168h"

How long to retain logs locally before deletion.

Masking Sensitive Data

audit.hub.mask.peer · string[]

JSONPath expressions to mask in peer information.

audit.hub.mask.metadata · string[]

Metadata keys to mask.

audit.hub.mask.checkResources · string[]

JSONPath expressions to mask in CheckResources logs.

audit.hub.mask.planResources · string[]

JSONPath expressions to mask in PlanResources logs.

audit:
  enabled: true
  backend: hub
  hub:
    storagePath: /var/cerbos/audit
    retentionPeriod: 168h
    mask:
      peer:
        - address
        - forwarded_for
      metadata:
        - authorization
      checkResources:
        - inputs[*].principal.attr.ssn
        - inputs[*].auxData
      planResources:
        - input.principal.attr.secretKey

Ingest Configuration

audit.hub.ingest.minFlushInterval · duration · default: "5s"

Minimum duration between Hub ingest requests. Min: 2s.

audit.hub.ingest.flushTimeout · duration · default: "5s"

Maximum timeout for each ingest request. Max: 10s.

audit.hub.ingest.numGoRoutines · integer · default: "4"

Number of goroutines for streaming logs from local DB.

audit.hub.ingest.maxBatchSizeBytes · integer · default: "4194304"

Maximum cumulative size in bytes for a batch of log entries (4MB).

audit:
  enabled: true
  backend: hub
  hub:
    storagePath: /var/cerbos/audit
    ingest:
      minFlushInterval: 3s
      flushTimeout: 5s
      numGoRoutines: 8
      maxBatchSizeBytes: 2097152  # 2MB

Pipe Output

audit.hub.pipeOutput.enabled · boolean · default: "false"

Enable piping logs to another backend in addition to Hub.

audit.hub.pipeOutput.backend · string

Additional backend to send logs to: file, local, or kafka.

audit:
  enabled: true
  backend: hub
  hub:
    storagePath: /var/cerbos/audit
    pipeOutput:
      enabled: true
      backend: file
  file:
    path: /var/log/cerbos/audit.log

Kafka Backend

Stream audit logs to Kafka topics for real-time processing.

audit.kafka.brokers · string[] · required

List of Kafka broker addresses.

audit.kafka.topic · string · required

Kafka topic to write audit entries to.

audit.kafka.encoding · string · default: "json"

Encoding format: json or protobuf.

audit.kafka.ack · string · default: "all"

Acknowledgment mode: none, leader, or all. Idempotency disabled when not all.

audit.kafka.clientID · string · default: "cerbos"

Client ID reported in Kafka connections.

audit.kafka.compression · string[] · default: "['snappy', 'none']"

Compression algorithms in priority order: none, gzip, snappy, lz4, zstd.

audit.kafka.closeTimeout · duration · default: "30s"

Timeout when closing client to flush remaining messages.

audit.kafka.maxBufferedRecords · integer · default: "250"

Maximum records to buffer in memory in async mode.

audit.kafka.produceSync · boolean · default: "false"

Force synchronous message production. Significant performance impact.

audit:
  enabled: true
  backend: kafka
  kafka:
    brokers:
      - kafka-1.internal:9092
      - kafka-2.internal:9092
      - kafka-3.internal:9092
    topic: cerbos.audit.log
    encoding: json
    ack: all
    clientID: cerbos-prod
    compression:
      - snappy
      - lz4
    closeTimeout: 30s
    maxBufferedRecords: 1000
    produceSync: false

TLS Authentication

audit.kafka.authentication.tls.caPath · string · required

Path to CA certificate for verifying broker certificates.

audit.kafka.authentication.tls.certPath · string

Path to client certificate for mutual TLS.

audit.kafka.authentication.tls.keyPath · string

Path to client private key for mutual TLS.

audit.kafka.authentication.tls.reloadInterval · duration · default: "0s"

Interval to reload TLS certificates. Set to 0 to disable.

audit.kafka.authentication.tls.insecureSkipVerify · boolean · default: "false"

Skip verification of server certificate chain and hostname.

audit:
  enabled: true
  backend: kafka
  kafka:
    brokers:
      - kafka.internal:9093
    topic: cerbos.audit.log
    authentication:
      tls:
        caPath: /etc/cerbos/kafka/ca.crt
        certPath: /etc/cerbos/kafka/client.crt
        keyPath: /etc/cerbos/kafka/client.key
        reloadInterval: 5m

Never set insecureSkipVerify: true in production. This disables critical security checks.

Complete Examples

Production File Logging

audit:
  enabled: true
  backend: file
  accessLogsEnabled: true
  decisionLogsEnabled: true
  excludeMetadataKeys:
    - authorization
    - cookie
  decisionLogFilters:
    checkResources:
      ignoreAllowAll: false
  file:
    path: /var/log/cerbos/audit.log
    logRotation:
      maxFileSizeMB: 500
      maxFileAgeDays: 90
      maxFileCount: 30

Production Local Database

audit:
  enabled: true
  backend: local
  accessLogsEnabled: true
  decisionLogsEnabled: true
  excludeMetadataKeys:
    - authorization
  local:
    storagePath: /var/cerbos/audit
    retentionPeriod: 720h  # 30 days
    advanced:
      bufferSize: 512
      maxBatchSize: 64
      flushInterval: 5s
      gcInterval: 60m

Production Kafka Streaming

audit:
  enabled: true
  backend: kafka
  accessLogsEnabled: true
  decisionLogsEnabled: true
  excludeMetadataKeys:
    - authorization
    - cookie
  decisionLogFilters:
    checkResources:
      ignoreAllowAll: true
  kafka:
    brokers:
      - kafka-1.prod:9093
      - kafka-2.prod:9093
      - kafka-3.prod:9093
    topic: cerbos.audit.production
    encoding: protobuf
    ack: all
    clientID: cerbos-prod-cluster
    compression:
      - zstd
      - snappy
    maxBufferedRecords: 2000
    authentication:
      tls:
        caPath: /etc/cerbos/kafka/ca.crt
        certPath: /etc/cerbos/kafka/client.crt
        keyPath: /etc/cerbos/kafka/client.key

Development Configuration

audit:
  enabled: true
  backend: file
  accessLogsEnabled: true
  decisionLogsEnabled: true
  file:
    path: stdout