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

The plugin is integrated by the Jira Administrator to communicate with the Lifecycle server
Jira Administrators associate projects with applications in Lifecycle
Administrators identify the policies to create Jira issues
Tickets are created for new violations in Jira projects
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.

Install the Sonatype for Jira Data Center from the Atlassian Marketplace

Important

When migrated from Jira Server to Jira Data Center from version 1.10.2 or previous versions, uninstall the previous plugin and re-install a data center-compatible version

The server-compatible plugin versions cannot be automatically upgraded to data center-compatible versions.

Configure the plugin

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

In Jira, navigate to the settings icon
Select Applications
Select IQ Jira Plugin
Enter the Sonatype IQ Configuration parameters
Select Save
Select Test to confirm the connection to the Lifecycle server
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

Navigate to the desired project in Jira.
Click on the Project Settings gear icon in the lower left of your screen.
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

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:

Select the policy for which notifications will be created upon its violation
Select Webhook from the Recipient Type option
Select the appropriate Webhook from the Select Webhook option
Select Add
Specify the stages to create notifications

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

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

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

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 System → Logging 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.