Setup a Playbook to Automatically Create Jira Issues/Tickets – Red Canary Support

Issue

We are using Jira to track our company's tech support cases as well as our security incidents. How can we setup Red Canary to create a new ticket ("issue") in Jira whenever a threat is detected?

Environment

Red Canary Portal
Automation

Resolution

While the Red Canary Portal does not currently have any built-in Jira playbook actions, you can workaround this using the Invoke Webhook or API playbook action and Jira's REST API. Before getting started, you will need to generate an API token in Atlassian and BASE64 encode the authentication string, if you have not already.

To configure this automation, follow the steps below.

Navigate to Automation > Playbooks, then click Create New Playbook
Click Add Action then add the Invoke Webhook or API action

Configure playbook action fields as follows, replacing the <angled bracket> values with your own, and the brackets removed

HTTP Method: POST
URL: https://<MySubdomain>.atlassian.net/rest/api/3/issue
Allow Untrusted Connections: No

HTTP Headers: See code block below

authorization=Basic <BASE64EncodedString>
content-type=application/json

Payload: Custom Payload

{
    "fields": {
        "summary": "Red Canary Threat Detected",
        "issuetype": {
            "id": "<IssueTypeID>"
        },
        "project": {
            "key": "<ProjectKey>"
        },
        "description": {
            "type": "doc",
            "version": 1,
            "content": [
                {
                    "type": "paragraph",
                    "content": [
                        {
                            "text": "Details: Endpoint $JSON:Endpoint.hostname \n\nUsername $JSON:EndpointUser.username \n\nSensorID is $JSON:Endpoint.sensor_id \n\nDetection Details $JSON:Detection.details \n\nDetection URL $JSON:Detection.url",
                            "type": "text"
                        }
                    ]
                }
            ]
        }
    }
}

Provide the playbook a name and/or description, then click Save to finalize changes
The playbook configuration should look similar to the following screenshot
Navigate to Automation > Triggers, then click Configure New Trigger
From the list of triggers, select When a Threat is Published
Under the newly created trigger, click Add Condition and add the following trigger
- Threat > Severity > Is one of > High, Medium > Save
Click Connect Playbook and connect your new Invoke Webhook or API playbook
The final set of automation should look similar to the following screenshot

Key Concepts and Troubleshooting

A correctly encoded BASE64 string should look similar to the following truncated example in your playbook's header
- ```
authorization=Basic ABCdef123gHiJKL[...]456Mnop78qr9TUV000wx0yZ=
```
Some available object attributes may translate to text that includes invalid escape characters in JSON strings, such as \, which will result in the playbook failing unless the attributes are formatted as $JSON:Variable.name in the payload
If the playbook action's Payload is set to All Attributes as JSON, the action will fail as a Custom Payload is required to pass valid fields to the Jira API
While the example payload template can be customized to fit your needs, the Jira API requires IssueType and Project to be defined in the payload in order to create a new Jira issue
To identify valid IssueType IDs, run the following API call from your system's CLI or API client, replacing the <angled bracket> values with your own and the brackets removed (leave values in 'single quotes' where indicated), and refer to the ID of the desired Issue name (i.e. Task, Story, etc.)
- ```
curl --request GET \
  --url https://<MySubdomain>.atlassian.net/rest/api/3/issue/createmeta/<ProjectKey>/issuetypes \
  --header 'authorization: Basic <BASE64EncodedString>' \
  --header 'content-type: application/json'
```

Experiencing Playbook Errors?

If the playbook is failing, your API token may be missing permissions or a field is configured with an invalid value. Verify your user role and API token have permissions to the appropriate projects and API scopes and run the test below from a script interpreter or API client.

To test your API call independent of Red Canary's platform, run the following command from your system's CLI (e.g. CMD, PowerShell, Terminal, etc.) or API client, replacing the <angled bracket> values with your own and the brackets removed (leave quotations intact where present)

curl --request POST \
  --url https://<MySubdomain>.atlassian.net/rest/api/3/issue \
  --header 'authorization: Basic <BASE64EncodedString>' \
  --header 'content-type: application/json' \
  --data '{
  "fields": {
    "issuetype": {
      "id": "<IssueTypeID>"
    },
    "project": {
      "key": "<ProjectKey>"
    },
    "summary": "This is a test",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "My API permissions and payload syntax are correct."
            }
          ]
        }
      ]
    }
  }
}'

If this test fails, troubleshoot any returned errors by referring to Jira API documentation and/or Atlassian support to verify your API permissions and scopes, or chosen fields and values

Cause

Red Canary does not currently offer a built-in playbook action for creating Jira issues. However, the Jira API can be used in conjunction with the Invoke Webhook or API playbook action as a highly-customizable workaround.