Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
List reviewsGET /api/orgs/{org}/reviewsread
Request a reviewPOST /api/orgs/{org}/reviewswrite
Get a reviewGET /api/orgs/{org}/reviews/{id}read
Get a review's logGET /api/orgs/{org}/reviews/{id}/logsread
Cancel a reviewPOST /api/orgs/{org}/reviews/{id}/cancelwrite

#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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
statusstringnoOnly reviews in this state. A value that is not a state matches nothing. One of: queued, running, completed, failed, skipped, cancelled.
repoIdstringnoOnly reviews of this repository.
prNumberintegernoOnly reviews of this pull request. Needs repoId, because pull request numbers are per repository.
limitintegernoHow many to return, 1 to 200. Default 50.
offsetintegernoHow 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)

FieldTypeAlways presentDescription
itemsarray of ReviewyesReviews, at most limit of them.
totalintegeryesHow 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

StatusCodeWhen
400bad_requestprNumber 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
repoIdstringyesThe repository, by its id.
prNumberintegeryesThe pull request number on the code host: a whole number from 1 to 2147483647, the largest number a code host gives a pull request.
forcebooleannoReview 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

StatusCodeWhen
404not_foundNo repository of this organisation has the repoId sent.
400bad_requestprNumber is not a whole number from 1 to 2147483647, or force is not true or false.
404not_foundThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundNo 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundNo 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundNo review of this organisation has that id.
409not_runningThe 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.

FieldTypeAlways presentDescription
idstringyesThe review id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository the pull request is in.
repoFullNamestringyesThe repository as owner/name.
prNumberintegeryesThe pull request number on the code host.
titlestringyesThe pull request title when the review was requested.
authorstringyesThe code-host login of the pull request author.
baseRefstringyesThe branch the pull request merges into.
headRefstringyesThe branch the pull request comes from.
baseShastringyesThe commit the pull request is based on.
headShastringyesThe commit that was reviewed. There is one review per head commit.
triggerstringyesWhat 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.
statusstringyesWhere the review stands. skipped means it was decided not to review this pull request: see skipReason.
skipReasonstring or nullyesWhy the review was skipped (a filter, the size limit, no seat, the monthly quota, a draft). Null unless status is skipped.
checkConclusionstring or nullyesThe result of the check Nullgap set on the pull request. Null until the review has finished. One of: success, failure, neutral, null.
findingsCountintegeryesHow many findings this review raised.
privacyRunPrivacy or nullyes
createdAtstringyesWhen the review was requested.
startedAtstring or nullyesWhen work on it began. Null while it is queued, and for a skipped review.
finishedAtstring or nullyesWhen it finished, was skipped or failed. Null until then.
supplyChainCountintegernoHow 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.
supplyChainNotestring or nullnoSet when the dependency check could not finish. Read it as "not checked", never as a clean result.
suppressedCountintegernoHow 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.
prUrlstring or nullnoThe pull request on the code host. Absent on reviews from before it was kept.

#ReviewRequested

The review a request led to.

FieldTypeAlways presentDescription
idstringyesThe review id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository the pull request is in.
repoFullNamestringyesThe repository as owner/name.
prNumberintegeryesThe pull request number on the code host.
titlestringyesThe pull request title when the review was requested.
authorstringyesThe code-host login of the pull request author.
baseRefstringyesThe branch the pull request merges into.
headRefstringyesThe branch the pull request comes from.
baseShastringyesThe commit the pull request is based on.
headShastringyesThe commit that was reviewed. There is one review per head commit.
triggerstringyesWhat 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.
statusstringyesWhere the review stands. skipped means it was decided not to review this pull request: see skipReason.
skipReasonstring or nullyesWhy the review was skipped (a filter, the size limit, no seat, the monthly quota, a draft). Null unless status is skipped.
checkConclusionstring or nullyesThe result of the check Nullgap set on the pull request. Null until the review has finished. One of: success, failure, neutral, null.
findingsCountintegeryesHow many findings this review raised.
privacyRunPrivacy or nullyes
createdAtstringyesWhen the review was requested.
startedAtstring or nullyesWhen work on it began. Null while it is queued, and for a skipped review.
finishedAtstring or nullyesWhen it finished, was skipped or failed. Null until then.
supplyChainCountintegernoHow 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.
supplyChainNotestring or nullnoSet when the dependency check could not finish. Read it as "not checked", never as a clean result.
suppressedCountintegernoHow 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.
prUrlstring or nullnoThe pull request on the code host. Absent on reviews from before it was kept.
alreadyReviewedbooleanyesTrue 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.

FieldTypeAlways presentDescription
idstringyesThe review id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository the pull request is in.
repoFullNamestringyesThe repository as owner/name.
prNumberintegeryesThe pull request number on the code host.
titlestringyesThe pull request title when the review was requested.
authorstringyesThe code-host login of the pull request author.
baseRefstringyesThe branch the pull request merges into.
headRefstringyesThe branch the pull request comes from.
baseShastringyesThe commit the pull request is based on.
headShastringyesThe commit that was reviewed. There is one review per head commit.
triggerstringyesWhat 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.
statusstringyesWhere the review stands. skipped means it was decided not to review this pull request: see skipReason.
skipReasonstring or nullyesWhy the review was skipped (a filter, the size limit, no seat, the monthly quota, a draft). Null unless status is skipped.
checkConclusionstring or nullyesThe result of the check Nullgap set on the pull request. Null until the review has finished. One of: success, failure, neutral, null.
findingsCountintegeryesHow many findings this review raised.
privacyRunPrivacy or nullyes
createdAtstringyesWhen the review was requested.
startedAtstring or nullyesWhen work on it began. Null while it is queued, and for a skipped review.
finishedAtstring or nullyesWhen it finished, was skipped or failed. Null until then.
supplyChainCountintegernoHow 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.
supplyChainNotestring or nullnoSet when the dependency check could not finish. Read it as "not checked", never as a clean result.
suppressedCountintegernoHow 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.
prUrlstring or nullnoThe pull request on the code host. Absent on reviews from before it was kept.
supplyChainarray of SupplyChainPackageyesThe packages this pull request adds or changes that are not clean. Empty when there are none.
findingsarray of FindingRecordyesThe findings this review raised.
suppressedarray of SuppressedFindingyesWhat 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.

FieldTypeAlways presentDescription
atstringyesWhen the line was written.
levelstringyesHow serious the line is. One of: info, warn, error.
messagestringyesWhat 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.

FieldTypeAlways presentDescription
zeroRetentionbooleanyesTrue when every Nullgap AI call in the run was confirmed as keeping no data afterwards.
identifiersMaskedintegeryesHow 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.

FieldTypeAlways presentDescription
ecosystemstringyesThe package ecosystem.
namestringyesThe package name.
versionstringyesThe version the code pins.
verdictstringyesThe 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.
reasonsarray of SupplyChainReasonyesEvery signal found, strongest first. May be empty.
advisoriesarray of PackageAdvisoryyesThe advisories that list this version. May be empty.
fixedVersionstring or nullnoThe first version without the flaw, when an advisory names one.
manifeststring or nullyesThe manifest or lockfile that pins the package.
directboolean or nullyesTrue when the code depends on the package directly, false when through another package, null when that is not known.
policyPolicyMatchno
findingIdstringnoThe 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.

FieldTypeAlways presentDescription
idstringyesThe id of the finding. Use it in every route that takes a finding id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository it was found in.
repoFullNamestringyesThe name of that repository.
sourcestringyesWhat kind of run first reported it. One of: review, pentest.
sourceIdstringyesThe id of that review or pentest.
prNumberinteger or nullyesThe pull request it was found on. null when it did not come from a pull request.
findingFindingyesThe flaw itself. finding.status says how far it was checked.
statestringyesWhat 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.
stateReasonstring or nullyesThe reason given with the last decision.
stateBystring or nullyesWho last changed the state: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when nobody has.
firstSeenAtstringyesWhen it was first reported.
resolvedAtstring or nullyesWhen it last left the open state. null while open.
remediationobject or nullyesThe latest fix run for this finding. null when none was started.
remediation.runIdstringyesThe id of the fix run.
remediation.statusstringyesWhere that run stands. One of: queued, running, completed, failed, skipped, cancelled.
remediation.outcomestring or nullyesHow 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.prUrlstring or nullyesThe pull request the run opened, when it opened one.
externalIssueUrlstring or nullyesThe issue filed for it in your tracker, when one was.
notesarray of FindingNotenoReplies and comments about this finding, oldest first. The latest 100 are kept. Absent when there are none.
resolvedInShastring or nullnoThe commit in which the flagged code was no longer present. Set when a review closed the finding as patched; absent or null otherwise.
validationFindingValidationnoThe check by a Nullgap researcher, for workspaces that have it. Absent when the finding is not subject to it.
priorityPriorityyesHow urgent it is. Always present in answers: records stored before priorities existed get theirs worked out on the way out.
sightingsarray of FindingSightingnoEvery 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.
riskReviewAtstring or nullnoAccepted risks only: the date the acceptance is to be looked at again. After it the finding is raised again when found.
earlierDecisionobject or nullnoSet 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.findingIdstringyesThe finding that was dismissed earlier.
earlierDecision.decisionstringyesWhat was decided about it. One of: false_positive, accepted_risk.
earlierDecision.notestringyesWhy this one was raised all the same.
stateHistoryarray of FindingStateChangenoEvery 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.
fixRunsarray of FindingFixRunnoThe fix runs started for this finding, oldest first, the latest 20 kept. Absent when none was recorded.
traceFindingTracenoWhat 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.

FieldTypeAlways presentDescription
idstringyesThe id of this held-back record.
repoIdstringyesThe repository it was found in.
repoFullNamestringyesThe name of that repository.
findingFindingyesThe flaw that was found and not raised.
priorityPriorityyesHow urgent it would be. Always present in answers.
kindstringyessame_finding: the very finding that was dismissed, found again. pattern: other code that matches the dismissed code.
decisionstringyesThe earlier decision it rests on. One of: false_positive, accepted_risk.
decidedBystring or nullyesWho took that decision.
decidedAtstring or nullyesWhen that decision was taken.
reasonstring or nullyesThe reason given with that decision.
dismissedFindingIdstringyesThe finding the decision was taken on.
whyarray of stringyesWhy it counts as the same, one statement per entry.
similaritynumber or nullyesHow alike the surrounding function is, from 0 to 1. null for same_finding.
sightingsarray of FindingSightingyesEvery run that found it and held it back, oldest first.
firstAtstringyesWhen it was first held back.
lastAtstringyesWhen it was last found and held back.
restoredAtstring or nullyesWhen someone brought it back. null while it is held back.
restoredBystring or nullyesWho brought it back.
restoredFindingIdstring or nullyesThe 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.

FieldTypeAlways presentDescription
idstringyesThe stable name of the rule that matched.
categorystringyesWhat kind of signal it is. One of: lockfile, confusion, typosquat, install-script, registry, content.
strengthstringyesstrong: no honest explanation. notable: worth a person's look by itself. weak: common in honest packages, given as context.
severitystringyesHow serious the signal is. One of: critical, high, medium, low, info.
summarystringyesThe signal in plain words.
filestringnoA project file (for lockfile signals) or a path inside the package (for signals from its contents).
lineintegernoThe line in file, when there is one.
excerptstringnoA short piece of the text that matched, with secrets masked.

#PackageAdvisory

A published advisory that lists this package version.

FieldTypeAlways presentDescription
idstringyesThe advisory id.
summarystringyesWhat the advisory says, in one line.
severitystringyesThe severity the advisory states.
kindstringyesWhether 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.

FieldTypeAlways presentDescription
actionstringyesblock: the organisation does not permit this package. allow: the organisation exempted it.
rulestringyesWhich of the organisation's rules matched. One of: blocked-package, allowed-package, min-age, install-script, registry.
detailstringyesThe 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.

FieldTypeAlways presentDescription
idstringyesThe 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.
modulestringyesThe part of Nullgap that produced it: code, deps (dependencies), redteam or another.
ruleIdstringyesThe rule or check that raised it.
titlestringyesA one-line name for the flaw.
descriptionstringyesWhat is wrong and why it matters.
severitystringyesHow serious the flaw is if exploited. One of: critical, high, medium, low, info.
confidencenumberyesHow confident the engine is that the finding is real, from 0 to 1.
cwearray of stringnoThe weakness classes it belongs to.
cvearray of stringnoPublished vulnerabilities it corresponds to, mostly on dependency findings.
locationLocationnoWhere in the code it is. Absent on findings that are not about a line of code.
packagePackageRefnoThe package concerned, on dependency findings.
sourcestringyesA 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.
statusstringyesHow 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.
evidencearray of EvidenceyesThe reasoning and checks recorded for the finding, in order.
remediationstringnoHow to fix it, in words.
patchPatchnoThe fix written for it, when one has been.
fingerprintstringyesA value that stays the same for this flaw across runs.
triageFindingTriagenoThe shape of the flagged code and how exposed it is.
triageVerdictTriageVerdictnoThe 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.

FieldTypeAlways presentDescription
authorstringyesWho wrote it: an email address, a code host login, or api-key:<name> for a note added with an API key.
textstringyesThe note, up to 2000 characters.
atstringyesWhen it was written.
viastringyesWhere 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.

FieldTypeAlways presentDescription
statusstringyespending: 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.
atstring or nullyesWhen the researcher decided. null while pending.
notestring or nullyesWhat the researcher wrote for you.
severityBeforestringnoThe severity before an adjustment. Present only when status is adjusted.
requestedAtstringnoWhen your workspace asked for this expert review. Absent when the review came with a researcher-validation contract.
requestedBystringnoThe name of the person in your workspace who asked.
scopestringnoWhether the request was for this finding alone or for the whole pentest report. One of: finding, pentest.
requestNotestring or nullnoWhat you asked the researcher to check.
openedAtstring or nullnoWhen a researcher first opened the finding for this request. Once set, the request can no longer be cancelled.
previousobjectnoThe decision a new request for another look replaces. Restored if the request is cancelled.
previous.statusstringyesThe earlier decision. One of: confirmed, adjusted, rejected.
previous.atstring or nullyesWhen it was made.
previous.notestring or nullyesWhat the researcher wrote.
previous.severityBeforestringnoThe 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.

FieldTypeAlways presentDescription
levelstringyesHow urgent the finding is, P0 being the most urgent.
fromSeveritystringyesWhat the severity alone would give: critical P0, high P1, medium P2, low and info P3.
provenbooleanyesTrue when the finding was reproduced, in the sandbox or against the running application.
reasonsarray of stringyesWhy it is this level, most important first, written to be shown to people as they are.

#FindingSighting

One run that reported a finding.

FieldTypeAlways presentDescription
sourcestringyesWhat kind of run reported it. One of: review, pentest.
sourceIdstringyesThe id of that review or pentest.
prNumberinteger or nullyesThe pull request, for a review. null for a pentest.
atstringyesWhen that run reported it.

#FindingStateChange

One change of a finding's state.

FieldTypeAlways presentDescription
atstringyesWhen the state changed.
bystring or nullyesWho changed it: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when not known.
fromstring or nullyesThe 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.
tostringyesThe state after. One of: open, patched, accepted_risk, false_positive.
reasonstring or nullyesThe reason given with the change.
reviewAtstring or nullyesAccepted risks: the review date set with the decision.
viastring or nullyesHow the change came about when it was not a single decision in the console.

#FindingFixRun

One fix run started for a finding.

FieldTypeAlways presentDescription
runIdstringyesThe id of the fix run.
startedAtstringyesWhen it was started.
finishedAtstring or nullyesWhen it ended. null while it runs.
statusstringyesWhere that run stands. One of: queued, running, completed, failed, skipped, cancelled.
outcomestring or nullyesHow it ended for this finding. null until it has. One of: fixed, unverified, no_fix_needed, false_positive, failed, null.
prUrlstring or nullyesThe 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.

FieldTypeAlways presentDescription
dataFlowobject or nullyesThe data-flow path. Null when none was recorded.
dataFlow.stepsarray of TraceStepyesThe path, entry point first and sink last.
dataFlow.entryPointstring or nullyesWhere the data comes in.
dataFlow.sinkstring or nullyesWhere it does harm.
dataFlow.confirmedBystringyesindependent-check: the path the independent check confirmed. finder: the path as first reported, not confirmed hop by hop.
callPathobject or nullyesThe call path from an entry point to the flagged code. Null when none was recorded.
callPath.stepsarray of TraceStepyesThe calls, entry point first.
callPath.basisstringyesHow the path was worked out and what it cannot see.
diagramstring or nullyesA 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.
proofobject or nullyesThe proof on record. Null when the finding was not reproduced.
proof.kindstringyessandbox: a probe run in the sandbox. live: a request against a running application in the live-testing scope.
proof.summarystringyesWhat the proof showed. Up to 400 characters.
proof.reproducedbooleanyesWhether the flaw was reproduced.
proof.outcomestringnoFor 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.
occurrencesintegeryesHow many times runs have raised this finding. 1 when the count was not recorded.
skillstring or nullyesThe skill that raised it, when one did.
verdictTriageVerdict or nullyes
historyarray of objectyesDecisions and notes on the finding, oldest first; entries without a time come last.
history[].atstring or nullyesWhen. Null when the time was not recorded.
history[].bystring or nullyesWho: a member, independent check, researcher, or null when it was the system.
history[].whatstringyesWhat happened.
history[].detailstringnoMore, when there is more. Up to 500 characters.
missingarray of stringyesEach 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.

FieldTypeAlways presentDescription
filestringyesPath of the file, relative to the repository root, with forward slashes.
startLineintegeryesThe first flagged line, counted from 1.
endLineintegernoThe last flagged line, when the finding spans several.
snippetstringnoThe flagged code. Keys, tokens and passwords in it are masked.

#PackageRef

The package a dependency finding is about.

FieldTypeAlways presentDescription
ecosystemstringyesThe package registry: npm, PyPI, crates.io or another.
namestringyesThe package name.
versionstringyesThe version in use.
fixedVersionstringnoThe first version without the problem, when one is known.
manifeststringnoThe manifest or lockfile the package was found in, relative to the repository root.
directbooleannoTrue 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.

FieldTypeAlways presentDescription
kindstringyesWhat 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.
summarystringyesOne or two sentences saying what this step showed.
detailstringnoThe longer text of the step. On probe evidence these are the probe files.
commandstringnoThe command that was run, on evidence that ran one.
exitCodeintegernoWhat the command exited with.
outputstringnoWhat the command printed.
proofProofRecordnoOn probe evidence written by the proof step: how the reproduction went.

#Patch

A fix written for a finding.

FieldTypeAlways presentDescription
diffstringyesA unified diff, applicable with git apply from the repository root.
descriptionstringyesWhat the patch changes, in plain words.
verifiedbooleanyesTrue when the patch passed its checks on a fresh checkout.
verificationPatchVerificationnoHow it was checked, when it was.
attemptsarray of PatchAttemptnoEvery attempt made, oldest first. diff is the last one.
unprovenobjectnoPresent only on a patch written without reproducing the flaw. Such a patch is never verified.
unproven.reasonstringyesWhy the flaw was not reproduced.
unproven.proofstringyesWhat the reproduction attempt recorded. Never reproduced, and never not_reproduced: when the code behaved safely no patch is written.
unproven.acceptedbooleanyesTrue 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.independentReviewerbooleanyesTrue 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.

FieldTypeAlways presentDescription
shapeFlawShapenoWhat the flagged code looks like. Absent when the finding is not about code.
exposureExposurenoHow the code can be reached, and by whom.

#TriageVerdict

The independent check's verdict on a finding, in a fixed shape.

FieldTypeAlways presentDescription
verdictstringyesWhat the independent check concluded. One of: true_positive, false_positive.
confidencestringyesHow sure it is. A low verdict is left for a person: nothing is rejected or downgraded on it.
severitystringyesThe severity after weighing prerequisites, impact and difficulty. One of: critical, high, medium, low, info.
severityBeforestringnoThe severity first claimed, present only when the check changed it. One of: critical, high, medium, low, info.
severityReasonsarray of stringyesWhy the severity is what it is.
mitigationsarray of stringyesControls found on the path (validation, authorisation, safe APIs, limits), whether or not they stop the flaw.
weaknessFitsboolean or nullyesWhether the weakness class named on the finding fits what the code does. Null when the check did not say.
reasoningstringyesThe check's reasoning, in plain words.
confirmedPatharray of stringyesThe hops of the reported path that the check confirmed in the code.
atstringnoWhen the verdict was given.

#TraceStep

One step of a path through the code.

FieldTypeAlways presentDescription
nintegeryesIts position on the path, from 1.
textstringyesWhat happens at this step. Up to 400 characters.
filestringnoThe file, when the step names one.
lineintegernoThe 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".

FieldTypeAlways presentDescription
outcomestringyesWhat 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.
attemptsintegeryesHow many probe attempts were made, 1 or 2.
missingstringnoFor environment_missing: what the sandbox lacked, in a few words.
dependenciesstringyesWhether the project's dependencies were in place before the probe ran. One of: installed, present, not_installed, not_needed.
controlHeldbooleannoThe harmless control run behaved safely. Absent when no control was run.
repeatablebooleannoThe probe gave the same result when run a second time. Set when the outcome is reproduced.
auditedbooleannoAn 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.
variantHeldbooleannoA 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.
modelsAskedintegernoPresent 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.
declinedintegernoPresent only when writing the probe was declined at least once: how many of the models asked declined.

#PatchVerification

How a patch was checked.

FieldTypeAlways presentDescription
probePassedbooleanyesThe probe no longer reproduces the flaw on a fresh, patched checkout.
testsPassedboolean or nullyesWhether the project’s own tests pass with the patch. null when the project has no test command.
logstringyesThe output of the verification run.
checksarray of FixChecknoEvery check, in the order it ran. Absent on patches recorded before checks were itemised.
refusedarray of stringnoWhy 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.

FieldTypeAlways presentDescription
attemptintegeryesWhich try this was, counted from 1.
verifiedbooleanyesWhether this attempt passed every check.
reasonstringnoWhy this attempt was not accepted. Absent when it was.
proposedbooleannoOnly 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.
filesarray of stringyesThe 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.

FieldTypeAlways presentDescription
vintegeryesThe version of this description. Always 1.
familiesarray of stringyesThe weakness families of the finding, sorted.
filestringyesThe file of the flagged line.
fnstring or nullyesThe function that encloses the flagged line. null for code outside any named function.
indexedbooleanyesTrue when the code index covered the file, so fn and callers are facts and not gaps.
anchorstringyesThe flagged statement, normalised. Empty when it carries too little to identify anything.
sinkstringyesThe statement where the dangerous operation happens, normalised. Equal to anchor when the evidence names no other.
ordinalintegeryesWhich of several identical statements in the enclosing function this is. 0 is the first.
sourcestring or nullyesThe line where the data comes in, normalised, when the evidence names it.
entrystring or nullyesThe registration line of the entry point the code is reached from, normalised.
nearstringyesA hash of the code within a few lines of the flagged statement.
widearray of stringyesA sketch of the whole enclosing function, used to score how alike two functions are.
callersarray of string or nullyesOne entry per caller of the enclosing function. null when not known.
familystringyesFindings 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.

FieldTypeAlways presentDescription
reachablestringyesWhether the flawed code is called from an entry point. One of: yes, no, not_determined.
entryPointobject or nullyesThe entry point, when the code is reachable from one.
entryPoint.kindstringyesWhat sort of entry point it is.
entryPoint.namestringyesIts name in the code.
entryPoint.filestringyesThe file it is registered in.
entryPoint.lineintegeryesThe line it is registered on.
entryPoint.methodstringnoFor an HTTP entry point: the method.
entryPoint.routestringnoFor an HTTP entry point: the route.
authenticationstringyesWhether that entry point asks for a signed-in caller. One of: required, none, not_determined.
surfacestringyesWho can get to the entry point. One of: internet, internal, admin, cli, test, not_determined.
attackerControlledstringyesWhether the value that reaches the flaw comes from the caller. One of: yes, no, not_determined.
basisarray of stringyesHow each fact above was established, one line each.

#FixCheck

One named check a fix went through.

FieldTypeAlways presentDescription
namestringyesWhich 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).
statusstringyesnot_run is never a pass: the check could not be made, and detail says why.
detailstringyesOne plain sentence: what was seen, or why the check could not run.
placestringnoFor a fix that covers several places: the one this check belongs to, as file:line.

Nullgap documentation