Nexus IQ for Jira

Table of Contents

Overview 

Nexus IQ for Jira is an Atlassian Jira plugin that automates the creation of Jira project issues in response to IQ Server application evaluation policy violation events. The plugin allows you to prioritize and track remediation of open-source policy violations from Nexus IQ Server inside Jira.

Nexus IQ for Jira automatically creates Jira project issues when IQ Server application policies are violated. It can also be enabled to automatically transition project issues upon remediation of related policy violations.

How Does it Work? 

  1. The Nexus IQ for Jira plugin is installed in Jira as an application by the Jira administrator. The plugin is configured with the appropriate Nexus IQ Server URL and credentials, which enable the plugin to accept webhook requests from the Nexus IQ Server.
  2. Within Jira, Jira Project Administrators can associate a Jira project with specific Nexus IQ applications and/or organizations. They have the ability to define transitions to be applied upon policy violation remediation, specific field mappings and default values.
  3. Within Nexus IQ Server, the IQ Server Policy Administrators can identify and configure the application policies that trigger the creation of a Jira issues using the Jira webhook notification.
  4. When Nexus IQ finds a new application policy violation, tickets will automatically get created for the associated Jira project to help track remediation of those violations.
  5. If enabled and valid for the current issue state, a subsequent policy evaluation can detect the policy violations that have been remediated and apply the configured transition to relevant Jira issues.

Requirements and Limitations

The IQ Server user that is used to connect the Jira and IQ Server accounts should have the Policy Administrator role. For more information on role mapping, review our documention on user management.

The Nexus IQ for Jira integration is compatible with both Jira Server and Jira Data Center. For more details on the Jira Server versions supported, please check the plugin's Atlassian Marketplace listing.

To create notifications for Jira Cloud, use our JIRA Configuration REST API.

The Nexus IQ for Jira plugin is verified by Sonatype to work on Jira Data Center. You may proceed with this configuration despite Jira Data Center's compatibility message.

Jira Plugin Installation and Configuration 


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

Install Nexus IQ for Jira from the Atlassian Marketplace 

 https://marketplace.atlassian.com/apps/1220548/nexus-iq-for-jira?hosting=server&tab=overview

Configure connection of the Jira plugin with your Nexus IQ Server 

Configuration of the Nexus IQ for Jira plugin is done at the global Jira instance level.

  1. Navigate to the cog icon in the top right corner in Jira.
  2. Select Applications from the pop-up menu.
  3. Select IQ Jira Plugin. The Nexus IQ Configuration page shows up.
  4. Enter the Nexus IQ Configuration parameters.
  5. Click the Save button to save the configuration.
  6. Click the Test button to confirm that a connection can be established.

Configure the Nexus IQ Server Webhook 

Method 1:

Once the connection has been Tested, the option to Create webhook will appear on the Nexus IQ Configuration page (see screenshot above). This option automatically creates and configures a webhook on IQ Server. Note that the credentials used for this connection are the credentials you entered into the form. Use credentials that have the Policy Administrator permissions inside IQ Server.

Also note that clicking Create webhook does not save the credentials in the Jira configuration. Use the Save button to save the credentials in the Jira configuration.

Method 2: 

Configure a webhook manually using the webhook URL provided in the box below the Nexus IQ Configuration form. Follow this guide to manually create an IQ Server webhook. Please make sure that the Violation Alert event type is checked and a Secret Key is set and matches the secret key on the Jira server's Nexus IQ Configuration page.

Jira Project to Nexus IQ Server Associations 


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

Configure mapping between a Jira project and an organization and/or application within the Nexus IQ 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 Nexus 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 IQ organization and/or applications. When a new policy violation related to these IQ organizations or applications occurs, a new Jira issue gets created. Configure the Jira to IQ mapping and specify ticket creation settings: 

Issue Type: Select the Jira issue ticket type to be created. The form fields will vary based on the selected issue type.

Issue Aggregation:  Configure the issue aggregation: By Component creates one parent issue and adds each component that violates policy as a sub-task and By IQ Evaluation creates one issue for all policy violations in an IQ evaluation.

IQ Applications: Configure the IQ applications to trigger the creation of tickets for this Jira project.

IQ Organizations: Configure the IQ organizations to trigger the creation of tickets for this Jira project.

Labels: Specify one or more Jira labels for the tickets created. The label can be used to query for these automatically created tickets later. 

Automate Workflow Transition:  Automatically apply workflow transition when all policy violations are remediated. Requires Nexus IQ Server 98 or later.

Workflow Transition: Select the name of the workflow transition to be applied when all policy violations are remediated. Requires Nexus IQ Server 98 or later.

Reporter: Add the Reporter associated with the automatically created tickets.

Note: One or more application or organization is required to trigger the creation of policy violation tickets. 

Custom and 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.

Once Nexus IQ Mapping is configured, Jira issues will get created upon new policy violations.

If Automate Workflow Transition is enabled, Nexus IQ for Jira will attempt to apply the selected Workflow Transition to issues when policy violations are successfully remediated. In order for the automated transition to be applied, the selected transition must be valid for the current ticket state and all other workflow requirements such as required fields must be met. Once the transition has been successfully applied, a comment will be created on the issue with a link to the latest Nexus IQ Server scan report. If the transition cannot be applied, Jira server logs will receive an entry with reason of 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 configured its communication with IQ 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 drop-down menu.
  3. Select the appropriate Webhook from the Select Webhook drop-down menu.
  4. Click Add to add the notification.
  5. Specify the stage(s) to create notification for (build, release, etc).

Review policy violation tickets within the Jira Server 

When Policy Violations are detected by the Nexus IQ server, new Jira issues will be created on the project board with the "New" status. 


The following Jira fields will be populated as follows:

  • Type: Corresponds to the selected Issue Type on the Nexus IQ Mapping page.

  • Priority: Nexus IQ Server Threat Level 10 is mapped to the highest Jira Priority and Threat Level 0 is mapped to the lowest Priority for the selected Jira project. If additional Jira Priorities are available, they will be assigned using a linear function.
    For example, given a set of 5 Jira priorities then the mapping between Threat level and Priority field value would be:

    Threat LevelJira Priority
    9-10blocker (1)
    7-8critical (2)
    4-6major (3)
    2-3minor (4)
    0-1trivial (5)
  • Labels: Corresponds to selected Label on the Nexus IQ Mapping page.
  • Reporter: Corresponds to selected Reporter on the Nexus IQ Mapping page.

Troubleshooting 

Supported and Unsupported field types

Default values are required for any mandatory fields in Jira. Supported fields are listed below. The unsupported field type will display a warning on the Nexus IQ Mapping page. The plugin will ignore the unsupported fields if they get marked as optional in Jira.

SupportedUnsupported
  • Float
  • Freetext
  • Textfield
  • URL
  • Version
  • Select
  • Multiselect
  • Radio
  • Labels
  • Date Picker
  • Date Time
  • Group Picker
  • Multi-Group Picker
  • Multi-User Picker
  • Project
  • Read-Only Text
  • User Picker
  • Cascading Select
  • Checkbox
  • Multi Checkboxes

Tips 

Confirm that all instructions are followed as described above.

Then, check for the following:

  1. Policy evaluation: Double-check the policy and make sure notifications are sent to the Jira IQ webhook.
    1. Nexus IQ for Jira remembers violations it has already seen to avoid the creation of duplicate issues. As a consequence, if the same scan is used multiple times for testing, nothing will happen as these violations have already been sent to Jira.
  2. Webhook configuration: Make sure the webhook URL configured on the Nexus IQ server matches the URL on the "Nexus IQ Configuration" page on Jira.
  3. Check the IQ configuration screen on Jira for error messages. The message box will display the status of the last webhook received from the Nexus IQ server. See the sample screenshot below for a misconfigured mapping from an IQ application to Jira project. Make sure at least one IQ Application or IQ Organization to be mapped to the project.

  1. Click the Test button on the Nexus IQ Configuration page on Jira. Note: The test button tests the connection from Jira to IQ, not from IQ to Jira.
  2. Check that the Violation Alerts are mapped to the correct Jira project on the 'Nexus IQ mapping' page in the Jira project settings.
  3. Check that the stage during which the violation was triggered matches a selected stage of the webhook used for the IQ Server notification.

Logging 

Error messages are sent to Jira's default log4j logger. Out-of-the-box Jira is configured to log messes of level WARN or higher to the log files. Log levels can be temporarily changed by navigating to 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:

PackageDescription
com.sonatype.jira.iq.data.service.WebhookService
Events in relation to Webhooks received from IQ server. Log levels used are INFO for success messages and ERROR for failures.
com.sonatype.jira.iq.data.service.ConfigurationService
Configuration errors are displayed directly in Jira's web interface. Currently, this is only used for logging internal errors with log level ERROR.
com.sonatype.jira.iq.data.service.IqClientImpl
Errors communicating with IQ server are logged with log level ERROR.
com.sonatype.jira.iq.data.service.PolicyAlertTrackingServiceImpl
Policy violations stored for de-duplication in Jira's local database as logged at DEBUG level.
com.sonatype.jira.iq.rest.IqIssueResource
HTTP messages are logged at DEBUG level.
com.sonatype.jira.iq.rest.AdminResource
User interactions in the 'Project settings' are logged at INFO level and failures at WARN level.
com.sonatype.jira.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.