To help administrators keep track of various events, Security for Bitbucket (version 3.20.0 and later) places certain entries in Bitbucket’s Audit Log.

Accessing the Audit Log via UI

From the Administration panel, choose Audit Log:

This brings up the “Advanced audit log” page:

From here, click on the + More button. A new Categories drop-down will appear. From that, select “Soteri Security for Bitbucket”:

and then click on the Apply button. The events can then be seen:

Clicking on a given event’s arrow will expand the event, revealing more details:

Accessing the Audit Log via REST call

  • Bitbucket exposes REST APIs that you can use to export CSVs or JSON

  • If you integrate with an ELK stack setup or some other SIEM solution, you could automate sending of emails to the appropriate parties for certain audit events

Using the Bitbucket REST APIs to export CSVs or JSON

As an example, you may export CSV of just “Hook Skip” Events like so:

curl -u admin 'https://{bitbucket.server}/bitbucket/rest/auditing/1.0/events?actions=Security%20hook%20skipped&categories=Soteri%20Security%20for%20Bitbucket&limit=100&outputFormat=csv' -o hook-skip-events.csv
CODE

  • bitbucket.server is the URL of your Bitbucket server,

CSVs can be filtered by both repository and project, by adding query parameters to the URL:

?affectedObject=PROJECT,{proj_id1};PROJECT,{proj_id2};REPOSITORY,{repo_id1};REPOSITORY,{repo_id2}&limit=10&outputFormat=csv

The ID of a project can be obtained from its project key:

curl -u admin 'https://{bitbucket.server}/bitbucket/rest/api/latest/projects/{project_key}'
CODE

You can follow these instructions to find the project ids or repository ids:

The export endpoint will return JSON if the outputFormat=csv argument is excluded. This might make it easier to use for automation compared to the CSV format.

Setting up an integration with an external service to consume the audit log

If you integrate with an ELK stack setup or some other SIEM solution, you could automate sending of emails to the appropriate parties whenever the hook is skipped

For example, If you hook your audit logs up to something like Splunk, or Amazon CloudWatch Agent, such tools can set up email alerts to the appropriate people.

  • Bitbucket’s instructions for setting up log integrations:

https://confluence.atlassian.com/bitbucketserver/audit-log-integrations-996643661.html

  • Instructions for setting up email notification actions for Splunk

https://docs.splunk.com/Documentation/Splunk/9.0.4/Alert/Emailnotification

Viewing audited events via a REST call

Events which affect a particular repository may be viewed via a REST call like this:

curl -u admin https://{bitbucket.server}/rest/audit/latest/projects/{projectKey}/repos/{repoSlug}/events
CODE

where

  • admin is your Bitbucket admin user (you’ll be prompted for a password),

  • bitbucket.server is the URL of your Bitbucket server,

  • projectKey is the project containing the repository, and

  • repoSlug is the repository slug whose events we want to fetch.

Audited Events

The following events are currently recorded in the Audit Log:

  • Changes in the Global Hook status or mode

  • Built-in rule toggles

  • Custom rule creation, deletion, changes, or toggles

  • Findings being marked or unmarked as reviewed

  • Per-repository settings toggles

  • Individual or group access changes to the Global Settings

  • Changes to soteri-security.yml on the default branch of a repository

  • Skipping the Soteri security hook by way of the specialized commit message **skip-soteri-security-check**