Nexus IQ for Jira
Prioritize and track remediation of open source policy violations from Nexus IQ Server inside Jira
Nexus IQ for JIra is an Atlassian Jira plugin which helps automate the creation of Jira project issues in response to IQ Server application evaluation policy violation events.
Nexus IQ for Jira automatically creates Jira project issues when IQ Server application policies are violated.
How Does it Work?
After the Nexus IQ for Jira plugin is installed into Jira, a Jira administrator configures it with IQ Server credentials and verifies it can accept webhook requests from IQ Server.
Next, Jira Project Administrators map IQ applications and organizations to a Jira project issue creation fields.
Then IQ Server Policy Administrators identify and configure which application policies should trigger the creation of a Jira issues using the Jira webhook notification.
Finally when a new policy violation is triggered for an IQ application, issues are automatically created inside your Jira project to help track remediation of those violations.
Please ensure Nexus IQ for Jira minimum requirements are met before using this plugin.
Jira Plugin Installation
You can install Nexus IQ for Jira from the Atlassian Marketplace.
Configure connection of the Jira add-on with IQ Server
Configuration of the Nexus IQ for Jira add-on is performed at the global, Jira instance level.
- 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.
Configure mapping between a Jira project and an organization and/or application within IQ server
Configuration of the mapping is performed at the Jira project level. This configuration will be performed for each Jira project which is to have policy violation tickets created automatically.
- Navigate to the desired project within Jira
- Click on the "Project Settings" gear icon in the lower left of your screen.
- Click on the Nexus IQ menu option.
If an empty page is shown when clicking on the Nexus IQ link, make sure you are signed into Jira with a user that has Administer Project permissions for the project.
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.Now you can begin to configure the Jira to IQ mapping and also specify how you want the tickets to be created:
Issue Type: You have to select which type of Jira issue ticket you want to be created. Depending on the selected issue type, additional fields will be added to the form.
Issue Context: You can have one ticket created per-component, or one ticket created per application. If "per component" is selected, a sub-task is created for each component violation.
IQ Applications: Zero or more IQ applications which will trigger the creation of tickets for this Jira project
IQ Organizations: Zero or more IQ organizations which will trigger the creation of tickets for this Jira project
Labels: You can specify one or more Jira labels which will automatically be added to the tickets created. This can be used to query for these automatically created tickets later.
Reporter: Standard Jira field, add the Reporter who should be associated with the automatically created tickets
Note: You must have at least one application or organization specified to trigger the creation of policy violation tickets.
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.
Configure Jira notifications within IQ Server
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.