REST API For Scripting and Automation

Security for Jira provides many REST API endpoints for a variety of tasks. While many are documented here, the complete list is available in the REST API Browser. Please contact support if you need a particular endpoint which is not available.

Getting started

Viewing all endpoints using the REST API Browser

Jira Data Center includes a built-in REST API Browser to see all the REST API endpoints available in your instance, including those provided by Security for Jira. Follow Atlassian’s instructions for using the REST API Browser first, to ensure that you can access it.

To see all Security for Jira REST endpoints, ensure that “Show only public APIs” is unchecked, and search for security/.

Authentication and basic parameters

Reference the Jira REST API for Jira’s built-in REST API, which is useful for getting lists of projects, issue IDs in projects, and so forth.

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 Jira instance - replace {jira-address} with the address of your Jira instance.

Disabling XRSF checks

Some of these API calls will fail by default if called from a host that is not part of the Jira 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)

Running scans and getting results

Note that you must be a project administrator or any user granted explicit app access who can view a project to run scans and get scan results.

Getting scan results

Getting scan results for a project

CODE

curl -u admin "https://{jira-address}/rest/security/latest/project/{key}?start={start}&size={size}&reviewed={reviewed}"

where

key is the project key
start is the 0-indexed offset of the findings to fetch
size is the number of results to fetch per request
reviewed is an optional parameter which can be used to filter the findings by if they’re reviewed or not. If omitted, both reviewed and unreviewed findings are returned.

Getting scan results for an issue

CODE

curl -u admin "https://{jira-address}/rest/security/latest/issue/{key}?start={start}&size={size}&reviewed={reviewed}"

where

key is the issue key (i.e. “FOO-100”)
start is the 0-indexed offset of the findings to fetch
size is the number of results to fetch per request
reviewed is an optional parameter which can be used to filter the findings by if they’re reviewed or not. If omitted, both reviewed and unreviewed findings are returned.

Running Scans

Scanning all projects

CODE

curl -u admin -X POST "https://{jira-address}/rest/security/latest/scan/all"

Scanning a single project

CODE

curl -u admin -X POST "https://{jira-address}/rest/security/latest/scan/project?key={key}"

where

key is the project key

Scanning a single issue

CODE

curl -u admin -X POST "https://{jira-address}/rest/security/latest/scan/issue?key={key}"

where

key is the issue key (i.e. “FOO-100”)

Scanning Rules

You must be a Jira administrator any user granted explicit app access to view and modify scanning rules.

Get a list of all scanning rules

This includes both built-in and custom rules.

CODE

curl -u admin "https://{jira-address}/rest/security/latest/rules"

Enable or disable a built-in scanning rule

CODE

curl -u admin -X PUT "https://{jira-address}/rest/security/latest/rules/built-in/{name}?enabled={enabled}"

where

name is the name of the rule in question (e.g., AWS_CLIENT_ID – these rule names appear on the Settings page obtained via Enabling and Disabling Scanning Rules), and
enabled is the desired rule state, true or false.

Create a new custom rule

CODE

curl -u admin -X POST "https://{jira-address}/rest/security/latest/rules/custom" -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 “Get a list of all scanning rules” endpoint above. Then,

CODE

curl -u admin -X DELETE "https://{jira-address}/rest/security/latest/rules/custom/{rule-ID}"

Reviewing findings

You must be a project administrator or any user granted explicit app access who can view the project to review findings in a particular project. For more information, see Hiding false positives, revoked credentials, etc..

Adding a new reviewed false positive

CODE

curl -u admin -X POST -H "Content-Type: application/json" "https://{jira-address}/rest/security/latest/review/project/{key}/create" --data '{"matchText":"$MATCH","ruleName":"$RULENAME"}'

where

key is the project key,
$MATCH is the exact string to be reviewed, and
$RULENAME is the name of the rule which generated this finding.

Removing a reviewed false positive

CODE

curl -u admin -X POST -H "Content-Type: application/json" "https://{jira-address}/rest/security/latest/review/project/{key}/delete" --data '{"matchText":"$MATCH"}'

where

key is the project key, and
$MATCH is the exact string to be un-reviewed.

Deleting all reviewed false positives for a project

CODE

curl -u admin -X DELETE "https://{jira-address}/rest/security/latest/review/project/{key}?confirm=true"

where

key is the project key, and
confirm must be true to complete the operation.

Exporting findings

You must be a project administrator any user granted explicit app access who can view the project to export findings for that project.

Export findings for a particular project

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/export/project/{key}/findings"

where

key is the project key.

Export findings for all projects

Only projects you can administer, or projects you can view if you are granted explicit app access are included.

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/export/reviewed/findings"

Exporting Reviewed False Positives

You must be a project administrator any user granted explicit app access who can view the project to export findings for that project.

For a particular project

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/export/reviewed/project/{key}/findings"

where

key is the case-sensitive key for the project in question.

For all projects

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/export/reviewed/findings"

Exporting Attachment Scan Information

You must be a project administrator any user granted explicit app access who can view the project to export attachment scan information for that project.

For a particular project

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/export/attachments/project/{key}"

where

key is the case-sensitive key for the project in question.

For all projects

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/export/attachments"

Global reviewed false positives

Globally reviewed false positives can be managed by Jira 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://{jira-address}/rest/security/latest/global-reviewed/create"

where

jira-address is the URL of your Jira 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://{jira-address}/rest/security/latest/global-reviewed/delete"

where

jira-address is the URL of your Jira server
filename is the CSV you want to upload

Deleting all globally reviewed false positives

CODE

curl -u admin -X DELETE "https://{jira-address}/rest/security/latest/global-reviewed?confirm=true"

where

jira-address is the URL of your Jira server
confirm must be set to true to complete the operation

Viewing and Changing Settings

You can view and change settings as a Jira administrator or any user granted explicit app access via the API.

Viewing Settings

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/settings"

Changing Settings

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/settings?autoScan={bool}&scanAttachments={bool}&logLevelOverride={level}" -XPUT

You may provide the query parameters for the specific settings you want to change; any settings not included will not be changed.

Available Parameters for Settings

autoScan (true or false) - Whether to keep project scans up to date. Equivalent to the Keep project scans up to date setting switch.
scanAttachments (true or false) - If attachment scanning is enabled, as described on Scanning Files Attached to Issues.
parallelScans (an integer) – Configure the number of scans in parallel per node, as described in the Scan Performance page.
logLevelOverride (one of TRACE, DEBUG, INFO, WARN (default), or ERROR) - Configure the system log to include messages at this level as Warn messages. The Enable additional logging sets this to DEBUG as described in the Enabling debug logging page.

Viewing the List of Users with Explicit Access

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/settings/entity-permissions"

Modifying the List of Users with Explicit Access

The current explicit access list will be deleted and replaced with the new list when using this API.

CODE

curl -u admin -O -J "https://{jira-address}/rest/security/latest/settings/entity-permissions" -XPUT --data-binary '[{ "type": "{USER or GROUP}", "idOrKey": "{user key or group name}"}]'