API reference
Findings
List, read, triage and export findings, and see what was held back because of an earlier decision.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| Export findings | GET /api/orgs/{org}/findings/export | read |
| Get the evidence bundle | GET /api/orgs/{org}/findings/{id}/evidence | read |
| Add a note | POST /api/orgs/{org}/findings/{id}/notes | write |
| Request an expert review | POST /api/orgs/{org}/findings/{id}/expert-review | admin |
| Cancel an expert review request | DELETE /api/orgs/{org}/findings/{id}/expert-review | admin |
| Request an expert review of a pentest report | POST /api/orgs/{org}/pentests/{id}/expert-review | admin |
| Cancel an expert review request for a pentest | DELETE /api/orgs/{org}/pentests/{id}/expert-review | admin |
| List findings | GET /api/orgs/{org}/findings | read |
| Triage several findings | POST /api/orgs/{org}/findings/bulk | write |
| List held-back findings | GET /api/orgs/{org}/suppressions | read |
| Restore a held-back finding | POST /api/orgs/{org}/suppressions/{id}/restore | write |
| Get a finding | GET /api/orgs/{org}/findings/{id} | read |
| Triage a finding | PATCH /api/orgs/{org}/findings/{id} | write |
| List similar findings | GET /api/orgs/{org}/findings/{id}/similar | read |
| File an issue | POST /api/orgs/{org}/findings/{id}/issue | write |
| Get a fix prompt | GET /api/orgs/{org}/findings/{id}/fix-prompt | read |
#Export findings
GET /api/orgs/{org}/findings/export
Downloads every finding that matches the filters as one file; there is no paging. The filters and the order are those of the findings list. The answer is a file attachment named nullgap-<organisation>-findings with the extension of the format, and it is written as a stream, so a failure part-way ends the connection early. Each export is recorded in the audit log. In the console this is for admins and owners; an API key of any scope may call it.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | string | no | The file format. csv (the default, text/csv): one row per finding. json (application/json): the full finding records. sarif (application/sarif+json): SARIF 2.1.0, for code-scanning tools. |
state | string | no | Only findings in this state: open, patched, accepted_risk or false_positive. all (the default) does not filter. Any other value matches nothing. |
severity | string | no | Only findings of this severity. One of: critical, high, medium, low, info. |
priority | string | no | Only findings of this priority level. One of: P0, P1, P2, P3. |
source | string | no | Only findings first reported by this kind of run. One of: review, pentest. |
repoId | string | no | Only findings in this repository. |
file | string | no | Only findings in exactly this file: the path relative to the repository root, as in finding.location.file. A leading ./ or / is ignored. Combine with repoId when several repositories share paths. |
q | string | no | Text to look for, ignoring case, in the title, the rule id, the file path, the repository name and the CWE ids. |
sort | string | no | severity (the default): most severe first, then most recently first seen. priority: most urgent first, then most severe. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/export"
Answer (200, text/csv)
The file, in the format asked for.
csv (text/csv; charset=utf-8): a header row, then one row per finding, lines ending in CRLF. The columns, in order: id, severity, state, assurance (proven, verified or unverified), title, weakness (the CWE ids, separated by spaces), repository, source (review or pentest), pull_request, file (the manifest for a dependency finding), line, first_seen, resolved_at, resolved_in (the commit), state_reason, decided_by, fix_pull_request, issue, fix_proven (yes when the pull request in fix_pull_request is a fix proven by reproduction, no when it is a fix proposed without proof, empty when there is none), expert_review (requested, confirmed, adjusted or rejected when a Nullgap security researcher was asked to review the finding, empty otherwise). A value with no content is an empty cell. A cell that would start with =, +, -, @, a tab or a carriage return is prefixed with an apostrophe, so a spreadsheet does not read it as a formula.
json (application/json; charset=utf-8): one object, { "exportedAt": "<date and time>", "findings": [ ... ] }, where each entry is a full finding record exactly as the single-finding route returns it.
sarif (application/sarif+json; charset=utf-8, file extension .sarif): a SARIF 2.1.0 log with one run. tool.driver is Nullgap with one rule per distinct rule id (its properties carry tags with the CWE and CVE ids and a security-severity score). Each result has ruleId, level (error for critical and high, warning for medium, note for low and info), message.text (the title, the description and the suggested fix), one location (file and lines; the manifest for a dependency finding), partialFingerprints.nullgapFingerprint, and properties with status, confidence, source, module, findingId, state, assurance, repository and pullRequest. A finding in the state false_positive or accepted_risk is still exported, with a suppressions entry whose justification is the reason that was given.
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | format is not csv, json or sarif, or severity, priority or sort is not one of its allowed values. |
| 403 | forbidden | A signed-in member who is not an admin or owner asks for the export. |
#Get the evidence bundle
GET /api/orgs/{org}/findings/{id}/evidence
Returns everything that backs one finding in one document: the finding, how far it was checked, the chain of evidence, the reproduction when there is one, the patch, the privacy record of the run that reported it, and the notes. The bundle carries its own SHA-256 so it can be shown to be unaltered. It is generated on each call, so generatedAt and sha256 differ from call to call. With format=md the answer is not JSON but a Markdown file (text/markdown; charset=utf-8), sent as an attachment named nullgap-evidence-<finding id>.md, that holds the same content for reading.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | string | no | json (the default) for the bundle as JSON, md for a Markdown file. Any value other than md gives JSON. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/evidence"
Answer (200, application/json)
A EvidenceBundle object.
{
"schema": "nullgap.evidence/1",
"generatedAt": "2026-11-16T09:30:00.000Z",
"hashCovers": "SHA-256 of this bundle in its JSON form without the sha256 and generatedAt fields, serialised with keys sorted at every level and no whitespace.",
"finding": {
"id": "fnd_8f3a2c9d1b4e",
"title": "SQL injection in order lookup",
"severity": "high",
"cwe": [
"CWE-89"
],
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"repository": "acme/shop",
"source": "review",
"pullRequest": 128,
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1"
},
"assurance": {
"level": "proven",
"statement": "A probe was run against this code in an isolated sandbox and reproduced the flaw. The command, its output and the probe files are in the Proof section."
},
"evidence": [
{
"kind": "reasoning",
"summary": "The id reaches the query without validation.",
"detail": "req.query.id flows from src/routes.js:18 into db.query at src/orders.js:42."
}
],
"proof": {
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"files": "// probe.js\nconst res = await fetch(base + \"/orders?id=1 OR 1=1\");"
},
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"verified": true,
"description": "Pass the order id as a bound parameter."
},
"run": {
"id": "rev_2a6d9f1c4b7e",
"kind": "review",
"commit": "4e8a1c3b5d7f9a0b2c4d6e8f0a1b3c5d7e9f1a2b",
"finishedAt": "2026-11-16T09:30:00.000Z",
"privacy": {
"zeroRetention": true,
"identifiersMasked": 14
}
},
"expertReview": {
"status": "confirmed",
"decidedAt": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high",
"requestedAt": "2026-11-16T09:30:00.000Z"
},
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"sha256": "3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855e"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No finding with this id exists in the organisation. |
#Add a note
POST /api/orgs/{org}/findings/{id}/notes
Adds a note to the finding, signed with the caller, and returns the finding with the note in notes. A finding keeps its latest 100 notes. Notes cannot be edited or removed.
Who may call it: An API key with the write scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
text | string | yes | The note, 1 to 2000 characters after surrounding spaces are removed. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Confirmed with the orders team, fix planned for this sprint."}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/notes"
Answer (200, application/json)
A FindingRecord object.
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | text is missing, not a string, empty, or longer than 2000 characters. |
| 404 | not_found | No finding with this id exists in the organisation. |
#Request an expert review
POST /api/orgs/{org}/findings/{id}/expert-review
Asks a Nullgap security researcher to review this finding (the expert review add-on). Admins only. The finding gets validation.status pending; when the researcher decides, validation says what was decided, the researcher's notes appear in notes under the name Nullgap researcher, and a finding.expert_reviewed webhook event is sent. Works for findings from pull request reviews and from pentests; the finding must be open. Asking again for a finding that is already waiting changes nothing and answers 200. A finding a researcher has already reviewed answers 409 unless again is true. The request is your consent for a Nullgap researcher to read the finding, its evidence and its code. Who the researcher is is not disclosed.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
note | string | no | What you want the researcher to check, up to 1000 characters. Optional. |
again | boolean | no | Ask for another look at a finding a researcher has already reviewed. The earlier decision is kept until the new one is made. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"note":"Please check whether the admin check in middleware.js stops this.","again":false}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/expert-review"
Answer (200, application/json)
A ExpertReviewRequestResult object.
{
"requested": 1,
"alreadyPending": 0,
"alreadyReviewed": 0,
"findings": [
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | note is longer than 1000 characters, or again is not a boolean. |
| 403 | forbidden | The caller is not an admin. |
| 403 | add_on_required | The workspace does not have the expert review add-on. Contact us to add it. |
| 404 | not_found | No finding with this id exists in the organisation. |
| 409 | already_reviewed | A researcher has already reviewed the finding and again is not true. |
| 409 | not_open | The finding is not open. |
#Cancel an expert review request
DELETE /api/orgs/{org}/findings/{id}/expert-review
Withdraws your request for an expert review of this finding, as long as a researcher has not opened it yet. A finding that had an earlier decision gets it back. Admins only. Takes no body.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Example request
curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/expert-review"
Answer (200, application/json)
A ExpertReviewCancelResult object.
{
"cancelled": 1,
"kept": 0,
"findings": [
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The caller is not an admin. |
| 404 | not_found | No finding with this id exists in the organisation. |
| 409 | not_requested | There is no request of yours waiting on the finding. |
| 409 | review_started | A researcher has already opened the finding. |
#Request an expert review of a pentest report
POST /api/orgs/{org}/pentests/{id}/expert-review
Asks a Nullgap security researcher to review every open proven or verified finding of a finished pentest. Admins only. Findings already waiting are left as they are; findings already reviewed are left as they are unless again is true. When the last finding is decided, the pentest's reports are revised once to carry the reviewed result. The request is your consent for a Nullgap researcher to read those findings, their evidence and their code.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
note | string | no | What you want the researcher to check, up to 1000 characters. Optional. |
again | boolean | no | Also ask for another look at findings a researcher has already reviewed. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"note":"Focus on the payment flows.","again":false}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/expert-review"
Answer (200, application/json)
A ExpertReviewRequestResult object.
{
"requested": 1,
"alreadyPending": 0,
"alreadyReviewed": 0,
"findings": [
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | note is longer than 1000 characters, or again is not a boolean. |
| 403 | forbidden | The caller is not an admin. |
| 403 | add_on_required | The workspace does not have the expert review add-on. Contact us to add it. |
| 404 | not_found | No pentest of this organisation has that id. |
| 409 | not_finished | The pentest has not finished. |
| 409 | nothing_to_review | The pentest has no open proven or verified findings. |
| 409 | already_reviewed | Every such finding has already been reviewed and again is not true. |
#Cancel an expert review request for a pentest
DELETE /api/orgs/{org}/pentests/{id}/expert-review
Withdraws the requests waiting on this pentest's findings that a researcher has not opened yet. Findings a researcher has already opened stay in review and are counted in kept. Admins only. Takes no body.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/expert-review"
Answer (200, application/json)
A ExpertReviewCancelResult object.
{
"cancelled": 1,
"kept": 0,
"findings": [
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The caller is not an admin. |
| 404 | not_found | No pentest of this organisation has that id. |
| 409 | not_requested | No request of yours is waiting on the pentest's findings. |
| 409 | review_started | A researcher has already opened every requested finding. |
#List findings
GET /api/orgs/{org}/findings
Lists the organisation’s findings, most severe first unless sort=priority is given. One flaw is one finding however many runs reported it: see sightings on each. Findings that were held back because of an earlier decision are not in this list; they are under the suppressions route.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
state | string | no | Only findings in this state: open, patched, accepted_risk or false_positive. all (the default) does not filter. Any other value matches nothing. |
severity | string | no | Only findings of this severity. One of: critical, high, medium, low, info. |
priority | string | no | Only findings of this priority level. One of: P0, P1, P2, P3. |
source | string | no | Only findings first reported by this kind of run. One of: review, pentest. |
repoId | string | no | Only findings in this repository. |
file | string | no | Only findings in exactly this file: the path relative to the repository root, as in finding.location.file. A leading ./ or / is ignored. Combine with repoId when several repositories share paths. |
q | string | no | Text to look for, ignoring case, in the title, the rule id, the file path, the repository name and the CWE ids. |
sort | string | no | severity (the default): most severe first, then most recently first seen. priority: most urgent first, then most severe. |
limit | integer | no | How many to return, 1 to 200. Default 50. |
offset | integer | no | How many to skip from the start. Default 0. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings?limit=20"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of FindingRecord | yes | The findings, at most limit of them. |
total | integer | yes | How many match in all, before limit and offset. |
{
"items": [
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
],
"total": 42
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | severity, priority or sort is not one of its allowed values. |
#Triage several findings
POST /api/orgs/{org}/findings/bulk
Applies one decision, with one reason, to several findings: the ones listed in ids, and with like that finding together with every finding like it (same repository, same weakness class, same dangerous statement, in any state). Each finding is changed, audited and remembered exactly as a single change would be. A finding already in that state with that reason is skipped. Send expect with like to be sure nothing is changed if the group has grown or shrunk since you looked.
Who may call it: An API key with the write scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of string | no | The findings to change, up to 500. Ids that do not exist are reported under skipped. |
like | string | no | A finding id. That finding and every finding like it are added to the ones to change. |
expect | integer | no | Used with like: how many findings you expect that to be, the finding itself included. If the number is now different, nothing is changed. |
state | string | yes | The state to move to. open reopens a finding. patched records that it was fixed. accepted_risk and false_positive dismiss it and need a reason. |
reason | string | no | Why. Required for accepted_risk and false_positive, optional otherwise. Up to 2000 characters. |
reviewAt | string or null | no | For accepted_risk only: a date in the future on which the acceptance is to be looked at again. After it the finding is raised again when found. Leave out, or send null, for none. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids":["fnd_8f3a2c9d1b4e"],"like":"fnd_8f3a2c9d1b4e","expect":3,"state":"false_positive","reason":"The id is validated as an integer two lines above.","reviewAt":null}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/bulk"
Answer (200, application/json)
A BulkTriageResult object.
{
"changed": [
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
],
"skipped": [
{
"id": "fnd_0b4d7e1a9c3f",
"why": "Already in this state with this reason"
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | ids is not a list of up to 500 strings, or neither ids nor like selects a finding that exists. |
| 400 | bad_request | state is missing or not one of the four states; a dismissal has no reason; reason is longer than 2000 characters; or reviewAt is given for a state other than accepted_risk, is not a date, or is not in the future. |
| 404 | not_found | The finding named in like does not exist. |
| 409 | changed | The number of findings like the one in like is no longer the number given in expect. Nothing was changed. |
#List held-back findings
GET /api/orgs/{org}/suppressions
Lists the findings that runs produced and Nullgap did not raise, because the team had already dismissed the same finding or code that is the same. Each entry says which decision it rests on and why it counts as the same. Most recently held back first.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
state | string | no | active (the default): still held back. restored: brought back since. all: both. |
repoId | string | no | Only those found in this repository. |
sourceId | string | no | Only those held back by this run: the id of a review or a pentest. |
source | string | no | Used with sourceId to say which kind of run it names. Ignored without sourceId. |
limit | integer | no | How many to return, 1 to 200. Default 50. |
offset | integer | no | How many to skip from the start. Default 0. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/suppressions?limit=20"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of SuppressedFinding | yes | The held-back findings, at most limit of them. |
total | integer | yes | How many match in all, before limit and offset. |
{
"items": [
{
"id": "sup_6e2b9d0a4c7f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"kind": "pattern",
"decision": "false_positive",
"decidedBy": "dana@acme.example",
"decidedAt": "2026-10-02T11:20:00.000Z",
"reason": "The id is validated as an integer two lines above.",
"dismissedFindingId": "fnd_5a0e3c8b7d19",
"why": [
"Same weakness class and the same dangerous statement."
],
"similarity": 0.96,
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"firstAt": "2026-11-03T08:12:00.000Z",
"lastAt": "2026-11-16T09:30:00.000Z",
"restoredAt": "2026-11-16T09:30:00.000Z",
"restoredBy": "dana@acme.example",
"restoredFindingId": "fnd_8f3a2c9d1b4e"
}
],
"total": 42
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | state is not active, restored or all. |
#Restore a held-back finding
POST /api/orgs/{org}/suppressions/{id}/restore
Brings a held-back finding back. What happens depends on its kind. same_finding: the dismissed finding itself is reopened, which also raises everything its decision was holding back. pattern: this entry becomes an open finding of its own and the remembered pattern is removed, so everything else that pattern was holding back is raised too; the finding that was dismissed first keeps its state.
Who may call it: An API key with the write scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the held-back record, such as sup_6e2b9d0a4c7f. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/suppressions/sup_6e2b9d0a4c7f/restore"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
finding | FindingRecord | yes | The finding that is now open: the reopened one, or the new one this entry became. |
alsoRestored | integer | yes | How many other held-back findings came back with it. |
{
"finding": {
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
},
"alsoRestored": 1
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No held-back record with this id exists, or the dismissed finding it points to no longer exists. |
| 409 | already_restored | This entry has already been brought back. |
#Get a finding
GET /api/orgs/{org}/findings/{id}
Returns one finding with its evidence, its priority, the decision taken about it and the runs that reported it. This answer also carries trace: the data-flow path, the call path from an entry point, a diagram, the proof, the independent check's verdict and the history of decisions, each read from what was recorded. A part that was not recorded is null and named in trace.missing.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e"
Answer (200, application/json)
A FindingRecord object.
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No finding with this id exists in the organisation. |
#Triage a finding
PATCH /api/orgs/{org}/findings/{id}
Changes what the team has decided about a finding, and records who decided and why. Dismissing a finding (accepted_risk or false_positive) needs a reason, and is remembered: the same finding, and code that is the same, is held back in later runs and listed under suppressions instead of being raised again. Moving a dismissed finding to another state forgets that, and raises whatever the decision was holding back. Every change is written to the audit log, sent to webhooks as finding.state_changed, and passed on to a linked Jira issue when status sync is on. The same checks apply to decisions made in the console and from Slack.
Who may call it: An API key with the write scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
state | string | yes | The state to move to. open reopens a finding. patched records that it was fixed. accepted_risk and false_positive dismiss it and need a reason. |
reason | string | no | Why. Required for accepted_risk and false_positive, optional otherwise. Up to 2000 characters. |
reviewAt | string or null | no | For accepted_risk only: a date in the future on which the acceptance is to be looked at again. After it the finding is raised again when found. Leave out, or send null, for none. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"state":"false_positive","reason":"The id is validated as an integer two lines above.","reviewAt":null}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e"
Answer (200, application/json)
A FindingRecord object.
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | state is missing or not one of the four states; a dismissal has no reason; reason is longer than 2000 characters; or reviewAt is given for a state other than accepted_risk, is not a date, or is not in the future. |
| 404 | not_found | No finding with this id exists in the organisation. |
#List similar findings
GET /api/orgs/{org}/findings/{id}/similar
Returns the other findings in the same repository that are like this one (same weakness class, same dangerous statement), the dismissals already taken on them, and how many later findings the decision on this one is holding back. Use it before deciding, and to choose between one decision and a bulk decision with like.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/similar"
Answer (200, application/json)
A SimilarFindings object.
{
"determined": true,
"similar": [
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
],
"decisions": [
{
"findingId": "fnd_5a0e3c8b7d19",
"title": "SQL injection in invoice lookup",
"file": "src/invoices.js",
"decision": "false_positive",
"reason": "The id is validated as an integer two lines above.",
"by": "dana@acme.example",
"at": "2026-10-02T11:20:00.000Z",
"reviewAt": "2027-02-01T00:00:00.000Z"
}
],
"suppressedByThis": 2
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No finding with this id exists in the organisation. |
#File an issue
POST /api/orgs/{org}/findings/{id}/issue
Creates an issue for the finding in the organisation’s connected issue tracker and returns the finding with externalIssueUrl set. A finding has one issue: if it already has one, nothing is created and the finding is returned as it is, whichever tracker is named.
Who may call it: An API key with the write scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
tracker | string | yes | The tracker to file the issue in. It must be connected under integrations. One of: jira, linear. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tracker":"jira"}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/issue"
Answer (200, application/json)
A FindingRecord object.
{
"id": "fnd_8f3a2c9d1b4e",
"orgId": "org_1d4c7b9a2e5f",
"repoId": "repo_4b7e1a9c2d3f",
"repoFullName": "acme/shop",
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"finding": {
"id": "f_3c9e1a7b2d4f",
"module": "code",
"ruleId": "sql-injection",
"title": "SQL injection in order lookup",
"description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
"severity": "high",
"confidence": 0.9,
"cwe": [
"CWE-89"
],
"cve": [
"CVE-2021-23337"
],
"location": {
"file": "src/orders.js",
"startLine": 42,
"endLine": 44,
"snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
},
"package": {
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true
},
"source": "builtin",
"status": "proven",
"evidence": [
{
"kind": "probe",
"summary": "The probe read another customer’s order by changing the id in the query string.",
"detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
"command": "node probe.js",
"exitCode": 0,
"output": "REPRODUCED: 3 rows returned for a single order id",
"proof": {
"outcome": "reproduced",
"attempts": 1,
"missing": "A running PostgreSQL database",
"dependencies": "installed",
"controlHeld": true,
"repeatable": true,
"audited": true,
"variantHeld": true,
"modelsAsked": 2,
"declined": 1
}
}
],
"remediation": "Pass the id as a bound parameter instead of building the SQL text.",
"patch": {
"diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n- db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+ db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
"description": "Pass the order id as a bound parameter.",
"verified": true,
"verification": {
"probePassed": true,
"testsPassed": true,
"log": "probe: exit 1 (safe)\ntests: 48 passed",
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"refused": [
"The patch removes the endpoint instead of fixing it."
]
},
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"unproven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"proof": "no_probe",
"accepted": true,
"independentReviewer": true
}
},
"fingerprint": "5b1f0c9a7e2d4a61",
"triage": {
"shape": {
"v": 1,
"families": [
"sql-injection"
],
"file": "src/orders.js",
"fn": "getOrder",
"indexed": true,
"anchor": "db . query ( `…` )",
"sink": "db . query ( `…` )",
"ordinal": 0,
"source": "const id = req . query . id",
"entry": "app . get ( \"\" , getOrder )",
"near": "9c41f0a7d2b3",
"wide": [
"03af19c2"
],
"callers": [
"listOrders:5e7a01bc"
],
"family": "b7d2e94a10c6"
},
"exposure": {
"reachable": "yes",
"entryPoint": {
"kind": "http",
"name": "getOrder",
"file": "src/routes.js",
"line": 18,
"method": "GET",
"route": "/orders"
},
"authentication": "none",
"surface": "internet",
"attackerControlled": "yes",
"basis": [
"GET /orders is registered in src/routes.js:18 with no sign-in check."
]
}
},
"triageVerdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
}
},
"state": "open",
"stateReason": "Internal tool, reachable only over the VPN.",
"stateBy": "dana@acme.example",
"firstSeenAt": "2026-11-10T14:05:00.000Z",
"resolvedAt": "2026-11-16T09:30:00.000Z",
"remediation": {
"runId": "run_7c1e4a9b2d6f",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
},
"externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
"notes": [
{
"author": "dana@acme.example",
"text": "Confirmed with the orders team, fix planned for this sprint.",
"at": "2026-11-16T09:30:00.000Z",
"via": "console"
}
],
"resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
"validation": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "Reproduced against staging with a second account.",
"severityBefore": "medium",
"requestedAt": "2026-11-16T09:30:00.000Z",
"requestedBy": "Dana Lee",
"scope": "finding",
"requestNote": "Please check whether the admin check in middleware.js stops this.",
"openedAt": "2026-11-16T09:30:00.000Z",
"previous": {
"status": "confirmed",
"at": "2026-11-16T09:30:00.000Z",
"note": "string",
"severityBefore": "high"
}
},
"priority": {
"level": "P0",
"fromSeverity": "P1",
"proven": true,
"reasons": [
"Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
]
},
"sightings": [
{
"source": "review",
"sourceId": "rev_2a6d9f1c4b7e",
"prNumber": 128,
"at": "2026-11-16T09:30:00.000Z"
}
],
"riskReviewAt": "2027-02-01T00:00:00.000Z",
"earlierDecision": {
"findingId": "fnd_5a0e3c8b7d19",
"decision": "false_positive",
"note": "Raised although it resembles a dismissed finding: this one was reproduced."
},
"stateHistory": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"from": "open",
"to": "accepted_risk",
"reason": "Internal tool, reachable only over the VPN.",
"reviewAt": "2027-02-01T23:59:59.000Z",
"via": "one decision for 5 findings"
}
],
"fixRuns": [
{
"runId": "run_7c1e4a9b2d6f",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"status": "completed",
"outcome": "fixed",
"prUrl": "https://github.com/acme/shop/pull/131"
}
],
"trace": {
"dataFlow": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"entryPoint": "GET /orders (src/orders/list.ts:22)",
"sink": "db.query in src/orders/repo.ts:57",
"confirmedBy": "independent-check"
},
"callPath": {
"steps": [
{
"n": 1,
"text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
"file": "src/orders/list.ts",
"line": 22
}
],
"basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
},
"diagram": "flowchart TD\n s1[\"GET /orders reads sort\"]\n s2[\"db.query\"]\n s1 --> s2",
"proof": {
"kind": "sandbox",
"summary": "The probe read another customer's order by changing the sort column.",
"reproduced": true,
"outcome": "reproduced"
},
"occurrences": 3,
"skill": "injection-review",
"verdict": {
"verdict": "true_positive",
"confidence": "high",
"severity": "high",
"severityBefore": "critical",
"severityReasons": [
"Needs a signed-in account, which any customer can create."
],
"mitigations": [
"The id is parsed as an integer in the router, which does not stop the injection in the sort column."
],
"weaknessFits": true,
"reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
"confirmedPath": [
"src/orders/list.ts:22 reads req.query.sort"
],
"at": "2026-11-16T09:30:00.000Z"
},
"history": [
{
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example",
"what": "State set to accepted risk",
"detail": "Behind the office network until the migration in March."
}
],
"missing": [
"No call path from an entry point was recorded."
]
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | tracker is not jira or linear. |
| 400 | not_connected | That tracker is not connected for the organisation. |
| 400 | tracker_rejected | The tracker refused to create the issue (a wrong project, a revoked token). The message is the tracker’s own. |
| 404 | not_found | No finding with this id exists in the organisation. |
#Get a fix prompt
GET /api/orgs/{org}/findings/{id}/fix-prompt
Returns a piece of text that describes the finding and how to fix it, written to be handed to a coding assistant or a developer working in a local checkout. Nothing is started or changed.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id of the finding, such as fnd_8f3a2c9d1b4e. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/fix-prompt"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
prompt | string | yes | The hand-off text. |
{
"prompt": "Fix the SQL injection in src/orders.js at line 42 of acme/shop. The order id from the query string is placed into the SQL text. Pass it as a bound parameter, then run the tests."
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No finding with this id exists in the organisation. |
#Objects
The objects the operations above take and return.
#EvidenceBundle
Everything that backs one finding, in one document you can keep or hand to an auditor.
| Field | Type | Always present | Description |
|---|---|---|---|
schema | string | yes | The format of this document. |
generatedAt | string | yes | When this copy was produced. Not covered by sha256. |
hashCovers | string | yes | What sha256 is taken over, in words. |
finding | object | yes | The finding, in summary. |
finding.id | string | yes | The finding id. |
finding.title | string | yes | Its title. |
finding.severity | string | yes | Its severity. One of: critical, high, medium, low, info. |
finding.cwe | array of string | yes | Its weakness classes. Empty when none. |
finding.description | string | yes | What is wrong. |
finding.remediation | string or null | yes | How to fix it. |
finding.location | Location or null | yes | |
finding.repository | string | yes | The repository. |
finding.source | string | yes | What kind of run first reported it. One of: review, pentest. |
finding.pullRequest | integer or null | yes | The pull request it was found on. |
finding.state | string | yes | What the team decided. One of: open, patched, accepted_risk, false_positive. |
finding.stateReason | string or null | yes | The reason given with that decision. |
finding.firstSeenAt | string | yes | When it was first reported. |
finding.resolvedAt | string or null | yes | When it left the open state. |
finding.resolvedInSha | string or null | yes | The commit in which the flagged code was no longer present. |
assurance | object | yes | How far the finding was checked. |
assurance.level | string | yes | How far the finding was checked. proven: a probe reproduced it (finding.status is proven or fixed). verified: an independent review could not refute it, and it was not reproduced. unverified: anything else. |
assurance.statement | string | yes | The same, as a sentence you can quote. |
evidence | array of object | yes | The reasoning and checks recorded for the finding, in order. |
evidence[].kind | string | yes | What sort of step it is. See Evidence.kind. |
evidence[].summary | string | yes | What the step showed. |
evidence[].detail | string or null | yes | The longer text. Always null on probe steps: the probe files are under proof. |
proof | object or null | yes | The reproduction: the last probe that ran a command. null unless the assurance level is proven. |
proof.command | string or null | yes | The command that reproduced the flaw. |
proof.exitCode | integer or null | yes | What it exited with. |
proof.output | string or null | yes | What it printed. |
proof.files | string or null | yes | The probe files. |
patch | object or null | yes | The fix written for the finding. null when there is none. |
patch.diff | string | yes | The unified diff. |
patch.verified | boolean | yes | Whether it passed its checks. |
patch.description | string | yes | What it changes. |
run | object or null | yes | The run that first reported the finding. null when that run is no longer stored. |
run.id | string | yes | The id of the review or pentest. |
run.kind | string | yes | Which of the two it is. One of: review, pentest. |
run.commit | string or null | yes | The commit that was examined: the head commit of the pull request for a review, the ref for a pentest. |
run.finishedAt | string or null | yes | When the run ended. |
run.privacy | RunPrivacy or null | yes | |
expertReview | object | no | The review by a Nullgap security researcher. Present only when there is one. |
expertReview.status | string | yes | Where the review stands. One of: pending, confirmed, adjusted, rejected. |
expertReview.decidedAt | string or null | yes | When the researcher decided. null while pending. |
expertReview.note | string or null | yes | What the researcher wrote. |
expertReview.severityBefore | string or null | yes | The severity before an adjustment. |
expertReview.requestedAt | string or null | yes | When your workspace asked for it. null for a review under a researcher-validation contract. |
notes | array of FindingNote | yes | Replies and comments about the finding, oldest first. Empty when there are none. |
history | array of FindingStateChange | yes | Every recorded change of the finding's state, oldest first. Empty when none was recorded. |
sha256 | string | yes | The SHA-256, in hexadecimal, of the canonical JSON of this bundle with the sha256 and generatedAt fields removed (keys sorted at every level, no whitespace). generatedAt is left out so every download of an unchanged finding carries the same hash. Recompute it to see that the bundle is unaltered. |
#FindingRecord
A finding as your organisation holds it: the flaw (finding), where it came from, what the team decided (state), and what was done about it. Internal details are left out of every answer: whether the pull request came from a fork, who opened it, and which researcher validated the finding.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id of the finding. Use it in every route that takes a finding id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository it was found in. |
repoFullName | string | yes | The name of that repository. |
source | string | yes | What kind of run first reported it. One of: review, pentest. |
sourceId | string | yes | The id of that review or pentest. |
prNumber | integer or null | yes | The pull request it was found on. null when it did not come from a pull request. |
finding | Finding | yes | The flaw itself. finding.status says how far it was checked. |
state | string | yes | What the team has decided about it. open: to be dealt with. patched: fixed. accepted_risk: real, and accepted. false_positive: not a real issue. This is separate from finding.status, which says how far Nullgap checked it. |
stateReason | string or null | yes | The reason given with the last decision. |
stateBy | string or null | yes | Who last changed the state: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when nobody has. |
firstSeenAt | string | yes | When it was first reported. |
resolvedAt | string or null | yes | When it last left the open state. null while open. |
remediation | object or null | yes | The latest fix run for this finding. null when none was started. |
remediation.runId | string | yes | The id of the fix run. |
remediation.status | string | yes | Where that run stands. One of: queued, running, completed, failed, skipped, cancelled. |
remediation.outcome | string or null | yes | How it ended. null until it has. unverified means a fix was proposed as a draft pull request but was not proven by reproducing the flaw: it is not a verified fix. |
remediation.prUrl | string or null | yes | The pull request the run opened, when it opened one. |
externalIssueUrl | string or null | yes | The issue filed for it in your tracker, when one was. |
notes | array of FindingNote | no | Replies and comments about this finding, oldest first. The latest 100 are kept. Absent when there are none. |
resolvedInSha | string or null | no | The commit in which the flagged code was no longer present. Set when a review closed the finding as patched; absent or null otherwise. |
validation | FindingValidation | no | The check by a Nullgap researcher, for workspaces that have it. Absent when the finding is not subject to it. |
priority | Priority | yes | How urgent it is. Always present in answers: records stored before priorities existed get theirs worked out on the way out. |
sightings | array of FindingSighting | no | Every run that reported this flaw, oldest first, up to the latest 50. One flaw is one finding, however often and by whichever route it is found. Absent on findings reported once before sightings were recorded. |
riskReviewAt | string or null | no | Accepted risks only: the date the acceptance is to be looked at again. After it the finding is raised again when found. |
earlierDecision | object or null | no | Set when this finding resembles one the team dismissed earlier but was raised all the same, with the rule that required it. Cleared as soon as someone decides about this finding. |
earlierDecision.findingId | string | yes | The finding that was dismissed earlier. |
earlierDecision.decision | string | yes | What was decided about it. One of: false_positive, accepted_risk. |
earlierDecision.note | string | yes | Why this one was raised all the same. |
stateHistory | array of FindingStateChange | no | Every change of state, oldest first, the latest 50 kept. state, stateBy and stateReason hold the latest only. Absent when the state has not changed since the trail was introduced. |
fixRuns | array of FindingFixRun | no | The fix runs started for this finding, oldest first, the latest 20 kept. Absent when none was recorded. |
trace | FindingTrace | no | What backs the finding, laid out for a reader: the data-flow path, the call path, a diagram, the proof, the verdict and the history. Present when one finding is read (GET /findings/{id}); lists leave it out. |
#ExpertReviewRequestResult
What an expert review request did.
| Field | Type | Always present | Description |
|---|---|---|---|
requested | integer | yes | Findings now waiting for a researcher because of this request. |
alreadyPending | integer | yes | Findings that were already waiting; nothing changed for them. |
alreadyReviewed | integer | yes | Findings already reviewed and left as they were. Send again: true to ask for another look. |
findings | array of FindingRecord | yes | The findings the request covers, as they are now. |
#ExpertReviewCancelResult
What cancelling an expert review request did.
| Field | Type | Always present | Description |
|---|---|---|---|
cancelled | integer | yes | Requests withdrawn. |
kept | integer | yes | Requests a researcher had already opened, which stay in review. |
findings | array of FindingRecord | yes | The findings that had a request, as they are now. |
#BulkTriageResult
The result of one decision applied to several findings.
| Field | Type | Always present | Description |
|---|---|---|---|
changed | array of FindingRecord | yes | The findings that were changed, as they are now. |
skipped | array of object | yes | The findings left as they were, each with why. |
skipped[].id | string | yes | The finding id. |
skipped[].why | string | yes | Why it was left as it was: Not found, or Already in this state with this reason. |
#SuppressedFinding
A finding that a run produced and Nullgap did not raise, because the team had already decided about it or about code that is the same. Nothing is held back silently: every one is listed here with why and whose decision it rests on, and anyone on the team can bring it back.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id of this held-back record. |
repoId | string | yes | The repository it was found in. |
repoFullName | string | yes | The name of that repository. |
finding | Finding | yes | The flaw that was found and not raised. |
priority | Priority | yes | How urgent it would be. Always present in answers. |
kind | string | yes | same_finding: the very finding that was dismissed, found again. pattern: other code that matches the dismissed code. |
decision | string | yes | The earlier decision it rests on. One of: false_positive, accepted_risk. |
decidedBy | string or null | yes | Who took that decision. |
decidedAt | string or null | yes | When that decision was taken. |
reason | string or null | yes | The reason given with that decision. |
dismissedFindingId | string | yes | The finding the decision was taken on. |
why | array of string | yes | Why it counts as the same, one statement per entry. |
similarity | number or null | yes | How alike the surrounding function is, from 0 to 1. null for same_finding. |
sightings | array of FindingSighting | yes | Every run that found it and held it back, oldest first. |
firstAt | string | yes | When it was first held back. |
lastAt | string | yes | When it was last found and held back. |
restoredAt | string or null | yes | When someone brought it back. null while it is held back. |
restoredBy | string or null | yes | Who brought it back. |
restoredFindingId | string or null | yes | The finding it became when it was brought back. |
#SimilarFindings
Findings like one finding, and what was decided about them.
| Field | Type | Always present | Description |
|---|---|---|---|
determined | boolean | yes | False when the finding carries no code shape (it predates them, or it is not about code), so nothing can be said about similar findings. |
similar | array of FindingRecord | yes | Other findings in the same repository with the same weakness class and the same dangerous statement, in any state. |
decisions | array of object | yes | Dismissals already taken on findings like this one, newest first. |
decisions[].findingId | string | yes | The finding the decision was taken on. |
decisions[].title | string | yes | Its title. |
decisions[].file | string or null | yes | The file it is in. |
decisions[].decision | string | yes | What was decided. One of: false_positive, accepted_risk. |
decisions[].reason | string or null | yes | The reason given. |
decisions[].by | string or null | yes | Who decided. |
decisions[].at | string or null | yes | When. |
decisions[].reviewAt | string or null | yes | For an accepted risk: when it is to be looked at again. |
suppressedByThis | integer | yes | How many later findings are currently held back because of the decision on this finding. |
#Location
Where in the code a finding is.
| Field | Type | Always present | Description |
|---|---|---|---|
file | string | yes | Path of the file, relative to the repository root, with forward slashes. |
startLine | integer | yes | The first flagged line, counted from 1. |
endLine | integer | no | The last flagged line, when the finding spans several. |
snippet | string | no | The flagged code. Keys, tokens and passwords in it are masked. |
#RunPrivacy
How the AI processing of one run was protected. Null on a run until it has made its first Nullgap AI call.
| Field | Type | Always present | Description |
|---|---|---|---|
zeroRetention | boolean | yes | True when every Nullgap AI call in the run was confirmed as keeping no data afterwards. |
identifiersMasked | integer | yes | How many identifiers (names, e-mail addresses, numbers) were replaced with made-up values before Nullgap AI saw them. |
#FindingNote
A reply or comment about a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
author | string | yes | Who wrote it: an email address, a code host login, or api-key:<name> for a note added with an API key. |
text | string | yes | The note, up to 2000 characters. |
at | string | yes | When it was written. |
via | string | yes | Where it was written. code-host: a reply on the pull request. console: the console or this API. researcher: by a Nullgap security researcher during an expert review; author is then always Nullgap researcher. |
#FindingStateChange
One change of a finding's state.
| Field | Type | Always present | Description |
|---|---|---|---|
at | string | yes | When the state changed. |
by | string or null | yes | Who changed it: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when not known. |
from | string or null | yes | The state before. null when the finding came into being with this change (brought back from the held-back list). One of: open, patched, accepted_risk, false_positive, null. |
to | string | yes | The state after. One of: open, patched, accepted_risk, false_positive. |
reason | string or null | yes | The reason given with the change. |
reviewAt | string or null | yes | Accepted risks: the review date set with the decision. |
via | string or null | yes | How the change came about when it was not a single decision in the console. |
#Finding
A flaw as the engine reported it: what it is, where, how serious, and what backs it. Text in evidence[].summary never names the AI behind it other than as Nullgap AI.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id the engine gave this finding. To address a finding in the API use the id of the record that carries it (fnd_…), not this one. |
module | string | yes | The part of Nullgap that produced it: code, deps (dependencies), redteam or another. |
ruleId | string | yes | The rule or check that raised it. |
title | string | yes | A one-line name for the flaw. |
description | string | yes | What is wrong and why it matters. |
severity | string | yes | How serious the flaw is if exploited. One of: critical, high, medium, low, info. |
confidence | number | yes | How confident the engine is that the finding is real, from 0 to 1. |
cwe | array of string | no | The weakness classes it belongs to. |
cve | array of string | no | Published vulnerabilities it corresponds to, mostly on dependency findings. |
location | Location | no | Where in the code it is. Absent on findings that are not about a line of code. |
package | PackageRef | no | The package concerned, on dependency findings. |
source | string | yes | A label for the check that raised it. Findings that are another place of an already proven flaw carry variant; a finding raised by a skill carries llm-skill: followed by the skill id. |
status | string | yes | How far the finding was checked. The product shows this as one of three assurance levels: proven and fixed are proven (a probe reproduced the flaw; fixed adds that a patch exists and passed verification on a fresh checkout), verified is verified (an independent review of the code could not refute it, but it was not reproduced), and candidate is unverified (flagged, the independent review did not complete, not reproduced: a lead to confirm). rejected (an independent check called it a false positive) is never stored, so it does not appear in answers. |
evidence | array of Evidence | yes | The reasoning and checks recorded for the finding, in order. |
remediation | string | no | How to fix it, in words. |
patch | Patch | no | The fix written for it, when one has been. |
fingerprint | string | yes | A value that stays the same for this flaw across runs. |
triage | FindingTriage | no | The shape of the flagged code and how exposed it is. |
triageVerdict | TriageVerdict | no | The independent check's verdict in a fixed shape: true or false positive, how sure, the severity it settled on and why. Absent on findings raised before verdicts were kept and on those the check did not reach. |
#FindingValidation
A check of the finding by a Nullgap researcher, on top of the automated ones. Who the researcher is is not disclosed.
| Field | Type | Always present | Description |
|---|---|---|---|
status | string | yes | pending: waiting for a researcher. confirmed: a researcher reproduced or accepted it. adjusted: confirmed with a different severity. rejected: a researcher found it is not a real issue, and the finding is closed as a false positive. |
at | string or null | yes | When the researcher decided. null while pending. |
note | string or null | yes | What the researcher wrote for you. |
severityBefore | string | no | The severity before an adjustment. Present only when status is adjusted. |
requestedAt | string | no | When your workspace asked for this expert review. Absent when the review came with a researcher-validation contract. |
requestedBy | string | no | The name of the person in your workspace who asked. |
scope | string | no | Whether the request was for this finding alone or for the whole pentest report. One of: finding, pentest. |
requestNote | string or null | no | What you asked the researcher to check. |
openedAt | string or null | no | When a researcher first opened the finding for this request. Once set, the request can no longer be cancelled. |
previous | object | no | The decision a new request for another look replaces. Restored if the request is cancelled. |
previous.status | string | yes | The earlier decision. One of: confirmed, adjusted, rejected. |
previous.at | string or null | yes | When it was made. |
previous.note | string or null | yes | What the researcher wrote. |
previous.severityBefore | string | no | The severity before that adjustment. |
#Priority
How urgent a finding is: its severity, moved by what is known about exposure. Up one step when the code is reachable from an internet-facing entry point that needs no sign-in, or is proven and reachable from an internet-facing entry point. Down two steps for test-only code; down one step each when it is only reached through a command-line, internal or administration entry point, when no call chain leads to it, and when the value is not under an attacker’s control (two steps down at most). A proven finding is never placed below what its severity gives.
| Field | Type | Always present | Description |
|---|---|---|---|
level | string | yes | How urgent the finding is, P0 being the most urgent. |
fromSeverity | string | yes | What the severity alone would give: critical P0, high P1, medium P2, low and info P3. |
proven | boolean | yes | True when the finding was reproduced, in the sandbox or against the running application. |
reasons | array of string | yes | Why it is this level, most important first, written to be shown to people as they are. |
#FindingSighting
One run that reported a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
source | string | yes | What kind of run reported it. One of: review, pentest. |
sourceId | string | yes | The id of that review or pentest. |
prNumber | integer or null | yes | The pull request, for a review. null for a pentest. |
at | string | yes | When that run reported it. |
#FindingFixRun
One fix run started for a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
runId | string | yes | The id of the fix run. |
startedAt | string | yes | When it was started. |
finishedAt | string or null | yes | When it ended. null while it runs. |
status | string | yes | Where that run stands. One of: queued, running, completed, failed, skipped, cancelled. |
outcome | string or null | yes | How it ended for this finding. null until it has. One of: fixed, unverified, no_fix_needed, false_positive, failed, null. |
prUrl | string or null | yes | The pull request the run opened, when it opened one. |
#FindingTrace
What backs one finding, laid out for a reader. Every part is read from what was recorded when the finding was raised and checked; nothing is worked out afresh.
| Field | Type | Always present | Description |
|---|---|---|---|
dataFlow | object or null | yes | The data-flow path. Null when none was recorded. |
dataFlow.steps | array of TraceStep | yes | The path, entry point first and sink last. |
dataFlow.entryPoint | string or null | yes | Where the data comes in. |
dataFlow.sink | string or null | yes | Where it does harm. |
dataFlow.confirmedBy | string | yes | independent-check: the path the independent check confirmed. finder: the path as first reported, not confirmed hop by hop. |
callPath | object or null | yes | The call path from an entry point to the flagged code. Null when none was recorded. |
callPath.steps | array of TraceStep | yes | The calls, entry point first. |
callPath.basis | string | yes | How the path was worked out and what it cannot see. |
diagram | string or null | yes | A Mermaid flowchart of the data flow, or of the call path when there is no data flow. Null when the path has fewer than two steps. |
proof | object or null | yes | The proof on record. Null when the finding was not reproduced. |
proof.kind | string | yes | sandbox: a probe run in the sandbox. live: a request against a running application in the live-testing scope. |
proof.summary | string | yes | What the proof showed. Up to 400 characters. |
proof.reproduced | boolean | yes | Whether the flaw was reproduced. |
proof.outcome | string | no | For sandbox: the proof's outcome. Only not_reproduced means a probe ran and the code behaved safely; environment_missing, budget_exhausted, no_probe and probe_broken mean it was not tested. |
occurrences | integer | yes | How many times runs have raised this finding. 1 when the count was not recorded. |
skill | string or null | yes | The skill that raised it, when one did. |
verdict | TriageVerdict or null | yes | |
history | array of object | yes | Decisions and notes on the finding, oldest first; entries without a time come last. |
history[].at | string or null | yes | When. Null when the time was not recorded. |
history[].by | string or null | yes | Who: a member, independent check, researcher, or null when it was the system. |
history[].what | string | yes | What happened. |
history[].detail | string | no | More, when there is more. Up to 500 characters. |
missing | array of string | yes | Each part that was not recorded for this finding, in a sentence. Quote these instead of filling the gap. |
#PackageRef
The package a dependency finding is about.
| Field | Type | Always present | Description |
|---|---|---|---|
ecosystem | string | yes | The package registry: npm, PyPI, crates.io or another. |
name | string | yes | The package name. |
version | string | yes | The version in use. |
fixedVersion | string | no | The first version without the problem, when one is known. |
manifest | string | no | The manifest or lockfile the package was found in, relative to the repository root. |
direct | boolean | no | True when the project depends on it directly, false when it comes in through another package. |
#Evidence
One step in the chain that backs a finding. The steps are listed in the order they happened.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | What sort of evidence this is. engine: a static rule matched. reasoning: the written analysis of the code. probe: a reproduction attempt in the sandbox. transcript: a recorded exchange. verification: the independent check of the finding. dynamic: a test against the running application. |
summary | string | yes | One or two sentences saying what this step showed. |
detail | string | no | The longer text of the step. On probe evidence these are the probe files. |
command | string | no | The command that was run, on evidence that ran one. |
exitCode | integer | no | What the command exited with. |
output | string | no | What the command printed. |
proof | ProofRecord | no | On probe evidence written by the proof step: how the reproduction went. |
#Patch
A fix written for a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
diff | string | yes | A unified diff, applicable with git apply from the repository root. |
description | string | yes | What the patch changes, in plain words. |
verified | boolean | yes | True when the patch passed its checks on a fresh checkout. |
verification | PatchVerification | no | How it was checked, when it was. |
attempts | array of PatchAttempt | no | Every attempt made, oldest first. diff is the last one. |
unproven | object | no | Present only on a patch written without reproducing the flaw. Such a patch is never verified. |
unproven.reason | string | yes | Why the flaw was not reproduced. |
unproven.proof | string | yes | What the reproduction attempt recorded. Never reproduced, and never not_reproduced: when the code behaved safely no patch is written. |
unproven.accepted | boolean | yes | True when every check that needs no probe ran without failing and the independent review accepted the change. Only then was it offered, as a proposal. |
unproven.independentReviewer | boolean | yes | True when the review was done by a different Nullgap AI model from the one that wrote the change. |
#FindingTriage
Facts for triage, worked out from the code: the shape of the flagged code and how exposed it is. Absent on findings from before this existed and on package advisories.
| Field | Type | Always present | Description |
|---|---|---|---|
shape | FlawShape | no | What the flagged code looks like. Absent when the finding is not about code. |
exposure | Exposure | no | How the code can be reached, and by whom. |
#TriageVerdict
The independent check's verdict on a finding, in a fixed shape.
| Field | Type | Always present | Description |
|---|---|---|---|
verdict | string | yes | What the independent check concluded. One of: true_positive, false_positive. |
confidence | string | yes | How sure it is. A low verdict is left for a person: nothing is rejected or downgraded on it. |
severity | string | yes | The severity after weighing prerequisites, impact and difficulty. One of: critical, high, medium, low, info. |
severityBefore | string | no | The severity first claimed, present only when the check changed it. One of: critical, high, medium, low, info. |
severityReasons | array of string | yes | Why the severity is what it is. |
mitigations | array of string | yes | Controls found on the path (validation, authorisation, safe APIs, limits), whether or not they stop the flaw. |
weaknessFits | boolean or null | yes | Whether the weakness class named on the finding fits what the code does. Null when the check did not say. |
reasoning | string | yes | The check's reasoning, in plain words. |
confirmedPath | array of string | yes | The hops of the reported path that the check confirmed in the code. |
at | string | no | When the verdict was given. |
#TraceStep
One step of a path through the code.
| Field | Type | Always present | Description |
|---|---|---|---|
n | integer | yes | Its position on the path, from 1. |
text | string | yes | What happens at this step. Up to 400 characters. |
file | string | no | The file, when the step names one. |
line | integer | no | The line, when the step names one. |
#ProofRecord
The record of one attempt to reproduce a finding. It lets a reader tell "it was run and did not reproduce" from "it could not be run here".
| Field | Type | Always present | Description |
|---|---|---|---|
outcome | string | yes | What happened when the finding was sent for reproduction. reproduced: the probe showed the flaw and its harmless control behaved safely. not_reproduced: the probe ran correctly and the code behaved safely. probe_broken: no trustworthy probe (it errored, timed out, or its control did not hold). no_probe: no probe was produced. environment_missing: the code cannot run in the sandbox as it is (see missing). budget_exhausted: the limit for one proof ran out first. |
attempts | integer | yes | How many probe attempts were made, 1 or 2. |
missing | string | no | For environment_missing: what the sandbox lacked, in a few words. |
dependencies | string | yes | Whether the project's dependencies were in place before the probe ran. One of: installed, present, not_installed, not_needed. |
controlHeld | boolean | no | The harmless control run behaved safely. Absent when no control was run. |
repeatable | boolean | no | The probe gave the same result when run a second time. Set when the outcome is reproduced. |
audited | boolean | no | An independent reviewer read the probe and accepted that it exercises the project's own code and observes the unsafe effect. False when the run had no such reviewer. |
variantHeld | boolean | no | A second, different input for the same flaw also reproduced on the unpatched code. False: one was supplied and did not reproduce. Absent: none was supplied. |
modelsAsked | integer | no | Present only when writing the probe was declined at least once: how many Nullgap AI models were asked to write it. Each was sent the same request, unchanged. |
declined | integer | no | Present only when writing the probe was declined at least once: how many of the models asked declined. |
#PatchVerification
How a patch was checked.
| Field | Type | Always present | Description |
|---|---|---|---|
probePassed | boolean | yes | The probe no longer reproduces the flaw on a fresh, patched checkout. |
testsPassed | boolean or null | yes | Whether the project’s own tests pass with the patch. null when the project has no test command. |
log | string | yes | The output of the verification run. |
checks | array of FixCheck | no | Every check, in the order it ran. Absent on patches recorded before checks were itemised. |
refused | array of string | no | Why the patch was refused, one sentence per reason. Empty or absent when it was not refused. |
#PatchAttempt
One try at writing a fix. A run makes a bounded number of them, each told why the previous one failed.
| Field | Type | Always present | Description |
|---|---|---|---|
attempt | integer | yes | Which try this was, counted from 1. |
verified | boolean | yes | Whether this attempt passed every check. |
reason | string | no | Why this attempt was not accepted. Absent when it was. |
proposed | boolean | no | Only on a fix written without reproducing the flaw: this attempt passed every check that needs no probe and was accepted as a proposal. verified is still false. |
files | array of string | yes | The files this attempt changed. |
#FlawShape
What the flagged code looks like, in a form that survives renames and moved lines. Nullgap uses it to recognise code the team has already decided about. Treat the hashes as opaque; family is the one value worth comparing.
| Field | Type | Always present | Description |
|---|---|---|---|
v | integer | yes | The version of this description. Always 1. |
families | array of string | yes | The weakness families of the finding, sorted. |
file | string | yes | The file of the flagged line. |
fn | string or null | yes | The function that encloses the flagged line. null for code outside any named function. |
indexed | boolean | yes | True when the code index covered the file, so fn and callers are facts and not gaps. |
anchor | string | yes | The flagged statement, normalised. Empty when it carries too little to identify anything. |
sink | string | yes | The statement where the dangerous operation happens, normalised. Equal to anchor when the evidence names no other. |
ordinal | integer | yes | Which of several identical statements in the enclosing function this is. 0 is the first. |
source | string or null | yes | The line where the data comes in, normalised, when the evidence names it. |
entry | string or null | yes | The registration line of the entry point the code is reached from, normalised. |
near | string | yes | A hash of the code within a few lines of the flagged statement. |
wide | array of string | yes | A sketch of the whole enclosing function, used to score how alike two functions are. |
callers | array of string or null | yes | One entry per caller of the enclosing function. null when not known. |
family | string | yes | Findings with the same weakness family and the same sink statement share this key. It is what "findings like this one" means. |
#Exposure
What is known about how the flawed code can be reached. It is worked out from the code alone. A fact that could not be established is not_determined and never moves the priority in either direction.
| Field | Type | Always present | Description |
|---|---|---|---|
reachable | string | yes | Whether the flawed code is called from an entry point. One of: yes, no, not_determined. |
entryPoint | object or null | yes | The entry point, when the code is reachable from one. |
entryPoint.kind | string | yes | What sort of entry point it is. |
entryPoint.name | string | yes | Its name in the code. |
entryPoint.file | string | yes | The file it is registered in. |
entryPoint.line | integer | yes | The line it is registered on. |
entryPoint.method | string | no | For an HTTP entry point: the method. |
entryPoint.route | string | no | For an HTTP entry point: the route. |
authentication | string | yes | Whether that entry point asks for a signed-in caller. One of: required, none, not_determined. |
surface | string | yes | Who can get to the entry point. One of: internet, internal, admin, cli, test, not_determined. |
attackerControlled | string | yes | Whether the value that reaches the flaw comes from the caller. One of: yes, no, not_determined. |
basis | array of string | yes | How each fact above was established, one line each. |
#FixCheck
One named check a fix went through.
| Field | Type | Always present | Description |
|---|---|---|---|
name | string | yes | Which check. applies: the patch applies to a fresh checkout. scope: the patch widens no risk and stays on files related to the finding. probe: the probe that reproduced the flaw no longer does. variant: a second input for the same flaw no longer reproduces either. control: ordinary use still works. tests: the project’s own tests pass. For a fix proposed without reproducing the flaw (outcome unverified), the three probe runs are not_run and two more checks are made: build (the changed files still parse) and review (an independent review of the change accepted that it closes the flaw without changing other behaviour). For a dependency fix, in place of the three probe runs: lockfile (the lockfile was regenerated from the edited manifest in the sandbox, with install scripts off) and resolved (the affected version is no longer in the manifest or the lockfile). |
status | string | yes | not_run is never a pass: the check could not be made, and detail says why. |
detail | string | yes | One plain sentence: what was seen, or why the check could not run. |
place | string | no | For a fix that covers several places: the one this check belongs to, as file:line. |
Nullgap documentation