Skip to main content

Sonatype for Jira Cloud

Sonatype for Jira Cloud is an Atlassian Marketplace plugin that automately creates issues in response to new violations as they occur during your policy evaluation. Prioritize and track the remediation of open-source component risk directly in your development workflow.

Steps for Configuration

Perform as a Jira Cloud site-level admin.

  1. Install Plugin

  2. Configure the plugin in Jira Cloud

  3. Configure the plugin per project to receive tickets

To perform as IQ Server and Policy Administrator

  1. Add webhook to the Jira Cloud in IQ Server

  2. Set up notifications on the Lifecycle policy

Install from the Atlassian Marketplace

Install the Sonatype for Jira plugin directly from the Atlassian Marketplace

NexusIQ_for_Jira.png

Requirements

  • A Sonatype Lifecycle license with IQ Server version 168 or greater

  • The latest Sonatype for Jira plugin installed

  • A webhook endpoint from Jira with a secured secret key

Warning

The secret key will be created by your team to encrypt requests. Keep the key secret as it will have permission to send requests to add issues in your Jira instance.

Configure Sonatype for the Jira Cloud Plugin

After installing the plugin we need the webhook to send requests to Jira

Lifecycle_Configuration.png
  1. In Jira, log in as an account with permission to manage applications

  2. Goto 'Apps' in the top menu

  3. Select the option to 'Manage your apps'

  4. Select 'Lifecycle Configuration' from the right menu

  5. Fill in the secured secret key for managing webhooks

  6. Add the IQ Server Base URL for report links

  7. Select Submit to save the entry

  8. Copy the webhook URL to configure the IQ Server webhook in a later step

Assign Applications to Jira Projects

You will need to associate Lifecycle applications to your Jira projects before new violations are created as issues.

issue_mapping.png
  1. Navigate to your Jira project

  2. Select Project Settings

  3. From the left menu, select the 'Lifecycle Project Configuration'

  4. Select what type of issue for violations to create

    1. The available options are: Task, Story, Bug, Epic

  5. Select the issue aggregation method

    1. By Component - Create a subtask for each component with violations

    2. By IQ Evaluation - Create a single issue which lists all violations accross all components

  6. List the Lifecycle Organizations and Applications for the project

    1. Include a comma-separated list of Organizations or Application Ids from Lifecycle

    2. Select the Organizations and Applications from the drop-down when using the 'Organization and Application Summary' webhook event type

  7. Fill required fields based on the issue type

  8. Set the optional Workflow Transition state to refresh the ticket when the violations are resolved in Lifecycle

Create a webhook in the Lifecycle server

The Lifecycle server webhooks are used to communicate with the plugin

  1. Log into the Lifecycle server as an administrator

  2. Select Webhooks from the System Preferences gear icon in the top right menu

  3. Select Add a Webhook

  4. Paste in the webhook URL from the plugin

  5. Include a meaningful description to be displayed as a notification option

  6. Use the same secret key entered in the plugin configuration

  7. Set the event type to Violation Alert

  8. Optionally, create a webhook with the Organization and Application Summary event type

    1. This event is used to populate the applications dropdown from the project configuration

  9. Select Create to save the webhook

Note

The Organization and Application Summary webhook event may result in slow performance and potential security concerns for Lifecycle servers with hundreds of applications.

The assigning applications dropdown is only present when this webhook is configured. Instead, you will need to provide a comma-separated list of organizations and application Ids.

Configure Notifications on Policies

Not all policy violations require a Jira ticket to be created whenever it is found. Notifications in Lifecycle are set on each policy for the stages you wish tickets to be created. For example, creating tickets on all security-critical and security-high violations at the build stage. The following steps will need to be performed for each policy violation you will want to configure a Jira notification for.

  1. Sign into an account with policy administration access permissions

  2. From Orgs and Policies selection the policy to edit

  3. Select Webhook from the Recipient Type drop-down menu

  4. Select the appropriate Webhook from the Select Webhook drop-down menu

  5. Click Add to add the notification

  6. Specify the stage(s) to create notifications for (build, release, etc)

126655373.png

Review violation tickets within the plugin

When violations are detected by the Lifecycle server, new issues are created on the project board with the New status.

Example of issue aggregation of By IQ Evaluation

Lifecycle_notification.png

A subtask is created for each of the components attached to the primary report scan ticket for the issue aggregation of By Component

child_issues.png

The following fields are populated as follows:

  • Type: Corresponds to the selected issue type on the mapping page.

  • Labels: Corresponds to a selected label on the mapping page.

  • Reporter: Corresponds to a selected reporter on the mapping page.

  • Priority: Lifecycle threat level 10 is mapped to the highest Jira priority with the threat of 0 is mapped to the lowest priority. Additional priorities are assigned using a linear function.

    Threat Level

    Jira Priority

    9-10

    blocker (1)

    7-8

    critical (2)

    4-6

    major (3)

    2-3

    minor (4)

    0-1

    trivial (5)

Supported and unsupported field types

Default values are required for mandatory fields in Jira. The plugin will ignore the unsupported fields if they are marked optional in Jira.

The supported fields are: Float, Freetext, Textfield, URL, Version, Select, Multiselect, Radio, Labels

Jira Integration troubleshooting tips

Confirm that all instructions are followed.

  • Check that policy notifications are sent to the Jira webhook.

    1. Jira issues are only created for new violations

    2. No Action is taken when the violation has already been sent to Jira

  • Verify the webhook URL matches between the Lifecycle server and Jira

  • Check the IQ configuration screen on Jira for error messages

    • The message box will display the status of the last webhook received from the Lifecycle server

    • At least one application or organization needs to be mapped to the project

  • Click the Test button on the Sonatype IQ Configuration page on Jira

  • Check that the violation alerts are mapped to the correct Jira project

  • Check that the evaluation stage matches the configured webhook notification