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
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:
curl -u admin -X PUT "https://{bitbucket.server}/rest/security/latest/status/total_rescan?force=false{&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,force
controls whether already scanned and up-to-date branches will be rescanned (can betrue
orfalse
), andemail
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 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
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:
curl -u admin -X PUT "https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}?force=false{&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,force
controls whether already scanned and up-to-date branches will be rescanned (can betrue
orfalse
), andemail
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:
curl -u user -X PUT "https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos/{repoSlug}?force=false{&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,force
controls whether already scanned and up-to-date branches will be rescanned (can betrue
orfalse
), andemail
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:
curl -u user -X PUT "https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos/{repoSlug}/branches?name={branch}&force=false{&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,force
controls whether already scanned and up-to-date branches will be rescanned (can betrue
orfalse
), andemail
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:
curl -u admin -X DELETE https://{bitbucket.server}/rest/security/latest/status/scheduled
To cancel started (currently scanning) scans:
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, use the following command:
curl -u admin -o report.zip https://{bitbucket.server}/rest/security/latest/export-report?confirmExpensiveOperation=true
It 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 these requests:
curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/{projectKey}
curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/{projectKey}/repos/{repoSlug}
curl -u admin https://{bitbucket.server}/rest/security/latest/export-report/projects/{projectKey}/repos/{repoSlug}?branch={branch}
Exporting reviewed findings
To export the full list of reviewed findings for all projects and repositories, use the following command:
curl -u admin -o reviewed.zip https://{bitbucket.server}/rest/security/latest/export/reviewed
It will save the reviewed findings into the file reviewed.zip
in the working directory.
To export reviewed findings only for a specific project or repository:
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}