Jira Destination

Configuring Jira as an alert destination in your Panther Console

Overview

Two-way syncing of a Panther alert's status, assignee, and comments with its corresponding Jira issue is in open beta starting with Panther version 1.105, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.

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 in the specified project with the specified assignee.

You can choose to sync status updates, assignees, and comments between Panther alerts and their corresponding Jira issues.

Currently, only Jira Cloud is supported as an alert destination. The on-premises version of Jira is not supported.

One-way sync vs. two-way sync

With the Jira alert destination in Panther, you can enable one-way sync or two-way sync for assignee, status, and/or comments.

• One-way sync: When the status or assignee is updated or a comment is created on a Panther alert, the same change in status, assignee, or comment is made on the corresponding Jira issue.

• Two-way sync: In addition to the one-way sync functionality, when the status or assignee is updated or a comment is created or updated on a Jira issue that was created by a Panther alert, the same change in status, assignee, or comment is made on the corresponding Panther alert.

How to set up Jira alert destinations in Panther

Prerequisites

Prerequisite for two-way sync

To enable two-way sync, you must first install the panther-jira-app in your Atlassian instance, which will allow Panther to receive updates to Jira issues Panther created. Panther will not receive updates for issues that were not created by Panther.

To install panther-jira-app:

1. On the panther-jira-app page, click Get app.

2. Under Select a site to install this app on, choose the Jira instance for which you would like to enable Panther two-way sync.

3. Click Install.

   • You will finish configuring this app after configuring the Jira alert destination in Panther.

Prerequisite for one-way or two-way sync of assignees

If you plan to enable one-way or two-way assignee sync, each of your organization's users who will be assigned to Jira issues created by Panther alerts must make their email available to installed apps in Jira. Each of these users should complete the process below:

1. In your Atlassian console, visit the Profile and visibility tab within your account settings.

2. Scroll down to the Contact section.

3. For your email address, set the Who can see this? value to Anyone.

Step 1: Create a Jira API key

You (the user generating this API key) will be displayed as the actor making the update when Panther performs an action in Jira (i.e., creates an issue, updates the assignee, status, or comments).

1. Log in to your Atlassian account and navigate to the API Token management page.

2. Click Create API Token, add a descriptive label, and click Create:
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 it again.

Step 2: Configure the Jira alert destination in Panther

1. In the left-side navigation bar of your Panther Console, click Configure > Alert Destinations.

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. Click Jira.

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 Token: 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 Levels: Select the severity level of alerts to send to this Destination.

   • Default Alert Types: Select the alert types to send to this Destination.

   • Log Types: 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.

5. Proceed to Step 3, below.

Step 3: Configure Panther/Jira syncing

1. In the Syncing Options section, make a selection for each of the following:

   • Alert Status:

     • Do not sync: Updates to the status of an alert in Panther will not be reflected on the corresponding Jira issue, and vice versa.

     • One-Way: 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. It is important that all Jira statuses are able to be transitioned from any other Jira status. This can be configured in the corresponding Jira project's workflow settings.

     • Two-Way: In addition to the one-way functionality described above, if the status of a Jira issue is updated, the status of the corresponding Panther alert will also be updated.

   • Assignee:

     • Do not sync: Updates to the assignee of an alert in Panther will not be reflected on the corresponding Jira issue, and vice versa.

     • One-Way: 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 the email address associated to the Panther account cannot be found in Jira (either because it does not exist or has not been made visible, as described in the Prerequisites), an update to the Jira issue will not be performed.

       • Currently, updates to the alert assignee in a Panther Slack Bot do not sync to the associated Jira issue.

     • Two-Way: In addition to the one-way functionality described above, if the assignee of a Jira issue is updated, the assignee will also be updated on the Panther alert, as long as there is a Panther user with a matching email address.

   • Comments:

     • Do not sync: Comments left on an alert in Panther will not be reflected on the corresponding Jira issue, and vice versa.

     • One-Way: 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.

       • When a comment posted on an alert in Panther is synced to the corresponding Jira issue, the comment text is prepended with "[Panther user] commented on 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.

     • Two-Way: In addition to the one-way functionality described above, if a comment is posted on a Jira issue, the comment will also be posted on the Panther alert.

       • When a comment posted on a Jira issue is synced to the corresponding Panther alert, the comment text is prepended with "[Jira user] commented on Jira:"

       • When a comment on a Jira issue is edited, the comment on the Panther alert will be edited.

       • There are some limitations to comment formatting in Panther. See Comment formatting in Panther for more information.

2. Click Continue.

3. (Only if you enabled one-way or two-way status syncing) On the Map Panther and JIRA Statuses page, map the Panther alert statuses to the corresponding status you want to use in Jira.

   • Click Continue.
4. (Only if you enabled two-way sync for alert status, assignee, or comments) On the Two-Way Sync page, copy the Panther Instance URL and API Token and store them in a secure location, as you will need them in the next step. The API Token will not be shown to you again.

   • Click Continue.

Step 4 (for two-way sync only): Finish setting up the Panther Cloud Sync app

If you did not enable two-way sync for status, assignee, or comments, you can skip this step.

1. In your Jira console, navigate to your apps, then click Manage apps.

2. Under User-installed apps, click Panther Cloud Sync to expand its section.

3. Click Configure.

4. Under Panther Application Configuration, enter values for the following fields:

   • Panther Instance URL: Enter the Panther Instance URL you generated in Panther in the previous step.

   • Panther Secret: Enter the API Token you generated in Panther in the previous step.

   • Tracked Jira Project: Select the project you would like to sync to Panther. This project should match the one for which you entered a Project Key in Panther.

5. Click Save.

Step 5: Finish setting up the Jira alert destination in Panther

• On the final page of the destination configuration in Panther, 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.

Comment formatting in Panther

When two-way sync for comments is enabled and a comment on a Jira issue is created or updated, advanced formatting (e.g., tables or images) will be stripped from the comment's representation in Panther.

The comment formats supported in Panther include:

• Bold

• Italic

• Strikethrough

• Links

• Code blocks

• Paragraphs and line breaks

• Quotes

• Bulleted lists

• Numbered lists

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 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.