Nullgap.dev Docs

Findings

One finding across runs

How Nullgap recognises a flaw it has seen before, so that one flaw is one finding however many reviews and pentests report it.

One flaw is one finding, whichever run finds it and however often. When a pull request review and a pentest report the same flaw, or a scheduled pentest finds last month's finding again, the stored finding gains a sighting. No second finding is created.

#What you see

  • The finding keeps its id, its firstSeenAt date, its triage state and its notes.
  • sightings lists every run that reported it, oldest first.
  • In lists, a finding reported more than once has a Found by N runs badge. On the finding, Reference shows Found by with a link to each run.
  • Each run's own findings list includes the finding, so a pentest's report still covers it.
  • No finding.created event is sent for a later sighting. The run's review.completed or pentest.completed event lists the finding.
{
  "id": "fnd_8f3a2c9d1b4e",
  "source": "review",
  "sourceId": "rev_1c7e4a9b3d05",
  "prNumber": 7,
  "firstSeenAt": "2026-10-28T09:12:40.000Z",
  "sightings": [
    { "source": "review", "sourceId": "rev_1c7e4a9b3d05", "prNumber": 7, "at": "2026-10-28T09:12:40.000Z" },
    { "source": "pentest", "sourceId": "pen_4c1d9e7a2b60", "prNumber": null, "at": "2026-11-16T14:01:58.000Z" }
  ]
}

The sample is abridged. source, sourceId and prNumber on the record stay those of the first run. The 50 most recent sightings are kept, one per run.

#Fingerprints

Every finding has a fingerprint: a short hash that identifies the flaw. It is computed from:

  • the kind of check and the rule that raised it;
  • the file;
  • the text of the flagged line (or the line number, when no line text was recorded);
  • for a dependency, the package name and version.

Because the fingerprint uses the text of the line and not its number, it survives code being added or removed above the flaw. It changes when the flagged line itself is edited, when the file is renamed, or when a different rule reports the flaw.

The fingerprint is shown under Reference on a finding, is in finding.fingerprint, and is exported in SARIF as partialFingerprints.nullgapFingerprint. A stored finding keeps its original fingerprint even when a later run describes the flaw differently.

#How a finding is recognised again

A fingerprint alone would miss a flaw that a review and a pentest describe under different rule names. So a finding from a new run is compared with the repository's stored findings in three steps, strongest first. The first step that matches decides.

  1. The same fingerprint.
  2. The same flaw, by place or by root cause:

    • the same file, within a few lines, with weakness classes that do not contradict each other (one report says SQL injection, another "improper input validation");
    • or the same root cause reported from two places: both name the same dangerous operation on the same line, whatever file each report is anchored in;
    • or the same statement in the same function, after lines moved above it.
  3. The same code, moved. Only when the stored finding's flagged code is no longer where it was: the file is gone, or the line is no longer in it. The new finding then has to have the identical statement, the identical code within six lines, and an enclosing function at least 90% alike.

Some things are never merged:

  • Two findings that need different fixes, wherever they sit.
  • Two independent places. The same weakness at two dangerous operations far apart in one file is two findings.
  • Two routes missing the same check. Access-control findings are not merged because they reach the same sensitive operation: each route is its own flaw.
  • Identical code that exists in two places at once. A copy is a second finding. The "moved" step applies only when the original is gone.
  • Findings in different repositories.

Findings that are alike but not the same are shown under Findings like this on each of them. They stay separate findings. To decide them together, see Bulk actions.

#A review and a pentest

A pentest joins any stored finding of the repository: one from a pull request review, or one from an earlier pentest.

A pull request review joins the findings of its own pull request and the findings pentests reported. By place or root cause it does not join a finding that belongs to a different pull request: two pull requests that introduce the same mistake each get their own finding, because each is fixed on its own branch.

When a review and a pentest report the same flaw:

  • there is one finding, with a sighting for each run;
  • the finding's description, evidence and location are updated to the latest run's;
  • a proof is never lost. If the stored finding was proven by one kind of run and a different kind of run finds it again without reproducing it, the proof and its evidence are kept. Only the location and the exposure facts are refreshed.
  • the priority is worked out again.

#What a later sighting does to the state

The stored finding isWhen a later run finds it again
openIt stays open and gains a sighting.
patchedIt is reopened: the flaw is back. A linked Jira issue is reopened, when status sync is on.
false_positive or accepted_riskIt is held back, unless one of the rules in Memory of dismissals raises it again.

Not being found again does not close a finding. A finding is closed as patched automatically only by a later review of the same pull request that sees the flagged code gone, or by a retest.

#Duplicates inside one run

Before anything is stored, a run merges its own duplicates: the same flaw raised under two headings, or by static analysis and by review. The surviving finding keeps the evidence of both, with an entry saying what else flagged it. This is why a finding's evidence can name more than one rule.

#Two runs at the same moment

Storing a run's findings takes a lock on the repository. Two runs that finish together, such as two pull requests reviewed at once, or a review and a pentest, end with one finding for a shared flaw, not two.

#If two findings look like duplicates

The comparison is cautious: when it cannot tell, it keeps two findings. If you see two findings for what you judge to be one flaw:

  • check whether they need the same fix. Two call sites of one unsafe helper are two places, and a class fix can repair them with one change;
  • triage them together with one reason, using Bulk actions.

There is no manual merge.

Nullgap documentation