REST API for Mass Scanning

This documentation does not include all REST API endpoints. 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

You can schedule re-scan of all data on your Bitbucket with a single REST-call like this:

CODE

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

admin is your Bitbucket admin user (you’ll be prompted for a password)
bitbucket.server is URL of your Bitbucket server
force controls whether already scanned and up-to-date branches will be rescanned. Can be true or false.
email is an optional parameter that may be specified multiple times. Once the scan is completed, an email notification will be sent to the specified email addresses.
- e.g. email=admin1@comany.co&email=admin2@company.co

You can monitor progress of scanning on Security Scan Report page.

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

To 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}?force=false{&email=admin@company.co}"

admin is your Bitbucket admin user (you’ll be prompted for a password)
bitbucket.server is URL of your Bitbucket server
projectKey is the key of the project to be scanned
force controls whether already scanned and up-to-date branches will be rescanned. Can be true or false
email is an optional parameter that may be specified multiple times. Once the scan is completed, an email notification will be sent to the specified email addresses.
- e.g. email=admin1@comany.co&email=admin2@company.co

Scanning a repository

To scan all the branches of a single repository:

CODE

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

admin is your Bitbucket admin user (you’ll be prompted for a password)
bitbucket.server is 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
force controls whether already scanned and up-to-date branches will be rescanned. Can be true or false
email is an optional parameter that may be specified multiple times. Once the scan is completed, an email notification will be sent to the specified email addresses.
- e.g. email=admin1@comany.co&email=admin2@company.co

Scanning a branch

To scan a single branch in a repository:

CODE

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

admin is your Bitbucket admin user (you’ll be prompted for a password)
bitbucket.server is 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.
force controls whether already scanned and up-to-date branches will be rescanned. Can be true or false
email is an optional parameter that may be specified multiple times. Once the scan is completed, an email notification will be sent to the specified email addresses.
- e.g. email=admin1@comany.co&email=admin2@company.co

Changing the amount of parallel scans

To optimize the load, you can try to change number of parallel threads used Security for Bitbucket during rescan with an additional REST-call:

BASH

curl -u admin -X PUT https://{bitbucket.server}/rest/security/latest/status/active/4

This command will change number of scan threads to 4. As of performance considerations, you cannot set number of threads greater than number of available CPUs. For maximum performance, you can specify 0 value to use all available CPUs, but be advised that this can affect overall Bitbucket server performance dramatically.

Exporting detected vulnerabilities

To export the full list of detected vulnerabilities from all projects, repositories and branches use the following command:

BASH

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

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

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

BASH

curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/<PROJECT_KEY>
curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/<PROJECT_KEY>/repos/<REPOSITORY_SLUG>
curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/<PROJECT_KEY>/repos/<REPOSITORY_SLUG>?branch=<BRANCH_NAME>