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 thereadscope.
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
| Console | API field | Meaning |
|---|---|---|
Priority badge, P0 to P3 | priority.level | How urgent it is. See Priority and exposure. |
| Severity badge | finding.severity | critical, high, medium, low or info: how bad the flaw is if used. |
| State badge | state | open, patched, accepted_risk or false_positive. See Triage. |
| Assurance badge | finding.status | How far it was checked. See Assurance. |
| PR review or Pentest | source | The kind of run that first reported it. sourceId is that run, and prNumber the pull request for a review. |
CWE-… badges | finding.cwe | The weakness class. finding.cve carries CVE ids for a dependency. |
| confidence | finding.confidence | From 0 to 1: how sure the reviewer was, before the independent checks. It is not the assurance level. |
| The heading | finding.title | One 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 seen | firstSeenAt | When 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.
| Assurance | finding.status | Meaning |
|---|---|---|
| Proven | proven, fixed | A probe reproduced the flaw and the demonstration passed its checks. fixed additionally means a patch passed verification. |
| Verified | verified | An independent review read the code path and could not refute it. It was not reproduced by running it. |
| Unverified | candidate | The 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 section | API field | Meaning |
|---|---|---|
| What is wrong | finding.description | The flaw in words: what input reaches what operation, and what an attacker gains. |
| Where | finding.location | file and startLine, with endLine when it spans lines, and snippet: the flagged line. Secrets in the snippet are masked. |
finding.package | For 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.
kind | What it records |
|---|---|
engine | A static-analysis rule matched, or another report of the same flaw was merged into this one. |
reasoning | The 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. |
verification | The independent review's verdict and the path it confirmed. On a finding with a patch, the result of verifying the patch. |
probe | An attempt to reproduce the flaw in the sandbox. Carries the proof record. |
dynamic | A test against a running deployment, from live testing. |
transcript | A 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.
| Console | Field | Meaning |
|---|---|---|
| The outcome badge | proof.outcome | Reproduced, Tried, did not reproduce, Probe did not run, No probe written, Could not run in the sandbox or Stopped at the limit. |
| attempts | proof.attempts | 1 or 2. |
| Safe-input check | proof.controlHeld | Whether the same call with ordinary input behaved safely. |
| Dependencies | proof.dependencies | Whether the project's dependencies were installed for the run. |
| Show the probe command and output | command, exitCode, output, detail | Exactly 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 section | API field | Meaning |
|---|---|---|
| How to fix | finding.remediation | Advice in words. |
| Patch | finding.patch | Present 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 it | remediation | The latest fix run for this finding: runId, status, outcome and prUrl. GET /automation-runs/{runId} has the full report. |
| Open linked issue | externalIssueUrl | The 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.
| Console | API field | Meaning |
|---|---|---|
| Rule | finding.ruleId | The rule or heading that raised it. Starts with custom/ for a custom check and variant/ for a variant. |
| Fingerprint | finding.fingerprint | The stable identity of the flaw. See One finding across runs. |
| Raised by | finding.source | What raised it. See the table below. |
| Custom check | First evidence entry | The name of your check, when one found it. |
| Found from | First evidence entry | The finding whose mistake this repeats, when a variant search found it. |
| Source | source, sourceId | Open PR review or Open pentest: the first run that reported it. |
| Found by | sightings | Every 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.source | Raised by |
|---|---|
llm-review | The 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 |
variant | The 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>). |
builtin | One 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 check | One 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-chain | The 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
| Field | When | Meaning |
|---|---|---|
stateReason, stateBy, resolvedAt | After a triage decision | Why, who, and when. stateBy is nullgap when Nullgap changed the state itself. |
resolvedInSha | Closed as patched by a review | The commit in which the flagged code was no longer present. |
riskReviewAt | Accepted risks with a review date | The date the acceptance is to be looked at again. |
earlierDecision | A finding that resembles a dismissed one but was raised all the same | findingId, decision and a note naming the rule that required it. See Memory of dismissals. |
finding.triage.exposure | Code findings from recent runs | The reachability facts behind the priority. |
validation | Workspaces with researcher validation | See 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.status | Console badge | Meaning |
|---|---|---|
pending | Awaiting researcher | Not looked at yet. |
confirmed | Validated by a researcher | A researcher reproduced or accepted it. |
adjusted | Validated, severity adjusted | Confirmed with a different severity. severityBefore holds the earlier one. |
rejected | Rejected by a researcher | Found 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.
#Related
Nullgap documentation