Links

Jira Destination

Configuring Jira as an alert destination in your Panther Console

Overview

Destinations are integrations that receive alerts from rules, policies, system health notifications, and rule errors. Panther supports configuring Jira as the destination where you will receive alerts.
When an alert is forwarded to a Jira destination, a bug, story, or task is created and assigned to the specified assignee in the specified project.
Currently, only Jira Cloud is supported as an alert destination. The on-premises version of Jira is not supported.

How to set up Jira alert destinations in Panther

Creating a Jira API key

  1. 1.
    Log in to your Atlassian account and navigate to the API Token management page.
  2. 2.
    Click Create API Token, add a descriptive label, and click Create:
    The Token Management page in an Atlassian account is open. There is a popup dialog labeled "Create an API Token." It contains a "Label" field and the words "Jira API Key" are typed into it. There is a blue Create button at the bottom.
  3. 3.
    Click Copy and store the token in a secure location.
    • Note: The token is sensitive information and you will not be able to view the token again.

Configuring the Jira alert destination in Panther

  1. 1.
    In the left-side navigation bar of your Panther Console, click Configure > Alert Destinations.
  2. 2.
    Click +Add your first Destination.
    • If you have already created Destinations, click Create New in the upper right side of the page to add a new Destination.
  3. 3.
    Click Jira.
  4. 4.
    Fill out the form:
    • Display Name: Enter a descriptive name.
    • Organization Domain: Enter your organization's Jira domain.
      • For example: https://example.atlassian.net.
    • Project Key: Enter the project identifier within your organization. You can find this in Jira in your project settings page or by browsing your organizations' Jira projects and locating the key column.
    • Email: Enter the email address of the Jira user who has permissions to create the new issues with the corresponding Jira API Key.
    • Jira API Key: Enter the API token you generated in the earlier steps of this documentation.
    • Issue Type: Enter the Issue type from Jira. This can be Bug, Story, Task, or any custom type.
    • Assignee ID: Enter the unique ID of the user or group that the Issue will be assigned to.
      • To find the ID, go to a user or group's public Jira profile and locate the trailing string from the URL of their profile. Example: If a user's profile URL is https://example.atlassian.net/jira/people/5f8f26dabd12345678910abcd, their ID is 5f8f26dabd12345678910abcd.
    • Labels: Enter the associated Jira labels.
    • Severity: Select the severity level of alerts to send to this Destination.
    • Alert Types: Select the alert types to send to this Destination.
    • Log Type: By default, we will send alerts from all log types. Specify log types here if you want to only send alerts from specific log types.
    • One-Way Status Syncing: When this field is set to ON, when the status of an alert is changed in the Panther Console or Slack Bot, or via the Panther API, the status of the corresponding Jira issue is also updated.
      • Any alert status changes made in Panther will also be added as a comment on the associated Jira issue.
      • If you have custom transition rules in your Jira project workflows, Panther may not be able to transition the ticket from one status to the next.
      • If the status of a Jira issue is updated in Jira, the status will not sync back to Panther.
    • One-Way Assignee Syncing: When this field set to ON, when the assignee of a Panther alert is updated (in the Panther Console or via the Panther API), the assignee of the corresponding Jira issue is also updated.
      • The Panther alert and Jira issue assignees are matched by email address. If no Jira user exists with the email address associated to the Panther user account, an update to the Jira issue will not be performed.
      • If the assignee of a Jira issue is updated in Jira, the assignee change will not sync back to Panther.
      • Currently, updates to the alert assignee in a Panther Slack Bot do not sync to the associated Jira issue.
    • One-Way Comment Syncing: When this field set to ON, when a comment is posted on a Panther alert (in the Panther Console or via the Panther API), the comment is also posted on the corresponding Jira issue.
      • If a comment is posted on a Jira issue, the comment will not sync back to Panther.
      • When syncing a comment from Panther to Jira, Panther tries to maintain the original formatting so that comments look identical. In rare cases, due to conversion limitations, the comment may be formatted differently—without a loss of content.
  5. 5.
    Click Add Destination.
    • If you enabled one-way status syncing, you will see the "Map Panther and JIRA Statuses" page. Map the Panther alert statuses to the corresponding status you want to use in Jira, then click Continue.
  6. 6.
    On the final page, optionally click Send Test Alert to test the integration using a test payload. When you are finished, click Finish Setup.
For information on troubleshooting Jira alert destinations, please see this KB article: Guide to Troubleshooting Jira Alert Destinations in Panther.

Alert Context Formatting

The alert_context payload is JSON pretty printed using JIRA's native formatting. Additionally, Panther Rule ID and Alert ID fields are surfaced in the ticket’s description for better automation support.
The image shows an alert in Jira. It contains the title "Test alert title", fields for Description, Runbook, Rule ID, Alert ID, Severity, Tags, and AlertContext.
The request body payload looks similar to the example below:
Request body payload
{
"fields": {
"summary": "Some Failure: My Summary",
"description": "*Description:* My Description\n [Click here to view in the Panther UI|https://panther.io/alerts/my-alert-id?source=jira]\n *Rule ID:* my-rule-id\n *Alert ID:* my-alert-id\n *Severity:* INFO\n *AlertContext:*\n {code:JSON}\n{\n \"some\": \"json\",\n \"or\": \"code\",\n}{code}",
"project": {
"key": "MYPROJ"
},
"issuetype": {
"name": "Task"
},
"assignee": {
"id": "assignee-jira-id"
},
"labels": ["my-label"]
}
}
The request header that Panther sends is in the following format:
Authorization: Basic <base64encoded(username:apikey)>

Additional Information on Destinations

For more information on alert routing order, modifying or deleting destinations, and workflow automation, please see the Panther docs: Destinations.