Audit logs
This information only applies to organizations on the Pro and Enterprise plans.
Your private BSR instance records certain events and actions that happen in the server and allows server administrators to query them. This allows administrators to satisfy security, traceability, accountability, policy, and compliance needs, among others.
Audit events
Each audited event answers the question of what happened, when it happened, who did the action, which resource was affected, and sometimes includes an additional payload and metadata. An audited event looks like this:
message Event {
// Unique id of the audited event.
string event_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 additional details about the audited event.
EventMetadata metadata = 6;
oneof payload {
// ... specific payload details depending on the event type.
}
}
See the audit API docs for details about the supported payloads.
For both Actors and Resources, each one holds its Type
, ID
and Name
, making the payload of the event sometimes
unnecessary.
Actor types are either User
events or System
events. If the actor is a User, which it is in most scenarios, the
metadata include its User Agent
, IP
and internal Trace ID
for further investigation and debugging.
Resource
types can be one of User
, Organization
, Organization Member
, Repository
, Repository Contributor
,
Repository Commit
, or Plugin
.
Currently, the BSR audits most events that result in mutations to the data it manages. That includes changes to resources like Users, Organizations, and Repository permissions to name a few. The complete list of audited events, associated payloads, and their respective type specifications can be found in the BSR's schema documentation. Treat it as a living document, since it will grow to keep pace with new BSR features as they're released.
For more in-depth descriptions of each event type, see the event details section.
Querying audit events
An administrator can access the BSR's audit logs by using the
ListAuditedEvents
RPC.
This endpoint currently supports filtering events by time period and result pagination.
Audit event details
User Events
These events have a User
as an affected resource.
Event | Details |
---|---|
User Created | User creates an account in the BSR server. |
User Deactivated | BSR admin accounts are able to deactivate Users’ accounts. In that scenario, an UserDeactivated event is logged. |
User Deleted | Depending on the BSR instance configuration, Users might be able to self-delete their accounts. BSR administrators can also force-delete BSR users. In both scenarios, the user deletion event is logged. |
User Logged In | BSR logs an UserLoggedIn event in three scenarios: (1) User authenticated/logged in via SAML (their account is auto provisioned in the system). (2) User logged in via SSO (OAuth/OIDC) and already had a registered account. (3) User logged in via SSO (OAuth/OIDC) and then registers an account (we only log the event if the user follows through with the account registration). |
User Logged Out | User manually logs out of the server. |
Organization Events
These events have either an Organization
or an Organization Member
as an affected resource. BSR Organizations can
have multiple members, with different access roles.
Event | Resource | Details |
---|---|---|
Organization Created | Organization | An Organization was created in the BSR. |
Organization Deleted | Organization | An Organization was deleted from the BSR. |
Organization Member Added | Organization Member | A User was added to an Organization with a certain role. The Organization details and new role are logged. |
Organization Member Removed | Organization Member | A User was removed from an Organization. The Organization details and old role are logged. |
Organization Member Role Changed | Organization Member | A User that is already an Organization Member was set a different role. The Organization details, old and new roles are logged. |
Repository Events
These events have either a Repository
, Repository Contributor
, or Repository Commit
as the affected resource. BSR
Repositories can have multiple contributors, with different access roles. BSR Repositories have public or private
visibility.
Event | Resource | Details |
---|---|---|
Repository Created | Repository | A Repository was created in the BSR. The Owner details and visibility are logged. |
Repository Deleted | Repository | A Repository was deleted from the BSR. The Owner details and visibility are logged. |
Repository Visibility Changed | Repository | A Repository changed its visibility in the BSR. The Owner details, old visibility and new visibility are logged. |
Repository Commit Pushed | Repository Commit | A Repository Commit was pushed to the BSR. The Owner and Repository details, along with the label name (if any) are logged. |
Repository Contributor Added | Repository Contributor | A User was added to a Repository with a certain role. The Owner and Repository details, and Contributor new role are logged. |
Repository Contributor Removed | Repository Contributor | A User was removed from a Repository. The Owner and Repository details, and Contributor old role are logged. |
Repository Contributor Role Changed | Repository Contributor | A User that is already a Repository Contributor was set a different role. The Owner and Repository details, and Contributor old and new roles are logged. |
Plugin Events
These events have a Plugin
as the affected resource.
Event | Details |
---|---|
Plugin Created | A Plugin was created in the BSR. |
Plugin Deleted | A Plugin was deleted from the BSR. |