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.

Enabling collection

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

Accessing the logs

Once collection is enabled, the logs can accessed via the Audit logs tab in Cerbos Hub. From here you can select which logs to view:

Decision logs

The decision logs are records of the authorization decisions made by the Cerbos PDP. These logs provide detailed information about each decision, including the inputs, Cerbos policies evaluated, and the ALLOW/DENY decisions along with any outputs from rule evaluation. Besides providing a comprehensive audit trail, these records can be used for troubleshooting purposes and to understand how Cerbos policies are used within your organization.

There are two views in this section. The JSON view provides access to the raw log entry while the decision view provides a compact view consisting of the most pertinent details extracted from the log entry.

Decision logs

Decision logs JSON

In the decision view, clicking on a log entry will open the details pane which shows the full request and response data, including the principal, resource, action, policy decision, and other metadata. In the case of a PlanResources request, the detailed plan is also shown.

Decision logs detail

In addition to viewing a particular time range, you can further filter the logs by a particular PDP ID, principal, resource kind, action, or policy decision as well.

Access logs

The access logs are records of all the API requests received by the Cerbos PDP. The valid CheckResources and PlanResources API calls would have a corresponding decision log entry with the the same call ID. API requests that are invalid or unauthenticated are logged as well and can be used for identifying misconfigured clients or unauthorized access attempts.

You can filter the logs by a particular PDP and a time range.

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.