Jira tickets for findings

The gateway turns findings into tickets in your own Jira and keeps them in step with the findings: one ticket per finding, each linking back to the finding in ShakerScan, and a comment and a move to a done status when a retest proves the fix. It works with Jira Cloud and with Jira Data Center or Server.

Connect Jira (administrators)

Open Jira in the console. Under Connection:

1. Choose Jira Cloud or Jira Data Center or Server and enter the site address (https://your-company.atlassian.net, or https://jira.example.com/jira with its context path). The address must be HTTPS.

2. Enter the credential of the account the tickets are created as. A dedicated account is best:

   • Cloud: the account's e-mail address and an API token (id.atlassian.com, Security, API tokens).
   • Data Center: a personal access token (your Jira profile, Personal access tokens).

   The account needs Browse, Create issues, Add comments and Transition issues in the project.

3. Enter the project key (SEC) and the issue type (Bug by default).

4. Map each severity to a Jira priority by name, or leave one empty for no priority.

5. Optionally:

   • Extra labels for every ticket;
   • Fixed field values, as JSON with Jira field ids ({"components": [{"name": "Web"}]}, custom fields, versions, environment, due date, assignee, reporter, security level);
   • Finding values into custom fields, as JSON from a custom field id to severity, cvss_score, cwe, location, finding_link, target_id or finding_id;
   • the close transition by name. Left empty, the first transition into a done status is used;
   • whether to comment and to close when a retest proves the fix (both on by default);
   • how often to read the tickets' status back from Jira (every 15 minutes by default; 0 turns it off).

Check and save checks the token, the project and the issue type with Jira first, and saves nothing when Jira refuses. The token is stored encrypted with the installation key, is never shown again and is never logged. Leaving the token field empty when you change other settings keeps the saved token. Changing the site address or account needs the token again. Disconnect removes the token, and the tickets and their links stay.

Every connection change is in the audit log (jira.connect, jira.disconnect).

Create tickets

Operators and administrators create tickets. A viewer sees them.

• Console, Jira, Create tickets: paste finding ids or finding page links, one per line, up to 50 at a time. Or give a target id and a severity to file every open finding of that target at or above it, 50 per request.

• On a finding's page: the session menu (the round button at the bottom right) shows the finding's ticket, or Create Jira ticket, which opens the console with the finding filled in.

• From a terminal, with a token that acts for you:

  shakerscan api POST /_enterprise/jira/tickets '{"finding_ids": ["<finding id>"]}'
  shakerscan api POST /_enterprise/jira/tickets '{"target_id": "<target id>", "min_severity": "high"}'
  shakerscan api GET '/_enterprise/jira/tickets/<finding id>'
  

  A shared token that acts for nobody (CI, automation) cannot create tickets.

A finding never gets two tickets. A finding that already has one is answered with it. Each ticket carries the labels shakerscan and shakerscan-finding-<finding id>, and the gateway searches Jira for that label before it creates anything. So a ticket filed before a restore, or before a gateway rollback, is found again and linked, not filed twice. When Jira's answer to a create does not arrive (a timeout, a dropped connection), the gateway does not post again. It looks for the issue by its label until it appears, for up to ten minutes. If the issue never appears, the ticket is marked failed, and asking again searches before it creates.

What a ticket contains

• The summary [ShakerScan] <Severity>: <title> (<host>).
• Severity, CVSS, CWE, the location (scheme, host and path, with the query string and fragment dropped, since they can carry tokens) and when the finding was first seen.
• The scanner's description of the finding, as plain text.
• A link to the finding in ShakerScan, where the evidence, the request and response, and retest are.

A ticket never carries evidence, requests, responses, notes or cookies. Scanner-reported text is sent as plain text, so it cannot become a link, a mention or markup in Jira.

When a retest proves the fix

When a retest proves a finding fixed, the gateway:

1. adds a comment to the ticket saying so, with the time and a link to the finding;
2. moves the ticket to a done status, unless it is in one already.

Each step is recorded before it is sent and checked in Jira before a retry, so a comment is never posted twice. If Jira refuses (no transition into a done status from the ticket's current status for this account, say), the ticket's fixes show the reason under Jira, and the health card warns. While the licence is expired, these updates wait and are posted once a licence is installed.

Status from Jira

The Tickets list shows each ticket's Jira status, read back every 15 minutes (or on Sync now). Jira's status never changes a finding in ShakerScan. Closing a ticket in Jira does not mark the finding fixed: only a retest proves a fix. A ticket deleted in Jira shows "not found".

Backup, restore and rollback

The connection and the tickets are kept in the workflow state (workflow.sqlite3), which backup.sh already backs up and restore.sh restores (Recurring scans). The token is stored there encrypted with the installation key, which is in the encrypted identity backup. A restore that brings back both together keeps Jira connected. A workflow file restored without its identity backup keeps the tickets, but the health card asks an administrator to enter the token again. A gateway update that is rolled back keeps the tickets created during the update. A rollback to a gateway older than 0.2.0-beta.49, which has no Jira, leaves Jira unconnected after the next upgrade. Connect it again, and creating a ticket for a finding that already had one finds and links the existing issue by its label.

Limits

• One Jira site and one project per installation.
• HTTPS sites only.
• A ticket moved to another project, or a project renamed, gets a new key in Jira. The gateway keeps the key it recorded, and the status reads "not found" until the ticket is created again for the finding, which finds the moved issue by its label.
• Jira Cloud's search can take a few seconds to see a new issue. Two people creating a ticket for the same finding at the same moment get one ticket, because the gateway's own record is claimed first.