REST API for Mass Scanning

This documentation does not include all REST API endpoints or parameters. Please contact support if you need REST API access not documented here. All REST API endpoints are available in the REST API Browser.

Triggering a full Bitbucket rescan

If you are a Bitbucket admin or have been explicitly granted Security for Bitbucket permissions, you can schedule a rescan of all data on your Bitbucket instance with a single REST call like this:

CODE

curl -u admin -X PUT "https://{bitbucket.server}/rest/security/latest/status/total_rescan{?email=admin@company.co}"

where

admin is your Bitbucket admin user (you’ll be prompted for a password).
bitbucket.server is the URL of your Bitbucket server.
email is an optional parameter that may be specified multiple times. Once the scan is completed, an e-mail notification will be sent to the specified e-mail addresses.
- e.g., email=admin1@company.co&email=admin2@company.co

You can monitor progress of scanning on the Soteri Global Dashboard.

Please note that if you have a large Bitbucket instance, all existing branches in all projects and repositories will be scanned, which may be very resource-consumptive and may take a long time to complete.

Scanning a project

If you are a project administrator or higher (Bitbucket admin, explicitly granted Security for Bitbucket permissions), you can scan all the branches of all the repositories in a project:

CODE

curl -u admin -X PUT "https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}{?email=admin@company.co}"

where

admin is your project admin user (you’ll be prompted for a password).
bitbucket.server is the URL of your Bitbucket server.
projectKey is the key of the project to be scanned.
email is an optional parameter that may be specified multiple times. Once the scan is completed, an e-mail notification will be sent to the specified e-mail addresses.
- e.g., email=admin1@company.co&email=admin2@company.co

Scanning a repository

If you have repository write permissions or higher, you can scan all the branches of a single repository:

CODE

curl -u user -X PUT "https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos/{repoSlug}{?email=admin@company.co}"

where

user is your user (you’ll be prompted for a password).
bitbucket.server is the URL of your Bitbucket server.
projectKey is the key of the project to be scanned.
repoSlug is the slug (identifier) of the repository to be scanned.
email is an optional parameter that may be specified multiple times. Once the scan is completed, an e-mail notification will be sent to the specified e-mail addresses.
- e.g., email=admin1@company.co&email=admin2@company.co

Scanning a branch

If you have repository write permissions or higher, you can scan a single branch in a repository:

CODE

curl -u user -X PUT "https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos/{repoSlug}/branches?name={branch}{?email=admin@company.co}"

where

user is your user (you’ll be prompted for a password).
bitbucket.server is the URL of your Bitbucket server.
projectKey is the key of the project to be scanned.
repoSlug is the slug (identifier) of the repository to be scanned.
branch is the name of the branch to be scanned.
email is an optional parameter that may be specified multiple times. Once the scan is completed, an e-mail notification will be sent to the specified e-mail addresses.
- e.g. email=admin1@company.co&email=admin2@company.co

Parallel Scans

See Scan Performance Tuning for details on how to adjust scan performance settings, like the number of scans run in parallel.

Cancelling Scans

To cancel queued (not started) scans:

BASH

curl -u admin -X DELETE https://{bitbucket.server}/rest/security/latest/status/scheduled

To cancel started (currently scanning) scans:

BASH

curl -u admin -X DELETE https://{bitbucket.server}/rest/security/latest/status/running

Exporting detected vulnerabilities

To export the full list of detected vulnerabilities from all projects, repositories, and branches, in a .zip file, use the following command:

BASH

curl -u admin -o report.zip https://{bitbucket.server}/rest/security/latest/export-report?confirmExpensiveOperation=true

This will save vulnerabilities into the file report.zip in the working directory. Note that this may be very time and resource consumptive if you have many repositories or many detected vulnerabilities, so Bitbucket performance can be affected significantly.

To export vulnerabilities only for a selected project / repository / branch, use requests like these:

BASH

curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/{projectKey}?allowlisted=true&reviewed=false
curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/{projectKey}/repos/{repoSlug}?allowlisted=true&reviewed=false
curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/{projectKey}/repos/{repoSlug}?branch={branch}&allowlisted=true&reviewed=false

The below parameters can be added to any of the exports APIs to filter the results by a scan date range:

startDate: Include failing lines scanned at or after this date. The date should be in ISO 8601 format, for example: 2024-09-07T00:01:12Z
endDate: Include failing lines scanned strictly before this date. The date should be in ISO 8601 format, for example: 2024-09-07T00:01:12Z
branch: If provided, export only this branch within the provided project and repository.
allowlisted: Optional parameter to filter allowlisted findings in the export. If true, only allowlisted findings will be provided. If false, only findings that are not allowlisted will be provided.
reviewed: Optional parameter to filter reviewed findings in the export. If true, only reviewed findings will be provided. If false, only findings that are not reviewed will be provided.

These export scan findings in CSV format.

See Exporting a report for external use for more information about the CSV format.

Exporting reviewed false positives

To export the full list of reviewed false positives for all projects and repositories, use the following command:

BASH

curl -u admin -o reviewed.zip https://{bitbucket.server}/rest/security/latest/export/reviewed

It will save the reviewed false positives into the file reviewed.zip in the working directory.

To export reviewed false positives only for a specific project or repository:

CODE

curl -u admin https://{bitbucket.server}/rest/security/latest/export/reviewed/projects/{projectKey}
curl -u admin https://{bitbucket.server}/rest/security/latest/export/reviewed/projects/{projectKey}/repos/{repoSlug}