Nullgap.dev Docs

Findings

Triage

The four states of a finding, who can change them and how, what a reason and a review date do, and what reopens a finding automatically.

Triage is deciding what to do about a finding: fix it, accept it, or dismiss it. Each decision is recorded with who made it and why, and the reason is used in later reviews.

#The four states

stateConsole labelMeaningNeeds a reason
openOpenNot dealt with yet. Every new finding starts here.No
patchedPatchedFixed. Set by a person, by a pull request review that sees the flagged code gone, by a retest, or by a Jira issue being closed.No
accepted_riskAccepted riskReal, and your team has decided to live with it, optionally until a review date.Yes
false_positiveFalse positiveNot a real issue in this code.Yes

accepted_risk and false_positive are dismissals. A dismissal is remembered, so the same finding is not raised again. See Memory of dismissals.

#Who can change a state

WhereWho
The consoleAny member of the organisation
The APIA key with the write or admin scope
A reply on the pull requestMembers of the organisation whose code-host login is linked to their account, and collaborators with write access to the repository
SlackMembers who have linked their Slack identity. See Slack.
JiraWhoever moves the linked issue, when status sync is on. See Jira.

Every route goes through the same checks: the same four states are allowed and a dismissal needs a reason, wherever it is made.

#In the console

Open the finding. Under State, press Open, Patched, Accepted risk or False positive.

  • Open and Patched apply at once.
  • Accepted risk and False positive open a dialog that asks for a Reason. For an accepted risk it also offers Review on (optional).

To decide many findings at once, see Bulk actions.

#By API

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"accepted_risk","reason":"Internal reporting tool, reachable only from the office network. Replacing it in Q2.","reviewAt":"2027-06-30T23:59:59.000Z"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e"
FieldMeaning
stateOne of the four states. Required.
reasonUp to 2,000 characters. Required for accepted_risk and false_positive.
reviewAtA date in the future. Only allowed with accepted_risk.

The answer is the finding with state, stateReason, stateBy and resolvedAt updated. A request is refused with 400 bad_request when the state is not one of the four, a dismissal has no reason, reviewAt is given for another state, is not a date, or is not in the future. See the reference.

#By replying on the pull request

Reply to one of Nullgap's comments on the pull request. The reply must start with the command.

ReplyEffect
!fp <reason>Marks the finding as a false positive
!accept <reason>Marks it as an accepted risk
!validConfirms the finding. If it was not open, it is reopened.
!reopenReopens it
@nullgap fixStarts a verified fix
Anything elseSaved as a note on the finding
  • A reason of at least three characters is required after !fp and !accept.
  • Reply in the finding's own thread, or include its reference, which starts with fnd_, from the summary table. A reply that cannot be matched to exactly one finding changes nothing, and Nullgap says so in the thread.
  • At most 12 replies per pull request are acted on per minute.
  • The decision is recorded as made by the code-host login, followed by "(pull request reply)".

The comments themselves are described on Comments and commands.

#Through Jira

When a finding has been filed as a Jira issue and status sync is on:

  • An issue that moves into a done status marks its finding patched, with the reason "Closed in Jira" and the issue key.
  • An issue that moves from a done status back to to-do or in progress reopens its finding.
  • In the other direction, a state change in Nullgap adds a comment to the issue and moves it to a done or a to-do status.

Changes that came from Jira are recorded with "Jira" as the person. See Jira.

#What a decision does

Whichever way it is made, a state change:

  • sets state, stateReason and stateBy, and sets resolvedAt (or clears it when the finding goes back to open);
  • writes an entry to the audit log: finding.open, finding.patched, finding.accepted_risk or finding.false_positive, with the reason and the channel;
  • sends the finding.state_changed webhook event;
  • moves the linked Jira issue, when status sync is on.

A dismissal does two more things:

  • It is remembered for the repository. See Memory of dismissals.
  • Its reason is added to the application's threat model, under Learned from feedback on the Context page, so later reviews take it into account.

#Reasons

Write the reason for someone who was not there: what makes this safe, or why the risk is acceptable. "Not exploitable" teaches nothing. "The id is cast to an integer in parseOrderId before it reaches the query" does.

The reason appears:

  • on the finding, next to who decided;
  • in the exports, as state_reason, and as the justification of a SARIF suppression;
  • in the full pentest report, as the triage note;
  • in the threat model, where reviewers read it on later runs.

#Review dates for accepted risks

reviewAt is the date an accepted risk is to be looked at again. In the console it is Review on (optional); the earliest date offered is tomorrow, and the acceptance runs to the end of the day you pick.

  • Until the date, the finding is not raised again when it is found in the same function.
  • After the date, the finding is raised again the next time a run finds it. The reason then reads "Raised again: the risk was accepted until" the date "and that date has passed".
  • Nothing happens on the date itself. An accepted risk whose code is never reviewed or tested again stays accepted. Use a scheduled pentest if you want the date to bite.
  • Without a review date, the acceptance has no end.

The date is returned as riskReviewAt on the finding. Changing the state to anything else clears it.

#Changes Nullgap makes itself

Some states are set without a person. stateBy is then nullgap, and the reason says what was seen.

ChangeWhen
open to patchedA later review of the same pull request finds the flagged code is no longer in its latest commit. resolvedInSha records the commit.
open to patchedA retest finds the flagged code gone and does not find the flaw again.
open to false_positiveA later review of the same pull request looked at the same spot and refuted the finding.
open to false_positiveA fix run's probe exercised the flagged code and it behaved safely.
open to false_positiveA Nullgap researcher rejected the finding, in workspaces with researcher validation. stateBy is then "Nullgap researcher".

A finding Nullgap closed this way stays closed as that one finding. It is not remembered as a pattern, so it never holds back other findings.

#What reopens a finding automatically

A closed finding goes back to open in these cases.

The finding wasWhat happenedReason recorded
patchedA later run found the flaw again.The earlier reason is kept.
false_positiveA later run found it again and reproduced it in the sandbox."Raised again: it was dismissed as a false positive, and has now been reproduced in the sandbox."
false_positiveA later run found it again and the code around it has changed since the dismissal."Raised again: the code around it has changed since it was dismissed as a false positive."
accepted_riskA later run found it again after its review date."Raised again: the risk was accepted until" the date, "and that date has passed."
Any closed stateThe linked Jira issue was moved back from done."Reopened in Jira" and the issue key
A dismissalSomeone brought it back from a run's held-back list.See Memory of dismissals.

When Nullgap reopens a dismissal, the finding carries earlierDecision: the earlier decision and its reason, so nothing is lost. The console shows it as a notice with Open the earlier decision. A researcher's rejection is removed, and the finding goes back to them.

Reopening a dismissal, by hand or automatically, also releases everything that dismissal was holding back.

Time alone reopens nothing. A dismissed finding that is found again and does not meet one of the rows above stays dismissed, and is listed on the run as held back.

Nullgap documentation