Nullgap.dev Docs

Integrations

Jira

File findings as Jira issues and keep the issue's status and the finding's state in step in both directions.

With Jira connected you can file a finding as an issue in one Jira project, and Nullgap keeps the two in step: closing the finding moves the issue to done, and closing the issue in Jira marks the finding fixed.

Nullgap works with Jira Cloud sites, that is addresses ending in .atlassian.net. One Jira site and one project can be connected per organisation.

#Connect Jira

You need to be an admin or owner in Nullgap, and you need a Jira account that can create issues in the project, with an API token for that account.

  1. Open Integrations. Under Issue tracking, choose Connect next to Jira.
  2. Fill in the fields and save.
FieldAPI nameWhat to enter
Site addressbaseUrlYour Jira site, for example https://your-team.atlassian.net. Must be https and end in .atlassian.net.
Account emailemailThe e-mail address of the Jira account the token belongs to. Issues and comments are created as this account.
API tokenapiTokenAn API token of that account.
Project keyprojectKeyThe short code in front of issue numbers, such as SEC in SEC-12. The project's name is accepted too when it matches exactly one project.

Nullgap asks Jira before it stores anything: it checks that the e-mail and token are accepted and that the account can see the project. If either fails, nothing is saved and you see Jira's reason (400 with the code tracker_rejected, or tracker_unreachable when Jira could not be reached).

The credentials are stored encrypted and are never shown again, in the console or through the API. Replace saves new ones; Disconnect deletes them.

Through the API (admin key):

curl -s -X PUT -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config":{"baseUrl":"https://acme.atlassian.net","email":"dana@acme.example","apiToken":"YOUR_JIRA_API_TOKEN","projectKey":"SEC"}}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/jira"

The answer:

{
  "kind": "jira",
  "connected": true,
  "label": "SEC",
  "needsReconnect": false,
  "statusSync": { "enabled": true, "webhookUrl": "https://nullgap.example/webhooks/jira/jhk_..." },
  "webhookSecret": "..."
}

webhookSecret is in this answer once, the first time Jira is connected. See the inbound webhook.

#File a finding as an issue

Open a finding and choose Create Jira issue. Any member can do this; through the API it needs a key with the write scope:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tracker":"jira"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_123/issue"

The answer is the finding, with the issue's address in externalIssueUrl.

The issue is created in the connected project with:

PartContent
SummaryThe severity in square brackets and the finding's title, for example [HIGH] SQL injection in order lookup.
TypeBug.
PriorityCritical is Highest, high is High, medium is Medium, low is Low, info is Lowest.
Labelssecurity and nullgap.
DescriptionA one-line statement of the impact, the finding's description, its severity, repository, file and line, weakness ids, pull request number and verification status, the remediation advice, and a link back to the finding in Nullgap (Open in Nullgap).

Things to know:

  • A finding has one issue link. Filing it again returns the finding unchanged and creates nothing, whichever tracker the existing link belongs to.
  • If the project's create screen has no priority or labels field, Jira refuses them. Nullgap then creates the issue once more with only the summary, type and description.
  • If Jira refuses the issue (the token was revoked, the project needs a field Nullgap does not send), no link is stored and you get 400 with the code tracker_rejected and Jira's own reason.
  • If Jira is not connected the answer is 400 with the code not_connected.

#Status sync

Status sync is on for a newly connected Jira. Switch it with Keep finding and issue status in step on the Jira row, or through the API (admin key):

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"statusSync":false}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/jira"

It applies only to findings whose issue link points to an issue on the connected Jira site.

#From Nullgap to Jira

When a linked finding changes state, whoever or whatever changed it (a person, an API key, a retest, a later review that no longer finds the code):

  1. The issue gets a comment: "Nullgap: this finding was marked as fixed by dana@acme.example." followed by the reason when one was given. The other wordings are "marked as a false positive", "accepted as a risk" and "reopened".
  2. The issue's status moves:
Finding changesIssue moves to
From open to fixed, false positive or accepted riskA status in Jira's "done" group
Back to openA status in Jira's "to do" group
From one closed state to another (fixed to false positive)Nowhere. Only the comment is added.

Jira sorts every status into a to-do, in-progress or done group, whatever your team has named it; Nullgap goes by that group. It asks Jira which steps the issue's workflow offers from where it is and takes the first that leads into the right group. An issue already in the right group is left where it is.

This needs nothing set up in Jira beyond the connection.

#From Jira to Nullgap

This direction needs a webhook in Jira (next section). Once it exists:

In JiraIn Nullgap
The issue moves into a status in the done groupEvery open finding linked to it is marked fixed, with the reason "Closed in Jira SEC-12".
The issue moves from a done status back to a to-do or in-progress statusEvery closed finding linked to it is reopened, with the reason "Reopened in Jira SEC-12". This includes a finding that was closed in Nullgap as a false positive or accepted risk.
The issue moves between statuses in the same group, or between to do and in progressNothing.
Anything else (comments, edits, other issues)Nothing.

A change that came from Jira is not sent back to Jira, and Jira's report of a move Nullgap made itself is recognised and dropped, so the two never chase each other.

#Set up the webhook in Jira

You need the Webhook URL and the Secret from the Jira row on the Integrations page. The secret is shown once, when Jira is first connected; if you did not copy it, choose Generate a new secret.

  1. In Jira, open Settings (the cog), then System, then WebHooks, and choose Create a WebHook. This needs a Jira administrator.
  2. Paste the URL into URL and the secret into Secret.
  3. Under Issue related events, tick Issue: updated. Nothing else is needed.
  4. Optional: limit it to the connected project with the filter project = SEC (your project key), so Jira sends only what matters here.
  5. Create the webhook.

Jira signs each call with the secret (the X-Hub-Signature header, an HMAC-SHA256 of the exact body). Nullgap answers 401 to a call without a valid signature, and gives the same answer for an address that does not exist.

#The secret and rotation

  • The webhook secret is returned once: in the answer to the first connection, and again each time you rotate it. It is stored encrypted and cannot be read back.
  • Generate a new secret on the Jira row, or the call below (admin key), replaces it. The webhook URL stays the same. Calls signed with the old secret are refused from that moment, so paste the new secret into the webhook in Jira straight away.
  • Saving new Jira credentials with Replace keeps the webhook URL and secret.
  • Disconnect deletes the credentials, the URL and the secret. Connecting again gives a new URL and a new secret; update or recreate the webhook in Jira.
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/jira/webhook-secret"

#What is recorded in the audit log

ActionWhenDetail
integration.connectedJira was connected or its credentials replacedjira
integration.disconnectedJira was disconnectedjira
integration.status_sync_on, integration.status_sync_offStatus sync was switchedjira
integration.webhook_secret_rotatedA new webhook secret was generatedjira
finding.issue_createdA finding was filed as an issueThe finding's title and jira
finding.issue_updatedNullgap commented on or moved a linked issueFor example "Jira SEC-12: commented, moved to done"
finding.patched, finding.openA finding was closed or reopened from JiraThe actor is Jira; the reason names the issue

See the audit log for how to read and export it.

#When something fails

Jira being slow, down or strict never blocks a change in Nullgap. The finding changes state first; the comment and the move happen afterwards.

What happenedWhat you see
The comment could not be addedThe move is still tried. The audit entry lists only what succeeded.
The issue's workflow offers no step into the right group, or Jira refused every step (for example a step whose screen has a required field)The comment is added and the status is left alone. The audit entry reads "no step to done is available in its workflow, status left as it was". Nullgap tries at most three steps.
Jira could not be reached for the moveThe audit entry reads "status change failed". It is not tried again; move the issue by hand.
The stored credentials can no longer be readThe Jira row shows Needs reconnecting. Enter the credentials again. Until then nothing is sent to Jira and events from Jira are not applied.
Nullgap could not apply an event from JiraIt answers 500, which makes Jira send the event again later.
Status sync is offEvents from Jira are accepted and ignored. Nothing is sent to Jira. Filing issues still works.

#What Nullgap does not do

  • It does not sync fields other than status: no assignee, priority, due date or comment sync after the issue is created.
  • It does not create issues on its own. A person or an API call files each one.
  • It does not delete or close issues when Jira is disconnected.
  • It does not work with Jira sites outside .atlassian.net.

The routes are listed in the integrations reference.

Nullgap documentation