REST API for Scripting & Automation
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.
Using the REST API Browser
If you’re using Bitbucket Server, you can use the built-in REST API Browser to see all the REST API Endpoints available in your Bitbucket Instance, including those provided by Security for Bitbucket. Follow Atlassian’s instructions for Using the REST API Browser first, to ensure that you can access it.
To see all Security for Bitbucket REST endpoints, ensure that “Show only public APIs” is unchecked, and search for security/
.
Authentication and basic parameters
Reference the Bitbucket REST API for Bitbucket’s built-in REST API, e.g. for querying lists of projects and repositories.
All requests use basic HTTP authentication. It is natively supported by most clients, such as python requests and curl.
All the URLs in the examples below are relative to the address of the Bitbucket Server instance.
If scanning a private repository (i.e. not part of a project), use ~username
as the project-key
parameter.
Disabling XRSF checks
Some of these API will fail by default if called from a host that is not part of the Bitbucket instance. To enable calling these APIs remotely, you may add the following header as documented here:
Example (python):
disable_xsrf_checks_header = {
"X-Atlassian-Token": "no-check"
}
requests.get(url, auth=(username, password), headers=disable_xsrf_checks_header)
Turning the security pre-receive hook on or off for a repository
By default, the pre-receive hook setting at the individual repository level starts as inherited
, so it will trigger or not according to the pre-receive hook setting at the project level as documented here. However, it can be changed so that it ignores the project-level setting.
Changing the pre-receive hook setting at the repository level via REST is a two-step process.
First:
curl -u admin -X PUT -H "Content-Type: application/json" --data '{"warnOnVulnerabilities":false}' https://{bitbucket.server}/rest/api/latest/projects/{projectKey}/repos/{repoSlug}/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/settings
Where:
admin
is your Bitbucket admin user (you'll be prompted for a password)bitbucket.server
is URL of your Bitbucket serverprojectKey
is the key of the projectrepoSlug
is the slug (identifier) of the repository
On Windows, the correct format for the data
option is --data "{\"warnOnVulnerabilities\":false}"
.
If it is desired that a commit with vulnerabilities goes through but warning messages are sent to the committer, replace false
with true
.
Then, to enable the security hook for a specific repository:
curl -u admin -X PUT https://{bitbucket.server}/rest/api/latest/projects/{projectKey}/repos/{repoSlug}/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/enabled
Alternately, to disable the security hook for a specific repository:
curl -u admin -X DELETE https://{bitbucket.server}/rest/api/latest/projects/{projectKey}/repos/{repoSlug}/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/enabled
Once the security hook is actually enabled, you may change its warning behavior by executing the first step above again, replacing the Boolean in the data
option with true
or false
as desired.
To revert this setting to its default value of inherited
:
curl -u admin -X DELETE https://{bitbucket.server}/rest/api/latest/projects/{projectKey}/repos/{repoSlug}/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/settings
Once the the pre-receive hook setting at the repository level has been reverted to inherited
, you will need to execute the first step above again before enabling or disabling the security hook.
Turning the security pre-receive hook on or off for a project
The REST API Calls for turning on or off the pre-receive hook for a project are just like the ones for a repository, but exclude the /repos/{repoSlug}
portion of the URL. For example:
curl -u admin -X PUT -H "Content-Type: application/json" --data '{"warnOnVulnerabilities":false}' https://{bitbucket.server}/rest/api/latest/projects/{projectKey}/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/settings
curl -u admin -X PUT https://{bitbucket.server}/rest/api/latest/projects/{projectKey}/settings/hooks/com.mohami.bitbucket.security-for-bitbucket:credentials-validation-hook/enabled
Fetch the security status of one or more projects
curl -u admin https://{bitbucket.server}/rest/security/latest/status/projects?start={start}&limit={limit}&name={name}
This returns a paged API JSON response of the security status of all projects.
Where:
start
is the “offset” andlimit
is the number of projects to fetchname
is an optional parameter which allows for filtering projects by name (not the project key).
Fetch the security status of one or more repositories
curl -u admin https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos?start={start}&limit={limit}&name={name}
This returns a paged API JSON response of the security status of all repositories in a project.
Where:
projectKey
is the project containing the repositories.start
is the 0-based “offset” andlimit
is the number of repositories to fetchname
is an optional parameter which allows for filtering repositories by name (not the repo slug).
For example, to list the first eight repository scan results, use a start
of 0
and a limit
of 8
. To list the next five repository scan results, use a start
of 8
and a limit
of 5
.
Fetch the security status of one or more branches
curl -u admin https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos/{repoSlug}/branches?name={name}
This returns a paged API JSON response of the security status of all a branches in a repository.
Where:
projectKey
is the project containing the repositories.repoSlug
is the repository slug whose branches we want to fetchstart
is the “offset” andlimit
is the number of repositories to fetchname
is an optional parameter which allows for filtering branches by name.
Fetching scan results for a specific branch
Method: GET
URL:
/rest/security/1.0/scan/{project-key}/repos/{repository-key}
Parameters
branch
: default repository branch used if omittedincludeAllowlisted
: true to include failing lines which have been whitelisted.rule
: scan status for a specific rule. Overall scan results if omitted.
Response (JSON encoded):
scanKey
: Unique key that can be used to refer to this scan, once subsequent scans are triggeredscanned
(boolean): True if scan results are present for the branchactual
(boolean): True if scan results are for the latest commit on the branch, false if the branch has been updated since the last scan.progress
(int): Percentage progress, between 0 and 100.running
(boolean)scheduled
(boolean)invalidLides
: The list of vulnerabilities found. Only available once a scan has completed (scanned=true)
Example (python):
response = requests.get(f"{domain}/rest/security/1.0/scan/{project}/repos/{repo_key}",
auth=('username', 'password'))
response.raise_for_status()
scanned = response.json()['scanned']
up_to_date = response.json()['actual']
Kicking off a new repository scan
Method: POST
URL:
/rest/security/1.0/scan/{project-key}/repos/{repository-key}
Parameters
branch
: default repository branch used if omitted
Example (python):
requests.post(f"{domain}/rest/security/1.0/scan/{project}/repos/{repo_key}?branch={branchName}",
auth=('username', 'password'))
Cancelling a running or queued scan
Method: DELETE
URL:
/rest/security/1.0/scan/{project-key}/repos/{repository-key}
Parameters
scanKey
: identifier of the scan to cancel
Example (python):
requests.delete(f"{domain}/rest/security/1.0/scan/{project}/repos/{repo_key}?scanKey={scanKey}",
auth=('username', 'password'))
Export scan results as CSV
This API endpoint is for exporting a single branch only. To export multiple branches or multiple repositories, reference REST API for Mass Scanning
Method: GET
URL:
/rest/security/1.0/export-report/{project-key}/repos/{repository-key}
Parameters
branch
: default repository branch used if omittedincludeAllowlisted
: true to include failing lines which have been whitelisted.ruleType
: scan results for a specific rule. All rules included by default.
Example (python):
response = requests.get(f"{domain}/rest/security/1.0/export-report/{project_key}/repos/{repo_key}",
auth=creds)
response.raise_for_status()
with open('results.csv', 'w') as f:
f.write(response.text)
Rules
Fetching a list of all global rules
Method: GET
URL:
/rest/security/1.0/rules
Response (JSON encoded):
List of rules. Each rule has the fields
id
,name
,regexp
,hardcoded
, andenabled
hardcoded
: this boolean will be “False” for custom rules. “True” for built-in rulesid
: Unique identifier that can be used to refer to custom rules in other API endpointsname
: Display name of the rule.regexp
: Regular expression for the rule. Only available for custom rules.
Example (python):
response = requests.get(f"{domain}/rest/security/1.0/rules", auth=creds)
custom_rules = [x for x in response.json() if not x['hardcoded']]
Fetch the names of all available rules for a specific repository
Due to the presence of custom soteri-security.yml
files, some branches may have additional scan rules available in addition to the global ones. This API call returns the full list of rules for a specific branch of a specific repository.
Method: GET
URL:
/rest/security/1.0/scan/{project-key}/rule_types/{repository-key}
Parameters
branch
: default repository branch used if omitted.
Response (JSON encoded):
list of rule names. Disabled rules are also included.
Example (python):
response = requests.get(f"{domain}/rest/security/1.0/scan/{project}/rule_types/{repo_key}",
auth=creds, params={'branch': 'master'})
Globally enabling a built-in rule
Rules can only be enabled or disabled globally (for all repositories) via the REST API. To disable or enable rules (or add custom rules) on a repository level, please update soteri-security.yml
as documented here. This API requires Bitbucket administrator access or explicit access given through the plugins settings page.
Method: POST
URL:
/rest/security/1.0/hardcoded/{rule-name}
Result: None. Enables the named rule globally.
response = requests.post(f"{domain}/rest/security/1.0/hardcoded/RSA", auth=creds)
Globally disabling a built-in rule
Rules can only be enabled or disabled globally (for all repositories) via the REST API. To disable or enable rules (or add custom rules) on a repository level, please update soteri-security.yml
as documented here. This API requires Bitbucket administrator access or explicit access given through the plugins settings page.
Method: DELETE
URL:
/rest/security/1.0/hardcoded/{rule-name}
Result: None. Enables the named rule globally.
response = requests.delete(f"{domain}/rest/security/1.0/hardcoded/RSA", auth=creds)
Reviewed Lines
This section documents the REST API for reviewing findings. For more information, see Hiding false positives, revoked credentials, etc..
Creating a reviewed line
curl -u admin -X POST -H "Content-Type: application/json" "https://{bitbucket.server}/rest/security/latest/review-lines/projects/{projectKey}/repos/{repoSlug}/create" --data '{"matchText": "$MATCH"}'
bitbucket.server
is URL of your Bitbucket serverprojectKey
is the key of the project this reviewed line is for.repoSlug
is the slug (identifier) of the repository this reviewed line is for.$MATCH
is the exact string to be reviewed.
Deleting a reviewed line
curl -u admin -X POST -H "Content-Type: application/json" "https://{bitbucket.server}/rest/security/latest/review-lines/projects/{projectKey}/repos/{repoSlug}/delete" --data '{"matchText": "$MATCH"}'
bitbucket.server
is URL of your Bitbucket serverprojectKey
is the key of the project the reviewed line to delete.repoSlug
is the slug (identifier) of the repository for the reviewed line to delete.$MATCH
is the exact string that should be unmarked as reviewed.
Deleting all reviewed lines for a repository
curl -u admin -X DELETE "https://{bitbucket.server}/rest/security/latest/review-lines/projects/{projectKey}/repos/{repoSlug}/delete"
bitbucket.server
is URL of your Bitbucket serverprojectKey
is the key of the project the reviewed line to delete.repoSlug
is the slug (identifier) of the repository for the reviewed line to delete.