Nullgap.dev Docs

Integrations

Slack

Send run updates to a Slack channel, and ask about, start and triage security work from Slack with the /nullgap command or by asking Nullgap AI.

Nullgap works with Slack in two separate ways. They are set up separately and you can use either or both.

What it doesHow it connects
Channel notificationsPosts a message to one channel when a review finds something, a pentest finishes or a fix run finishes.A Slack incoming-webhook URL that you paste into Nullgap.
Slack assistantThe /nullgap slash command (list findings, triage, see and start pentests, reviews and fixes), and answers by Nullgap AI when someone mentions @Nullgap or sends it a direct message.A Slack app you create in your own workspace from a manifest Nullgap gives you.

Both are on the Integrations page of the console.

#Channel notifications

#Connect a channel

You need to be an admin or owner of the organisation.

  1. In Slack, create an incoming webhook for the channel that should receive the messages, and copy its URL. It starts with https://hooks.slack.com/services/.
  2. In Nullgap, open Integrations. Under Notifications, choose Connect next to Slack.
  3. Paste the URL into Incoming webhook URL. Channel name is optional and for display only: the channel is decided by the webhook, not by this field.
  4. Save. The row now reads "Connected".

The URL is stored encrypted and is never shown again, in the console or through the API. To change the channel, choose Replace and paste a new URL. Disconnect deletes the stored URL.

The same can be done through the API with an admin key:

curl -s -X PUT -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config":{"webhookUrl":"https://hooks.slack.com/services/T0000/B0000/XXXXXXXX","channel":"#security-alerts"}}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/slack"

Only a https://hooks.slack.com/services/... address is accepted; anything else is refused with 400. See the integrations reference.

#What is posted and when

WhenMessage
A pull request review finishes and reported at least one finding that is still openThe repository and pull request number, the pull request's title and author, the number of findings by severity, and up to five findings as severity, title and file with line.
A pentest finishesThe repository, the revision tested, the number of lines in scope, the number of findings by severity and up to five finding titles. Sent even when there are no findings.
A fix run for a finding finishesThe repository, the finding's severity and title, and the outcome: a verified fix is ready, a fix was proposed but not proven (a draft for a person to review, when the automation allows unproven fixes), no change was needed, the finding turned out to be a false positive, or no verified fix was produced. Links to the pull request when there is one (a draft pull request for an unproven fix).

Things to know:

  • A review that reports nothing posts nothing.
  • A fix run started by an automation posts only if that automation has Post to the connected Slack channel ticked. A fix run you start by hand always posts.
  • A dependency fix run, a review or pentest that fails, and a fix run that is stopped by an error post nothing. Use outbound webhooks if you need those.
  • A message that Slack refuses is not sent again and there is no delivery log for channel notifications. The run itself is not affected.

#What is never posted

Source code, finding descriptions, proof, remediation advice and credentials are never sent to the channel. Text that comes from your repositories (titles, file paths, branch names) is escaped, and Slack mention and link syntax is removed from it, so a pull request title cannot ping @channel or plant a link.

#Slack assistant

The assistant has two parts:

  • The /nullgap command is a fixed set of commands. No AI is involved, and every answer is visible only to the person who ran the command.
  • Ask Nullgap is optional and needs the app's bot token. Mention @Nullgap in a channel it was invited to, or send it a direct message, and Nullgap AI answers in a thread under your question. See Ask Nullgap in Slack.

#Before you start

  • You are an owner of the Nullgap organisation. Setting up, replacing the secret and removing the assistant are owner actions done in the console; an API key cannot do them. If your account has multi-factor sign-in, you are asked for a fresh code.
  • You may create apps in your Slack workspace.

#Set it up

  1. In Nullgap, open Integrations and find the Slack assistant card. Choose Set up. The card now shows what belongs to your organisation only: App manifest (JSON), Slash command request URL, Interactivity request URL and Event Subscriptions request URL.
  2. In Slack's app management pages, create a new app from a manifest and pick your workspace.
  3. Paste the manifest from the card (it is JSON) and create the app. The manifest adds the slash command /nullgap with its request URL, switches on interactivity with its request URL (this is what makes the buttons work), subscribes to the bot events app_mention and message.im with the events request URL, turns on the App Home messages tab, and asks for the bot scopes commands, chat:write, app_mentions:read and im:history. These let the app read only messages that mention it or are sent to it directly.
  4. Install the app to your workspace.
  5. In the Slack app's Basic Information page, under App Credentials, show the Signing Secret and copy it.
  6. Back in Nullgap, paste it into Signing secret and connect. The card reads "Connected".

If you would rather configure the Slack app by hand, create a slash command /nullgap and switch on interactivity, and give each the matching request URL from the card.

#Switch on Ask Nullgap

  1. In the Slack app's OAuth & Permissions page, copy the Bot User OAuth Token. It starts with xoxb-.
  2. On the card, paste it into Bot token and connect. Nullgap asks Slack which workspace the token belongs to and from then on accepts events from that workspace only. A token Slack does not accept is refused.
  3. In the Slack app's Event Subscriptions page, check that the request URL is verified. Slack checks it when the app is created, before Nullgap has the signing secret, so you may need to choose Retry. The card shows Events connected once Slack has reached Nullgap.
  4. Invite @Nullgap to the channels where your team should be able to ask it. Direct messages work without that.

The bot token is stored encrypted, never shown again and never returned by the API. Switch off deletes it; the /nullgap command keeps working. Saving and removing it are owner actions and are recorded in the audit log.

If you created your Slack app before Ask Nullgap was available, open its App Manifest page in Slack, replace the manifest with the one on the card, save, reinstall the app when Slack asks, then follow the steps above. The request URLs stay the same.

#The signing secret

Slack signs every request it sends with the app's signing secret. Nullgap checks that signature (X-Slack-Signature, an HMAC-SHA256 over the timestamp and the exact request body) on every command and every button press, and refuses a request whose timestamp is more than five minutes from its own clock. A request that fails either check gets 401, the same answer as a request to an address that does not exist.

  • The secret is stored encrypted and never shown again.
  • It must be 16 to 128 letters and digits, as Slack shows it. Anything else is refused as a paste of something else.
  • Replace: regenerate the signing secret in the Slack app, then choose Replace signing secret on the card and paste the new one. Requests signed with the old secret are refused from that moment. The request URLs stay the same.
  • Remove: choose Remove on the card. The command and Ask Nullgap stop working, the stored secret and bot token are deleted and every person's Slack link is removed. Delete the Slack app in Slack as well. Setting the assistant up again gives new request URLs. Channel notifications are not affected.

A Slack user is nobody to Nullgap until they have linked their account. Until then every command answers with instructions and shows nothing about the organisation.

  1. In Slack, run /nullgap link.
  2. Open the link in the reply. Sign in to Nullgap if asked.
  3. Check that the page names your Slack user, then choose Yes, this is me.

The link works once, for ten minutes, and only for a signed-in member of the organisation. Asking again withdraws the earlier link. Only confirm a link you asked for yourself: whoever confirms it lets that Slack user act as them.

  • /nullgap unlink undoes it.
  • Your role is looked up again on every command and every button press. If your role is lowered or you are removed from the organisation, that takes effect in Slack at once: a link that belongs to someone who is no longer a member gives nothing.
  • Linking and unlinking are recorded in the audit log.

#Commands

CommandWhat it doesWho
/nullgap helpLists the commands.Linked members
/nullgap findingsThe most severe open findings, at most ten: severity, title, repository, file and line, the finding's id, and a link to it in the console.Linked members
/nullgap finding <id>One finding: severity, title, repository, file and line, state, who found it and when, with triage buttons.Linked members
/nullgap pentestsThe latest five pentests: repository, revision, status, number of findings when completed, date.Linked members
/nullgap pentest estimate <repository>The size of the default branch and what a pentest of it would be charged. Starts nothing.Linked members
/nullgap pentest start <repository>Shows the price and a Confirm button; on confirm, starts the pentest.Admins and owners
/nullgap review <repository> <pull request number>Shows the pull request and a Confirm button; on confirm, requests a review of its latest commit, as Review in the console does.Linked members
/nullgap fix <id>Shows the finding and a Confirm button; on confirm, starts a verified fix run that opens a pull request. When the finding was already decided (accepted risk, false positive, fixed) it says so first, and confirming starts the fix anyway. Uses automation credits.Linked members
/nullgap overviewOpen findings by severity, mean days to resolve over the last 30 days, and overdue counts.Linked members
/nullgap linkStarts linking your Slack user.Anyone in the workspace
/nullgap unlinkRemoves your link.Linked members

/nullgap findings takes two optional words, in this order: a severity (critical, high, medium, low or info) and a repository, for example /nullgap findings high acme/shop.

<repository> is owner/name, or just name when only one connected repository has that name. The finding id is the one /nullgap findings shows.

A command that takes longer than two seconds (an estimate has to read the repository) first answers "Working on it" and then posts the result in the same place.

#Triage from Slack

/nullgap finding <id> offers the changes that would do something: Accept risk, False positive and Reopen. Pressing one asks you to confirm. Accepting a risk and marking a false positive need a reason, as in the console; without one nothing changes and you are asked again. The change is the same one the console makes: it is written to the audit log under your name with "via Slack", it is sent to your outbound webhooks, it updates a linked Jira issue, and a false positive or accepted risk is remembered for later runs.

#Starting a pentest from Slack

/nullgap pentest start goes through the same checks as the console: the workspace must not be suspended or over its usage limit, and the pentest is charged the same way. The Confirm button works once, for ten minutes, and only for the person it was shown to. The price shown is a ceiling: if the codebase grew in the meantime, the pentest is not started and you are asked to run the command again.

A pentest started from Slack tests the whole repository on its default branch.

#Ask Nullgap in Slack

With the bot token saved, a linked member can mention @Nullgap or send it a direct message and ask in their own words, for example:

  • "what are the open critical findings in shop?"
  • "what did the last pentest of payments find?"
  • "how much would a pentest of acme/api cost?"
  • "review pull request 42 in acme/shop"
  • "start a fix for fnd_41d496a94e8b"

Nullgap AI answers in a thread under the question (in a direct message, in place). An answer in a channel can be read by everyone in that channel, as your question can: ask in a direct message when the channel should not see the answer.

  • It answers as you. Everything it looks up runs inside your organisation with the role you have right now. A Slack user who has not linked an account gets the linking instructions and nothing else. A suspended workspace, or a link that no longer meets your organisation's sign-in rules, is refused as for the command.
  • What it can see: the overview, findings (title, severity, state, repository, file and line, a short description), pentests, pull request reviews, repositories and pentest prices. Never source code, proof details or patches: it points you to the console for those.
  • It never acts on its own. Starting a pentest, reviewing a pull request, starting a fix and changing a finding's state are only offered. The reply carries a Confirm button that works once, for ten minutes, and only for the person who asked; anyone else who presses it is told so and nothing happens. The click goes through the same checks as the console: pentests need an admin and never cost more than the price shown, a fix on an already decided finding says so first, and accepting a risk or marking a false positive needs a reason you can edit. Everything done this way is recorded in the audit log under your name, "via Slack".
  • Text from your repositories is treated as data. Titles, descriptions, file paths and pull request titles can be written by anyone who can open a pull request. They are given to Nullgap AI marked as untrusted content, never followed as instructions, and stripped of mentions and links before anything is posted.
  • Updates. A pentest, review or fix started from Slack posts one short line when it finishes, for example "Pentest of acme/shop finished: 3 findings, 1 proven, 1 critical", with a link to the console. It goes to the thread it was asked in; started from the /nullgap command, it goes to your direct messages with the app.
  • Limits. 20 questions per person in any 10 minutes, and a daily limit per organisation. The /nullgap command is not affected.
  • Nothing is kept. Questions and answers are not stored. Each message is answered on its own, without memory of earlier ones.

#What the assistant will not do

  • Post anywhere it was not asked. The /nullgap command answers only you; Ask Nullgap answers in the thread or direct message it was asked in, and posts the finish update there.
  • Show source code, proof or remediation advice. The /nullgap command never shows descriptions; Ask Nullgap may summarise one.
  • Start, change or spend anything without a Confirm press by the person who asked.
  • Mark a finding as fixed.
  • Start a pentest with live testing, a branch other than the default, a folder selection or tester notes. Use the console or the API for those.
  • Do anything for a Slack user who has not linked an account, or more than that person's Nullgap role allows.
  • Change anything in a suspended workspace.

#Troubleshooting

What you seeLikely cause
Slack reports dispatch_failed or operation_timeout for /nullgapThe signing secret in Nullgap does not match the Slack app (paste it again), or the request URL in the Slack app is not the one on the card.
"Your Slack user is not connected to a Nullgap account yet"Run /nullgap link. If you had linked before, you were removed from the organisation, or the assistant was removed and set up again.
"Only an admin can do that"Your Nullgap role is member.
"This confirmation is no longer valid"The Confirm button was already used, was cancelled, or is older than ten minutes. Run the command or ask again.
"Only the person who asked for this can confirm it"The Confirm button was offered to someone else. Ask Nullgap yourself to get your own.
@Nullgap does not answerThe bot token is not saved, the events request URL is not verified in the Slack app (choose Retry under Event Subscriptions), the app was not invited to that channel, or your Slack user is not linked.
"You have asked a lot in the last few minutes"The per-person limit. Wait a few minutes, or use the /nullgap commands.
Buttons do nothingInteractivity is off in the Slack app, or its request URL is not the one on the card.
The card says "Needs reconnecting"The stored secret can no longer be read. Paste the signing secret again.

The API routes behind the card are listed in the Slack assistant reference.

Nullgap documentation