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
| Level | Console meaning | What severity alone gives |
|---|---|---|
P0 | Act now | Critical |
P1 | Act this week | High |
P2 | Plan it | Medium |
P3 | When convenient | Low 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:
| Move | When |
|---|---|
| Up one step | The code is reachable from an internet-facing entry point that needs no sign-in. |
| Up one step | The finding is proven, and the code is reachable from an internet-facing entry point (with or without sign-in). |
| Down two steps | The code is test-only. |
| Down one step | The code is reached through a command-line tool, an internal entry point or an administration interface, not from the internet. |
| Down one step | No call chain from any entry point leads to the code. |
| Down one step | The 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
| Finding | Facts | Priority |
|---|---|---|
| High severity SQL injection | Reachable from GET /orders/:id, internet-facing, no sign-in | P0: raised one step from P1 |
| High severity, proven | Internet-facing route behind sign-in | P0: raised one step, because it was reproduced |
| High severity, verified | Internet-facing route behind sign-in | P1: nothing moves it |
| Critical | Only reachable through an administration interface | P1: lowered one step |
| Medium | In test code, input written in the test | P3: test-only lowers it two steps, and the limit of two stops it there |
| High severity, proven | Reached through a command-line tool | P1: kept at the severity's level, because it is proven |
| Medium | Nothing about its exposure could be established | P2: 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."
]
}
| Field | Meaning |
|---|---|
level | The priority. |
fromSeverity | What the severity alone would give. When it differs from level, the console says "Raised from" or "Lowered from" that level. |
proven | Whether the finding was reproduced, in the sandbox or against a running deployment. |
reasons | Plain 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 row | Field | Values |
|---|---|---|
| Reachable from an entry point | reachable | yes, no (shown as "No call path found"), not_determined |
| Entry point | entryPoint | The route, command or handler: kind, name, file, line, and for a route method and route |
| Sign-in | authentication | required, none, not_determined |
| Who can reach it | surface | internet, internal, admin, cli, test, not_determined |
| Attacker-controlled input | attackerControlled | yes, 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.
yeswhen 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.noonly 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
internetunless its path or file is named as admin (admin) or as internal, debug or health (internal). A command iscli. A queue consumer or a scheduled job isinternal. Code in a test folder istest. - Sign-in.
requiredwhen a guard is written on the entry point itself;nonewhen 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.
yeswhen a probe supplied the input and reproduced the flaw, or when the independent review confirmed that a value from the request reaches it.nowhen 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.
#Related
Nullgap documentation