Nullgap.dev Docs

Findings

Triage verdict and trace

Read the independent check's verdict on a finding and the trace beside it, and know which parts were confirmed, which were only reported, and which were not recorded.

Every finding goes through an independent check before it is reported. Two things on the finding show what that check concluded and what it stood on:

  • The triage verdict: true or false positive, how confident the check was, the severity it settled on and why, the controls it found on the path, and the steps of the path it confirmed in the code.
  • The trace: the data-flow path as ordered steps, the call path from an entry point, a diagram, the proof, how often runs raised the finding, and the history of what was decided about it.

Nothing in the trace is worked out when you open the finding. Each part is read from what was recorded when the finding was raised and checked. A part that was not recorded is left empty and named as not recorded, so that nobody fills the gap with a guess.

The triage verdict is the check's opinion. It is not the finding's state: deciding whether a finding is open, patched, an accepted risk or a false positive stays with your team. See triage.

#Where to find them

In the console, open the finding. The sections Independent check: triage verdict and Trace are on the finding's page. A finding raised by a skill also shows Raised by skill with the skill's id.

Through the API, the verdict is finding.triageVerdict and the trace is trace, on one finding:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e" | jq '{verdict: .finding.triageVerdict, trace: .trace}'

The trace is returned for one finding only, not in lists. An MCP client gets both from get_finding.

#The triage verdict

{
  "verdict": "true_positive",
  "confidence": "high",
  "severity": "high",
  "severityBefore": "critical",
  "severityReasons": [
    "prerequisites: the caller must be signed in as any customer",
    "impact: reads the orders of other customers",
    "difficulty: one request with a changed id"
  ],
  "mitigations": [
    "src/middleware/auth.ts:41 requires a session; it does not check that the order belongs to the caller"
  ],
  "weaknessFits": true,
  "reasoning": "The id from the route reaches the query unchanged and the query filters by id only.",
  "confirmedPath": [
    "src/routes/orders.ts:18",
    "src/services/orders.ts:52",
    "src/db/orders.ts:77"
  ],
  "at": "2026-11-16T09:31:12.000Z"
}
FieldConsole labelMeaning
verdictTrue positive / False positiveWhat the check concluded
confidenceConfidencehigh, medium or low. See low confidence
severitySeverityThe severity after weighing prerequisites, impact and difficulty
severityBefore(was ...)The severity the finder claimed, present only when the check changed it
severityReasonsWhy this severityThe prerequisites, the impact and the difficulty, one line each
mitigationsControls found on the pathValidation, authorisation, safe APIs and limits the check found, whether or not they stop the flaw. Each says which
weaknessFitsWhether the weakness class the finder named fits what the code does. null when the check did not say
confirmedPathSteps of the reported path confirmed in the codeThe hops the check itself read and confirmed, as file:line
reasoningThe check's reasoning in its own words
atWhen the verdict was recorded

Read mitigations carefully. A control listed there was found on the path; it is not a statement that the path is safe. A true positive often lists a control that is present and does not help.

#Low confidence

low confidence means the check could not settle the question either way. In that case the check does not decide:

  • The finding is not marked verified, whichever way the low-confidence verdict leaned. When it is reported, it is reported as unverified.
  • Nothing about the finding changes automatically. It is left for a person to look at.
  • The evidence says so: "Independent check (Nullgap AI) was not confident either way; left for a person to decide".

#Where the verdict comes from

The verdict is produced by the independent check that already runs on every candidate, following the playbook of the built-in finding-triage skill. That skill cannot be switched off.

You can also ask for a fresh verdict on one finding by running finding-triage on demand. The new verdict is recorded on the finding and replaces the earlier one in triageVerdict. It does not change the finding's state or its assurance level.

A finding has no verdict when it was raised before verdicts were recorded, or when the check did not return one. The trace then lists "No triage verdict from the independent check is recorded for this finding".

#The trace

{
  "dataFlow": {
    "confirmedBy": "independent-check",
    "entryPoint": "GET /orders/:id (src/routes/orders.ts:18)",
    "sink": "db.query in src/db/orders.ts:77",
    "steps": [
      { "n": 1, "text": "Entry point: GET /orders/:id (src/routes/orders.ts:18)", "file": "src/routes/orders.ts", "line": 18 },
      { "n": 2, "text": "id passed to OrderService.find (src/services/orders.ts:52)", "file": "src/services/orders.ts", "line": 52 },
      { "n": 3, "text": "Sink: db.query in src/db/orders.ts:77", "file": "src/db/orders.ts", "line": 77 }
    ]
  },
  "callPath": null,
  "diagram": "flowchart TD\n  %% data flow\n  s1[\"Entry point: GET /orders/:id src/routes/orders.ts:18\"]\n  s2[\"id passed to OrderService.find src/services/orders.ts:52\"]\n  s3[\"Sink: db.query in src/db/orders.ts:77\"]\n  s1 --> s2\n  s2 --> s3",
  "proof": { "kind": "sandbox", "summary": "The probe read another customer's order.", "reproduced": true },
  "occurrences": 3,
  "skill": null,
  "verdict": null,
  "history": [
    { "at": "2026-11-10T08:12:40.000Z", "by": null, "what": "First raised by a pull request review" }
  ],
  "missing": [
    "No call path from an entry point was recorded: the parsed call graph did not establish one, or the finding was raised before call paths were kept.",
    "No triage verdict from the independent check is recorded for this finding."
  ]
}

#Data flow

The path the untrusted input takes, entry point first and the dangerous operation (the sink) last. confirmedBy says whose path it is, and it matters:

confirmedByConsole wordingMeaning
independent-checkas confirmed by the independent checkThe check read these steps in the code and confirmed them
finderas reported by the finder; not confirmed independentlyThis is the path the finder claimed. The check did not record a confirmed path of its own

The path the check confirmed is always preferred when both exist. Each step carries a file and line when the text names one.

#Call path

A route from an entry point to the flagged code, computed from the parsed call graph. It is a lead, not a conclusion: dynamic dispatch, reflection and framework wiring are not seen by the call graph, so basis says it is "a route to confirm by reading". It is recorded when the check verified the finding and a route was found.

#Diagram

diagram is the source of a Mermaid flowchart of the trace: the data flow when there is one, otherwise the call path. The console shows the source with a Copy diagram button, so you can paste it into a tool that renders Mermaid, such as an issue or a design document. Step text is reduced to plain words before it goes into the diagram.

#Proof

FieldMeaning
kindsandbox (a probe in the sandbox) or live (against the running application, during live testing)
reproducedWhether the flaw was reproduced
summaryWhat the proof showed, in a sentence

The full proof, with the probe and its output, is under proof on the finding.

#Occurrences and skill

occurrences is how many times runs have raised this finding; one finding is kept across runs, see duplicates. skill is the id of the skill that raised it, or null when a built-in reviewer did.

#History

Decisions and notes on the finding, oldest first: when it was first raised and by what kind of run, the triage verdict, a resemblance to an earlier dismissal, a researcher's review, notes from the console or the code host, and the current state when it is not open. Entries whose time was not recorded keep their place at the end.

#What was not recorded

missing lists, in a sentence each, the parts that were not recorded for this finding:

You seeMeaning
No data-flow path was recordedNeither the finder nor the check wrote one down
The data-flow path is the one the finder reportedThe check did not record a confirmed path
No call path from an entry point was recordedThe call graph did not establish one, or the finding is older than call paths
No proof was recordedThe finding was not reproduced in the sandbox or against a running application
The finding is marked proven but the proof record is not stored with itThe finding's level is proven and no proof record was found with it to summarise here
The number of runs that raised this finding is not recordedIt is counted as one
No triage verdict from the independent check is recordedSee above

When you write a report or an issue from a finding, say "not recorded" for these parts. Do not reconstruct them. The MCP tool get_finding passes the same list to a coding agent with that instruction.

#How to use them when you triage

  1. Start with the assurance level: proven, verified or unverified.
  2. Read the verdict's confidence. On low, the check has not decided and you are the reviewer.
  3. Compare confirmedPath with the data flow. Steps the check confirmed are the ones to rely on; a path marked as reported by the finder is a claim to check.
  4. Read mitigations for controls you know are effective in your deployment and the check could not see. That is the usual ground for an accepted risk or a false positive, with the control named in the reason.
  5. Decide the state. See triage.

Nullgap documentation