Audit logs#

A private BSR instance records mutations to the data it manages, and administrators can query those records through an audit API. This supports traceability, accountability, and compliance workflows on self-hosted deployments. Audit logs are a private-BSR feature; the public BSR at buf.build doesn’t expose this API.

What an audit event contains#

Every audited event records what happened, when it happened, who did it, and which resource was affected. Some events carry an additional payload with details specific to the event type.

message Event {
  // Unique id of the audited event.
  string id = 1;
  // Type of the audited event. It specifies "what" happened.
  EventType type = 2;
  // Actor of the audited event. It specifies "who" did it.
  Actor actor = 3;
  // Resource of the audited event. It specifies "which resource" was affected.
  Resource resource = 4;
  // Time of the audited event. It specifies "when" it happened.
  google.protobuf.Timestamp event_time = 5;
  // Metadata about the audited event. It specifies any additional details about the audited event.
  EventMetadata metadata = 6;
  // Payload of the audited event. It specifies additional context on the event.
  oneof payload {
    // ... specific payload details depending on the event type.
  }
}

Actor and Resource each carry a Type, ID, and Name, so the payload is often redundant for simple events.

An actor is either a User or the System. When the actor is a user, EventMetadata records the user agent and an internal trace ID to support investigation.

Resources include users, organizations, modules, policies, plugins, tokens, and instance-level settings, along with sub-resources such as organization members, module contributors, commits, and labels. The ResourceType enum lists every resource type.

The payload field varies by EventType. The audit API reference lists the fields for each payload, and the full EventType enum lists every event the BSR audits.

Event categories#

The tables below cover the most common events for users, organizations, modules, and plugins. The BSR also audits events for policies, labels, tokens, IdP group mappings, and instance-level settings. For the authoritative list, see the EventType enum.

User events#

Events with a User as the affected resource.

Event	Details
User Created	A user created an account on the BSR.
User Deactivated	A BSR admin deactivated a user’s account.
User Deleted	A user self-deleted their account (if the BSR instance allows it) or a BSR admin force-deleted the user.
User Logged In	Logged in three scenarios: the user authenticated via SAML and was auto-provisioned; the user logged in via SSO (OAuth/OIDC) with an existing account; or the user logged in via SSO and completed account registration.
User Logged Out	A user manually logged out.

Organization events#

Events with an Organization or Organization Member as the affected resource. Organizations have multiple members, each with a role.

Event	Resource	Details
Organization Created	Organization	An organization was created.
Organization Deleted	Organization	An organization was deleted.
Organization Member Added	Organization Member	A user was added to an organization. The organization and the new role are logged.
Organization Member Removed	Organization Member	A user was removed from an organization. The organization and the old role are logged.
Organization Member Roles Changed	Organization Member	An existing member’s roles were changed. The organization, old roles, and new roles are logged, along with the source of each role.

Module events#

Events with a Module, Module Contributor, or Module Commit as the affected resource. Modules have multiple contributors (each with a role) and a visibility (public or private).

Event	Resource	Details
Module Created	Module	A module was created. The owner, visibility, and default label name are logged.
Module Deleted	Module	A module was deleted. The owner and visibility are logged.
Module Visibility Changed	Module	A module’s visibility changed. The owner, old visibility, and new visibility are logged.
Module Commit Pushed	Module Commit	A commit was pushed. The owner, module, labels (if any), and B5 digest are logged.
Module Contributor Added	Module Contributor	A user was added as a contributor. The owner, module, and new role are logged.
Module Contributor Removed	Module Contributor	A user was removed as a contributor. The owner, module, and old role are logged.
Module Contributor Roles Changed	Module Contributor	An existing contributor’s roles were changed. The owner, module, old roles, and new roles are logged, along with the source of each role.

Plugin events#

Events with a Plugin as the affected resource.

Event	Details
Plugin Created	A plugin was created.
Plugin Deleted	A plugin was deleted.

Storing audit events in object storage#

Audit events are always configured to be stored in the database backing the BSR. Audit events may also be set up to export directly to object storage. They support S3, GCS, and Azure based object storage destinations.

To configure it, add the following block to your bsr.yaml:

auditLogs:
  objectStorage:
    enabled: true

Additionally, configure the storage backend of your choice:

S3#

auditLogs:
  objectStorage:
    enabled: true
    storage:
      secretName: example-storage-secret
      use: s3
      s3:
        bucketName: "example-bucket"
        endpoint: "example-"
        accessKeyId: ""
        region: ""
        forcePathStyle: false
        insecure: false
        objectPrefix: ""

If using accessKeyId, also create a matching secret:

$ kubectl create secret --namespace bsr generic example-storage-secret \
  --from-literal=secret_access_key=<s3 secret access key>

GCS#

auditLogs:
  objectStorage:
    enabled: true
    storage:
      use: gcs
      gcs:
        bucketName: ""
        objectPrefix: ""

Azure#

auditLogs:
  objectStorage:
    enabled: true
    storage:
      secretName: example-storage-secret
      use: azure
      azure:
        accountName: ""
        container: ""
        realm: core.windows.net
        useAccountKey: true
        objectPrefix: ""

If using useAccountKey, also create a matching secret:

  $ kubectl create secret --namespace bsr generic example-storage-secret \
    --from-literal=account_key=<azure account key>

Query audit events#

Audit events are read through the ListEvents RPC on buf.registry.audit.v1.AuditService. The endpoint supports filtering by time range, ordering by event time, and paginating through results. Only an administrator can call it.

The easiest way to call the endpoint is with buf curl, using a token for an admin account:

$ buf curl \
    --schema buf.build/bufbuild/registry \
    --user-agent "audit-export" \
    --header "Authorization: Bearer $BUF_TOKEN" \
    --data '{"page_size": 100}' \
    https://buf.build/buf.registry.audit.v1.AuditService/ListEvents

Replace buf.build with your BSR instance hostname and $BUF_TOKEN with an admin token. Pass a start_time and end_time in the request body to filter by time range, and use the returned next_page_token as the page_token in a subsequent call to page through large result sets. Results are returned newest first by default; set order to ORDER_EVENT_TIME_ASC to return the oldest events first. The maximum page_size is 250.