Nexus IQ for Jira
Nexus IQ for Jira
How to create Jira issues for policy violations using the Nexus IQ for Jira add-on
Install Nexus IQ for Jira
Get it from the Atlassian Marketplace: https://marketplace.atlassian.com/apps/1220548/nexus-iq-for-jira?hosting=server&tab=overview
Jira notifications are only available if the Nexus IQ for Jira add-on is installed and configured to communicate with IQ Server via a webhook. See the sections below for more information.
Configure connection of the Jira add-on with IQ Server
- At Jira, choose the cog icon at the top right corner.
- Select Applications from the pop-up menu.
- Select IQ Jira Plugin. The Nexus IQ Configuration page shows up.
- Set the IQ Server configuration parameters.
- Click the Test button to confirm that a connection can be established.
- Click the Save button to save the configuration.
Set up an IQ Server webhook
You can use the `Create webhook` button on the Nexus IQ Configuration page (see screenshot above) to automatically create and configure a webhook on IQ server. You need to 'Test' your connection before this option becomes available. Tip: The 'Create webhook' button uses the username and password directly from the form to authenticate with IQ server, not the saved credentials. This allows you to configure Nexus IQ for Jira with a limited "service account", but use your admin credentials to create the webhook. Pressing the 'Create webhook' button does not save the credentials in the Jira configuration, only the 'Save' button does.
Alternatively you can 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.
Map a Jira project to an IQ organization and/or application
First, you have to select which type of Jira issue you want to create. Depending on the selected issue type additional fields will be added to the form.
A Jira project can be mapped to one or more IQ organization and/or applications. When a new violation occurs that corresponds to these IQ organizations or applications a new Jira issue is created.
If the Issue context 'per component' is selected, a sub-task is created for each component violation.
At the bottom of the form you can find a list of custom fields and provide default values (e.g. the 'Reporter' field in the screenshot below). A custom field must be marked as required in Jira to be displayed in this list.
Once the mapping has been configured a Jira issue will be created when new policy violations occur.
Set up Jira notifications
The Jira notification will create a Jira issue when new policy violations are discovered during the development process. To create Jira notifications, you must have already installed the Jira add-on and configured its communication with IQ Server via a webhook.
To configure Jira notifications:
- Select the Policy for which you will be notified when that policy is violated.
- Select Webhook from the Recipient Type drop-down menu.
- Select the Webhook from the Select Webhook drop-down menu.
- Click Add to add the notification.
Once you have created the notification, you can then choose at which stage(s) you would like to be notified.
View Violations received from Nexus IQ Server
When Policy Violations are detected by IQ server then new Jira issues will be created.
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 configured for the selected Jira project and Threat Level 0 is mapped to the lowest Priority. If additional Jira Priorities are available they are assigned accordingly.
- Labels: Can be configured on the Nexus IQ Mapping page.
- Reporter: Can be configured on the Nexus IQ Mapping page.
Supported and Unsupported field types
If you use mandatory fields in Jira you have to provide default values. Currently not all types of files are supported.
If you field type is not supported you can mark the field as optional in Jira and the plugin will ignore it. If you use an unspported field type you will see a warning on the `Nexus IQ Mapping` page.
Please double check you have followed the instructions above. In addition you can perform the following checks:
- Policy evaluation: Please double check the policy and make sure that notifications are sent to the Jira IQ webhook.
- Nexus IQ for Jira remembers violations it has already seen to avoid creation of duplicate issues. As a consequence if you perform the same scan again and again for test purposes nothing will happen if these violations have already been sent to Jira before.
- Webhook configuration: Please make sure the webhook URL configured on IQ server matches the URL on the 'Nexus IQ Configuration' page on Jira.
- Check the IQ configuration screen on Jira for error messages. The message box will display the status of the last webhook received from IQ server. Below you can see an example of a misconfigured mapping from an IQ application to Jira project. (You have to choose at least one IQ Application or IQ Organisation to be mapped to this project.)
- Press the 'Test' button on the 'Nexus IQ Configuration' page on Jira. Note: This currently only tests the connection from Jira to IQ, but not from IQ to Jira.
- Double check that the Violation Alerts are mapped to the correct Jira project on the 'Nexus IQ mapping' page in the Jira project settings.
- Double check that the stage during which the violation was triggered matches a selected stage of the webhook used for the IQ Server notification.