Integrate with Jira

Integrate StackRox with Jira Software.

3 minute read

If you are using Jira Software, you can forward StackRox alert notifications to Jira to share and collaborate on critical information. This guide explains how to integrate the StackRox Kubernetes Security Platform with Jira.

You must have a Jira account with proper access to create and edit issues in the project with which you are integrating.

To forward alerts from the StackRox Kubernetes Security Platform to Jira:

  1. Set up a user in Jira. See Configure Jira.
  2. Use the Jira URL, username, and password to integrate Jira with the StackRox Kubernetes Security Platform. See Configure the StackRox Kubernetes Security Platform.
  3. Identify policies for which you want to send notifications, and update the notification settings for those policies. See Configure policy notifications.

Alerts in Jira
Alerts in Jira

Configure Jira

Create a user in Jira which have access to the projects for which you want to create issues. To create a new user, see the official Jira documentation topic Create, edit, or remove a user. To give users access to project roles and applications, see Assign users to groups, project roles, and applications.

If you are using Jira Software Cloud, after you create a user, you must create a token for the user.

  1. Go to https://id.atlassian.com/manage/api-tokens, to generate a new token.
  2. Use the token as Password when you Configure the StackRox Kubernetes Security Platform.

Configure the StackRox Kubernetes Security Platform

Create a new integration in the StackRox Kubernetes Security Platform by using the Jira server URL and user credentials.

  1. Navigate to Platform Configuration > Integrations.

  2. Under the Plugins section, select Jira.

  3. Select the New Integration icon.

  4. Enter a name for Integration Name.

  5. Enter your credentials in the Username and Password boxes.

  6. For Issue Type, enter a valid Jira Issue Type, for example Task, Subtask, or Bug.

  7. Enter the Jira server URL in the Jira URL box.

  8. Enter the key of the project in which you want to create issues in the Default Project box.

  9. Use the Label/Annotation Key For Project box to create issues in different Jira projects.

  10. If you use custom priorities in your JIRA project, use the Priority Mapping toggle to configure custom priorities.

  11. If you use mandatory custom fields in your JIRA project, enter them as JSON values in the Default Fields JSON (Necessary If Required Fields) box. For example:

    Copy
    {
     "customfield_10004": 3,
     "customfield_20005": "Alerts",
    }
  12. Select Test (checkmark icon) to test that the integration with Jira is working.

    Selecting Test creates a test issue in Jira. You can close or delete this issue from Jira.

  13. Select Create (save icon) to create the configuration.

Create issues in different Jira projects

You can configure the StackRox Kubernetes Security Platform to create issues in different Jira projects, so they directly go to the right team. To configure this:

  1. Configure Jira by setting up users with access to each project you want to send alerts.
  2. Add an annotation similar to the following in your deployment YAML file:
    Copy
    jira/project-key: <jira-project-key>
  3. Use the annotation key jira/project-key in the Label/Annotation Key For Project box when you Configure the StackRox Kubernetes Security Platform.

Once configured, if a deployment has the annotation, the StackRox Kubernetes Security Platform sends the alert to the project specified in the annotation. Otherwise, it sends the alert to the default project.

Configure custom priorities

Use the following instructions to configure custom priorities for your JIRA project.

When you Configure the StackRox Kubernetes Security Platform:

  1. Turn on the Priority Mapping toggle. The StackRox Kubernetes Security Platform gets the JIRA project schema, and auto fills the CRITICAL_SEVERITY, HIGH_SEVERITY, MEDIUM_SEVERITY, and LOW_SEVERITY boxes.
  2. Verify or update the priority values based on your JIRA project configuration.
  3. Select Test (checkmark icon) to test that the integration with Jira is working.
  4. If you get an error, follow the instructions in the troubleshoot JIRA integration section, otherwise select the Save icon to create the configuration.

Configure policy notifications

  1. Navigate to Platform Configuration > System policies.

  2. Select the check boxes for one or more policies for which you want to send alerts.

  3. Select Enable Notifications or Actions > Enable Notification (depends upon the StackRox Kubernetes Security Platform version you are using).

  4. In the Enable Notifications dialog, select the check box for the Jira notifier (same as the Integration Name). If you haven’t configured any other integrations, you’ll see the message No notifiers configured!.

    Configure policy notifications
    Configure policy notifications

  5. Select Enable.

  • The StackRox Kubernetes Security Platform sends notifications on an opt-in basis. To receive notifications, you must first assign a notifier to the policy.

  • Notifications are only sent once for a given alert. If you have assigned a notifier to a policy, you won’t receive a notification unless a violation generates a new alert. The StackRox Kubernetes Security Platform creates a new alert when:

    • a policy violation occurs for the first time in a deployment, or
    • a runtime-phase policy violation occurs in a deployment after you resolved the previous runtime alert for that policy in that deployment.

Troubleshoot JIRA integration

Sometimes you may get errors when you try to integrate the StackRox Kubernetes Security Platform with JIRA if you are using custom priorities or mandatory custom fields in your JIRA project. This error might be because of the mismatch between the severity and priority field values.

If you don’t know the custom priority values in your JIRA project, you can Use the roxctl CLI to enable debug logging for JIRA integration.

  • To install the roxctl command-line client, see the Install StackRox Central section in Quick start.
  • See the Debug an issue section to know more about debugging issues in the StackRox Kubernetes Security Platform.

To get the custom priority values from your JIRA project:

  1. Run the following command to turn on debug logging for JIRA integration.
    Copy
    roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level Debug --modules notifiers/jira
  2. Repeat the instructions to Configure the StackRox Kubernetes Security Platform. Now when you select the Checkmark icon to test that the integration, the integration fails, but the generated log contains your JIRA project schema along with your custom priorities.
  3. Run the following command to save the debugging information as a compressed .zip file.
    Copy
    roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump
  4. Unzip the .zip file to retrieve the custom priority values in use in your JIRA project.
  5. Turn off debug logging:
    Copy
    roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level Info

Configure the StackRox Kubernetes Security Platform again and use the priority values to configure custom priorities.

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.