Skip to main content
Skip table of contents

REST API for Scripting and 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.

Getting Started

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 calls 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 (curl):

BASH 
curl -u admin -H "X-Atlassian-Token: no-check" $URL

Example (Python):

PY 
disable_xsrf_checks_header = {
    "X-Atlassian-Token": "no-check"
}
requests.get(url, auth=(username, password), headers=disable_xsrf_checks_header)

Security Hook

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.

To enable the security hook for a specific repository:

BASH 
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/enabled

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 key of the project, and

  • repoSlug 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.

Alternately, to disable the security hook for a specific repository:

BASH 
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:

BASH 
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

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:

CODE 
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/enabled

Fetching Security Status

Fetch the security status of a single project

BASH 
curl -u admin https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}

where projectKey is the key of the desired project.

Fetch the security status of one or more projects

BASH 
curl -u admin https://{bitbucket.server}/rest/security/latest/status/projects?start={start}&limit={limit}&name={name}

where

  • start is the “offset” and limit is the number of projects to fetch, and

  • name is an optional parameter which allows for filtering projects by name (not the project key).

This returns a paged API JSON response of the security status of all projects.

Fetch the security status of a single repository

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

where projectKey and repoSlug are the project key and repository slug, respectively, for the desired repository.

Fetch the security status of one or more repositories

CODE 
curl -u admin https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos?start={start}&limit={limit}&name={name}

where

  • projectKey is the project containing the repositories,

  • start is the 0-based “offset” and limit is the number of repositories to fetch, and

  • name 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.

This returns a paged API JSON response of the security status of all repositories in a project.

Fetch the security status of one or more branches

CODE 
curl -u admin https://{bitbucket.server}/rest/security/latest/status/projects/{projectKey}/repos/{repoSlug}/branches?name={name}

where

  • projectKey is the project containing the repositories,

  • repoSlug is the repository slug whose branches we want to fetch,

  • start is the “offset” and limit is the number of repositories to fetch, and

  • name is an optional parameter which allows for filtering branches by name.

This returns a paged API JSON response of the security status of all a branches in a repository.

Running Scans and Getting Results

Triggering a new branch scan

If the branch is up-to-date, no additional scan will be performed. This API call returns a JSON object containing whether a scan is actually scheduled (scheduled: true) and the key of the scan if it is (scanKey). A scan will not be scheduled if the branch was previously scanned and the results are up to date.

  • Method: POST

  • URL: /rest/security/1.0/scan/{project-key}/repos/{repository-key}

  • Parameters

    • branch: default repository branch used if omitted.

Example (Python):

PY 
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):

PY 
requests.delete(f"{domain}/rest/security/1.0/scan/{project}/repos/{repo_key}?scanKey={scanKey}",
                         auth=('username', 'password'))

Fetching scan results

  • Method: GET

  • URL: /rest/security/1.0/scan/{project-key}/repos/{repository-key}

  • Parameters:

    • branch: default repository branch used if omitted.

    • includeAllowlisted: true to include failing lines which have been allowlisted.

    • 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 triggered.

    • scanned (boolean): True if scan results are present for the branch.

    • actual (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)

    • invalidLines: The list of vulnerabilities found. Only available once a scan has completed (scanned: true). Entries contain the following notable properties:

      • text: The full text of the line containing the finding, or if truncated: true (see below), only the specific text of the finding.

      • lineOffsetStart (int): The index of the character where the finding begins, within text.

      • lineOffsetEnd (int): The index of the character where the finding ends, within text.

      • truncated (boolean): Whether the line is too long to return in its entirety, and instead text contains only the finding itself.

Example (Python):

PY 
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']

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 omitted.

    • ruleType: scan results for a specific rule. All rules included by default.

    • includeAllowlisted: true to include failing lines which have been allowlisted.

    • includeReviewed: true to include failing lines which have been reviewed.

    • 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

Example (Python):

PY 
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, and enabled:

      • hardcoded: this boolean will be “False” for custom rules, “True” for built-in rules.

      • id: Unique identifier that can be used to refer to custom rules in other API endpoints.

      • name: Display name of the rule.

      • regexp: Regular expression for the rule. Only available for custom rules.

      • blocking: Whether the rule should block when the Security Hook is enabled. Only available for custom rules.

Example (Python):

PY 
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

This includes both built-in and custom rules. If per-repository configuration is enabled, some repositories might have custom rules defined in soteri-security.yml. This API call returns the full list of rule names for 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):

PY 
response = requests.get(f"{domain}/rest/security/1.0/scan/{project}/rule_types/{repo_key}", auth=creds)

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.

PY 
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.

PY 
response = requests.delete(f"{domain}/rest/security/1.0/hardcoded/RSA", auth=creds)

Create a new custom rule

CODE 
curl -u admin -X POST "https://{bitbucket.server}/rest/security/latest/rules" -H "Content-Type: application/json"  --data '{"name":"rule name","regexp":"rule-regex","enabled":true}'

Delete a custom rule

First, determine the ID of the custom rule by using the “Fetching a list of all global rules” endpoint above. Then,

CODE 
curl -u admin -X DELETE "https://{bitbucket.server}/rest/security/latest/rules/{rule-ID}"

Clear the validation error message associated with a custom rule

First, determine the ID of the custom rule by using the “Fetching a list of all global rules” endpoint above. Then,

CODE 
curl -u admin -X PUT "https://{bitbucket.server}/rest/security/latest/rules/{rule-ID}"

Marking Findings as Reviewed

This section documents the REST API for reviewing findings. For more information, see Hiding false positives, revoked credentials, etc..

Reviewed false positives in repository scope

Users with repository write access can review findings in the repository scope.

Adding a new reviewed false positive in the repository scope

CODE 
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", "ruleName": "$RULENAME"}'

where

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

  • projectKey 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 specific text of the finding (not the whole line). This value should be derived from the respective invalidLines entry documented in “Fetching scan results for a specific branch” above.

    • If the line is truncated (truncated: true), matchText should be the text of the invalidLines entry.

    • If the line is not truncated (truncated: false), matchText should be a substring of text, from lineOffsetStart to lineOffsetEnd.

    • In the Branch Security Analysis, this will be the highlighted portion of the finding.

  • $RULENAME is the name of the rule which generated this finding.

Removing a reviewed false positive in the repository scope

CODE 
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"}'

where

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

  • projectKey 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, and

  • $MATCH is the exact string that should be unmarked as reviewed.

Deleting all reviewed false positives for a repository

CODE 
curl -u admin -X DELETE "https://{bitbucket.server}/rest/security/latest/review-lines/projects/{projectKey}/repos/{repoSlug}/delete?confirm=true"

where

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

  • projectKey is the key of the project the reviewed line to delete, and

  • repoSlug is the slug (identifier) of the repository for the reviewed line to delete.

  • confirm must be set to true to complete the operation.

Global reviewed false positives

Globally reviewed false positives can be managed by Bitbucket administrators or those those with explicit access given through the plugins settings page.

Uploading new globally reviewed false positives

This endpoint accepts CSV uploads in a format described on Hiding false positives, revoked credentials, etc..

CODE 
curl -u admin -F file=@'{filename}' "https://{bitbucket.server}/rest/security/latest/global-reviewed/create"

where

  • bitbucket.server is the URL of your Bitbucket server

  • filename is the CSV you want to upload

Deleting globally reviewed false positives

This endpoint accepts CSV uploads in a format described on Hiding false positives, revoked credentials, etc..

CODE 
curl -u admin -F file=@'{filename}' "https://{bitbucket.server}/rest/security/latest/global-reviewed/delete"

where

  • bitbucket.server is the URL of your Bitbucket server

  • filename is the CSV you want to upload

Deleting all globally reviewed false positives

CODE 
curl -u admin -X DELETE "https://{bitbucket.server}/rest/security/latest/global-reviewed?confirm=true"

where

  • bitbucket.server is the URL of your Bitbucket server

  • confirm must be set to true to complete the operation

Debug Logging

This section documents the query and update of the additional logging setting from the settings pane. For more information, see: Enabling debug logging.

Querying the log level

CODE 
curl -u admin -X GET "https://{bitbucket.server}/rest/security/latest/loglevel"

where

  • bitbucket.server is the URL of your Bitbucket server

Setting the log level

CODE 
curl -u admin -X PUT "https://{bitbucket.server}/rest/security/latest/loglevel?logLevelOverride={logLevel}"

where

  • bitbucket.server is the URL of your Bitbucket server

  • logLevel is one of TRACE, DEBUG, INFO, WARN, or ERROR. All messages between the log level you set and WARN inclusive will become WARN messages.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close