Audit log collection

With just a simple configuration change, you can configure the PDPs to securely send audit logs to Cerbos Hub. This vastly simplifies the work that would otherwise be required to configure and deploy a log aggregation solution to securely collect, store and query audit logs from across your fleet.

To get started, you need to obtain a set of client credentials. Navigate to the Settings tab of your workspace and click on "Generate client credentials" to generate a client ID and a client secret. The client secret is not stored on Cerbos Hub and cannot be recovered. Make sure to save it in a secure place.

The client credentials can be provided to the PDP using environment variables or the configuration file. The environment variables to set are:

`CERBOS_HUB_CLIENT_ID`	Client ID
`CERBOS_HUB_CLIENT_SECRET`	Client secret
`CERBOS_HUB_PDP_ID`	Optional. A unique name for the PDP. If not provided, a random value is used.

Alternatively, you can define these values in the Cerbos configuration file as follows:

hub:
  credentials:
    pdpID: "..." # Optional. Identifier for this Cerbos instance.
    clientID: "..." # ClientID
    clientSecret: "..." # ClientSecret

To enable audit log collection, configure the hub audit log backend with a local storage path. This local storage path is important for preserving the audit logs until they are safely saved to Cerbos Hub. If there are any network interruptions or if the PDP process crashes, the audit logs generated up to that point are saved on disk and will be sent to Cerbos Hub the next time the PDP starts. If you’re using a container orchestrator or a cloud-based solution to deploy Cerbos, attach a persistent storage volume at this path to ensure that the data does not get lost.

server:
  httpListenAddr: ":3592" # The port the HTTP server will listen on
  grpcListenAddr: ":3593" # The port the gRPC server will listen on

hub:
  credentials:
    pdpID: "..." # Optional. Identifier for this Cerbos instance.
    clientID: "..." # ClientID
    clientSecret: "..." # ClientSecret

audit:
  enabled: true
  backend: hub
  hub:
    storagePath: "..." # Local storage path for buffering the audit logs.

Refer to Cerbos documentation for details about common audit configurations that apply to all backends.

To quickly try out the Cerbos Hub audit logs feature, you can use the following command.

mkdir -p /tmp/cerbos && docker run --rm --name cerbos \
 -p 3592:3592 -p 3593:3593 \
 -e CERBOS_HUB_CLIENT_ID="..." \
 -e CERBOS_HUB_CLIENT_SECRET="..." \
 -v /tmp/cerbos:/audit_logs \
 ghcr.io/cerbos/cerbos:latest server \
--set=audit.enabled=true \
--set=audit.backend=hub \
--set=audit.hub.storagePath=/audit_logs

Masking sensitive fields

You can define masks to filter out sensitive or personally identifiable information (PII) that might be included in the audit log entries. Masked fields are removed locally at the PDP and are never transmitted to Cerbos Hub.

Masks are defined using a subset of JSONPath syntax.

hub:
  credentials:
    pdpID: "..." # Optional. Identifier for this Cerbos instance.
    clientID: "..." # ClientID
    clientSecret: "..." # ClientSecret

audit:
  enabled: true
  backend: hub
  hub:
    storagePath: "..." # Local storage path for buffering the audit logs.
    mask:
      # Fields to mask from CheckResources requests
      checkResources:
        - inputs[*].principal.attr.foo
        - inputs[*].auxData
        - outputs
      # Fields to mask from the metadata
      metadata:
        - authorization
      # Fields to mask from the peer information
      peer:
        - address
        - forwarded_for
      # Fields to mask from the PlanResources requests.
      planResources:
        - input.principal.attr.nestedMap.foo

Use the local audit backend along with cerbosctl audit commands to inspect your audit logs locally and determine the paths that need to be masked.

In order to avoid slowing down request processing and to avoid any data losses, raw log entries are stored locally on disk at the storage path. The masks are applied later by the background process that syncs the on-disk log entries to Cerbos Hub. To avoid storing authentication tokens and other sensitive request parameters locally, use the top-level includeMetadataKeys and excludeMetadataKeys settings. Refer to Cerbos audit configuration for more details.

Advanced configuration

Advanced users can tune the local log retention period and other buffering settings. We generally do not recommend changing the default values unless absolutely necessary.

audit:
  enabled: true
  backend: hub
  hub:
    storagePath: "..." # Local storage path for buffering the audit logs.
    retentionPeriod: 168h # How long to keep buffered records on disk.
    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.