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 automates 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?
- The Nexus IQ for Jira plugin is installed into Jira as an application by the Jira administrator. The plugin is configured with the appropriate Nexus IQ Server URL and credentials. This enables the plugin to accept webhook requests from the Nexus IQ Server.
- Within Jira, Jira Project Administrators will associate a Jira project with specific Nexus IQ applications and/or organizations. They also have the ability to define specific field mappings and default values.
- Within Nexus IQ Server, the 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 application policy violation is identified by Nexus IQ for a configured application, issue tickets will be automatically created for 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 and Configuration
The initial installation and configuration of the plugin is done once and will apply to all Jira projects. This simply enables the integration of Jira and Nexus IQ Server.
Install Nexus IQ for Jira from the Atlassian Marketplace
Configure connection of the Jira plugin with your Nexus IQ Server
Configuration of the Nexus IQ for Jira plugin 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.
Associate a Jira project with one or more organizations/applications within Nexus IQ Server
Nexus IQ organization/applications are associated with a specific Jira project. You must perform the steps below for each Jira project which will receive policy violation notifications from Nexus IQ Server.
Configure mapping between a Jira project and an organization and/or application within IQ server
- 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 Nexus IQ Server to send policy violation notifications to Jira
Configure each desired IQ Server policy to send violation notification to Jira using the webhook associated with your Jira instance
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 plugin and configured its communication with IQ Server via a webhook (see above).
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 appropriate Webhook from the Select Webhook drop-down menu.
- Click Add to add the notification.
Once you have created the notification, you can then specify at which stage(s) you would like to be notified (build, release, etc.)
Review policy violation tickets within your Jira server
Policy violation issues are created on your project board with a "New" status.
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 your field type is not supported you can mark the field as optional in Jira and the plugin will ignore it. If you use an unsupported 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.
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. You can temporarily change log levels by visiting the System → Logging and profiling tab on the Jira administration page. To make log changes permanent or for advanced log4j settings you will need to edit 'WEB-INF/classes/log4j.properties'.
You can customize logging of the Jira plugin further by customizing the following log levels:
|Events in relation to Webhooks received from IQ server. Log levels used are INFO for success messages and ERROR for failures.|
|Configuration errors are displayed directly in Jira's web interface. Currently, this is only used for logging internal errors with log level ERROR.|
|Errors communicating with IQ server are logged with log level ERROR.|
|Policy violations stored for de-duplication in Jira's local database as logged at DEBUG level.|
|HTTP messages are logged at DEBUG level.|
|User interactions in the 'Project settings' are logged at INFO level and failures at WARN level.|