Nullgap.dev Docs

API reference

Findings

List, read, triage and export findings, and see what was held back because of an earlier decision.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
Export findingsGET /api/orgs/{org}/findings/exportread
Get the evidence bundleGET /api/orgs/{org}/findings/{id}/evidenceread
Add a notePOST /api/orgs/{org}/findings/{id}/noteswrite
Request an expert reviewPOST /api/orgs/{org}/findings/{id}/expert-reviewadmin
Cancel an expert review requestDELETE /api/orgs/{org}/findings/{id}/expert-reviewadmin
Request an expert review of a pentest reportPOST /api/orgs/{org}/pentests/{id}/expert-reviewadmin
Cancel an expert review request for a pentestDELETE /api/orgs/{org}/pentests/{id}/expert-reviewadmin
List findingsGET /api/orgs/{org}/findingsread
Triage several findingsPOST /api/orgs/{org}/findings/bulkwrite
List held-back findingsGET /api/orgs/{org}/suppressionsread
Restore a held-back findingPOST /api/orgs/{org}/suppressions/{id}/restorewrite
Get a findingGET /api/orgs/{org}/findings/{id}read
Triage a findingPATCH /api/orgs/{org}/findings/{id}write
List similar findingsGET /api/orgs/{org}/findings/{id}/similarread
File an issuePOST /api/orgs/{org}/findings/{id}/issuewrite
Get a fix promptGET /api/orgs/{org}/findings/{id}/fix-promptread

#Export findings

GET /api/orgs/{org}/findings/export

Downloads every finding that matches the filters as one file; there is no paging. The filters and the order are those of the findings list. The answer is a file attachment named nullgap-<organisation>-findings with the extension of the format, and it is written as a stream, so a failure part-way ends the connection early. Each export is recorded in the audit log. In the console this is for admins and owners; an API key of any scope may call it.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
formatstringnoThe file format. csv (the default, text/csv): one row per finding. json (application/json): the full finding records. sarif (application/sarif+json): SARIF 2.1.0, for code-scanning tools.
statestringnoOnly findings in this state: open, patched, accepted_risk or false_positive. all (the default) does not filter. Any other value matches nothing.
severitystringnoOnly findings of this severity. One of: critical, high, medium, low, info.
prioritystringnoOnly findings of this priority level. One of: P0, P1, P2, P3.
sourcestringnoOnly findings first reported by this kind of run. One of: review, pentest.
repoIdstringnoOnly findings in this repository.
filestringnoOnly findings in exactly this file: the path relative to the repository root, as in finding.location.file. A leading ./ or / is ignored. Combine with repoId when several repositories share paths.
qstringnoText to look for, ignoring case, in the title, the rule id, the file path, the repository name and the CWE ids.
sortstringnoseverity (the default): most severe first, then most recently first seen. priority: most urgent first, then most severe.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/export"

Answer (200, text/csv)

The file, in the format asked for.

csv (text/csv; charset=utf-8): a header row, then one row per finding, lines ending in CRLF. The columns, in order: id, severity, state, assurance (proven, verified or unverified), title, weakness (the CWE ids, separated by spaces), repository, source (review or pentest), pull_request, file (the manifest for a dependency finding), line, first_seen, resolved_at, resolved_in (the commit), state_reason, decided_by, fix_pull_request, issue, fix_proven (yes when the pull request in fix_pull_request is a fix proven by reproduction, no when it is a fix proposed without proof, empty when there is none), expert_review (requested, confirmed, adjusted or rejected when a Nullgap security researcher was asked to review the finding, empty otherwise). A value with no content is an empty cell. A cell that would start with =, +, -, @, a tab or a carriage return is prefixed with an apostrophe, so a spreadsheet does not read it as a formula.

json (application/json; charset=utf-8): one object, { "exportedAt": "<date and time>", "findings": [ ... ] }, where each entry is a full finding record exactly as the single-finding route returns it.

sarif (application/sarif+json; charset=utf-8, file extension .sarif): a SARIF 2.1.0 log with one run. tool.driver is Nullgap with one rule per distinct rule id (its properties carry tags with the CWE and CVE ids and a security-severity score). Each result has ruleId, level (error for critical and high, warning for medium, note for low and info), message.text (the title, the description and the suggested fix), one location (file and lines; the manifest for a dependency finding), partialFingerprints.nullgapFingerprint, and properties with status, confidence, source, module, findingId, state, assurance, repository and pullRequest. A finding in the state false_positive or accepted_risk is still exported, with a suppressions entry whose justification is the reason that was given.

Errors specific to this call

StatusCodeWhen
400bad_requestformat is not csv, json or sarif, or severity, priority or sort is not one of its allowed values.
403forbiddenA signed-in member who is not an admin or owner asks for the export.

#Get the evidence bundle

GET /api/orgs/{org}/findings/{id}/evidence

Returns everything that backs one finding in one document: the finding, how far it was checked, the chain of evidence, the reproduction when there is one, the patch, the privacy record of the run that reported it, and the notes. The bundle carries its own SHA-256 so it can be shown to be unaltered. It is generated on each call, so generatedAt and sha256 differ from call to call. With format=md the answer is not JSON but a Markdown file (text/markdown; charset=utf-8), sent as an attachment named nullgap-evidence-<finding id>.md, that holds the same content for reading.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Query parameters

NameTypeRequiredDescription
formatstringnojson (the default) for the bundle as JSON, md for a Markdown file. Any value other than md gives JSON.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/evidence"

Answer (200, application/json)

A EvidenceBundle object.

{
  "schema": "nullgap.evidence/1",
  "generatedAt": "2026-11-16T09:30:00.000Z",
  "hashCovers": "SHA-256 of this bundle in its JSON form without the sha256 and generatedAt fields, serialised with keys sorted at every level and no whitespace.",
  "finding": {
    "id": "fnd_8f3a2c9d1b4e",
    "title": "SQL injection in order lookup",
    "severity": "high",
    "cwe": [
      "CWE-89"
    ],
    "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
    "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
    "location": {
      "file": "src/orders.js",
      "startLine": 42,
      "endLine": 44,
      "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
    },
    "repository": "acme/shop",
    "source": "review",
    "pullRequest": 128,
    "state": "open",
    "stateReason": "Internal tool, reachable only over the VPN.",
    "firstSeenAt": "2026-11-10T14:05:00.000Z",
    "resolvedAt": "2026-11-16T09:30:00.000Z",
    "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1"
  },
  "assurance": {
    "level": "proven",
    "statement": "A probe was run against this code in an isolated sandbox and reproduced the flaw. The command, its output and the probe files are in the Proof section."
  },
  "evidence": [
    {
      "kind": "reasoning",
      "summary": "The id reaches the query without validation.",
      "detail": "req.query.id flows from src/routes.js:18 into db.query at src/orders.js:42."
    }
  ],
  "proof": {
    "command": "node probe.js",
    "exitCode": 0,
    "output": "REPRODUCED: 3 rows returned for a single order id",
    "files": "// probe.js\nconst res = await fetch(base + \"/orders?id=1 OR 1=1\");"
  },
  "patch": {
    "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
    "verified": true,
    "description": "Pass the order id as a bound parameter."
  },
  "run": {
    "id": "rev_2a6d9f1c4b7e",
    "kind": "review",
    "commit": "4e8a1c3b5d7f9a0b2c4d6e8f0a1b3c5d7e9f1a2b",
    "finishedAt": "2026-11-16T09:30:00.000Z",
    "privacy": {
      "zeroRetention": true,
      "identifiersMasked": 14
    }
  },
  "expertReview": {
    "status": "confirmed",
    "decidedAt": "2026-11-16T09:30:00.000Z",
    "note": "string",
    "severityBefore": "high",
    "requestedAt": "2026-11-16T09:30:00.000Z"
  },
  "notes": [
    {
      "author": "dana@acme.example",
      "text": "Confirmed with the orders team, fix planned for this sprint.",
      "at": "2026-11-16T09:30:00.000Z",
      "via": "console"
    }
  ],
  "history": [
    {
      "at": "2026-11-16T09:30:00.000Z",
      "by": "dana@acme.example",
      "from": "open",
      "to": "accepted_risk",
      "reason": "Internal tool, reachable only over the VPN.",
      "reviewAt": "2027-02-01T23:59:59.000Z",
      "via": "one decision for 5 findings"
    }
  ],
  "sha256": "3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855e"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo finding with this id exists in the organisation.

#Add a note

POST /api/orgs/{org}/findings/{id}/notes

Adds a note to the finding, signed with the caller, and returns the finding with the note in notes. A finding keeps its latest 100 notes. Notes cannot be edited or removed.

Who may call it: An API key with the write scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Request body (application/json)

FieldTypeRequiredDescription
textstringyesThe note, 1 to 2000 characters after surrounding spaces are removed.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Confirmed with the orders team, fix planned for this sprint."}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/notes"

Answer (200, application/json)

A FindingRecord object.

{
  "id": "fnd_8f3a2c9d1b4e",
  "orgId": "org_1d4c7b9a2e5f",
  "repoId": "repo_4b7e1a9c2d3f",
  "repoFullName": "acme/shop",
  "source": "review",
  "sourceId": "rev_2a6d9f1c4b7e",
  "prNumber": 128,
  "finding": {
    "id": "f_3c9e1a7b2d4f",
    "module": "code",
    "ruleId": "sql-injection",
    "title": "SQL injection in order lookup",
    "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
    "severity": "high",
    "confidence": 0.9,
    "cwe": [
      "CWE-89"
    ],
    "cve": [
      "CVE-2021-23337"
    ],
    "location": {
      "file": "src/orders.js",
      "startLine": 42,
      "endLine": 44,
      "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
    },
    "package": {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20",
      "fixedVersion": "4.17.21",
      "manifest": "package-lock.json",
      "direct": true
    },
    "source": "builtin",
    "status": "proven",
    "evidence": [
      {
        "kind": "probe",
        "summary": "The probe read another customer’s order by changing the id in the query string.",
        "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
        "command": "node probe.js",
        "exitCode": 0,
        "output": "REPRODUCED: 3 rows returned for a single order id",
        "proof": {
          "outcome": "reproduced",
          "attempts": 1,
          "missing": "A running PostgreSQL database",
          "dependencies": "installed",
          "controlHeld": true,
          "repeatable": true,
          "audited": true,
          "variantHeld": true,
          "modelsAsked": 2,
          "declined": 1
        }
      }
    ],
    "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
    "patch": {
      "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
      "description": "Pass the order id as a bound parameter.",
      "verified": true,
      "verification": {
        "probePassed": true,
        "testsPassed": true,
        "log": "probe: exit 1 (safe)\ntests: 48 passed",
        "checks": [
          {
            "name": "probe",
            "status": "passed",
            "detail": "The probe no longer reproduces on the patched code.",
            "place": "src/orders.js:42"
          }
        ],
        "refused": [
          "The patch removes the endpoint instead of fixing it."
        ]
      },
      "attempts": [
        {
          "attempt": 1,
          "verified": true,
          "reason": "The second input still reproduced the flaw.",
          "proposed": true,
          "files": [
            "src/orders.js"
          ]
        }
      ],
      "unproven": {
        "reason": "Nullgap AI declined to write a probe for this finding",
        "proof": "no_probe",
        "accepted": true,
        "independentReviewer": true
      }
    },
    "fingerprint": "5b1f0c9a7e2d4a61",
    "triage": {
      "shape": {
        "v": 1,
        "families": [
          "sql-injection"
        ],
        "file": "src/orders.js",
        "fn": "getOrder",
        "indexed": true,
        "anchor": "db . query ( `…` )",
        "sink": "db . query ( `…` )",
        "ordinal": 0,
        "source": "const id = req . query . id",
        "entry": "app . get ( \"\" , getOrder )",
        "near": "9c41f0a7d2b3",
        "wide": [
          "03af19c2"
        ],
        "callers": [
          "listOrders:5e7a01bc"
        ],
        "family": "b7d2e94a10c6"
      },
      "exposure": {
        "reachable": "yes",
        "entryPoint": {
          "kind": "http",
          "name": "getOrder",
          "file": "src/routes.js",
          "line": 18,
          "method": "GET",
          "route": "/orders"
        },
        "authentication": "none",
        "surface": "internet",
        "attackerControlled": "yes",
        "basis": [
          "GET /orders is registered in src/routes.js:18 with no sign-in check."
        ]
      }
    },
    "triageVerdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    }
  },
  "state": "open",
  "stateReason": "Internal tool, reachable only over the VPN.",
  "stateBy": "dana@acme.example",
  "firstSeenAt": "2026-11-10T14:05:00.000Z",
  "resolvedAt": "2026-11-16T09:30:00.000Z",
  "remediation": {
    "runId": "run_7c1e4a9b2d6f",
    "status": "completed",
    "outcome": "fixed",
    "prUrl": "https://github.com/acme/shop/pull/131"
  },
  "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
  "notes": [
    {
      "author": "dana@acme.example",
      "text": "Confirmed with the orders team, fix planned for this sprint.",
      "at": "2026-11-16T09:30:00.000Z",
      "via": "console"
    }
  ],
  "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
  "validation": {
    "status": "confirmed",
    "at": "2026-11-16T09:30:00.000Z",
    "note": "Reproduced against staging with a second account.",
    "severityBefore": "medium",
    "requestedAt": "2026-11-16T09:30:00.000Z",
    "requestedBy": "Dana Lee",
    "scope": "finding",
    "requestNote": "Please check whether the admin check in middleware.js stops this.",
    "openedAt": "2026-11-16T09:30:00.000Z",
    "previous": {
      "status": "confirmed",
      "at": "2026-11-16T09:30:00.000Z",
      "note": "string",
      "severityBefore": "high"
    }
  },
  "priority": {
    "level": "P0",
    "fromSeverity": "P1",
    "proven": true,
    "reasons": [
      "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
    ]
  },
  "sightings": [
    {
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "at": "2026-11-16T09:30:00.000Z"
    }
  ],
  "riskReviewAt": "2027-02-01T00:00:00.000Z",
  "earlierDecision": {
    "findingId": "fnd_5a0e3c8b7d19",
    "decision": "false_positive",
    "note": "Raised although it resembles a dismissed finding: this one was reproduced."
  },
  "stateHistory": [
    {
      "at": "2026-11-16T09:30:00.000Z",
      "by": "dana@acme.example",
      "from": "open",
      "to": "accepted_risk",
      "reason": "Internal tool, reachable only over the VPN.",
      "reviewAt": "2027-02-01T23:59:59.000Z",
      "via": "one decision for 5 findings"
    }
  ],
  "fixRuns": [
    {
      "runId": "run_7c1e4a9b2d6f",
      "startedAt": "2026-11-16T09:30:00.000Z",
      "finishedAt": "2026-11-16T09:30:00.000Z",
      "status": "completed",
      "outcome": "fixed",
      "prUrl": "https://github.com/acme/shop/pull/131"
    }
  ],
  "trace": {
    "dataFlow": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "entryPoint": "GET /orders (src/orders/list.ts:22)",
      "sink": "db.query in src/orders/repo.ts:57",
      "confirmedBy": "independent-check"
    },
    "callPath": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
    },
    "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
    "proof": {
      "kind": "sandbox",
      "summary": "The probe read another customer's order by changing the sort column.",
      "reproduced": true,
      "outcome": "reproduced"
    },
    "occurrences": 3,
    "skill": "injection-review",
    "verdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    },
    "history": [
      {
        "at": "2026-11-16T09:30:00.000Z",
        "by": "dana@acme.example",
        "what": "State set to accepted risk",
        "detail": "Behind the office network until the migration in March."
      }
    ],
    "missing": [
      "No call path from an entry point was recorded."
    ]
  }
}

Errors specific to this call

StatusCodeWhen
400bad_requesttext is missing, not a string, empty, or longer than 2000 characters.
404not_foundNo finding with this id exists in the organisation.

#Request an expert review

POST /api/orgs/{org}/findings/{id}/expert-review

Asks a Nullgap security researcher to review this finding (the expert review add-on). Admins only. The finding gets validation.status pending; when the researcher decides, validation says what was decided, the researcher's notes appear in notes under the name Nullgap researcher, and a finding.expert_reviewed webhook event is sent. Works for findings from pull request reviews and from pentests; the finding must be open. Asking again for a finding that is already waiting changes nothing and answers 200. A finding a researcher has already reviewed answers 409 unless again is true. The request is your consent for a Nullgap researcher to read the finding, its evidence and its code. Who the researcher is is not disclosed.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Request body (application/json)

FieldTypeRequiredDescription
notestringnoWhat you want the researcher to check, up to 1000 characters. Optional.
againbooleannoAsk for another look at a finding a researcher has already reviewed. The earlier decision is kept until the new one is made.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Please check whether the admin check in middleware.js stops this.","again":false}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/expert-review"

Answer (200, application/json)

A ExpertReviewRequestResult object.

{
  "requested": 1,
  "alreadyPending": 0,
  "alreadyReviewed": 0,
  "findings": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ]
}

Errors specific to this call

StatusCodeWhen
400bad_requestnote is longer than 1000 characters, or again is not a boolean.
403forbiddenThe caller is not an admin.
403add_on_requiredThe workspace does not have the expert review add-on. Contact us to add it.
404not_foundNo finding with this id exists in the organisation.
409already_reviewedA researcher has already reviewed the finding and again is not true.
409not_openThe finding is not open.

#Cancel an expert review request

DELETE /api/orgs/{org}/findings/{id}/expert-review

Withdraws your request for an expert review of this finding, as long as a researcher has not opened it yet. A finding that had an earlier decision gets it back. Admins only. Takes no body.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/expert-review"

Answer (200, application/json)

A ExpertReviewCancelResult object.

{
  "cancelled": 1,
  "kept": 0,
  "findings": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ]
}

Errors specific to this call

StatusCodeWhen
403forbiddenThe caller is not an admin.
404not_foundNo finding with this id exists in the organisation.
409not_requestedThere is no request of yours waiting on the finding.
409review_startedA researcher has already opened the finding.

#Request an expert review of a pentest report

POST /api/orgs/{org}/pentests/{id}/expert-review

Asks a Nullgap security researcher to review every open proven or verified finding of a finished pentest. Admins only. Findings already waiting are left as they are; findings already reviewed are left as they are unless again is true. When the last finding is decided, the pentest's reports are revised once to carry the reviewed result. The request is your consent for a Nullgap researcher to read those findings, their evidence and their code.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
notestringnoWhat you want the researcher to check, up to 1000 characters. Optional.
againbooleannoAlso ask for another look at findings a researcher has already reviewed.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Focus on the payment flows.","again":false}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/expert-review"

Answer (200, application/json)

A ExpertReviewRequestResult object.

{
  "requested": 1,
  "alreadyPending": 0,
  "alreadyReviewed": 0,
  "findings": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ]
}

Errors specific to this call

StatusCodeWhen
400bad_requestnote is longer than 1000 characters, or again is not a boolean.
403forbiddenThe caller is not an admin.
403add_on_requiredThe workspace does not have the expert review add-on. Contact us to add it.
404not_foundNo pentest of this organisation has that id.
409not_finishedThe pentest has not finished.
409nothing_to_reviewThe pentest has no open proven or verified findings.
409already_reviewedEvery such finding has already been reviewed and again is not true.

#Cancel an expert review request for a pentest

DELETE /api/orgs/{org}/pentests/{id}/expert-review

Withdraws the requests waiting on this pentest's findings that a researcher has not opened yet. Findings a researcher has already opened stay in review and are counted in kept. Admins only. Takes no body.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/expert-review"

Answer (200, application/json)

A ExpertReviewCancelResult object.

{
  "cancelled": 1,
  "kept": 0,
  "findings": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ]
}

Errors specific to this call

StatusCodeWhen
403forbiddenThe caller is not an admin.
404not_foundNo pentest of this organisation has that id.
409not_requestedNo request of yours is waiting on the pentest's findings.
409review_startedA researcher has already opened every requested finding.

#List findings

GET /api/orgs/{org}/findings

Lists the organisation’s findings, most severe first unless sort=priority is given. One flaw is one finding however many runs reported it: see sightings on each. Findings that were held back because of an earlier decision are not in this list; they are under the suppressions route.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
statestringnoOnly findings in this state: open, patched, accepted_risk or false_positive. all (the default) does not filter. Any other value matches nothing.
severitystringnoOnly findings of this severity. One of: critical, high, medium, low, info.
prioritystringnoOnly findings of this priority level. One of: P0, P1, P2, P3.
sourcestringnoOnly findings first reported by this kind of run. One of: review, pentest.
repoIdstringnoOnly findings in this repository.
filestringnoOnly findings in exactly this file: the path relative to the repository root, as in finding.location.file. A leading ./ or / is ignored. Combine with repoId when several repositories share paths.
qstringnoText to look for, ignoring case, in the title, the rule id, the file path, the repository name and the CWE ids.
sortstringnoseverity (the default): most severe first, then most recently first seen. priority: most urgent first, then most severe.
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/findings?limit=20"

Answer (200, application/json)

FieldTypeAlways presentDescription
itemsarray of FindingRecordyesThe findings, at most limit of them.
totalintegeryesHow many match in all, before limit and offset.
{
  "items": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ],
  "total": 42
}

Errors specific to this call

StatusCodeWhen
400bad_requestseverity, priority or sort is not one of its allowed values.

#Triage several findings

POST /api/orgs/{org}/findings/bulk

Applies one decision, with one reason, to several findings: the ones listed in ids, and with like that finding together with every finding like it (same repository, same weakness class, same dangerous statement, in any state). Each finding is changed, audited and remembered exactly as a single change would be. A finding already in that state with that reason is skipped. Send expect with like to be sure nothing is changed if the group has grown or shrunk since you looked.

Who may call it: An API key with the write scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
idsarray of stringnoThe findings to change, up to 500. Ids that do not exist are reported under skipped.
likestringnoA finding id. That finding and every finding like it are added to the ones to change.
expectintegernoUsed with like: how many findings you expect that to be, the finding itself included. If the number is now different, nothing is changed.
statestringyesThe state to move to. open reopens a finding. patched records that it was fixed. accepted_risk and false_positive dismiss it and need a reason.
reasonstringnoWhy. Required for accepted_risk and false_positive, optional otherwise. Up to 2000 characters.
reviewAtstring or nullnoFor accepted_risk only: a date in the future on which the acceptance is to be looked at again. After it the finding is raised again when found. Leave out, or send null, for none.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["fnd_8f3a2c9d1b4e"],"like":"fnd_8f3a2c9d1b4e","expect":3,"state":"false_positive","reason":"The id is validated as an integer two lines above.","reviewAt":null}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/bulk"

Answer (200, application/json)

A BulkTriageResult object.

{
  "changed": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ],
  "skipped": [
    {
      "id": "fnd_0b4d7e1a9c3f",
      "why": "Already in this state with this reason"
    }
  ]
}

Errors specific to this call

StatusCodeWhen
400bad_requestids is not a list of up to 500 strings, or neither ids nor like selects a finding that exists.
400bad_requeststate is missing or not one of the four states; a dismissal has no reason; reason is longer than 2000 characters; or reviewAt is given for a state other than accepted_risk, is not a date, or is not in the future.
404not_foundThe finding named in like does not exist.
409changedThe number of findings like the one in like is no longer the number given in expect. Nothing was changed.

#List held-back findings

GET /api/orgs/{org}/suppressions

Lists the findings that runs produced and Nullgap did not raise, because the team had already dismissed the same finding or code that is the same. Each entry says which decision it rests on and why it counts as the same. Most recently held back first.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
statestringnoactive (the default): still held back. restored: brought back since. all: both.
repoIdstringnoOnly those found in this repository.
sourceIdstringnoOnly those held back by this run: the id of a review or a pentest.
sourcestringnoUsed with sourceId to say which kind of run it names. Ignored without sourceId.
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/suppressions?limit=20"

Answer (200, application/json)

FieldTypeAlways presentDescription
itemsarray of SuppressedFindingyesThe held-back findings, at most limit of them.
totalintegeryesHow many match in all, before limit and offset.
{
  "items": [
    {
      "id": "sup_6e2b9d0a4c7f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "kind": "pattern",
      "decision": "false_positive",
      "decidedBy": "dana@acme.example",
      "decidedAt": "2026-10-02T11:20:00.000Z",
      "reason": "The id is validated as an integer two lines above.",
      "dismissedFindingId": "fnd_5a0e3c8b7d19",
      "why": [
        "Same weakness class and the same dangerous statement."
      ],
      "similarity": 0.96,
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "firstAt": "2026-11-03T08:12:00.000Z",
      "lastAt": "2026-11-16T09:30:00.000Z",
      "restoredAt": "2026-11-16T09:30:00.000Z",
      "restoredBy": "dana@acme.example",
      "restoredFindingId": "fnd_8f3a2c9d1b4e"
    }
  ],
  "total": 42
}

Errors specific to this call

StatusCodeWhen
400bad_requeststate is not active, restored or all.

#Restore a held-back finding

POST /api/orgs/{org}/suppressions/{id}/restore

Brings a held-back finding back. What happens depends on its kind. same_finding: the dismissed finding itself is reopened, which also raises everything its decision was holding back. pattern: this entry becomes an open finding of its own and the remembered pattern is removed, so everything else that pattern was holding back is raised too; the finding that was dismissed first keeps its state.

Who may call it: An API key with the write scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the held-back record, such as sup_6e2b9d0a4c7f.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/suppressions/sup_6e2b9d0a4c7f/restore"

Answer (200, application/json)

FieldTypeAlways presentDescription
findingFindingRecordyesThe finding that is now open: the reopened one, or the new one this entry became.
alsoRestoredintegeryesHow many other held-back findings came back with it.
{
  "finding": {
    "id": "fnd_8f3a2c9d1b4e",
    "orgId": "org_1d4c7b9a2e5f",
    "repoId": "repo_4b7e1a9c2d3f",
    "repoFullName": "acme/shop",
    "source": "review",
    "sourceId": "rev_2a6d9f1c4b7e",
    "prNumber": 128,
    "finding": {
      "id": "f_3c9e1a7b2d4f",
      "module": "code",
      "ruleId": "sql-injection",
      "title": "SQL injection in order lookup",
      "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
      "severity": "high",
      "confidence": 0.9,
      "cwe": [
        "CWE-89"
      ],
      "cve": [
        "CVE-2021-23337"
      ],
      "location": {
        "file": "src/orders.js",
        "startLine": 42,
        "endLine": 44,
        "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
      },
      "package": {
        "ecosystem": "npm",
        "name": "lodash",
        "version": "4.17.20",
        "fixedVersion": "4.17.21",
        "manifest": "package-lock.json",
        "direct": true
      },
      "source": "builtin",
      "status": "proven",
      "evidence": [
        {
          "kind": "probe",
          "summary": "The probe read another customer’s order by changing the id in the query string.",
          "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
          "command": "node probe.js",
          "exitCode": 0,
          "output": "REPRODUCED: 3 rows returned for a single order id",
          "proof": {
            "outcome": "reproduced",
            "attempts": 1,
            "missing": "A running PostgreSQL database",
            "dependencies": "installed",
            "controlHeld": true,
            "repeatable": true,
            "audited": true,
            "variantHeld": true,
            "modelsAsked": 2,
            "declined": 1
          }
        }
      ],
      "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
      "patch": {
        "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
        "description": "Pass the order id as a bound parameter.",
        "verified": true,
        "verification": {
          "probePassed": true,
          "testsPassed": true,
          "log": "probe: exit 1 (safe)\ntests: 48 passed",
          "checks": [
            {
              "name": "probe",
              "status": "passed",
              "detail": "The probe no longer reproduces on the patched code.",
              "place": "src/orders.js:42"
            }
          ],
          "refused": [
            "The patch removes the endpoint instead of fixing it."
          ]
        },
        "attempts": [
          {
            "attempt": 1,
            "verified": true,
            "reason": "The second input still reproduced the flaw.",
            "proposed": true,
            "files": [
              "src/orders.js"
            ]
          }
        ],
        "unproven": {
          "reason": "Nullgap AI declined to write a probe for this finding",
          "proof": "no_probe",
          "accepted": true,
          "independentReviewer": true
        }
      },
      "fingerprint": "5b1f0c9a7e2d4a61",
      "triage": {
        "shape": {
          "v": 1,
          "families": [
            "sql-injection"
          ],
          "file": "src/orders.js",
          "fn": "getOrder",
          "indexed": true,
          "anchor": "db . query ( `…` )",
          "sink": "db . query ( `…` )",
          "ordinal": 0,
          "source": "const id = req . query . id",
          "entry": "app . get ( \"\" , getOrder )",
          "near": "9c41f0a7d2b3",
          "wide": [
            "03af19c2"
          ],
          "callers": [
            "listOrders:5e7a01bc"
          ],
          "family": "b7d2e94a10c6"
        },
        "exposure": {
          "reachable": "yes",
          "entryPoint": {
            "kind": "http",
            "name": "getOrder",
            "file": "src/routes.js",
            "line": 18,
            "method": "GET",
            "route": "/orders"
          },
          "authentication": "none",
          "surface": "internet",
          "attackerControlled": "yes",
          "basis": [
            "GET /orders is registered in src/routes.js:18 with no sign-in check."
          ]
        }
      },
      "triageVerdict": {
        "verdict": "true_positive",
        "confidence": "high",
        "severity": "high",
        "severityBefore": "critical",
        "severityReasons": [
          "Needs a signed-in account, which any customer can create."
        ],
        "mitigations": [
          "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
        ],
        "weaknessFits": true,
        "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
        "confirmedPath": [
          "src/orders/list.ts:22 reads req.query.sort"
        ],
        "at": "2026-11-16T09:30:00.000Z"
      }
    },
    "state": "open",
    "stateReason": "Internal tool, reachable only over the VPN.",
    "stateBy": "dana@acme.example",
    "firstSeenAt": "2026-11-10T14:05:00.000Z",
    "resolvedAt": "2026-11-16T09:30:00.000Z",
    "remediation": {
      "runId": "run_7c1e4a9b2d6f",
      "status": "completed",
      "outcome": "fixed",
      "prUrl": "https://github.com/acme/shop/pull/131"
    },
    "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
    "notes": [
      {
        "author": "dana@acme.example",
        "text": "Confirmed with the orders team, fix planned for this sprint.",
        "at": "2026-11-16T09:30:00.000Z",
        "via": "console"
      }
    ],
    "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
    "validation": {
      "status": "confirmed",
      "at": "2026-11-16T09:30:00.000Z",
      "note": "Reproduced against staging with a second account.",
      "severityBefore": "medium",
      "requestedAt": "2026-11-16T09:30:00.000Z",
      "requestedBy": "Dana Lee",
      "scope": "finding",
      "requestNote": "Please check whether the admin check in middleware.js stops this.",
      "openedAt": "2026-11-16T09:30:00.000Z",
      "previous": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "string",
        "severityBefore": "high"
      }
    },
    "priority": {
      "level": "P0",
      "fromSeverity": "P1",
      "proven": true,
      "reasons": [
        "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
      ]
    },
    "sightings": [
      {
        "source": "review",
        "sourceId": "rev_2a6d9f1c4b7e",
        "prNumber": 128,
        "at": "2026-11-16T09:30:00.000Z"
      }
    ],
    "riskReviewAt": "2027-02-01T00:00:00.000Z",
    "earlierDecision": {
      "findingId": "fnd_5a0e3c8b7d19",
      "decision": "false_positive",
      "note": "Raised although it resembles a dismissed finding: this one was reproduced."
    },
    "stateHistory": [
      {
        "at": "2026-11-16T09:30:00.000Z",
        "by": "dana@acme.example",
        "from": "open",
        "to": "accepted_risk",
        "reason": "Internal tool, reachable only over the VPN.",
        "reviewAt": "2027-02-01T23:59:59.000Z",
        "via": "one decision for 5 findings"
      }
    ],
    "fixRuns": [
      {
        "runId": "run_7c1e4a9b2d6f",
        "startedAt": "2026-11-16T09:30:00.000Z",
        "finishedAt": "2026-11-16T09:30:00.000Z",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      }
    ],
    "trace": {
      "dataFlow": {
        "steps": [
          {
            "n": 1,
            "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
            "file": "src/orders/list.ts",
            "line": 22
          }
        ],
        "entryPoint": "GET /orders (src/orders/list.ts:22)",
        "sink": "db.query in src/orders/repo.ts:57",
        "confirmedBy": "independent-check"
      },
      "callPath": {
        "steps": [
          {
            "n": 1,
            "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
            "file": "src/orders/list.ts",
            "line": 22
          }
        ],
        "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
      },
      "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
      "proof": {
        "kind": "sandbox",
        "summary": "The probe read another customer's order by changing the sort column.",
        "reproduced": true,
        "outcome": "reproduced"
      },
      "occurrences": 3,
      "skill": "injection-review",
      "verdict": {
        "verdict": "true_positive",
        "confidence": "high",
        "severity": "high",
        "severityBefore": "critical",
        "severityReasons": [
          "Needs a signed-in account, which any customer can create."
        ],
        "mitigations": [
          "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
        ],
        "weaknessFits": true,
        "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
        "confirmedPath": [
          "src/orders/list.ts:22 reads req.query.sort"
        ],
        "at": "2026-11-16T09:30:00.000Z"
      },
      "history": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "what": "State set to accepted risk",
          "detail": "Behind the office network until the migration in March."
        }
      ],
      "missing": [
        "No call path from an entry point was recorded."
      ]
    }
  },
  "alsoRestored": 1
}

Errors specific to this call

StatusCodeWhen
404not_foundNo held-back record with this id exists, or the dismissed finding it points to no longer exists.
409already_restoredThis entry has already been brought back.

#Get a finding

GET /api/orgs/{org}/findings/{id}

Returns one finding with its evidence, its priority, the decision taken about it and the runs that reported it. This answer also carries trace: the data-flow path, the call path from an entry point, a diagram, the proof, the independent check's verdict and the history of decisions, each read from what was recorded. A part that was not recorded is null and named in trace.missing.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e"

Answer (200, application/json)

A FindingRecord object.

{
  "id": "fnd_8f3a2c9d1b4e",
  "orgId": "org_1d4c7b9a2e5f",
  "repoId": "repo_4b7e1a9c2d3f",
  "repoFullName": "acme/shop",
  "source": "review",
  "sourceId": "rev_2a6d9f1c4b7e",
  "prNumber": 128,
  "finding": {
    "id": "f_3c9e1a7b2d4f",
    "module": "code",
    "ruleId": "sql-injection",
    "title": "SQL injection in order lookup",
    "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
    "severity": "high",
    "confidence": 0.9,
    "cwe": [
      "CWE-89"
    ],
    "cve": [
      "CVE-2021-23337"
    ],
    "location": {
      "file": "src/orders.js",
      "startLine": 42,
      "endLine": 44,
      "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
    },
    "package": {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20",
      "fixedVersion": "4.17.21",
      "manifest": "package-lock.json",
      "direct": true
    },
    "source": "builtin",
    "status": "proven",
    "evidence": [
      {
        "kind": "probe",
        "summary": "The probe read another customer’s order by changing the id in the query string.",
        "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
        "command": "node probe.js",
        "exitCode": 0,
        "output": "REPRODUCED: 3 rows returned for a single order id",
        "proof": {
          "outcome": "reproduced",
          "attempts": 1,
          "missing": "A running PostgreSQL database",
          "dependencies": "installed",
          "controlHeld": true,
          "repeatable": true,
          "audited": true,
          "variantHeld": true,
          "modelsAsked": 2,
          "declined": 1
        }
      }
    ],
    "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
    "patch": {
      "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
      "description": "Pass the order id as a bound parameter.",
      "verified": true,
      "verification": {
        "probePassed": true,
        "testsPassed": true,
        "log": "probe: exit 1 (safe)\ntests: 48 passed",
        "checks": [
          {
            "name": "probe",
            "status": "passed",
            "detail": "The probe no longer reproduces on the patched code.",
            "place": "src/orders.js:42"
          }
        ],
        "refused": [
          "The patch removes the endpoint instead of fixing it."
        ]
      },
      "attempts": [
        {
          "attempt": 1,
          "verified": true,
          "reason": "The second input still reproduced the flaw.",
          "proposed": true,
          "files": [
            "src/orders.js"
          ]
        }
      ],
      "unproven": {
        "reason": "Nullgap AI declined to write a probe for this finding",
        "proof": "no_probe",
        "accepted": true,
        "independentReviewer": true
      }
    },
    "fingerprint": "5b1f0c9a7e2d4a61",
    "triage": {
      "shape": {
        "v": 1,
        "families": [
          "sql-injection"
        ],
        "file": "src/orders.js",
        "fn": "getOrder",
        "indexed": true,
        "anchor": "db . query ( `…` )",
        "sink": "db . query ( `…` )",
        "ordinal": 0,
        "source": "const id = req . query . id",
        "entry": "app . get ( \"\" , getOrder )",
        "near": "9c41f0a7d2b3",
        "wide": [
          "03af19c2"
        ],
        "callers": [
          "listOrders:5e7a01bc"
        ],
        "family": "b7d2e94a10c6"
      },
      "exposure": {
        "reachable": "yes",
        "entryPoint": {
          "kind": "http",
          "name": "getOrder",
          "file": "src/routes.js",
          "line": 18,
          "method": "GET",
          "route": "/orders"
        },
        "authentication": "none",
        "surface": "internet",
        "attackerControlled": "yes",
        "basis": [
          "GET /orders is registered in src/routes.js:18 with no sign-in check."
        ]
      }
    },
    "triageVerdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    }
  },
  "state": "open",
  "stateReason": "Internal tool, reachable only over the VPN.",
  "stateBy": "dana@acme.example",
  "firstSeenAt": "2026-11-10T14:05:00.000Z",
  "resolvedAt": "2026-11-16T09:30:00.000Z",
  "remediation": {
    "runId": "run_7c1e4a9b2d6f",
    "status": "completed",
    "outcome": "fixed",
    "prUrl": "https://github.com/acme/shop/pull/131"
  },
  "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
  "notes": [
    {
      "author": "dana@acme.example",
      "text": "Confirmed with the orders team, fix planned for this sprint.",
      "at": "2026-11-16T09:30:00.000Z",
      "via": "console"
    }
  ],
  "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
  "validation": {
    "status": "confirmed",
    "at": "2026-11-16T09:30:00.000Z",
    "note": "Reproduced against staging with a second account.",
    "severityBefore": "medium",
    "requestedAt": "2026-11-16T09:30:00.000Z",
    "requestedBy": "Dana Lee",
    "scope": "finding",
    "requestNote": "Please check whether the admin check in middleware.js stops this.",
    "openedAt": "2026-11-16T09:30:00.000Z",
    "previous": {
      "status": "confirmed",
      "at": "2026-11-16T09:30:00.000Z",
      "note": "string",
      "severityBefore": "high"
    }
  },
  "priority": {
    "level": "P0",
    "fromSeverity": "P1",
    "proven": true,
    "reasons": [
      "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
    ]
  },
  "sightings": [
    {
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "at": "2026-11-16T09:30:00.000Z"
    }
  ],
  "riskReviewAt": "2027-02-01T00:00:00.000Z",
  "earlierDecision": {
    "findingId": "fnd_5a0e3c8b7d19",
    "decision": "false_positive",
    "note": "Raised although it resembles a dismissed finding: this one was reproduced."
  },
  "stateHistory": [
    {
      "at": "2026-11-16T09:30:00.000Z",
      "by": "dana@acme.example",
      "from": "open",
      "to": "accepted_risk",
      "reason": "Internal tool, reachable only over the VPN.",
      "reviewAt": "2027-02-01T23:59:59.000Z",
      "via": "one decision for 5 findings"
    }
  ],
  "fixRuns": [
    {
      "runId": "run_7c1e4a9b2d6f",
      "startedAt": "2026-11-16T09:30:00.000Z",
      "finishedAt": "2026-11-16T09:30:00.000Z",
      "status": "completed",
      "outcome": "fixed",
      "prUrl": "https://github.com/acme/shop/pull/131"
    }
  ],
  "trace": {
    "dataFlow": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "entryPoint": "GET /orders (src/orders/list.ts:22)",
      "sink": "db.query in src/orders/repo.ts:57",
      "confirmedBy": "independent-check"
    },
    "callPath": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
    },
    "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
    "proof": {
      "kind": "sandbox",
      "summary": "The probe read another customer's order by changing the sort column.",
      "reproduced": true,
      "outcome": "reproduced"
    },
    "occurrences": 3,
    "skill": "injection-review",
    "verdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    },
    "history": [
      {
        "at": "2026-11-16T09:30:00.000Z",
        "by": "dana@acme.example",
        "what": "State set to accepted risk",
        "detail": "Behind the office network until the migration in March."
      }
    ],
    "missing": [
      "No call path from an entry point was recorded."
    ]
  }
}

Errors specific to this call

StatusCodeWhen
404not_foundNo finding with this id exists in the organisation.

#Triage a finding

PATCH /api/orgs/{org}/findings/{id}

Changes what the team has decided about a finding, and records who decided and why. Dismissing a finding (accepted_risk or false_positive) needs a reason, and is remembered: the same finding, and code that is the same, is held back in later runs and listed under suppressions instead of being raised again. Moving a dismissed finding to another state forgets that, and raises whatever the decision was holding back. Every change is written to the audit log, sent to webhooks as finding.state_changed, and passed on to a linked Jira issue when status sync is on. The same checks apply to decisions made in the console and from Slack.

Who may call it: An API key with the write scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Request body (application/json)

FieldTypeRequiredDescription
statestringyesThe state to move to. open reopens a finding. patched records that it was fixed. accepted_risk and false_positive dismiss it and need a reason.
reasonstringnoWhy. Required for accepted_risk and false_positive, optional otherwise. Up to 2000 characters.
reviewAtstring or nullnoFor accepted_risk only: a date in the future on which the acceptance is to be looked at again. After it the finding is raised again when found. Leave out, or send null, for none.

Example request

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":"false_positive","reason":"The id is validated as an integer two lines above.","reviewAt":null}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e"

Answer (200, application/json)

A FindingRecord object.

{
  "id": "fnd_8f3a2c9d1b4e",
  "orgId": "org_1d4c7b9a2e5f",
  "repoId": "repo_4b7e1a9c2d3f",
  "repoFullName": "acme/shop",
  "source": "review",
  "sourceId": "rev_2a6d9f1c4b7e",
  "prNumber": 128,
  "finding": {
    "id": "f_3c9e1a7b2d4f",
    "module": "code",
    "ruleId": "sql-injection",
    "title": "SQL injection in order lookup",
    "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
    "severity": "high",
    "confidence": 0.9,
    "cwe": [
      "CWE-89"
    ],
    "cve": [
      "CVE-2021-23337"
    ],
    "location": {
      "file": "src/orders.js",
      "startLine": 42,
      "endLine": 44,
      "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
    },
    "package": {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20",
      "fixedVersion": "4.17.21",
      "manifest": "package-lock.json",
      "direct": true
    },
    "source": "builtin",
    "status": "proven",
    "evidence": [
      {
        "kind": "probe",
        "summary": "The probe read another customer’s order by changing the id in the query string.",
        "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
        "command": "node probe.js",
        "exitCode": 0,
        "output": "REPRODUCED: 3 rows returned for a single order id",
        "proof": {
          "outcome": "reproduced",
          "attempts": 1,
          "missing": "A running PostgreSQL database",
          "dependencies": "installed",
          "controlHeld": true,
          "repeatable": true,
          "audited": true,
          "variantHeld": true,
          "modelsAsked": 2,
          "declined": 1
        }
      }
    ],
    "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
    "patch": {
      "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
      "description": "Pass the order id as a bound parameter.",
      "verified": true,
      "verification": {
        "probePassed": true,
        "testsPassed": true,
        "log": "probe: exit 1 (safe)\ntests: 48 passed",
        "checks": [
          {
            "name": "probe",
            "status": "passed",
            "detail": "The probe no longer reproduces on the patched code.",
            "place": "src/orders.js:42"
          }
        ],
        "refused": [
          "The patch removes the endpoint instead of fixing it."
        ]
      },
      "attempts": [
        {
          "attempt": 1,
          "verified": true,
          "reason": "The second input still reproduced the flaw.",
          "proposed": true,
          "files": [
            "src/orders.js"
          ]
        }
      ],
      "unproven": {
        "reason": "Nullgap AI declined to write a probe for this finding",
        "proof": "no_probe",
        "accepted": true,
        "independentReviewer": true
      }
    },
    "fingerprint": "5b1f0c9a7e2d4a61",
    "triage": {
      "shape": {
        "v": 1,
        "families": [
          "sql-injection"
        ],
        "file": "src/orders.js",
        "fn": "getOrder",
        "indexed": true,
        "anchor": "db . query ( `…` )",
        "sink": "db . query ( `…` )",
        "ordinal": 0,
        "source": "const id = req . query . id",
        "entry": "app . get ( \"\" , getOrder )",
        "near": "9c41f0a7d2b3",
        "wide": [
          "03af19c2"
        ],
        "callers": [
          "listOrders:5e7a01bc"
        ],
        "family": "b7d2e94a10c6"
      },
      "exposure": {
        "reachable": "yes",
        "entryPoint": {
          "kind": "http",
          "name": "getOrder",
          "file": "src/routes.js",
          "line": 18,
          "method": "GET",
          "route": "/orders"
        },
        "authentication": "none",
        "surface": "internet",
        "attackerControlled": "yes",
        "basis": [
          "GET /orders is registered in src/routes.js:18 with no sign-in check."
        ]
      }
    },
    "triageVerdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    }
  },
  "state": "open",
  "stateReason": "Internal tool, reachable only over the VPN.",
  "stateBy": "dana@acme.example",
  "firstSeenAt": "2026-11-10T14:05:00.000Z",
  "resolvedAt": "2026-11-16T09:30:00.000Z",
  "remediation": {
    "runId": "run_7c1e4a9b2d6f",
    "status": "completed",
    "outcome": "fixed",
    "prUrl": "https://github.com/acme/shop/pull/131"
  },
  "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
  "notes": [
    {
      "author": "dana@acme.example",
      "text": "Confirmed with the orders team, fix planned for this sprint.",
      "at": "2026-11-16T09:30:00.000Z",
      "via": "console"
    }
  ],
  "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
  "validation": {
    "status": "confirmed",
    "at": "2026-11-16T09:30:00.000Z",
    "note": "Reproduced against staging with a second account.",
    "severityBefore": "medium",
    "requestedAt": "2026-11-16T09:30:00.000Z",
    "requestedBy": "Dana Lee",
    "scope": "finding",
    "requestNote": "Please check whether the admin check in middleware.js stops this.",
    "openedAt": "2026-11-16T09:30:00.000Z",
    "previous": {
      "status": "confirmed",
      "at": "2026-11-16T09:30:00.000Z",
      "note": "string",
      "severityBefore": "high"
    }
  },
  "priority": {
    "level": "P0",
    "fromSeverity": "P1",
    "proven": true,
    "reasons": [
      "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
    ]
  },
  "sightings": [
    {
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "at": "2026-11-16T09:30:00.000Z"
    }
  ],
  "riskReviewAt": "2027-02-01T00:00:00.000Z",
  "earlierDecision": {
    "findingId": "fnd_5a0e3c8b7d19",
    "decision": "false_positive",
    "note": "Raised although it resembles a dismissed finding: this one was reproduced."
  },
  "stateHistory": [
    {
      "at": "2026-11-16T09:30:00.000Z",
      "by": "dana@acme.example",
      "from": "open",
      "to": "accepted_risk",
      "reason": "Internal tool, reachable only over the VPN.",
      "reviewAt": "2027-02-01T23:59:59.000Z",
      "via": "one decision for 5 findings"
    }
  ],
  "fixRuns": [
    {
      "runId": "run_7c1e4a9b2d6f",
      "startedAt": "2026-11-16T09:30:00.000Z",
      "finishedAt": "2026-11-16T09:30:00.000Z",
      "status": "completed",
      "outcome": "fixed",
      "prUrl": "https://github.com/acme/shop/pull/131"
    }
  ],
  "trace": {
    "dataFlow": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "entryPoint": "GET /orders (src/orders/list.ts:22)",
      "sink": "db.query in src/orders/repo.ts:57",
      "confirmedBy": "independent-check"
    },
    "callPath": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
    },
    "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
    "proof": {
      "kind": "sandbox",
      "summary": "The probe read another customer's order by changing the sort column.",
      "reproduced": true,
      "outcome": "reproduced"
    },
    "occurrences": 3,
    "skill": "injection-review",
    "verdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    },
    "history": [
      {
        "at": "2026-11-16T09:30:00.000Z",
        "by": "dana@acme.example",
        "what": "State set to accepted risk",
        "detail": "Behind the office network until the migration in March."
      }
    ],
    "missing": [
      "No call path from an entry point was recorded."
    ]
  }
}

Errors specific to this call

StatusCodeWhen
400bad_requeststate is missing or not one of the four states; a dismissal has no reason; reason is longer than 2000 characters; or reviewAt is given for a state other than accepted_risk, is not a date, or is not in the future.
404not_foundNo finding with this id exists in the organisation.

#List similar findings

GET /api/orgs/{org}/findings/{id}/similar

Returns the other findings in the same repository that are like this one (same weakness class, same dangerous statement), the dismissals already taken on them, and how many later findings the decision on this one is holding back. Use it before deciding, and to choose between one decision and a bulk decision with like.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/similar"

Answer (200, application/json)

A SimilarFindings object.

{
  "determined": true,
  "similar": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ],
  "decisions": [
    {
      "findingId": "fnd_5a0e3c8b7d19",
      "title": "SQL injection in invoice lookup",
      "file": "src/invoices.js",
      "decision": "false_positive",
      "reason": "The id is validated as an integer two lines above.",
      "by": "dana@acme.example",
      "at": "2026-10-02T11:20:00.000Z",
      "reviewAt": "2027-02-01T00:00:00.000Z"
    }
  ],
  "suppressedByThis": 2
}

Errors specific to this call

StatusCodeWhen
404not_foundNo finding with this id exists in the organisation.

#File an issue

POST /api/orgs/{org}/findings/{id}/issue

Creates an issue for the finding in the organisation’s connected issue tracker and returns the finding with externalIssueUrl set. A finding has one issue: if it already has one, nothing is created and the finding is returned as it is, whichever tracker is named.

Who may call it: An API key with the write scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Request body (application/json)

FieldTypeRequiredDescription
trackerstringyesThe tracker to file the issue in. It must be connected under integrations. One of: jira, linear.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tracker":"jira"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/issue"

Answer (200, application/json)

A FindingRecord object.

{
  "id": "fnd_8f3a2c9d1b4e",
  "orgId": "org_1d4c7b9a2e5f",
  "repoId": "repo_4b7e1a9c2d3f",
  "repoFullName": "acme/shop",
  "source": "review",
  "sourceId": "rev_2a6d9f1c4b7e",
  "prNumber": 128,
  "finding": {
    "id": "f_3c9e1a7b2d4f",
    "module": "code",
    "ruleId": "sql-injection",
    "title": "SQL injection in order lookup",
    "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
    "severity": "high",
    "confidence": 0.9,
    "cwe": [
      "CWE-89"
    ],
    "cve": [
      "CVE-2021-23337"
    ],
    "location": {
      "file": "src/orders.js",
      "startLine": 42,
      "endLine": 44,
      "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
    },
    "package": {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20",
      "fixedVersion": "4.17.21",
      "manifest": "package-lock.json",
      "direct": true
    },
    "source": "builtin",
    "status": "proven",
    "evidence": [
      {
        "kind": "probe",
        "summary": "The probe read another customer’s order by changing the id in the query string.",
        "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
        "command": "node probe.js",
        "exitCode": 0,
        "output": "REPRODUCED: 3 rows returned for a single order id",
        "proof": {
          "outcome": "reproduced",
          "attempts": 1,
          "missing": "A running PostgreSQL database",
          "dependencies": "installed",
          "controlHeld": true,
          "repeatable": true,
          "audited": true,
          "variantHeld": true,
          "modelsAsked": 2,
          "declined": 1
        }
      }
    ],
    "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
    "patch": {
      "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
      "description": "Pass the order id as a bound parameter.",
      "verified": true,
      "verification": {
        "probePassed": true,
        "testsPassed": true,
        "log": "probe: exit 1 (safe)\ntests: 48 passed",
        "checks": [
          {
            "name": "probe",
            "status": "passed",
            "detail": "The probe no longer reproduces on the patched code.",
            "place": "src/orders.js:42"
          }
        ],
        "refused": [
          "The patch removes the endpoint instead of fixing it."
        ]
      },
      "attempts": [
        {
          "attempt": 1,
          "verified": true,
          "reason": "The second input still reproduced the flaw.",
          "proposed": true,
          "files": [
            "src/orders.js"
          ]
        }
      ],
      "unproven": {
        "reason": "Nullgap AI declined to write a probe for this finding",
        "proof": "no_probe",
        "accepted": true,
        "independentReviewer": true
      }
    },
    "fingerprint": "5b1f0c9a7e2d4a61",
    "triage": {
      "shape": {
        "v": 1,
        "families": [
          "sql-injection"
        ],
        "file": "src/orders.js",
        "fn": "getOrder",
        "indexed": true,
        "anchor": "db . query ( `…` )",
        "sink": "db . query ( `…` )",
        "ordinal": 0,
        "source": "const id = req . query . id",
        "entry": "app . get ( \"\" , getOrder )",
        "near": "9c41f0a7d2b3",
        "wide": [
          "03af19c2"
        ],
        "callers": [
          "listOrders:5e7a01bc"
        ],
        "family": "b7d2e94a10c6"
      },
      "exposure": {
        "reachable": "yes",
        "entryPoint": {
          "kind": "http",
          "name": "getOrder",
          "file": "src/routes.js",
          "line": 18,
          "method": "GET",
          "route": "/orders"
        },
        "authentication": "none",
        "surface": "internet",
        "attackerControlled": "yes",
        "basis": [
          "GET /orders is registered in src/routes.js:18 with no sign-in check."
        ]
      }
    },
    "triageVerdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    }
  },
  "state": "open",
  "stateReason": "Internal tool, reachable only over the VPN.",
  "stateBy": "dana@acme.example",
  "firstSeenAt": "2026-11-10T14:05:00.000Z",
  "resolvedAt": "2026-11-16T09:30:00.000Z",
  "remediation": {
    "runId": "run_7c1e4a9b2d6f",
    "status": "completed",
    "outcome": "fixed",
    "prUrl": "https://github.com/acme/shop/pull/131"
  },
  "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
  "notes": [
    {
      "author": "dana@acme.example",
      "text": "Confirmed with the orders team, fix planned for this sprint.",
      "at": "2026-11-16T09:30:00.000Z",
      "via": "console"
    }
  ],
  "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
  "validation": {
    "status": "confirmed",
    "at": "2026-11-16T09:30:00.000Z",
    "note": "Reproduced against staging with a second account.",
    "severityBefore": "medium",
    "requestedAt": "2026-11-16T09:30:00.000Z",
    "requestedBy": "Dana Lee",
    "scope": "finding",
    "requestNote": "Please check whether the admin check in middleware.js stops this.",
    "openedAt": "2026-11-16T09:30:00.000Z",
    "previous": {
      "status": "confirmed",
      "at": "2026-11-16T09:30:00.000Z",
      "note": "string",
      "severityBefore": "high"
    }
  },
  "priority": {
    "level": "P0",
    "fromSeverity": "P1",
    "proven": true,
    "reasons": [
      "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
    ]
  },
  "sightings": [
    {
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "at": "2026-11-16T09:30:00.000Z"
    }
  ],
  "riskReviewAt": "2027-02-01T00:00:00.000Z",
  "earlierDecision": {
    "findingId": "fnd_5a0e3c8b7d19",
    "decision": "false_positive",
    "note": "Raised although it resembles a dismissed finding: this one was reproduced."
  },
  "stateHistory": [
    {
      "at": "2026-11-16T09:30:00.000Z",
      "by": "dana@acme.example",
      "from": "open",
      "to": "accepted_risk",
      "reason": "Internal tool, reachable only over the VPN.",
      "reviewAt": "2027-02-01T23:59:59.000Z",
      "via": "one decision for 5 findings"
    }
  ],
  "fixRuns": [
    {
      "runId": "run_7c1e4a9b2d6f",
      "startedAt": "2026-11-16T09:30:00.000Z",
      "finishedAt": "2026-11-16T09:30:00.000Z",
      "status": "completed",
      "outcome": "fixed",
      "prUrl": "https://github.com/acme/shop/pull/131"
    }
  ],
  "trace": {
    "dataFlow": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "entryPoint": "GET /orders (src/orders/list.ts:22)",
      "sink": "db.query in src/orders/repo.ts:57",
      "confirmedBy": "independent-check"
    },
    "callPath": {
      "steps": [
        {
          "n": 1,
          "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
          "file": "src/orders/list.ts",
          "line": 22
        }
      ],
      "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
    },
    "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
    "proof": {
      "kind": "sandbox",
      "summary": "The probe read another customer's order by changing the sort column.",
      "reproduced": true,
      "outcome": "reproduced"
    },
    "occurrences": 3,
    "skill": "injection-review",
    "verdict": {
      "verdict": "true_positive",
      "confidence": "high",
      "severity": "high",
      "severityBefore": "critical",
      "severityReasons": [
        "Needs a signed-in account, which any customer can create."
      ],
      "mitigations": [
        "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
      ],
      "weaknessFits": true,
      "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
      "confirmedPath": [
        "src/orders/list.ts:22 reads req.query.sort"
      ],
      "at": "2026-11-16T09:30:00.000Z"
    },
    "history": [
      {
        "at": "2026-11-16T09:30:00.000Z",
        "by": "dana@acme.example",
        "what": "State set to accepted risk",
        "detail": "Behind the office network until the migration in March."
      }
    ],
    "missing": [
      "No call path from an entry point was recorded."
    ]
  }
}

Errors specific to this call

StatusCodeWhen
400bad_requesttracker is not jira or linear.
400not_connectedThat tracker is not connected for the organisation.
400tracker_rejectedThe tracker refused to create the issue (a wrong project, a revoked token). The message is the tracker’s own.
404not_foundNo finding with this id exists in the organisation.

#Get a fix prompt

GET /api/orgs/{org}/findings/{id}/fix-prompt

Returns a piece of text that describes the finding and how to fix it, written to be handed to a coding assistant or a developer working in a local checkout. Nothing is started or changed.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/fix-prompt"

Answer (200, application/json)

FieldTypeAlways presentDescription
promptstringyesThe hand-off text.
{
  "prompt": "Fix the SQL injection in src/orders.js at line 42 of acme/shop. The order id from the query string is placed into the SQL text. Pass it as a bound parameter, then run the tests."
}

Errors specific to this call

StatusCodeWhen
404not_foundNo finding with this id exists in the organisation.

#Objects

The objects the operations above take and return.

#EvidenceBundle

Everything that backs one finding, in one document you can keep or hand to an auditor.

FieldTypeAlways presentDescription
schemastringyesThe format of this document.
generatedAtstringyesWhen this copy was produced. Not covered by sha256.
hashCoversstringyesWhat sha256 is taken over, in words.
findingobjectyesThe finding, in summary.
finding.idstringyesThe finding id.
finding.titlestringyesIts title.
finding.severitystringyesIts severity. One of: critical, high, medium, low, info.
finding.cwearray of stringyesIts weakness classes. Empty when none.
finding.descriptionstringyesWhat is wrong.
finding.remediationstring or nullyesHow to fix it.
finding.locationLocation or nullyes
finding.repositorystringyesThe repository.
finding.sourcestringyesWhat kind of run first reported it. One of: review, pentest.
finding.pullRequestinteger or nullyesThe pull request it was found on.
finding.statestringyesWhat the team decided. One of: open, patched, accepted_risk, false_positive.
finding.stateReasonstring or nullyesThe reason given with that decision.
finding.firstSeenAtstringyesWhen it was first reported.
finding.resolvedAtstring or nullyesWhen it left the open state.
finding.resolvedInShastring or nullyesThe commit in which the flagged code was no longer present.
assuranceobjectyesHow far the finding was checked.
assurance.levelstringyesHow far the finding was checked. proven: a probe reproduced it (finding.status is proven or fixed). verified: an independent review could not refute it, and it was not reproduced. unverified: anything else.
assurance.statementstringyesThe same, as a sentence you can quote.
evidencearray of objectyesThe reasoning and checks recorded for the finding, in order.
evidence[].kindstringyesWhat sort of step it is. See Evidence.kind.
evidence[].summarystringyesWhat the step showed.
evidence[].detailstring or nullyesThe longer text. Always null on probe steps: the probe files are under proof.
proofobject or nullyesThe reproduction: the last probe that ran a command. null unless the assurance level is proven.
proof.commandstring or nullyesThe command that reproduced the flaw.
proof.exitCodeinteger or nullyesWhat it exited with.
proof.outputstring or nullyesWhat it printed.
proof.filesstring or nullyesThe probe files.
patchobject or nullyesThe fix written for the finding. null when there is none.
patch.diffstringyesThe unified diff.
patch.verifiedbooleanyesWhether it passed its checks.
patch.descriptionstringyesWhat it changes.
runobject or nullyesThe run that first reported the finding. null when that run is no longer stored.
run.idstringyesThe id of the review or pentest.
run.kindstringyesWhich of the two it is. One of: review, pentest.
run.commitstring or nullyesThe commit that was examined: the head commit of the pull request for a review, the ref for a pentest.
run.finishedAtstring or nullyesWhen the run ended.
run.privacyRunPrivacy or nullyes
expertReviewobjectnoThe review by a Nullgap security researcher. Present only when there is one.
expertReview.statusstringyesWhere the review stands. One of: pending, confirmed, adjusted, rejected.
expertReview.decidedAtstring or nullyesWhen the researcher decided. null while pending.
expertReview.notestring or nullyesWhat the researcher wrote.
expertReview.severityBeforestring or nullyesThe severity before an adjustment.
expertReview.requestedAtstring or nullyesWhen your workspace asked for it. null for a review under a researcher-validation contract.
notesarray of FindingNoteyesReplies and comments about the finding, oldest first. Empty when there are none.
historyarray of FindingStateChangeyesEvery recorded change of the finding's state, oldest first. Empty when none was recorded.
sha256stringyesThe SHA-256, in hexadecimal, of the canonical JSON of this bundle with the sha256 and generatedAt fields removed (keys sorted at every level, no whitespace). generatedAt is left out so every download of an unchanged finding carries the same hash. Recompute it to see that the bundle is unaltered.

#FindingRecord

A finding as your organisation holds it: the flaw (finding), where it came from, what the team decided (state), and what was done about it. Internal details are left out of every answer: whether the pull request came from a fork, who opened it, and which researcher validated the finding.

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.

#ExpertReviewRequestResult

What an expert review request did.

FieldTypeAlways presentDescription
requestedintegeryesFindings now waiting for a researcher because of this request.
alreadyPendingintegeryesFindings that were already waiting; nothing changed for them.
alreadyReviewedintegeryesFindings already reviewed and left as they were. Send again: true to ask for another look.
findingsarray of FindingRecordyesThe findings the request covers, as they are now.

#ExpertReviewCancelResult

What cancelling an expert review request did.

FieldTypeAlways presentDescription
cancelledintegeryesRequests withdrawn.
keptintegeryesRequests a researcher had already opened, which stay in review.
findingsarray of FindingRecordyesThe findings that had a request, as they are now.

#BulkTriageResult

The result of one decision applied to several findings.

FieldTypeAlways presentDescription
changedarray of FindingRecordyesThe findings that were changed, as they are now.
skippedarray of objectyesThe findings left as they were, each with why.
skipped[].idstringyesThe finding id.
skipped[].whystringyesWhy it was left as it was: Not found, or Already in this state with this reason.

#SuppressedFinding

A finding that a run produced and Nullgap did not raise, because the team had already decided about it or about code that is the same. Nothing is held back silently: every one is listed here with why and whose decision it rests on, and anyone on the team can bring it back.

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.

#SimilarFindings

Findings like one finding, and what was decided about them.

FieldTypeAlways presentDescription
determinedbooleanyesFalse when the finding carries no code shape (it predates them, or it is not about code), so nothing can be said about similar findings.
similararray of FindingRecordyesOther findings in the same repository with the same weakness class and the same dangerous statement, in any state.
decisionsarray of objectyesDismissals already taken on findings like this one, newest first.
decisions[].findingIdstringyesThe finding the decision was taken on.
decisions[].titlestringyesIts title.
decisions[].filestring or nullyesThe file it is in.
decisions[].decisionstringyesWhat was decided. One of: false_positive, accepted_risk.
decisions[].reasonstring or nullyesThe reason given.
decisions[].bystring or nullyesWho decided.
decisions[].atstring or nullyesWhen.
decisions[].reviewAtstring or nullyesFor an accepted risk: when it is to be looked at again.
suppressedByThisintegeryesHow many later findings are currently held back because of the decision on this finding.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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