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):
curl -u admin -H "X-Atlassian-Token: no-check" $URL
Example (Python):
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
curl -u admin "https://{jira-address}/rest/security/latest/project/{key}?start={start}&size={size}&reviewed={reviewed}"
where
key
is the project keystart
is the 0-indexed offset of the findings to fetchsize
is the number of results to fetch per requestreviewed
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
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 fetchsize
is the number of results to fetch per requestreviewed
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
curl -u admin -X POST "https://{jira-address}/rest/security/latest/scan/all"
Scanning a single project
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
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.
curl -u admin "https://{jira-address}/rest/security/latest/rules"
Enable or disable a built-in scanning rule
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), andenabled
is the desired rule state,true
orfalse
.
Create a new custom rule
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,
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
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
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
curl -u admin -X DELETE "https://{jira-address}/rest/security/latest/review/project/{key}?confirm=true"
where
key
is the project key, andconfirm
must betrue
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
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.
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
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
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
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
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. .
curl -u admin -F file=@'{filename}' "https://{jira-address}/rest/security/latest/global-reviewed/create"
where
jira-address
is the URL of your Jira serverfilename
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. .
curl -u admin -F file=@'{filename}' "https://{jira-address}/rest/security/latest/global-reviewed/delete"
where
jira-address
is the URL of your Jira serverfilename
is the CSV you want to upload
Deleting all globally reviewed false positives
curl -u admin -X DELETE "https://{jira-address}/rest/security/latest/global-reviewed?confirm=true"
where
jira-address
is the URL of your Jira serverconfirm
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
curl -u admin -O -J "https://{jira-address}/rest/security/latest/settings"
Changing Settings
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
orfalse
) - Whether to keep project scans up to date. Equivalent to theKeep project scans up to date
setting switch.scanAttachments
(true
orfalse
) - 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 ofTRACE
,DEBUG
,INFO
,WARN
(default), orERROR
) - Configure the system log to include messages at this level as Warn messages. TheEnable additional logging
sets this toDEBUG
as described in the Enabling debug logging page.
Viewing the List of Users with Explicit Access
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.
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}"}]'