Nullgap.dev Docs

Findings

Expert review

Ask a Nullgap security researcher to review a finding, or every proven or verified finding of a pentest report, by hand.

An expert review puts a Nullgap security researcher on a finding. The researcher reads the finding, its evidence and the code it points at, and decides whether it is real, whether it can be exploited, and whether its severity is right. You can ask for one finding, from a pull request review or a pentest, or for the whole report of a finished pentest.

#What you need first

  • The expert review add-on. Workspaces on the Pro and Enterprise plans have it; for others, contact us. Without it, asking answers that expert review is an add-on.
  • The admin or owner role. By API, a key with the admin scope.
  • An open finding. A finding you have closed must be reopened first.

#What the researcher sees

Asking is your consent for a Nullgap researcher to read the findings it covers, with their evidence and code. Nothing else in the workspace is opened. Every read is written to your audit log as finding.viewed_for_validation, and the request itself as finding.expert_review_requested or pentest.expert_review_requested. The researcher is never named: decisions and notes are signed Nullgap researcher.

#Ask for one finding

  1. Open the finding.
  2. Press Request expert review.
  3. Optionally, write What should the researcher check?, up to 1,000 characters.
  4. Press Request expert review.

The finding shows a yellow note, A Nullgap security researcher will review this finding, and Expert review requested next to its status, here and in the findings list.

#Ask for a whole pentest report

  1. Open a finished pentest.
  2. Press Request expert review of this report.
  3. Optionally, write what the researcher should check, and press Request expert review.

Every open proven or verified finding of the pentest is sent. Findings already waiting are left as they are, and so are findings a researcher has already reviewed. When the last finding is decided, the pentest's reports are revised once to carry the reviewed result, and say that they were revised.

#Cancel a request

Until a researcher has opened a finding, an admin can withdraw the request: press Cancel request on the finding, or Cancel the expert review request on the pentest. Once a researcher has started, the request can no longer be cancelled; on a pentest, the findings a researcher has opened stay in review and the rest are withdrawn. A cancelled request is written to the audit log.

#What comes back

On the findingWhat it means
Expert reviewedThe researcher confirmed the finding as reported.
Severity adjusted by an expertThe researcher confirmed the finding with a different severity. The finding shows the change, and its priority follows the new severity.
Ruled out by an expertThe researcher found it is not exploitable as reported. The finding is closed as a false positive with the researcher's reason. Reopen it if you disagree.

The researcher's note is shown on the finding, and every note the researcher writes, including notes written while the review is under way, appears in the finding's comments under Nullgap researcher. The notes are also in the finding's trace, its evidence bundle and the expert_review column of exports.

When a researcher decides, Nullgap tells you:

  • the person who asked, by e-mail, and your Slack channel, when Slack is connected, with the title, the decision and a link;
  • the finding.expert_reviewed webhook event.

#Ask for another look

A finding a researcher has reviewed shows Ask for another look. The earlier decision stays until the new one is made, and comes back if you cancel the new request.

#By API

Ask for one finding:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"We think the admin check in middleware.js stops this."}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/expert-review"

The answer says how many findings were sent (requested), how many were already waiting (alreadyPending) and how many had already been reviewed (alreadyReviewed), with the findings as they are now. Asking again for a finding that is already waiting changes nothing. A finding already reviewed answers 409 already_reviewed; send "again": true to ask for another look.

Ask for a finished pentest:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Focus on the payment flows."}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/pen_5c2e8a1f4b7d/expert-review"

Cancel, before a researcher has opened it:

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/expert-review"

The finding's validation holds where the review stands: status (pending, confirmed, adjusted or rejected), note, severityBefore, and for a request requestedAt, requestedBy, scope and requestNote. See the API reference for every field.

Nullgap documentation