Nullgap.dev Docs

Findings

Priority and exposure

How a finding's priority, P0 to P3, is worked out from its severity and what is known about its exposure, and what "not determined" means.

Severity says how bad a flaw is if it is used. Priority says how soon to deal with it. Nullgap starts from the severity and moves it by facts about exposure: can the code be reached, from where, by whom, and with whose input. The reasons are written out on every finding.

The rules are fixed code. No AI is asked, so the same facts always give the same priority.

#The four levels

LevelConsole meaningWhat severity alone gives
P0Act nowCritical
P1Act this weekHigh
P2Plan itMedium
P3When convenientLow and info

The level is on every finding as priority.level, and in the Priority column of every findings list.

#How severity is moved

Start from the level the severity gives. Then:

MoveWhen
Up one stepThe code is reachable from an internet-facing entry point that needs no sign-in.
Up one stepThe finding is proven, and the code is reachable from an internet-facing entry point (with or without sign-in).
Down two stepsThe code is test-only.
Down one stepThe code is reached through a command-line tool, an internal entry point or an administration interface, not from the internet.
Down one stepNo call chain from any entry point leads to the code.
Down one stepThe value that reaches the flaw is not under an attacker's control.

Three limits apply:

  • A finding goes up at most one step. The two "up" rows do not add.
  • A finding goes down at most two steps in total, however many "down" rows apply.
  • A proven finding is never placed below what its severity gives. A working exploit is not argued down by where the code sits. If the rules would lower it, it is kept at the severity's level and the reasons say so.

The result stays within P0 to P3.

#Examples

FindingFactsPriority
High severity SQL injectionReachable from GET /orders/:id, internet-facing, no sign-inP0: raised one step from P1
High severity, provenInternet-facing route behind sign-inP0: raised one step, because it was reproduced
High severity, verifiedInternet-facing route behind sign-inP1: nothing moves it
CriticalOnly reachable through an administration interfaceP1: lowered one step
MediumIn test code, input written in the testP3: test-only lowers it two steps, and the limit of two stops it there
High severity, provenReached through a command-line toolP1: kept at the severity's level, because it is proven
MediumNothing about its exposure could be establishedP2: what the severity gives

#The reasons shown

priority.reasons lists why the level is what it is, most important first. They are shown as written, in the Priority section of a finding and when you hover the priority badge in a list.

{
  "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.",
    "Not determined, so not counted either way: whether the input is attacker-controlled."
  ]
}
FieldMeaning
levelThe priority.
fromSeverityWhat the severity alone would give. When it differs from level, the console says "Raised from" or "Lowered from" that level.
provenWhether the finding was reproduced, in the sandbox or against a running deployment.
reasonsPlain sentences: the starting level, each move, and what was not determined.

#The exposure facts

The facts behind the priority are in finding.triage.exposure, and in the console under the reasons.

Console rowFieldValues
Reachable from an entry pointreachableyes, no (shown as "No call path found"), not_determined
Entry pointentryPointThe route, command or handler: kind, name, file, line, and for a route method and route
Sign-inauthenticationrequired, none, not_determined
Who can reach itsurfaceinternet, internal, admin, cli, test, not_determined
Attacker-controlled inputattackerControlledyes, no, not_determined

basis holds one line per fact saying how it was established. The console shows it under How each fact was established.

How each fact is read off the code:

  • Reachable. yes when the flagged line is inside an entry point, when the independent review confirmed a path that starts at one, or when the parsed call graph has a chain from one. no only when no chain from any entry point leads to the code and nothing suggests an indirect call.
  • Who can reach it. An HTTP route is internet unless its path or file is named as admin (admin) or as internal, debug or health (internal). A command is cli. A queue consumer or a scheduled job is internal. Code in a test folder is test.
  • Sign-in. required when a guard is written on the entry point itself; none when the entry point is marked as public or is a route that is called before anyone is signed in, such as a sign-in route.
  • Attacker-controlled input. yes when a probe supplied the input and reproduced the flaw, or when the independent review confirmed that a value from the request reaches it. no when the input is written in a test.

These are heuristics about the code as written. A route that is internet-facing in the code may sit behind a private network in your deployment, and the reverse. Treat the priority as a starting order, and correct for what you know about your own infrastructure.

#Not determined

A fact that could not be established is not_determined. It is shown as "Not determined", and it moves nothing in either direction. It is never treated as a "no".

Common reasons:

  • A sign-in guard may be applied somewhere other than on the entry point itself, for example in middleware registered elsewhere. Sign-in is then not determined, not "none".
  • The call graph could not resolve a call, for example one made through reflection or a dynamic dispatch. Reachability is then not determined, not "no".
  • The finding is not tied to an entry point, so who can reach it cannot be said.
  • The finding is about a dependency, not a line of code. It carries no exposure facts at all, and its priority is what the severity gives.
  • The finding was stored before exposure facts were recorded.

The last reason on such a finding lists what was not determined, beginning "Not determined, so not counted either way".

#Using priority

In the console, Findings has an Any priority filter and a sort choice between Most urgent first and Most severe first.

By API, filter with priority and sort with sort=priority:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings?state=open&priority=P0&sort=priority"

With sort=priority the most urgent come first, then the most severe. Without it the list is most severe first.

Priority is recomputed whenever a run reports the finding again, a fix run updates it, or a researcher adjusts its severity. A finding that becomes proven can therefore move up.

Priority does not change the pull request check. The check is decided by severity. See Checks and gating.

Nullgap documentation