The integration with Jira currently requires the URL of a Jira server that accepts inbound communication from the Rapid7 Insight platform and an account with the following permissions:
- Browse projects
- View read-only workflow
- Assignable user
- Create issues
- Assign issues
- Edit issues
- Close issues
- Delete issues (optional)
- Modify reporter
- Set issue security
- Add comments
For Jira Cloud, the account will need to have the
atlassian-addons-project-access role for the integration to work.
The minimum permissions above allow you to create a connection, but you must be aware of other fields required to create a ticket. If the account does not have access to a required field you may not be able to save field mappings correctly.
If your Jira instance is configured with firewall rules, see Configure communications with the Insight Platform for current static IP addresses for the Insight Platform.
Creating a new Jira ticketing connection for your Remediation Projects
- Click the Projects tab.
- On the "Remediation Projects" page, click Add a ticketing connection.
- On the "Ticketing Connection Settings" view, click the Jira Software ticketing option in the ticketing area.
This starts the Jira connection configuration wizard.
- Give your ticketing connection a name.
- This name will be used to identify the connection on your "Settings" page in InsightVM.
- In the "URL" field, enter the URL of your Jira server.
- In the "Username / Email" field, enter the email address that corresponds to the Jira account you want to use for authentication.
NOTE - Email address requirement
Jira Cloud requires an email address in this field in order to authenticate. Additionally, note that this integration only supports basic authentication to your Jira instance. Single sign-on (SSO) authentication is not supported.
- In the Password/Token field, enter your password in the Password field if you’re using JIRA on-prem. If you’re using JIRA Cloud, enter the API token in the Token field provided by your Jira Cloud account.
NOTE - API token requirement
Jira Cloud requires an API access token in this field in order to authenticate. To obtain a token for your Jira Cloud instance, follow these steps:
- Go to id.atlassian.com and log in.
- In the "Helpful links" section, click Manage profile.
- Click Security in your left navigation menu.
- In the "API token" section, click Create and manage API tokens.
- Click the Create API token button to generate your token.
- Click Save and Continue when ready.
- Click Solution Status Mapping to map one or more Jira issue statuses to one of the following Remediation Project statuses. JIRA status updates will trigger the remediation solution status to update to one of the following, depending on mapping:
- Awaiting Verification - The remediator has taken action to mitigate the vulnerability and is now awaiting verification, the vulnerability no longer exists, or the remediation failed.
- Will Not Fix - The item cannot be remediated.
Changing the status of a Jira ticket can change the status of a remediation solution, but changing the solution status will not change a Jira ticket's status. If a remediation solution has multiple tickets with different solution statuses, tickets with “Awaiting verification” status will be prioritized first.
For example, imagine that a remediation solution has 2 tickets, A and B. The status mapped to Awaiting Verification field is “Done,” while the status mapped to the Will Not Fix field is “In Progress.” If the status of Ticket A is set to “Done,” and the status of Ticket B is set to “Canceled,” then the remediation solution status is set to “Awaiting verification,” because an employee needs to verify the status of Ticket A.
- Click Save. The ticketing template wizard opens to the Ticketing Connection page. The ticketing template wizard has three pages:
Complete the Ticketing Connection page to select the Jira project for automated ticketing and the type of work item that you want to create, e.g Task. The available Issue Types are based on the Project Name that you select. Click Next to continue to the Ticketing Project and Field Mapping page.
Assignee field needs to be visible in JIRA
The Assignee field needs to be visible in JIRA in order to create tickets successfully.
Complete the Ticketing Project and Field Mapping page to draft a template of the ticket that you generate from your Remediation Project. You can configure how concise or detailed you want the summary and description to be with variables for information, such as a solution name ($SOL_NAME), asset list ($ASSET_NAME_LIST), and other data related to your vulnerability scans.
Click the Syntax Help button to open a dictionary that lists all of the supported placeholders.
Delete issues permission is optional
If you omit the delete issues permission, the test ticket that is created when you save field mapping to check your permissions for your selected project cannot be deleted through ticketing integration but can be deleted in JIRA.
Click Next to continue to the Assignment Rules page.
Complete the Assignment Rules page to create rules for assigning automatically generated tickets to your team based on factors like the ownership of assets and expertise of the assignees. The list of rules is ordered by preference. Every ticket is assigned based on the first rule whose asset filter conditions are satisfied. If no rule is matched, the incident is assigned to the Default Assignee. Click on the +New Rule button to create additional rules.
- When you are done creating all of the necessary rules, click Save to exit from the ticketing wizard.
Editing a ticketing connection for Remediation Projects
To edit a ticketing connection:
- Click the Management tab.
- Click Edit for the ticketing connection that you want to edit.
- Edit the Connection Settings, Solution Status, and Configuration pages as necessary.