Skip to main content

Sonatype for Jira Data Center

Sonatype for Jira Data Center is an Atlassian Jira plugin that automates the creation of Jira issues for new policy violations.

  • Prioritize remediation of open-source policy violations from the Lifecycle server inside the Jira Data Center

  • Automatically create Jira issues when new violations occur

  • Transition project issues once they have been remediated in the application code

Workflow overview

  1. The plugin is integrated by the Jira Administrator to communicate with the Lifecycle server

  2. Jira Administrators associate projects with applications in Lifecycle

  3. Administrators identify the policies to create Jira issues

  4. Tickets are created for new violations in Jira projects

  5. Remediated violations are updated in the corresponding tickets

Requirements

  • Sonatype Lifecycle license and configured IQ Server

  • IQ Server account with the Policy Administrator role

  • Jira Administrator account to install and configure the plugin

For details on the Jira Data Center versions supported, please check the plugin's Atlassian Marketplace listing.

Note

The Sonatype for Jira plugin is verified by Sonatype to work on the Jira Data Center

Installation

The initial installation is only required once and will apply to all Jira projects. This configuration enables the integration between Jira and Sonatype IQ Server.

Important

To upgrade a previously installed plugin to version 1.10.2, it will need to be reinstalled. It cannot be updated.

Configure the plugin

Configuration of the Sonatype for Jira Data Center plugin is done at the global Jira instance level.

configure-jira-plugin-data-center.png
  1. In Jira, navigate to the settings icon

  2. Select Applications

  3. Select IQ Jira Plugin

  4. Enter the Sonatype IQ Configuration parameters

  5. Select Save

  6. Select Test to confirm the connection to the Lifecycle server

  7. Select Create webhook to add a webhook

Manually configuring the Lifecycle server webhook

Manually configure a webhook using these configure webhook steps

  • The Violation Alert event type is required

  • Use the same secret key in both the webhook and IQ configuration

Jira project to Lifecycle server associations

Sonatype Lifecycle organization/applications are associated with a specific Jira project. Follow the steps below for each Jira project intended to receive policy violation notifications from the Sonatype IQ Server.

Configure mapping between a Jira project and an organization and/or application within the Lifecycle server

  1. Navigate to the desired project in Jira.

  2. Click on the Project Settings gear icon in the lower left of your screen.

  3. Click on the Sonatype IQ menu option. If the page is empty after clicking the link, sign into Jira with a user with Administer Project permissions for the project.

A Jira project can be mapped to one or more Lifecycle organizations or applications. When new violations occurs, new issues are created.

Issue Type

The form fields will vary based on the selected issue Jira issue ticket type to be created

Issue Aggregation
  • By Component - creates a parent issue and adds each component in the report as a sub-task

  • By IQ Evaluation - creates a single issue for all violations from the report

IQ Applications

Set the applications associated with the project

IQ Organizations

Set the organizations associated with the project

Labels

Specify one or more Jira labels for the tickets created

Automate Workflow Transition

Apply workflow transition when the violations are remediated

Workflow Transition

The workflow transition to be applied when the violations are remediated

Reporter

The account associated with the automatically created tickets

  • One or more applications or organizations are required to trigger the creation of policy violation tickets

  • Default fields (e.g. the 'Reporter' field in the screenshot below) appear at the bottom of the page

  • A custom field must be marked as required in Jira to be displayed on this form

187203588.png

Automate Workflow Transition

Sonatype IQ for Jira will attempt to apply the selected Workflow Transition to issues when policy violations are successfully remediated.

  • The selected transition must be valid for the current ticket state

  • Workflow requirements must be met (for example: required fields)

  • A comment is created on the issue linking to the Lifecycle scan report

  • Errors are logged with an entry on the reason for failure

Configure Notifications to Jira

The Jira notification creates a Jira issue when new policy violations are discovered. To create Jira notifications, install the Jira plugin and configure its communication with the Lifecycle server via a webhook (see above).

To configure Jira notifications:

  1. Select the policy for which notifications will be created upon its violation

  2. Select Webhook from the Recipient Type option

  3. Select the appropriate Webhook from the Select Webhook option

  4. Select Add

  5. Specify the stages to create notifications

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

Jira logging

Error messages are sent to Jira's default log4j logger of levels WARN or higher. Log levels can be temporarily changed by navigating to the SystemLogging and Profiling tab on the Jira administration page.

To make log changes permanent or for advanced log4j settings, edit 'WEB-INF/classes/log4j.properties'.

The logging of the Jira plugin can be customized using the following log levels:

Package

Description

Plugin events have the following prefix:

com.sonatype.jira

iq.data.service.WebhookService

Events with Webhooks.

Log levels used are INFO for success messages and ERROR for failures.

iq.data.service.ConfigurationService

Configuration errors are displayed directly in Jira's web interface.

Currently, this is only used for logging internal errors at ERROR level.

iq.data.service.IqClientImpl

Errors communicating with the IQ Server are logged at ERROR level.

iq.data.service.PolicyAlertTrackingServiceImpl

Policy violations are stored for de-duplication in Jira's local database as logged at DEBUG level.

iq.rest.IqIssueResource

HTTP messages are logged at DEBUG level.

iq.rest.AdminResource

User interactions in the 'Project settings' are logged at INFO level and failures at WARN level.

iq.issue.IssueResolverImpl

Workflow transitions that could not be successfully applied are logged at INFO level.

Issue resolution and transitions are logged at DEBUG level.