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
state | Console label | Meaning | Needs a reason |
|---|---|---|---|
open | Open | Not dealt with yet. Every new finding starts here. | No |
patched | Patched | Fixed. 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_risk | Accepted risk | Real, and your team has decided to live with it, optionally until a review date. | Yes |
false_positive | False positive | Not 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
| Where | Who |
|---|---|
| The console | Any member of the organisation |
| The API | A key with the write or admin scope |
| A reply on the pull request | Members of the organisation whose code-host login is linked to their account, and collaborators with write access to the repository |
| Slack | Members who have linked their Slack identity. See Slack. |
| Jira | Whoever 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"
| Field | Meaning |
|---|---|
state | One of the four states. Required. |
reason | Up to 2,000 characters. Required for accepted_risk and false_positive. |
reviewAt | A 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.
| Reply | Effect |
|---|---|
!fp <reason> | Marks the finding as a false positive |
!accept <reason> | Marks it as an accepted risk |
!valid | Confirms the finding. If it was not open, it is reopened. |
!reopen | Reopens it |
@nullgap fix | Starts a verified fix |
| Anything else | Saved as a note on the finding |
- A reason of at least three characters is required after
!fpand!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,stateReasonandstateBy, and setsresolvedAt(or clears it when the finding goes back toopen); - writes an entry to the audit log:
finding.open,finding.patched,finding.accepted_riskorfinding.false_positive, with the reason and the channel; - sends the
finding.state_changedwebhook 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.
| Change | When |
|---|---|
open to patched | A later review of the same pull request finds the flagged code is no longer in its latest commit. resolvedInSha records the commit. |
open to patched | A retest finds the flagged code gone and does not find the flaw again. |
open to false_positive | A later review of the same pull request looked at the same spot and refuted the finding. |
open to false_positive | A fix run's probe exercised the flagged code and it behaved safely. |
open to false_positive | A 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 was | What happened | Reason recorded |
|---|---|---|
patched | A later run found the flaw again. | The earlier reason is kept. |
false_positive | A 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_positive | A 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_risk | A 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 state | The linked Jira issue was moved back from done. | "Reopened in Jira" and the issue key |
| A dismissal | Someone 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.
#Related
Nullgap documentation