Setup Canopy and Jira

Owned by Dave Ryan
Last updated: Dec 20, 2018

Canopy integration with Jira has been tested on Jira cloud and Jira. However, custom deployments may require adaptations to the process described below.

Why Jira?

What we typically see in the pentest and security assessment process is that the end product is a PDF document, and possibly a XLSX. This pushes the responsibility onto the "client" (or recipient of that data) to move it into other systems so people can use it - in some cases, the XLSX is the "system" in use, which makes tracking and correctly resolving security issues difficult.

We believe that Canopy should be a cog in the overall process of helping users manage their security. Jira is one of the most common ticketing systems in use, and so it makes sense that Canopy should support integration to help the data flow more easily from security assessments to the developers, IT operations teams and others who need it.

Jira support in Canopy

Canopy supports the following:

  • Support for connecting to one or multiple Jira instances
  • Creating Jira tickets from Canopy findings
  • Linking Canopy findings to an existing Jira ticket
  • Creating findings as sub-tasks on existing Jira tickets
  • Link to Jira issue from Canopy for easy navigation.
  • Field mapping between Canopy and Jira

It is currently not possible to receive notifications from Jira when an issue's status has been updated on when any other changes on the Jira side occur, or to push updated information from Canopy to Jira, if the content has been changed in Canopy. Also, Jira is responsible for content management on its side. 

In 2019 (Q1 and Q2), CheckSec will be working on further integration with Jira, including support for Jira webhooks to facilitate bi-directional communication between Jira and Canopy - e.g. for status updates, comments, and so on.

Jira and Canopy setup

Getting a token from Jira

Connecting to Jira requires a token. Jira supports oauth. To obtain a token and set up Canopy on your Jira system, please follow these steps:

https://developer.atlassian.com/cloud/jira/platform/jira-rest-api-oauth-authentication/

The steps relating to Canopy are summarised here:

  1. openssl genrsa -out privkey.pem 2048
  2. openssl rsa -pubout -in privkey.pem -out pubkey.pem
  3. Add an application link to Jira(Incoming Auth) using the value from pubkey.pem as the public key
  4. jirashell -s https://checksec.atlassian.net -od -ck THE_CONSUMER_KEY_SET_IN_JIRA -k privkey.pem -pt
  5. Authenticate as the user that Canopy will use via the URL provided by jirashell

The access_token and access_token_secret will be used for configuring the Jira integration in Canopy.

Adding a Jira instance to Canopy

Connecting Jira and Canopy is currently an admin task and is performed under the Admin → Ticket Trackers section of Canopy. Navigating to that section provides the option to create a new Ticket Tracker and to view/edit existing ones:

Clicking the + TRACKER button shows the Add tracker window, which allows you to set the following fields for each Ticket Tracker:

  • Name: a name used to reference the ticket tracker.
  • Tracker type: the type of ticketing system we're connecting to.
  • Server URL: the full URL for connecting to the ticketing system.
  • Verify certificates: allows administrators to turn on/off TLS certificate validation (turn it off to allow for self-signed certificate - not recommended, but may be required in certain environments).
  • CA certificate path (optional): allows one to specify a custom CA path for certificate verification.
  • Client certificate path (optional) : the path to the client certificate on the operating system (e.g. /etc/ssl/certs/mycert.crt). Note that the key must be accessible by Canopy (file permissions).
  • Client certificate key path (optional): the path to the client secret key on the operating system (e.g. /etc/ssl/keys/mykey.key). Note that the key must be accessible by Canopy (file permissions).

Jira is the only type of Ticket Tracker supported at the moment. Support for Service Now will be added in Q1 2019.

Authenticating to Jira

Below the main fields, one can configure the authentication options:

  • None: No authentication is required.
  • Basic auth: username and password.
  • OAuth: using the access tokens obtained above.

The following section appears at the end of the Ticket Tracker add/edit screen. Select the authentication type required and fill in the values:

The token and key information was obtained in the section above.

Checking configurations and access

If you need to check the configuration and access to a Ticket Tracker, select the Ticket Tracker and click on the info icon in the menu bar:

Deleting Ticket Trackers

A Ticket Tracker can be deleted by selecting the ticket tracker and deleting it using the delete icon.

Working with Jira

Once the administrative side is set up, users can now work with Jira. For further information, see: Working with Jira