Nullgap.dev Docs

Findings

Reading a finding

Every part of a finding as the console and the API show it, from severity and assurance to evidence, proof, patch and sightings.

A finding is one flaw in one place, with everything known about it: what is wrong, how far it was checked, the evidence, how to fix it, and what your team has decided. This page goes through each part, with the console's name for it and the API field behind it.

#Where to open one

  • In the console: Findings, or the Findings tab of a pull request review or a pentest. Selecting a row opens the finding.
  • By API: GET /findings/{id}. Any member can read findings, and so can an API key with the read scope.
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e"
{
  "id": "fnd_8f3a2c9d1b4e",
  "repoId": "repo_5b2e8a1c9d3f",
  "repoFullName": "acme/shop",
  "source": "pentest",
  "sourceId": "pen_4c1d9e7a2b60",
  "prNumber": null,
  "state": "open",
  "stateReason": null,
  "stateBy": null,
  "firstSeenAt": "2026-11-16T14:01:58.000Z",
  "resolvedAt": null,
  "priority": {
    "level": "P0",
    "fromSeverity": "P1",
    "proven": true,
    "reasons": [
      "Severity high gives P1.",
      "Raised one step: reachable from GET /orders/:id, which is internet-facing and needs no sign-in."
    ]
  },
  "finding": {
    "ruleId": "pentest/injection/sql-injection",
    "title": "SQL injection in order lookup",
    "severity": "high",
    "confidence": 0.9,
    "cwe": ["CWE-89"],
    "status": "proven",
    "source": "llm-lens:injection",
    "location": { "file": "src/orders.js", "startLine": 42, "snippet": "return db.query(\"SELECT * FROM orders WHERE id = \" + id);" },
    "description": "The order id from the URL is concatenated into the query.",
    "remediation": "Pass the id as a query parameter instead of building the statement from it.",
    "evidence": [
      { "kind": "reasoning", "summary": "Path reported by the finder (unverified)" },
      { "kind": "verification", "summary": "Independent review (Nullgap AI) could not refute it" },
      { "kind": "probe", "summary": "Probe reproduced the vulnerability", "command": "node .nullgap-probe/probe.js", "exitCode": 0 }
    ],
    "fingerprint": "5c0e9a7d2b1f48a6c3d0e7f1"
  },
  "sightings": [
    { "source": "pentest", "sourceId": "pen_4c1d9e7a2b60", "prNumber": null, "at": "2026-11-16T14:01:58.000Z" }
  ],
  "remediation": null,
  "externalIssueUrl": null,
  "notes": []
}

The sample is abridged. The record has two levels: the outer one is what your organisation knows and decided about the finding, and finding is the flaw itself as the engine described it.

#The header

ConsoleAPI fieldMeaning
Priority badge, P0 to P3priority.levelHow urgent it is. See Priority and exposure.
Severity badgefinding.severitycritical, high, medium, low or info: how bad the flaw is if used.
State badgestateopen, patched, accepted_risk or false_positive. See Triage.
Assurance badgefinding.statusHow far it was checked. See Assurance.
PR review or PentestsourceThe kind of run that first reported it. sourceId is that run, and prNumber the pull request for a review.
CWE-… badgesfinding.cweThe weakness class. finding.cve carries CVE ids for a dependency.
confidencefinding.confidenceFrom 0 to 1: how sure the reviewer was, before the independent checks. It is not the assurance level.
The headingfinding.titleOne line naming the flaw. A title that starts Latent: is a real flaw in code a pull request adds that no entry point reaches yet; its severity is held at medium or below until it is wired up.
first seenfirstSeenAtWhen the first run reported it. It does not change when later runs find it again.

#Assurance

finding.status holds the engine's status. The console and the exports show it as one of three assurance levels.

Assurancefinding.statusMeaning
Provenproven, fixedA probe reproduced the flaw and the demonstration passed its checks. fixed additionally means a patch passed verification.
VerifiedverifiedAn independent review read the code path and could not refute it. It was not reproduced by running it.
UnverifiedcandidateThe independent review did not complete, so this may be a false positive. Confirm it before acting on it.

A candidate that the independent review refutes is never stored, so you do not see it. What the levels require is on Proof.

#What is wrong and where

Console sectionAPI fieldMeaning
What is wrongfinding.descriptionThe flaw in words: what input reaches what operation, and what an attacker gains.
Wherefinding.locationfile and startLine, with endLine when it spans lines, and snippet: the flagged line. Secrets in the snippet are masked.
finding.packageFor a dependency finding instead of a location: ecosystem, name, version, fixedVersion, the manifest that pins it, and whether it is a direct dependency.

#Evidence

finding.evidence is the chain of what was observed and decided, in order. The console shows it under Evidence; the probe has its own Proof section.

Every entry has a kind and a one-line summary. It may also have detail, and for commands that were run, command, exitCode and output.

kindWhat it records
engineA static-analysis rule matched, or another report of the same flaw was merged into this one.
reasoningThe reviewer's reasoning: the path from entry point to the dangerous operation. Also where the finding came from, when that was a custom check or a variant search.
verificationThe independent review's verdict and the path it confirmed. On a finding with a patch, the result of verifying the patch.
probeAn attempt to reproduce the flaw in the sandbox. Carries the proof record.
dynamicA test against a running deployment, from live testing.
transcriptA recorded exchange. Pull request reviews and pentests do not produce it.

Evidence never names which AI model produced it.

#Proof

When a probe was run, the console shows a Proof section built from the latest probe entry and its proof record.

ConsoleFieldMeaning
The outcome badgeproof.outcomeReproduced, Tried, did not reproduce, Probe did not run, No probe written, Could not run in the sandbox or Stopped at the limit.
attemptsproof.attempts1 or 2.
Safe-input checkproof.controlHeldWhether the same call with ordinary input behaved safely.
Dependenciesproof.dependenciesWhether the project's dependencies were installed for the run.
Show the probe command and outputcommand, exitCode, output, detailExactly what was run, what it printed, and the probe's files.

What each outcome means for the finding is on Proof.

#How to fix, and the patch

Console sectionAPI fieldMeaning
How to fixfinding.remediationAdvice in words.
Patchfinding.patchPresent once a fix run has written one: diff (a unified diff), description, verified, and verification with every check. A patch marked Not verified did not pass and was not proposed.
Fix itremediationThe latest fix run for this finding: runId, status, outcome and prUrl. GET /automation-runs/{runId} has the full report.
Open linked issueexternalIssueUrlThe Jira or Linear issue filed for it, if any.

The Fix it section also has Remediate, Copy prompt for your coding agent, and, when a tracker is connected, Create Jira issue or Create Linear issue. See Verified fixes.

#Where it came from

The Reference section gathers the identifiers.

ConsoleAPI fieldMeaning
Rulefinding.ruleIdThe rule or heading that raised it. Starts with custom/ for a custom check and variant/ for a variant.
Fingerprintfinding.fingerprintThe stable identity of the flaw. See One finding across runs.
Raised byfinding.sourceWhat raised it. See the table below.
Custom checkFirst evidence entryThe name of your check, when one found it.
Found fromFirst evidence entryThe finding whose mistake this repeats, when a variant search found it.
Sourcesource, sourceIdOpen PR review or Open pentest: the first run that reported it.
Found bysightingsEvery run that reported it. Shown when there is more than one.

Note the two different fields called source. On the record, source is review or pentest. Inside finding, source says what raised it:

finding.sourceRaised by
llm-reviewThe review of a pull request's change
llm-lens:<heading>A pentest's examination of a file under one heading, such as llm-lens:injection
llm-custom:<check id>One of your custom checks. The first evidence entry reads Found by your custom check "<name>".
llm-skill:<skill id>A skill, built-in or your own, running inside a review or a pentest. The finding's page shows Raised by skill
variantThe search for the same mistake as a confirmed finding. The first evidence entry reads Found by looking for the same mistake as "<title>" (<file>:<line>).
builtinOne of Nullgap's built-in static-analysis rules
The name of an automated check, such as Static code analysis, Secret detection, Dependency vulnerability scan or Infrastructure-as-code checkOne of the automated checks Nullgap runs in its sandbox. Several programs may stand behind one check; a finding names the check, not the program. Its ruleId is the check's own rule identifier, such as G101 or a CVE- or GHSA- advisory id.
Dependency advisory check, supply-chainThe dependency and supply-chain checks

Whatever raised a finding, it went through the same independent review before it was reported. What that review concluded, and the path it confirmed, are on triage verdict and trace.

#Sightings

sightings lists every run that reported this flaw, oldest first: source, sourceId, prNumber and at. A finding reported by a pull request review and later by a pentest is one finding with two sightings. In lists, the console shows a Found by N runs badge. Up to the 50 most recent sightings are kept.

#Notes

notes holds comments about the finding, oldest first. Each has author, text, at and via: console for a note added in the console or by API, code-host for a reply on the pull request that was not a command.

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Tracked in the Q1 hardening work."}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/notes"

A note may be up to 2,000 characters. The 100 most recent are kept. Adding one needs the write scope.

#Fields that appear only sometimes

FieldWhenMeaning
stateReason, stateBy, resolvedAtAfter a triage decisionWhy, who, and when. stateBy is nullgap when Nullgap changed the state itself.
resolvedInShaClosed as patched by a reviewThe commit in which the flagged code was no longer present.
riskReviewAtAccepted risks with a review dateThe date the acceptance is to be looked at again.
earlierDecisionA finding that resembles a dismissed one but was raised all the samefindingId, decision and a note naming the rule that required it. See Memory of dismissals.
finding.triage.exposureCode findings from recent runsThe reachability facts behind the priority.
validationWorkspaces with researcher validationSee below.

#Researcher validation

When Nullgap has switched researcher validation on for your workspace, each pentest finding also carries validation: a person's check on top of the automated ones.

validation.statusConsole badgeMeaning
pendingAwaiting researcherNot looked at yet.
confirmedValidated by a researcherA researcher reproduced or accepted it.
adjustedValidated, severity adjustedConfirmed with a different severity. severityBefore holds the earlier one.
rejectedRejected by a researcherFound not to be a real issue. The finding is closed as a false positive, with the researcher's reason.

validation.note is what the researcher wrote for you, and validation.at when they decided. The pentest carries a tally: validation.pending, validation.done and validation.completedAt. Each time a researcher opens one of your findings, that is written to your audit log.

Without researcher validation the field is absent.

Nullgap documentation