Skip to main content

Sonatype for Jira Cloud

Sonatype for Jira Cloud automatically 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

To perform as a Jira Cloud site admin:

  1. Install Sonatype for Jira Cloud

  2. Configure the integration in Jira Cloud

  3. Configure the integration 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 Sonatype for Jira Cloud

Install the integration directly from the Atlassian Marketplace

Sonatype for Jira Cloud

Configuration Requirements

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

  • The latest Sonatype for Jira integration 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 Jira Cloud

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

Integrations_-_Jira_Cloud_-_Configuration.png

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

  2. From the top navigation bar, select "Apps" and "Manage apps"

  3. Select "Sonatype for Jira"

  4. Fill in the secured secret key for managing webhooks

  5. Add the IQ Server Base URL for report links

  6. Select Submit to save the entry

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

Assign Sonatype Lifecycle Applications to Jira Projects

You must assign Sonatype Lifecycle applications to your Jira projects before new violations are created as issues.

Jira Cloud configuration to mapping tickets fields and defaults

  1. Navigate to your Jira project

  2. Select Project Settings

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

  4. Select the issue type to create violations

    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 that lists all violations across 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. Set the optional Workflow Transition state to refresh the ticket when the violations are resolved in Sonatype Lifecycle

  8. Fill in the required fields based on the issue type, i.e., Reporter (the account associated with the automatically-created tickets.)

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 Lifecycle detects violations, 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

Component violations are listed as child issues on the Jira ticket created by the notification.

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

    Highest

    7-8

    High

    4-6

    Medium

    2-3

    Low

    0-1

    Lowest

Note

Priority names for your organization can be different if they've been customized in Jira settings by a Jira admin.

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