ROOT:partial$attributes.adoc
The audit
block configures the audit logging settings for the Cerbos instance. Audit logs capture access records and decisions made by the engine along with the associated context data.
Note
|
Audit logging has some overhead in terms of resource usage (disk IO, CPU and memory). This overhead is usually negligible unless Cerbos is running in a resource-constrained environment. If resources are scarce or if you are expecting heavy traffic, disabling audit logging might have a positive impact on performance. |
audit:
enabled: true # Set to false to completely disable audit logging.
accessLogsEnabled: true # Log API access attempts
decisionLogsEnabled: true # Log policy decisions
excludeMetadataKeys: ['authorization'] # Excludes given gRPC request metadata keys from audit logs.(Takes precedence over includeMetadataKeys)
includeMetadataKeys: ['content-type'] # Includes given gRPC request metadata keys in audit logs.
decisionLogFilters: # DecisionLogFilters define the filters to apply while producing decision logs.
checkResources: # CheckResources defines the filters that apply to CheckResources calls.
ignoreAllowAll: false # IgnoreAllowAll ignores responses that don't contain an EFFECT_DENY.
planResources: # PlanResources defines the filters that apply to PlanResources calls.
ignoreAll: false # IgnoreAll prevents any plan responses from being logged. Takes precedence over other filters.
ignoreAlwaysAllow: false # IgnoreAlwaysAllow ignores ALWAYS_ALLOWED plans.
backend: local # Audit backend to use.
file: # Configuration for the file audit backend
path: /path/to/file.log # Path to the log file to use as output. The special values stdout and stderr can be used to write to stdout or stderr respectively.
local: # Configuration for the local audit backend
storagePath: /path/to/dir # Path to store the data
retentionPeriod: 168h # Records older than this will be automatically deleted
kafka:
ack: all # Ack mode for producing messages. Valid values are "none", "leader" or "all" (default). Idempotency is disabled when mode is not "all".
brokers: ['localhost:9092'] # Required. Brokers list to seed the Kafka client.
clientID: cerbos # ClientID reported in Kafka connections.
closeTimeout: 30s # CloseTimeout sets how long when closing the client to wait for any remaining messages to be flushed.
encoding: json # Encoding format. Valid values are "json" (default) or "protobuf".
maxBufferedRecords: 1000 # MaxBufferedRecords sets the maximum number of records the client should buffer in memory in async mode.
produceSync: false # ProduceSync forces the client to produce messages to Kafka synchronously. This can have a significant impact on performance.
topic: cerbos.audit.log # Required. Topic to write audit entries to.
To tune how request metadata (headers) is logged to access and decision log entries, configure includeMetadataKeys
and excludeMetadataKeys
as follows:
-
Both
includeMetadataKeys
andexcludeMetadataKeys
are empty: no metadata will be logged -
Only
includeMetadataKeys
is defined: only the metadata keys in the list will be logged -
Only
excludeMetadataKeys
is defined: everything except the keys defined in the list will be logged -
Both
includeMetadataKeys
andexcludeMetadataKeys
are defined: Only the keys in the include list will be logged if, and only if, they are not in the exclude list
Caution
|
If requests contain sensitive data such as authorization tokens, they will be captured by the audit logs and visible to anyone with access to the log files. Cerbos automatically excludes the authorization header. However, if you use other header keys to store sensitive data, always exclude them using the excludeMetadataKeys configuration setting.
|
The local
backend uses an embedded key-value store to save audit records. Records are preserved for seven days by default and can be queried using the Admin API, the cerbosctl audit
command or the cerbosctl decisions
text interface (TUI).
The only required setting for the local
backend is the storagePath
field which specifies the path on disk where the logs should be stored.
audit:
enabled: true
accessLogsEnabled: true
decisionLogsEnabled: true
backend: local
local:
storagePath: /path/to/dir
retentionPeriod: 168h
advanced:
bufferSize: 16 # Size of the memory buffer. Increasing this will use more memory and the chances of losing data during a crash.
maxBatchSize: 16 # Write batch size. If your records are small, increasing this will reduce disk IO.
flushInterval: 30s # Time to keep records in memory before committing.
gcInterval: 15m # How often the garbage collector runs to remove old entries from the log.
The file
backend writes audit records as newline-delimited JSON to a file or stdout/stderr. With this backend you can use your existing log aggregation system (DataDog agent, Elastic agent, Fluentd, Graylog — to name a few) to collect, process and archive the audit data from all Cerbos instances.
Note
|
This backend cannot be queried using the Admin API, cerbosctl audit or cerbosctl decisions .
|
audit:
enabled: true
accessLogsEnabled: true
decisionLogsEnabled: true
backend: file
file:
path: /path/to/audit.log
The path
field can be set to special names stdout
or stderr
to log to stdout or stderr. Note that this would result in audit logs being mixed up with normal Cerbos operational logs. It is recommended to use an actual file for audit log output if your container orchestrator has support for collecting logs from files in addition to stdout/stderr.
Audit log entries can be selected by setting a filter on log.logger == "cerbos.audit"
. Access log entries have log.kind == "access"
and decision log entries have log.kind == "decision"
.
The kafka
backend writes audit records to a Kafka topic. By default, the messages are published asynchronously to the specified topic in JSON format. The message header named cerbos.audit.kind
would have the value access
for access log entries and decision
for decision log entries.
You can configure the audit logger to produce data in the Protocol Buffers binary encoding format as well. The schema for messages is available at https://buf.build/cerbos/cerbos-api/docs/main:cerbos.audit.v1.
audit:
enabled: true
accessLogsEnabled: true
decisionLogsEnabled: true
backend: kafka
kafka:
brokers: ['broker1.kafka:9092', 'broker2.kafka:9092']
topic: cerbos.audit.log
audit:
enabled: true
accessLogsEnabled: true
decisionLogsEnabled: true
backend: kafka
kafka:
ack: all # Ack mode for producing messages. Valid values are "none", "leader" or "all" (default). Idempotency is disabled when mode is not "all".
brokers: ['localhost:9092'] # Required. Brokers list to seed the Kafka client.
clientID: cerbos # ClientID reported in Kafka connections.
closeTimeout: 30s # CloseTimeout sets how long when closing the client to wait for any remaining messages to be flushed.
encoding: json # Encoding format. Valid values are "json" (default) or "protobuf".
maxBufferedRecords: 1000 # MaxBufferedRecords sets the maximum number of records the client should buffer in memory in async mode.
produceSync: false # ProduceSync forces the client to produce messages to Kafka synchronously. This can have a significant impact on performance.
topic: cerbos.audit.log # Required. Topic to write audit entries to.