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.
- Open Integrations. Under Issue tracking, choose Connect next to Jira.
- Fill in the fields and save.
| Field | API name | What to enter |
|---|---|---|
| Site address | baseUrl | Your Jira site, for example https://your-team.atlassian.net. Must be https and end in .atlassian.net. |
| Account email | email | The e-mail address of the Jira account the token belongs to. Issues and comments are created as this account. |
| API token | apiToken | An API token of that account. |
| Project key | projectKey | The 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:
| Part | Content |
|---|---|
| Summary | The severity in square brackets and the finding's title, for example [HIGH] SQL injection in order lookup. |
| Type | Bug. |
| Priority | Critical is Highest, high is High, medium is Medium, low is Low, info is Lowest. |
| Labels | security and nullgap. |
| Description | A 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
400with the codetracker_rejectedand Jira's own reason. - If Jira is not connected the answer is
400with the codenot_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):
- 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".
- The issue's status moves:
| Finding changes | Issue moves to |
|---|---|
| From open to fixed, false positive or accepted risk | A status in Jira's "done" group |
| Back to open | A 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 Jira | In Nullgap |
|---|---|
| The issue moves into a status in the done group | Every 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 status | Every 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 progress | Nothing. |
| 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.
- In Jira, open Settings (the cog), then System, then WebHooks, and choose Create a WebHook. This needs a Jira administrator.
- Paste the URL into URL and the secret into Secret.
- Under Issue related events, tick Issue: updated. Nothing else is needed.
- Optional: limit it to the connected project with the filter
project = SEC(your project key), so Jira sends only what matters here. - 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
| Action | When | Detail |
|---|---|---|
integration.connected | Jira was connected or its credentials replaced | jira |
integration.disconnected | Jira was disconnected | jira |
integration.status_sync_on, integration.status_sync_off | Status sync was switched | jira |
integration.webhook_secret_rotated | A new webhook secret was generated | jira |
finding.issue_created | A finding was filed as an issue | The finding's title and jira |
finding.issue_updated | Nullgap commented on or moved a linked issue | For example "Jira SEC-12: commented, moved to done" |
finding.patched, finding.open | A finding was closed or reopened from Jira | The 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 happened | What you see |
|---|---|
| The comment could not be added | The 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 move | The audit entry reads "status change failed". It is not tried again; move the issue by hand. |
| The stored credentials can no longer be read | The 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 Jira | It answers 500, which makes Jira send the event again later. |
| Status sync is off | Events 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