API reference
Pull request reviews
Read pull request reviews and their logs, and request a review of one pull request.
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 |
|---|---|---|
| List reviews | GET /api/orgs/{org}/reviews | read |
| Request a review | POST /api/orgs/{org}/reviews | write |
| Get a review | GET /api/orgs/{org}/reviews/{id} | read |
| Get a review's log | GET /api/orgs/{org}/reviews/{id}/logs | read |
| Cancel a review | POST /api/orgs/{org}/reviews/{id}/cancel | write |
#List reviews
GET /api/orgs/{org}/reviews
Lists pull request reviews, newest first. A review in a list carries counts only (supplyChainCount, suppressedCount); the packages and findings are on the single review.
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 |
|---|---|---|---|
status | string | no | Only reviews in this state. A value that is not a state matches nothing. One of: queued, running, completed, failed, skipped, cancelled. |
repoId | string | no | Only reviews of this repository. |
prNumber | integer | no | Only reviews of this pull request. Needs repoId, because pull request numbers are per repository. |
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/reviews?limit=20"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of Review | yes | Reviews, at most limit of them. |
total | integer | yes | How many match in all, before limit and offset. |
{
"items": [
{
"id": "rev_3fa9c1d2e4b7",
"orgId": "org_5b1e7a90c3d2",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"prNumber": 128,
"title": "Add coupon codes to checkout",
"author": "dana-acme",
"baseRef": "main",
"headRef": "feature/coupons",
"baseSha": "9b2d4f6a8c0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a",
"headSha": "4e6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f",
"trigger": "opened",
"status": "completed",
"skipReason": "Draft pull request",
"checkConclusion": "failure",
"findingsCount": 2,
"privacy": {
"zeroRetention": true,
"identifiersMasked": 14
},
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:20.000Z",
"finishedAt": "2026-11-16T09:34:05.000Z",
"supplyChainCount": 1,
"supplyChainNote": "The advisory database did not answer, so dependencies were not checked.",
"suppressedCount": 0,
"prUrl": "https://github.com/acme/shop/pull/128"
}
],
"total": 42
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | prNumber is not a whole number from 1 to 2147483647, or is sent without repoId. |
#Request a review
POST /api/orgs/{org}/reviews
Asks for a review of a pull request at its current head commit. There is one review per head commit: when that commit already has a queued, running or completed review, that review is returned with alreadyReviewed: true and nothing new starts. Send force: true to review a commit again that already has a completed review; a queued or running one is still returned as it is. A review of the same pull request that is still queued for an older commit is cancelled. A review asked for here is done even when reviews are switched off for the repository, the pull request is a draft, or a review filter would leave it out. It can still be decided not to review it (no active plan, the size limit, no seat, the monthly quota): the call then answers 200 with a review whose status is skipped and whose skipReason says why. The call returns as soon as the review is queued; read the review to follow it.
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 |
|---|---|---|---|
repoId | string | yes | The repository, by its id. |
prNumber | integer | yes | The pull request number on the code host: a whole number from 1 to 2147483647, the largest number a code host gives a pull request. |
force | boolean | no | Review the head commit again even when it already has a completed review. Default false. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"repoId":"repo_a41c09be77d3","prNumber":128,"force":false}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reviews"
Answer (200, application/json)
A ReviewRequested object.
{
"id": "rev_3fa9c1d2e4b7",
"orgId": "org_5b1e7a90c3d2",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"prNumber": 128,
"title": "Add coupon codes to checkout",
"author": "dana-acme",
"baseRef": "main",
"headRef": "feature/coupons",
"baseSha": "9b2d4f6a8c0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a",
"headSha": "4e6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f",
"trigger": "opened",
"status": "completed",
"skipReason": "Draft pull request",
"checkConclusion": "failure",
"findingsCount": 2,
"privacy": {
"zeroRetention": true,
"identifiersMasked": 14
},
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:20.000Z",
"finishedAt": "2026-11-16T09:34:05.000Z",
"supplyChainCount": 1,
"supplyChainNote": "The advisory database did not answer, so dependencies were not checked.",
"suppressedCount": 0,
"prUrl": "https://github.com/acme/shop/pull/128",
"alreadyReviewed": false
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No repository of this organisation has the repoId sent. |
| 400 | bad_request | prNumber is not a whole number from 1 to 2147483647, or force is not true or false. |
| 404 | not_found | The repository has no pull request with that number. The message names the number and the repository. |
#Get a review
GET /api/orgs/{org}/reviews/{id}
Returns one review with the findings it raised, the packages it flagged, and what it produced but did not raise because of an earlier decision.
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. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reviews/ID"
Answer (200, application/json)
A ReviewDetail object.
{
"id": "rev_3fa9c1d2e4b7",
"orgId": "org_5b1e7a90c3d2",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"prNumber": 128,
"title": "Add coupon codes to checkout",
"author": "dana-acme",
"baseRef": "main",
"headRef": "feature/coupons",
"baseSha": "9b2d4f6a8c0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a",
"headSha": "4e6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f",
"trigger": "opened",
"status": "completed",
"skipReason": "Draft pull request",
"checkConclusion": "failure",
"findingsCount": 2,
"privacy": {
"zeroRetention": true,
"identifiersMasked": 14
},
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:20.000Z",
"finishedAt": "2026-11-16T09:34:05.000Z",
"supplyChainCount": 1,
"supplyChainNote": "The advisory database did not answer, so dependencies were not checked.",
"suppressedCount": 0,
"prUrl": "https://github.com/acme/shop/pull/128",
"supplyChain": [
{
"ecosystem": "npm",
"name": "lodash",
"version": "4.17.20",
"verdict": "vulnerable",
"reasons": [
{
"id": "typosquat",
"category": "typosquat",
"strength": "notable",
"severity": "medium",
"summary": "The name is one letter away from the popular package \"lodash\".",
"file": "package-lock.json",
"line": 412,
"excerpt": "\"lodahs\": \"^1.0.2\""
}
],
"advisories": [
{
"id": "GHSA-35jh-r3h4-6jhm",
"summary": "Command injection in the template function",
"severity": "high",
"kind": "vulnerability"
}
],
"fixedVersion": "4.17.21",
"manifest": "package-lock.json",
"direct": true,
"policy": {
"action": "block",
"rule": "min-age",
"detail": "Published 2 days ago; your organisation requires versions to be at least 7 days old."
},
"findingId": "fnd_8f3a2c9d1b07"
}
],
"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."
]
}
}
],
"suppressed": [
{
"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"
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No review of this organisation has that id. |
#Get a review's log
GET /api/orgs/{org}/reviews/{id}/logs
Returns the progress log of one review, oldest line first, as a plain list. The list is empty when the review has not written anything yet.
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. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reviews/ID/logs"
Answer (200, application/json)
The log lines, oldest first.
An array of LogLine.
[
{
"at": "2026-11-16T09:30:00.000Z",
"level": "info",
"message": "Mapping the attack surface: 42 entry points"
}
]
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No review of this organisation has that id. |
#Cancel a review
POST /api/orgs/{org}/reviews/{id}/cancel
Stops a queued or running review. Its status becomes cancelled and the work is stopped; when it was running, the check on the pull request says the review was cancelled. Nothing is concluded about the change. Request a review again to start a new one. Takes no body.
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. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reviews/ID/cancel"
Answer (200, application/json)
A Review object.
{
"id": "rev_3fa9c1d2e4b7",
"orgId": "org_5b1e7a90c3d2",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"prNumber": 128,
"title": "Add coupon codes to checkout",
"author": "dana-acme",
"baseRef": "main",
"headRef": "feature/coupons",
"baseSha": "9b2d4f6a8c0e1f3a5b7c9d1e3f5a7b9c1d3e5f7a",
"headSha": "4e6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f",
"trigger": "opened",
"status": "completed",
"skipReason": "Draft pull request",
"checkConclusion": "failure",
"findingsCount": 2,
"privacy": {
"zeroRetention": true,
"identifiersMasked": 14
},
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:20.000Z",
"finishedAt": "2026-11-16T09:34:05.000Z",
"supplyChainCount": 1,
"supplyChainNote": "The advisory database did not answer, so dependencies were not checked.",
"suppressedCount": 0,
"prUrl": "https://github.com/acme/shop/pull/128"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No review of this organisation has that id. |
| 409 | not_running | The review is neither queued nor running: it has already finished, been skipped, failed or been cancelled. |
#Objects
The objects the operations above take and return.
#Review
A security review of one pull request at one commit.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The review id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository the pull request is in. |
repoFullName | string | yes | The repository as owner/name. |
prNumber | integer | yes | The pull request number on the code host. |
title | string | yes | The pull request title when the review was requested. |
author | string | yes | The code-host login of the pull request author. |
baseRef | string | yes | The branch the pull request merges into. |
headRef | string | yes | The branch the pull request comes from. |
baseSha | string | yes | The commit the pull request is based on. |
headSha | string | yes | The commit that was reviewed. There is one review per head commit. |
trigger | string | yes | What asked for the review: the pull request was opened, new commits were pushed, someone asked through the console or API, or someone asked in a pull request comment. One of: opened, synchronize, manual, comment. |
status | string | yes | Where the review stands. skipped means it was decided not to review this pull request: see skipReason. |
skipReason | string or null | yes | Why the review was skipped (a filter, the size limit, no seat, the monthly quota, a draft). Null unless status is skipped. |
checkConclusion | string or null | yes | The result of the check Nullgap set on the pull request. Null until the review has finished. One of: success, failure, neutral, null. |
findingsCount | integer | yes | How many findings this review raised. |
privacy | RunPrivacy or null | yes | |
createdAt | string | yes | When the review was requested. |
startedAt | string or null | yes | When work on it began. Null while it is queued, and for a skipped review. |
finishedAt | string or null | yes | When it finished, was skipped or failed. Null until then. |
supplyChainCount | integer | no | How many packages this pull request adds or changes that are not clean. The packages themselves are on the single review, in supplyChain. Absent when dependencies were not checked. |
supplyChainNote | string or null | no | Set when the dependency check could not finish. Read it as "not checked", never as a clean result. |
suppressedCount | integer | no | How many findings this review produced and did not raise because of an earlier decision (a dismissal, or the same finding already known). They are listed on the single review, in suppressed. |
prUrl | string or null | no | The pull request on the code host. Absent on reviews from before it was kept. |
#ReviewRequested
The review a request led to.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The review id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository the pull request is in. |
repoFullName | string | yes | The repository as owner/name. |
prNumber | integer | yes | The pull request number on the code host. |
title | string | yes | The pull request title when the review was requested. |
author | string | yes | The code-host login of the pull request author. |
baseRef | string | yes | The branch the pull request merges into. |
headRef | string | yes | The branch the pull request comes from. |
baseSha | string | yes | The commit the pull request is based on. |
headSha | string | yes | The commit that was reviewed. There is one review per head commit. |
trigger | string | yes | What asked for the review: the pull request was opened, new commits were pushed, someone asked through the console or API, or someone asked in a pull request comment. One of: opened, synchronize, manual, comment. |
status | string | yes | Where the review stands. skipped means it was decided not to review this pull request: see skipReason. |
skipReason | string or null | yes | Why the review was skipped (a filter, the size limit, no seat, the monthly quota, a draft). Null unless status is skipped. |
checkConclusion | string or null | yes | The result of the check Nullgap set on the pull request. Null until the review has finished. One of: success, failure, neutral, null. |
findingsCount | integer | yes | How many findings this review raised. |
privacy | RunPrivacy or null | yes | |
createdAt | string | yes | When the review was requested. |
startedAt | string or null | yes | When work on it began. Null while it is queued, and for a skipped review. |
finishedAt | string or null | yes | When it finished, was skipped or failed. Null until then. |
supplyChainCount | integer | no | How many packages this pull request adds or changes that are not clean. The packages themselves are on the single review, in supplyChain. Absent when dependencies were not checked. |
supplyChainNote | string or null | no | Set when the dependency check could not finish. Read it as "not checked", never as a clean result. |
suppressedCount | integer | no | How many findings this review produced and did not raise because of an earlier decision (a dismissal, or the same finding already known). They are listed on the single review, in suppressed. |
prUrl | string or null | no | The pull request on the code host. Absent on reviews from before it was kept. |
alreadyReviewed | boolean | yes | True when nothing new was started because this commit already has a queued, running or completed review: the review returned is that one. False when a new review was queued or skipped. |
#ReviewDetail
One review with what it found.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The review id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository the pull request is in. |
repoFullName | string | yes | The repository as owner/name. |
prNumber | integer | yes | The pull request number on the code host. |
title | string | yes | The pull request title when the review was requested. |
author | string | yes | The code-host login of the pull request author. |
baseRef | string | yes | The branch the pull request merges into. |
headRef | string | yes | The branch the pull request comes from. |
baseSha | string | yes | The commit the pull request is based on. |
headSha | string | yes | The commit that was reviewed. There is one review per head commit. |
trigger | string | yes | What asked for the review: the pull request was opened, new commits were pushed, someone asked through the console or API, or someone asked in a pull request comment. One of: opened, synchronize, manual, comment. |
status | string | yes | Where the review stands. skipped means it was decided not to review this pull request: see skipReason. |
skipReason | string or null | yes | Why the review was skipped (a filter, the size limit, no seat, the monthly quota, a draft). Null unless status is skipped. |
checkConclusion | string or null | yes | The result of the check Nullgap set on the pull request. Null until the review has finished. One of: success, failure, neutral, null. |
findingsCount | integer | yes | How many findings this review raised. |
privacy | RunPrivacy or null | yes | |
createdAt | string | yes | When the review was requested. |
startedAt | string or null | yes | When work on it began. Null while it is queued, and for a skipped review. |
finishedAt | string or null | yes | When it finished, was skipped or failed. Null until then. |
supplyChainCount | integer | no | How many packages this pull request adds or changes that are not clean. The packages themselves are on the single review, in supplyChain. Absent when dependencies were not checked. |
supplyChainNote | string or null | no | Set when the dependency check could not finish. Read it as "not checked", never as a clean result. |
suppressedCount | integer | no | How many findings this review produced and did not raise because of an earlier decision (a dismissal, or the same finding already known). They are listed on the single review, in suppressed. |
prUrl | string or null | no | The pull request on the code host. Absent on reviews from before it was kept. |
supplyChain | array of SupplyChainPackage | yes | The packages this pull request adds or changes that are not clean. Empty when there are none. |
findings | array of FindingRecord | yes | The findings this review raised. |
suppressed | array of SuppressedFinding | yes | What this review produced and did not raise, each with the decision it rests on. Ones that were restored since are findings again and are not listed. |
#LogLine
One line of a run's progress log.
| Field | Type | Always present | Description |
|---|---|---|---|
at | string | yes | When the line was written. |
level | string | yes | How serious the line is. One of: info, warn, error. |
message | string | yes | What happened, in plain words. |
#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. |
#SupplyChainPackage
One package in the supply-chain list of a review or a pentest.
| Field | Type | Always present | Description |
|---|---|---|---|
ecosystem | string | yes | The package ecosystem. |
name | string | yes | The package name. |
version | string | yes | The version the code pins. |
verdict | string | yes | The verdict on this version. A clean package is listed only when an organisation rule blocks it; unknown ones are listed because unknown is not clean. |
reasons | array of SupplyChainReason | yes | Every signal found, strongest first. May be empty. |
advisories | array of PackageAdvisory | yes | The advisories that list this version. May be empty. |
fixedVersion | string or null | no | The first version without the flaw, when an advisory names one. |
manifest | string or null | yes | The manifest or lockfile that pins the package. |
direct | boolean or null | yes | True when the code depends on the package directly, false when through another package, null when that is not known. |
policy | PolicyMatch | no | |
findingId | string | no | The finding raised for this package, when there is one. |
#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. |
#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. |
#SupplyChainReason
One reason a package is worth a look. A reason is a signal, not a verdict.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The stable name of the rule that matched. |
category | string | yes | What kind of signal it is. One of: lockfile, confusion, typosquat, install-script, registry, content. |
strength | string | yes | strong: no honest explanation. notable: worth a person's look by itself. weak: common in honest packages, given as context. |
severity | string | yes | How serious the signal is. One of: critical, high, medium, low, info. |
summary | string | yes | The signal in plain words. |
file | string | no | A project file (for lockfile signals) or a path inside the package (for signals from its contents). |
line | integer | no | The line in file, when there is one. |
excerpt | string | no | A short piece of the text that matched, with secrets masked. |
#PackageAdvisory
A published advisory that lists this package version.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The advisory id. |
summary | string | yes | What the advisory says, in one line. |
severity | string | yes | The severity the advisory states. |
kind | string | yes | Whether the advisory reports malicious code in the package or a flaw in it. One of: malware, vulnerability. |
#PolicyMatch
The organisation rule that decided a package, and why.
| Field | Type | Always present | Description |
|---|---|---|---|
action | string | yes | block: the organisation does not permit this package. allow: the organisation exempted it. |
rule | string | yes | Which of the organisation's rules matched. One of: blocked-package, allowed-package, min-age, install-script, registry. |
detail | string | yes | The rule and why it matched, in plain words. |
#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. |
#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. |
#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. |
#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. |
#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. |
#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. |
#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