REST API For Scripting and Automation

Security for Confluence 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

Confluence 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 Confluence. Follow Atlassian’s instructions for using the REST API Browser first, to ensure that you can access it.

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

Authentication and basic parameters

Reference the Confluence REST API for Confluence’s built-in REST API, which is useful for getting lists of Spaces, content IDs in spaces, 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 Confluence instance - replace {confluence-address} with the address of your Confluence instance.

Disabling XRSF checks

Some of these API calls will fail by default if called from a host that is not part of the Confluence 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 space administrator to run scans.

Getting scan results for a space

BASH

curl -u admin "https://{confluence-address}/rest/security/latest/scan/space/{key}?reviewed={reviewed}&ruleIds={ruleIds}&page={page}&size={size}"

where

key is the case-sensitive key for the space in question.
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.
ruleIds is an optional comma-separated list of rule IDs (e.g.: ruleIds=AWS_SECRET_ACCESS_KEY,STRIPE_API_KEY,3). Built-in rules are referred to by name (e.g.: AWS_SECRET_ACCESS_KEY), but custom rules have a numeric ID (e.g.: 3). You can find rule IDs using the REST API For Scripting and Automation | Get-a-list-of-all-scanning-rules endpoint. If provided, only findings that match at least one of these rules will be returned.
page is the 0-indexed page of findings results to fetch.
size is an optional parameter to specify the number of results per page to fetch.

Confluence Space keys are case-sensitive. You can verify the case of the space key on the space details page.

Getting scan results for a content version

BASH

curl -u admin "https://{confluence-address}/rest/security/latest/scan/content/{id}?createdWhen={createdWhen}&reviewed={reviewed}&ruleIds={ruleIds}&page={page}&size={size}"

where

id is the content ID.
createdWhen is when the version of the content was created (e.g., 2021-08-15T17:54:36.860-05:00).
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.
ruleIds is an optional comma-separated list of Rule IDs (e.g.: ruleIds=AWS_SECRET_ACCESS_KEY,STRIPE_API_KEY,3). Built-in rules are referred to by name (e.g.: AWS_SECRET_ACCESS_KEY), but custom rules have a numeric ID (e.g.: 3). You can find rule IDs using the REST API For Scripting and Automation | Get-a-list-of-all-scanning-rules endpoint. If provided, only findings that match one of these rules will be returned.
page is the 0-indexed page of findings results to fetch.
size is an optional parameter to specify the number of results per page to fetch.

Scanning all spaces

CODE

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

Scanning a single space

CODE

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

where

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

Scanning the full history of a piece of content

CODE

curl -u admin -X POST "https://{confluence-address}/rest/security/latest/scan/content?id={id}"

where

id is the content ID.

Scanning a single content version

CODE

curl -u admin -X POST "https://{confluence-address}/rest/security/latest/scan/content/version?id={id}&createdWhen={createdWhen}"

where

id is the content ID.
createdWhen is when the version of the content was created (e.g., 2021-08-15T17:54:36.860-05:00).

Cancel scheduled scans

You must be a Confluence administrator or a user granted explicit app access to cancel scheduled scans.

BASH

curl -u admin -X DELETE "https://{confluence-address}/rest/security/latest/scan-queue/clear"

Scanning rules

You must be a Confluence administrator or a 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://{confluence-address}/rest/security/latest/rules"

Enable or disable a built-in scanning rule

CODE

curl -u admin -X PUT "https://{confluence-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).
enabled is the desired rule state, true or false.

Create a new custom rule

CODE

curl -u admin -X POST "https://{confluence-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://{confluence-address}/rest/security/latest/rules/custom/{rule-ID}"

Reviewing findings

You must be able to edit content in a space in order to review findings. For more information, see Hiding false positives, revoked credentials, etc..

Reviewing a finding

CODE

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

where

key is the case-sensitive key for the space in question.
$MATCH is the exact string to be reviewed.
$RULENAME is the name of the rule which generated this finding.

Un-reviewing a finding

CODE

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

where

key is the case-sensitive key for the space in question.
$MATCH is the exact string to be un-reviewed.

Deleting all reviewed findings for a space

You must be a space admin to use this endpoint.

CODE

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

where

key is the case-sensitive key for the space in question.
confirm must be true to complete the operation.

Exporting

You can export scan findings or reviewed findings.

Exporting Dashboard Overview

CODE

curl -u admin -O -J "https://{confluence-address}/rest/security/latest/dashboard/export?name={name}&type={type}"

where

name is an optional search filter query parameter for a particular space name.
type is an optional filter for only particular space types. May be “all”, “personal”, or “global”. Defaults to “all”.

Exporting All Findings

For a particular space

CODE

curl -u admin -O -J "https://{confluence-address}/rest/security/latest/export/space/{key}/findings?deduplicate={deduplicate}&historical={historical}"

where

key is the case-sensitive key for the space in question.
deduplicate is an optional query parameter that will override the global deduplication setting if provided.
historical is an optional query parameter that indicates whether you’d like to include historical findings in your export.

For all spaces

Only spaces you can administer are included.

CODE

curl -u admin -O -J "https://{confluence-address}/rest/security/latest/export/findings?deduplicate={deduplicate}&historical={historical}"

where

deduplicate is an optional query parameter that will override the global deduplication setting if provided.
historical is an optional query parameter that indicates whether you’d like to include historical findings in your export.

Exporting Reviewed False Positives

For a particular space

CODE

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

where

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

For all spaces

CODE

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

Exporting Attachment Scan Information

For a particular space

CODE

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

where

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

For all spaces

CODE

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

Global reviewed false positives

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

where

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

where

confluence-address is the URL of your Confluence server.
filename is the CSV you want to upload.

Deleting all globally reviewed false positives

CODE

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

where

confluence-address is the URL of your Confluence server.
confirm must be set to true to complete the operation.

Viewing and Changing Settings

You can view and change settings as an admin via the API.

Viewing Settings

CODE

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

Changing Settings

CODE

curl -u admin -O -J "https://{confluence-address}/rest/security/latest/settings?autoScan={bool}&emailForNewFindings={bool}&customEmailText={text}&scanAttachments={bool}&parallelScans={int}&logLevelOverride={level}&includePlaintextInExports={bool}&deduplicateExports={bool}" -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 space scans up to date. Equivalent to the Keep space scans up to date setting switch, as described in the Automatically Scanning Content page.
emailForNewFindings (true or false) - Whether to email authors who publish sensitive content. Equivalent to the Email authors when they publish potentially sensitive content setting switch, as described in the Email notifications for content authors page.
customEmailText (text, URL-encoded) - The custom text to include in the email to authors who publish sensitive content. Equivalent to the Customize emails text entry box, as described in the Email notifications for content authors page.
scanAttachments (true or false) If attachment scanning is enabled, as described on Scanning Files Attached to Pages.
parallelScans (an integer) – Configure 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.
includePlaintextInExports - When enabled, exported findings will contain the full text of the finding in the CSV output. When disabled, the CSV will contain a link to the report in its place. See: Exporting Findings | Redacting-findings-in-exported-reports.
deduplicateExports - When enabled, exported findings with the exact same text are deduplicated across the history of a given page. This behavior presents an export similar to the layout of the Security Analysis page. See: Exporting Findings | Deduplicate-Findings-in-Exports.

Viewing the List of Users with Explicit Access

CODE

curl -u admin -O -J "https://{confluence-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://{confluence-address}/rest/security/latest/settings/entity-permissions" -XPUT --data-binary '[{ "type": "{USER or GROUP}", "idOrKey": "{user key or group name}"}]'