Nullgap.dev Docs

API reference

Pentests

Estimate, start, follow, cancel and retest pentests, and check a live-testing sign-in.

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
Check live-testing accessPOST /api/orgs/{org}/pentests/verify-accessadmin
Estimate a pentestPOST /api/orgs/{org}/pentests/estimateread
Start a pentestPOST /api/orgs/{org}/pentestsadmin
List pentestsGET /api/orgs/{org}/pentestsread
Get a pentestGET /api/orgs/{org}/pentests/{id}read
Get a pentest's logGET /api/orgs/{org}/pentests/{id}/logsread
Get what a running pentest has found so farGET /api/orgs/{org}/pentests/{id}/liveread
Cancel a pentestPOST /api/orgs/{org}/pentests/{id}/canceladmin
See whether a stopped pentest can be resumedGET /api/orgs/{org}/pentests/{id}/resumeread
Resume a stopped pentestPOST /api/orgs/{org}/pentests/{id}/resumeadmin
Start the free retestPOST /api/orgs/{org}/pentests/{id}/retestadmin
Estimate the free retestPOST /api/orgs/{org}/pentests/{id}/retest/estimatewrite

#Check live-testing access

POST /api/orgs/{org}/pentests/verify-access

Checks, before a pentest is started, that a live-testing address is in scope, answers, and that the sign-in works for every identity. It sends a handful of requests to the address and can take up to a minute. Nothing is stored. A check that fails is not an error: the call answers 200 with ok: false and the reason in detail. Starting a pentest runs the same check on every target.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
urlstringyesThe address of the running application: http or https, no user name or password in it, not a private or loopback address, and its host on the organisation's scope list (an exact host, a host with port, or a *. wildcard entry; read the list with GET /api/orgs/{org}/scope-hosts). Up to 500 characters.
signInStepsstringnoHow to sign in, in plain words. Up to 5000 characters.
usernamestringnoThe user name of a throwaway test account. Up to 200 characters.
passwordstringnoThe password of that account. Up to 200 characters. Stored encrypted, never returned and never logged.
secondUsernamestringnoThe user name of a second test account with different rights, so access-control flaws can be shown by replaying one user's request as the other. Up to 200 characters.
secondPasswordstringnoThe password of the second account. Up to 200 characters.
identitiesarray of objectnoUp to five named test identities. With two or more, Nullgap replays what one identity can read as each of the others and signed out, to prove one user can reach another's data. When given, username, password, secondUsername and secondPassword are ignored; those older fields still work and become identities labelled "Account 1" and "Account 2".
identities[].labelstringyesWhat to call this identity, for example "Admin" or "Tenant B user". Unique within the target. Up to 60 characters.
identities[].levelstringnoThe access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only). Default user.
identities[].usernamestringnoThe user name to sign in with. Up to 200 characters.
identities[].passwordstringnoIts password. Up to 200 characters. Stored encrypted, never returned and never logged.
identities[].bearerTokenstringnoA token to send instead of signing in. Up to 4000 characters. Stored encrypted, never returned and never logged.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://staging.shop.acme.example","signInSteps":"Open /login, enter the e-mail address and password, press Sign in.","username":"pentest-user@acme.example","password":"a-throwaway-staging-password","secondUsername":"pentest-admin@acme.example","secondPassword":"another-throwaway-password","identities":[{"label":"Tenant B user","level":"user","username":"tenant-b@acme.example","password":"a-throwaway-staging-password","bearerToken":"eyJhbGciOi..."}]}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/verify-access"

Answer (200, application/json)

FieldTypeAlways presentDescription
okbooleanyesTrue when the address answered and every identity signed in.
detailstringyesWhat was found, in plain words. Up to 300 characters.
failedIdentitystringnoWhen an identity could not sign in: its label. The identities are checked in order and the check stops at the first that fails.
{
  "ok": true,
  "detail": "Signed in as pentest-user@acme.example and reached the account page.",
  "failedIdentity": "Tenant B user"
}

Errors specific to this call

StatusCodeWhen
400out_of_scopeA live-testing address is a private or loopback address, or its host is not on the organisation's scope list.

#Estimate a pentest

POST /api/orgs/{org}/pentests/estimate

Counts the lines of code in scope and works out the price, without starting anything. The code is fetched from the code host to be counted, so the call can take a while on a large repository. Call it before starting a pentest: priceUsd: null means the code needs a custom quote and a pentest of it will not start, unless quoteWaived is true.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
repoIdstringyesThe repository, by its id.
refstringnoThe branch, tag or commit to measure. Up to 200 characters. Default: the repository's default branch.
pathsarray of stringnoThe folders in scope: up to 50, each relative to the repository root, none starting with / or containing ... Leave out or send an empty list for the whole repository.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId":"repo_a41c09be77d3","ref":"main","paths":["services/api"]}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/estimate"

Answer (200, application/json)

A PentestEstimate object.

{
  "linesOfCode": 48210,
  "priceUsd": 0,
  "quoteWaived": true,
  "covered": true,
  "canStart": true,
  "blocked": {
    "code": "payment_required",
    "message": "Add a payment method or pentest credits first."
  }
}

Errors specific to this call

StatusCodeWhen
404not_foundNo repository of this organisation has the repoId sent.

#Start a pentest

POST /api/orgs/{org}/pentests

Starts a penetration test of a repository at one version. To make the call safe to repeat, send an Idempotency-Key header (8 to 128 letters, digits, dots, dashes, underscores or colons, one per pentest you mean to start): for 24 hours the same key with the same fields is answered with the pentest the first call started, and nothing is started or charged twice. Without the header every call starts a new pentest. This is the call that spends: the pentest is priced exactly as the estimate prices it, and when the workspace has no payment method on file the price is taken from its pentest credits at this moment. Estimate first. Before anything is priced or charged, every live-testing target is checked (in scope, answers, sign-in works); if any check fails, or the pentest cannot start for another reason, nothing is stored and nothing is charged. The call returns as soon as the pentest is queued, with status: "queued"; read the pentest to follow its status and phase. A pentest that fails or is cancelled is refunded. Live testing is optional. Without dynamicTarget or dynamicTargets the pentest works from the code alone. With them, findings are also tested against the running applications you name, which must be on the organisation's scope list: only test deployments you own or are authorised to test. Live tests only read, unless you send liveStateChanging: true together with disposableConfirmed: true. Test accounts are stored encrypted for this pentest and its retest and are never returned: the pentest shows each identity's label and level (identities), and hasCredentials and hasSecondAccount.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
repoIdstringyesThe repository, by its id.
refstringnoThe branch, tag or commit to test. Up to 200 characters. Default: the repository's default branch.
pathsarray of stringnoThe folders in scope: up to 50, each relative to the repository root, none starting with / or containing ... Leave out or send an empty list for the whole repository.
contextstringnoNotes for the testers: architecture, what matters most, what changed. Up to 20,000 characters.
applicationIdstringnoAn application of this repository. Its threat model and rules are handed to the run.
dynamicTargetobjectnoOne running application to test findings against. Ignored when dynamicTargets is sent as a list, even an empty one.
dynamicTarget.urlstringyesThe address of the running application: http or https, no user name or password in it, not a private or loopback address, and its host on the organisation's scope list (an exact host, a host with port, or a *. wildcard entry; read the list with GET /api/orgs/{org}/scope-hosts). Up to 500 characters.
dynamicTarget.signInStepsstringnoHow to sign in, in plain words. Up to 5000 characters.
dynamicTarget.usernamestringnoThe user name of a throwaway test account. Up to 200 characters.
dynamicTarget.passwordstringnoThe password of that account. Up to 200 characters. Stored encrypted, never returned and never logged.
dynamicTarget.secondUsernamestringnoThe user name of a second test account with different rights, so access-control flaws can be shown by replaying one user's request as the other. Up to 200 characters.
dynamicTarget.secondPasswordstringnoThe password of the second account. Up to 200 characters.
dynamicTarget.identitiesarray of objectnoUp to five named test identities. With two or more, Nullgap replays what one identity can read as each of the others and signed out, to prove one user can reach another's data. When given, username, password, secondUsername and secondPassword are ignored; those older fields still work and become identities labelled "Account 1" and "Account 2".
dynamicTarget.identities[].labelstringyesWhat to call this identity, for example "Admin" or "Tenant B user". Unique within the target. Up to 60 characters.
dynamicTarget.identities[].levelstringnoThe access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only). Default user.
dynamicTarget.identities[].usernamestringnoThe user name to sign in with. Up to 200 characters.
dynamicTarget.identities[].passwordstringnoIts password. Up to 200 characters. Stored encrypted, never returned and never logged.
dynamicTarget.identities[].bearerTokenstringnoA token to send instead of signing in. Up to 4000 characters. Stored encrypted, never returned and never logged.
dynamicTargetsarray of objectnoUp to five running applications to test findings against. Each is validated like dynamicTarget, and the same address may not be listed twice. When this is a list it is used and dynamicTarget is ignored.
dynamicTargets[].urlstringyesThe address of the running application: http or https, no user name or password in it, not a private or loopback address, and its host on the organisation's scope list (an exact host, a host with port, or a *. wildcard entry; read the list with GET /api/orgs/{org}/scope-hosts). Up to 500 characters.
dynamicTargets[].signInStepsstringnoHow to sign in, in plain words. Up to 5000 characters.
dynamicTargets[].usernamestringnoThe user name of a throwaway test account. Up to 200 characters.
dynamicTargets[].passwordstringnoThe password of that account. Up to 200 characters. Stored encrypted, never returned and never logged.
dynamicTargets[].secondUsernamestringnoThe user name of a second test account with different rights, so access-control flaws can be shown by replaying one user's request as the other. Up to 200 characters.
dynamicTargets[].secondPasswordstringnoThe password of the second account. Up to 200 characters.
dynamicTargets[].identitiesarray of objectnoUp to five named test identities. With two or more, Nullgap replays what one identity can read as each of the others and signed out, to prove one user can reach another's data. When given, username, password, secondUsername and secondPassword are ignored; those older fields still work and become identities labelled "Account 1" and "Account 2".
dynamicTargets[].identities[].labelstringyesWhat to call this identity, for example "Admin" or "Tenant B user". Unique within the target. Up to 60 characters.
dynamicTargets[].identities[].levelstringnoThe access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only). Default user.
dynamicTargets[].identities[].usernamestringnoThe user name to sign in with. Up to 200 characters.
dynamicTargets[].identities[].passwordstringnoIts password. Up to 200 characters. Stored encrypted, never returned and never logged.
dynamicTargets[].identities[].bearerTokenstringnoA token to send instead of signing in. Up to 4000 characters. Stored encrypted, never returned and never logged.
liveStateChangingbooleannoSend true to allow requests that change data on the live targets (creating, editing, deleting). Only the exact value true counts. It needs disposableConfirmed: true and at least one live-testing target. Default: live tests only read.
disposableConfirmedbooleannoYour confirmation that every live-testing target is a disposable staging environment whose data may be altered. Required, as the exact value true, when liveStateChanging is true; not read otherwise. The confirmation is written to the audit log.
maxPriceUsdnumbernoA ceiling for this run, in US dollars. When the price worked out at the start is above it, nothing starts and nothing is charged. Send the price the estimate showed to be sure the run costs no more than what was agreed to.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId":"repo_a41c09be77d3","ref":"main","paths":["services/api"],"context":"Payments service. Coupons are new and untested.","applicationId":"app_2d8f1c63a9e4","dynamicTarget":{"url":"https://staging.shop.acme.example","signInSteps":"Open /login, enter the e-mail address and password, press Sign in.","username":"pentest-user@acme.example","password":"a-throwaway-staging-password","secondUsername":"pentest-admin@acme.example","secondPassword":"another-throwaway-password","identities":[{"label":"Tenant B user","level":"user","username":"tenant-b@acme.example","password":"a-throwaway-staging-password","bearerToken":"eyJhbGciOi..."}]},"dynamicTargets":[{"url":"https://staging.shop.acme.example","signInSteps":"Open /login, enter the e-mail address and password, press Sign in.","username":"pentest-user@acme.example","password":"a-throwaway-staging-password","secondUsername":"pentest-admin@acme.example","secondPassword":"another-throwaway-password","identities":[{"label":"Tenant B user","level":"user","username":"tenant-b@acme.example","password":"a-throwaway-staging-password","bearerToken":"eyJhbGciOi..."}]}],"liveStateChanging":false,"disposableConfirmed":false,"maxPriceUsd":480}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests"

Answer (200, application/json)

A Pentest object.

{
  "id": "pen_7c2e9a41b6d0",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "repoFullName": "acme/shop",
  "applicationId": "app_2d8f1c63a9e4",
  "ref": "main",
  "paths": [
    "services/api"
  ],
  "dynamicTarget": {
    "url": "https://staging.shop.acme.example/",
    "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
    "hasCredentials": true,
    "hasSecondAccount": true,
    "identities": [
      {
        "label": "Tenant B user",
        "level": "user",
        "hasSecret": true
      }
    ]
  },
  "dynamicTargets": [
    {
      "url": "https://staging.shop.acme.example/",
      "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
      "hasCredentials": true,
      "hasSecondAccount": true,
      "identities": [
        {
          "label": "Tenant B user",
          "level": "user",
          "hasSecret": true
        }
      ]
    }
  ],
  "liveStateChanging": true,
  "context": "Payments service. Coupons are new and untested.",
  "linesOfCode": 48210,
  "priceUsd": 0,
  "covered": "agreement",
  "chargedForWork": 12.5,
  "workChargeSoFarUsd": 3.2,
  "status": "running",
  "phase": "testing",
  "findingsCount": 4,
  "createdBy": "dana@acme.example",
  "privacy": {
    "zeroRetention": true,
    "identifiersMasked": 14
  },
  "createdAt": "2026-11-16T09:30:00.000Z",
  "startedAt": "2026-11-16T09:30:20.000Z",
  "finishedAt": "2026-11-16T11:02:41.000Z",
  "advisoryCount": 3,
  "validation": {
    "pending": 1,
    "done": 3,
    "completedAt": "2026-11-17T14:10:00.000Z"
  },
  "retestOf": "pen_1a5d3e7f9b2c",
  "retestId": "pen_e83b6f20d4a1",
  "retest": {
    "fixed": 3,
    "stillOpen": 1,
    "added": 0
  },
  "suppressedCount": 0,
  "completedWithGaps": false,
  "creditsCharged": 0,
  "refunded": false,
  "failureReason": "The repository was removed",
  "cancelledBy": "dana@acme.example",
  "resumableUntil": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo repository of this organisation has the repoId sent, or applicationId is not an application of that repository.
400bad_requestA field is missing, too long or of the wrong kind; a path is absolute or leaves the repository; more than five live-testing targets are listed, or the same address twice; an address is not a valid http or https URL or contains a user name or password; or liveStateChanging is true and no live-testing target is given.
400out_of_scopeA live-testing address is a private or loopback address, or its host is not on the organisation's scope list.
400confirmation_requiredliveStateChanging is true and disposableConfirmed is not exactly true.
400access_check_failedA live-testing address did not answer or the sign-in did not work. Every target is checked before anything is priced or charged; the message names the host and says why.
402usage_limitThe workspace has reached its monthly usage limit.
400custom_quoteThe code in scope is large enough to need a custom quote (the estimate answers priceUsd: null), and the workspace is billed per run. The message gives the number of lines and the limit. Narrow paths so that each run is under the limit, or contact Nullgap.
402payment_requiredThe workspace has no payment method on file and not enough pentest credits for the price of this run.
402over_capThe price of this run is above the maxPriceUsd sent. Nothing was started or charged.
409idempotency_key_reusedThe Idempotency-Key header was used in the last 24 hours for a start with different fields.
409idempotency_in_progressAn earlier request with the same Idempotency-Key is still being handled. Send it again in a moment.

#List pentests

GET /api/orgs/{org}/pentests

Lists pentests, newest first, retests included. A pentest in a list carries counts only (advisoryCount, suppressedCount); findings, advisories, packages and reports are on the single pentest.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
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/pentests?limit=20"

Answer (200, application/json)

FieldTypeAlways presentDescription
itemsarray of PentestyesPentests, at most limit of them.
totalintegeryesHow many match in all, before limit and offset.
{
  "items": [
    {
      "id": "pen_7c2e9a41b6d0",
      "orgId": "org_5b1e7a90c3d2",
      "repoId": "repo_a41c09be77d3",
      "repoFullName": "acme/shop",
      "applicationId": "app_2d8f1c63a9e4",
      "ref": "main",
      "paths": [
        "services/api"
      ],
      "dynamicTarget": {
        "url": "https://staging.shop.acme.example/",
        "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
        "hasCredentials": true,
        "hasSecondAccount": true,
        "identities": [
          {
            "label": "Tenant B user",
            "level": "user",
            "hasSecret": true
          }
        ]
      },
      "dynamicTargets": [
        {
          "url": "https://staging.shop.acme.example/",
          "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
          "hasCredentials": true,
          "hasSecondAccount": true,
          "identities": [
            {
              "label": "Tenant B user",
              "level": "user",
              "hasSecret": true
            }
          ]
        }
      ],
      "liveStateChanging": true,
      "context": "Payments service. Coupons are new and untested.",
      "linesOfCode": 48210,
      "priceUsd": 0,
      "covered": "agreement",
      "chargedForWork": 12.5,
      "workChargeSoFarUsd": 3.2,
      "status": "running",
      "phase": "testing",
      "findingsCount": 4,
      "createdBy": "dana@acme.example",
      "privacy": {
        "zeroRetention": true,
        "identifiersMasked": 14
      },
      "createdAt": "2026-11-16T09:30:00.000Z",
      "startedAt": "2026-11-16T09:30:20.000Z",
      "finishedAt": "2026-11-16T11:02:41.000Z",
      "advisoryCount": 3,
      "validation": {
        "pending": 1,
        "done": 3,
        "completedAt": "2026-11-17T14:10:00.000Z"
      },
      "retestOf": "pen_1a5d3e7f9b2c",
      "retestId": "pen_e83b6f20d4a1",
      "retest": {
        "fixed": 3,
        "stillOpen": 1,
        "added": 0
      },
      "suppressedCount": 0,
      "completedWithGaps": false,
      "creditsCharged": 0,
      "refunded": false,
      "failureReason": "The repository was removed",
      "cancelledBy": "dana@acme.example",
      "resumableUntil": "2026-11-16T09:30:00.000Z"
    }
  ],
  "total": 42
}

#Get a pentest

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

Returns one pentest with its findings, the advisories against the packages the code pins, the supply-chain list, what it produced but did not raise, and its reports. Poll this to follow a running pentest: status and phase change as it goes. A failed pentest does not carry the reason here; its log does.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

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

Answer (200, application/json)

A PentestDetail object.

{
  "id": "pen_7c2e9a41b6d0",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "repoFullName": "acme/shop",
  "applicationId": "app_2d8f1c63a9e4",
  "ref": "main",
  "paths": [
    "services/api"
  ],
  "dynamicTarget": {
    "url": "https://staging.shop.acme.example/",
    "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
    "hasCredentials": true,
    "hasSecondAccount": true,
    "identities": [
      {
        "label": "Tenant B user",
        "level": "user",
        "hasSecret": true
      }
    ]
  },
  "dynamicTargets": [
    {
      "url": "https://staging.shop.acme.example/",
      "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
      "hasCredentials": true,
      "hasSecondAccount": true,
      "identities": [
        {
          "label": "Tenant B user",
          "level": "user",
          "hasSecret": true
        }
      ]
    }
  ],
  "liveStateChanging": true,
  "context": "Payments service. Coupons are new and untested.",
  "linesOfCode": 48210,
  "priceUsd": 0,
  "covered": "agreement",
  "chargedForWork": 12.5,
  "workChargeSoFarUsd": 3.2,
  "status": "running",
  "phase": "testing",
  "findingsCount": 4,
  "createdBy": "dana@acme.example",
  "privacy": {
    "zeroRetention": true,
    "identifiersMasked": 14
  },
  "createdAt": "2026-11-16T09:30:00.000Z",
  "startedAt": "2026-11-16T09:30:20.000Z",
  "finishedAt": "2026-11-16T11:02:41.000Z",
  "advisoryCount": 3,
  "validation": {
    "pending": 1,
    "done": 3,
    "completedAt": "2026-11-17T14:10:00.000Z"
  },
  "retestOf": "pen_1a5d3e7f9b2c",
  "retestId": "pen_e83b6f20d4a1",
  "retest": {
    "fixed": 3,
    "stillOpen": 1,
    "added": 0
  },
  "suppressedCount": 0,
  "completedWithGaps": false,
  "creditsCharged": 0,
  "refunded": false,
  "failureReason": "The repository was removed",
  "cancelledBy": "dana@acme.example",
  "resumableUntil": "2026-11-16T09:30:00.000Z",
  "advisories": [
    {
      "id": "GHSA-35jh-r3h4-6jhm",
      "cve": [
        "CVE-2021-23337"
      ],
      "package": "lodash",
      "version": "4.17.20",
      "ecosystem": "npm",
      "fixedVersion": "4.17.21",
      "severity": "high",
      "summary": "Command injection in the template function",
      "manifest": "package-lock.json",
      "direct": true,
      "usage": "imported",
      "usedIn": [
        "src/render/template.ts:3"
      ]
    }
  ],
  "supplyChain": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.20",
      "verdict": "vulnerable",
      "reasons": [
        {
          "id": "typosquat",
          "category": "typosquat",
          "strength": "notable",
          "severity": "medium",
          "summary": "The name is one letter away from the popular package \"lodash\".",
          "file": "package-lock.json",
          "line": 412,
          "excerpt": "\"lodahs\": \"^1.0.2\""
        }
      ],
      "advisories": [
        {
          "id": "GHSA-35jh-r3h4-6jhm",
          "summary": "Command injection in the template function",
          "severity": "high",
          "kind": "vulnerability"
        }
      ],
      "fixedVersion": "4.17.21",
      "manifest": "package-lock.json",
      "direct": true,
      "policy": {
        "action": "block",
        "rule": "min-age",
        "detail": "Published 2 days ago; your organisation requires versions to be at least 7 days old."
      },
      "findingId": "fnd_8f3a2c9d1b07"
    }
  ],
  "findings": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "orgId": "org_1d4c7b9a2e5f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "source": "review",
      "sourceId": "rev_2a6d9f1c4b7e",
      "prNumber": 128,
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "state": "open",
      "stateReason": "Internal tool, reachable only over the VPN.",
      "stateBy": "dana@acme.example",
      "firstSeenAt": "2026-11-10T14:05:00.000Z",
      "resolvedAt": "2026-11-16T09:30:00.000Z",
      "remediation": {
        "runId": "run_7c1e4a9b2d6f",
        "status": "completed",
        "outcome": "fixed",
        "prUrl": "https://github.com/acme/shop/pull/131"
      },
      "externalIssueUrl": "https://acme.atlassian.net/browse/SEC-42",
      "notes": [
        {
          "author": "dana@acme.example",
          "text": "Confirmed with the orders team, fix planned for this sprint.",
          "at": "2026-11-16T09:30:00.000Z",
          "via": "console"
        }
      ],
      "resolvedInSha": "9f2c1e7a4b6d8035c1e2f4a6b8d0c2e4f6a8b0c1",
      "validation": {
        "status": "confirmed",
        "at": "2026-11-16T09:30:00.000Z",
        "note": "Reproduced against staging with a second account.",
        "severityBefore": "medium",
        "requestedAt": "2026-11-16T09:30:00.000Z",
        "requestedBy": "Dana Lee",
        "scope": "finding",
        "requestNote": "Please check whether the admin check in middleware.js stops this.",
        "openedAt": "2026-11-16T09:30:00.000Z",
        "previous": {
          "status": "confirmed",
          "at": "2026-11-16T09:30:00.000Z",
          "note": "string",
          "severityBefore": "high"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "riskReviewAt": "2027-02-01T00:00:00.000Z",
      "earlierDecision": {
        "findingId": "fnd_5a0e3c8b7d19",
        "decision": "false_positive",
        "note": "Raised although it resembles a dismissed finding: this one was reproduced."
      },
      "stateHistory": [
        {
          "at": "2026-11-16T09:30:00.000Z",
          "by": "dana@acme.example",
          "from": "open",
          "to": "accepted_risk",
          "reason": "Internal tool, reachable only over the VPN.",
          "reviewAt": "2027-02-01T23:59:59.000Z",
          "via": "one decision for 5 findings"
        }
      ],
      "fixRuns": [
        {
          "runId": "run_7c1e4a9b2d6f",
          "startedAt": "2026-11-16T09:30:00.000Z",
          "finishedAt": "2026-11-16T09:30:00.000Z",
          "status": "completed",
          "outcome": "fixed",
          "prUrl": "https://github.com/acme/shop/pull/131"
        }
      ],
      "trace": {
        "dataFlow": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "entryPoint": "GET /orders (src/orders/list.ts:22)",
          "sink": "db.query in src/orders/repo.ts:57",
          "confirmedBy": "independent-check"
        },
        "callPath": {
          "steps": [
            {
              "n": 1,
              "text": "Entry point: GET /orders reads req.query.sort (src/orders/list.ts:22)",
              "file": "src/orders/list.ts",
              "line": 22
            }
          ],
          "basis": "Computed from the parsed call graph. Dynamic dispatch, reflection and framework wiring are not seen, so it is a route to confirm by reading."
        },
        "diagram": "flowchart TD\n  s1[\"GET /orders reads sort\"]\n  s2[\"db.query\"]\n  s1 --> s2",
        "proof": {
          "kind": "sandbox",
          "summary": "The probe read another customer's order by changing the sort column.",
          "reproduced": true,
          "outcome": "reproduced"
        },
        "occurrences": 3,
        "skill": "injection-review",
        "verdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        },
        "history": [
          {
            "at": "2026-11-16T09:30:00.000Z",
            "by": "dana@acme.example",
            "what": "State set to accepted risk",
            "detail": "Behind the office network until the migration in March."
          }
        ],
        "missing": [
          "No call path from an entry point was recorded."
        ]
      }
    }
  ],
  "suppressed": [
    {
      "id": "sup_6e2b9d0a4c7f",
      "repoId": "repo_4b7e1a9c2d3f",
      "repoFullName": "acme/shop",
      "finding": {
        "id": "f_3c9e1a7b2d4f",
        "module": "code",
        "ruleId": "sql-injection",
        "title": "SQL injection in order lookup",
        "description": "The order id from the query string is placed into the SQL text, so a caller can read any order.",
        "severity": "high",
        "confidence": 0.9,
        "cwe": [
          "CWE-89"
        ],
        "cve": [
          "CVE-2021-23337"
        ],
        "location": {
          "file": "src/orders.js",
          "startLine": 42,
          "endLine": 44,
          "snippet": "db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)"
        },
        "package": {
          "ecosystem": "npm",
          "name": "lodash",
          "version": "4.17.20",
          "fixedVersion": "4.17.21",
          "manifest": "package-lock.json",
          "direct": true
        },
        "source": "builtin",
        "status": "proven",
        "evidence": [
          {
            "kind": "probe",
            "summary": "The probe read another customer’s order by changing the id in the query string.",
            "detail": "probe.js sends GET /orders?id=1 OR 1=1 and prints the rows returned.",
            "command": "node probe.js",
            "exitCode": 0,
            "output": "REPRODUCED: 3 rows returned for a single order id",
            "proof": {
              "outcome": "reproduced",
              "attempts": 1,
              "missing": "A running PostgreSQL database",
              "dependencies": "installed",
              "controlHeld": true,
              "repeatable": true,
              "audited": true,
              "variantHeld": true,
              "modelsAsked": 2,
              "declined": 1
            }
          }
        ],
        "remediation": "Pass the id as a bound parameter instead of building the SQL text.",
        "patch": {
          "diff": "--- a/src/orders.js\n+++ b/src/orders.js\n@@ -42 +42 @@\n-  db.query(`SELECT * FROM orders WHERE id = ${req.query.id}`)\n+  db.query('SELECT * FROM orders WHERE id = ?', [req.query.id])\n",
          "description": "Pass the order id as a bound parameter.",
          "verified": true,
          "verification": {
            "probePassed": true,
            "testsPassed": true,
            "log": "probe: exit 1 (safe)\ntests: 48 passed",
            "checks": [
              {
                "name": "probe",
                "status": "passed",
                "detail": "The probe no longer reproduces on the patched code.",
                "place": "src/orders.js:42"
              }
            ],
            "refused": [
              "The patch removes the endpoint instead of fixing it."
            ]
          },
          "attempts": [
            {
              "attempt": 1,
              "verified": true,
              "reason": "The second input still reproduced the flaw.",
              "proposed": true,
              "files": [
                "src/orders.js"
              ]
            }
          ],
          "unproven": {
            "reason": "Nullgap AI declined to write a probe for this finding",
            "proof": "no_probe",
            "accepted": true,
            "independentReviewer": true
          }
        },
        "fingerprint": "5b1f0c9a7e2d4a61",
        "triage": {
          "shape": {
            "v": 1,
            "families": [
              "sql-injection"
            ],
            "file": "src/orders.js",
            "fn": "getOrder",
            "indexed": true,
            "anchor": "db . query ( `…` )",
            "sink": "db . query ( `…` )",
            "ordinal": 0,
            "source": "const id = req . query . id",
            "entry": "app . get ( \"\" , getOrder )",
            "near": "9c41f0a7d2b3",
            "wide": [
              "03af19c2"
            ],
            "callers": [
              "listOrders:5e7a01bc"
            ],
            "family": "b7d2e94a10c6"
          },
          "exposure": {
            "reachable": "yes",
            "entryPoint": {
              "kind": "http",
              "name": "getOrder",
              "file": "src/routes.js",
              "line": 18,
              "method": "GET",
              "route": "/orders"
            },
            "authentication": "none",
            "surface": "internet",
            "attackerControlled": "yes",
            "basis": [
              "GET /orders is registered in src/routes.js:18 with no sign-in check."
            ]
          }
        },
        "triageVerdict": {
          "verdict": "true_positive",
          "confidence": "high",
          "severity": "high",
          "severityBefore": "critical",
          "severityReasons": [
            "Needs a signed-in account, which any customer can create."
          ],
          "mitigations": [
            "The id is parsed as an integer in the router, which does not stop the injection in the sort column."
          ],
          "weaknessFits": true,
          "reasoning": "The sort column is taken from the query string and concatenated into the ORDER BY clause.",
          "confirmedPath": [
            "src/orders/list.ts:22 reads req.query.sort"
          ],
          "at": "2026-11-16T09:30:00.000Z"
        }
      },
      "priority": {
        "level": "P0",
        "fromSeverity": "P1",
        "proven": true,
        "reasons": [
          "Raised one step: reachable from GET /orders, which is internet-facing and needs no sign-in."
        ]
      },
      "kind": "pattern",
      "decision": "false_positive",
      "decidedBy": "dana@acme.example",
      "decidedAt": "2026-10-02T11:20:00.000Z",
      "reason": "The id is validated as an integer two lines above.",
      "dismissedFindingId": "fnd_5a0e3c8b7d19",
      "why": [
        "Same weakness class and the same dangerous statement."
      ],
      "similarity": 0.96,
      "sightings": [
        {
          "source": "review",
          "sourceId": "rev_2a6d9f1c4b7e",
          "prNumber": 128,
          "at": "2026-11-16T09:30:00.000Z"
        }
      ],
      "firstAt": "2026-11-03T08:12:00.000Z",
      "lastAt": "2026-11-16T09:30:00.000Z",
      "restoredAt": "2026-11-16T09:30:00.000Z",
      "restoredBy": "dana@acme.example",
      "restoredFindingId": "fnd_8f3a2c9d1b4e"
    }
  ],
  "reports": [
    {
      "id": "rpt_0c7a5e13f8b2",
      "orgId": "org_5b1e7a90c3d2",
      "pentestId": "pen_7c2e9a41b6d0",
      "kind": "full",
      "title": "Penetration test report: acme/shop",
      "shareToken": null,
      "shared": false,
      "createdAt": "2026-11-16T11:02:41.000Z",
      "snapshotId": "rsn_5e2a8c1f9d47",
      "revisedAt": "2026-11-18T15:20:00.000Z"
    }
  ],
  "coverage": {
    "outcome": "complete",
    "sourceFiles": 900,
    "indexed": 900,
    "examined": 240,
    "notExamined": 660,
    "excluded": {
      "vendored": 9800,
      "tests": 6100,
      "generated": 420,
      "minified": 35,
      "binary": 2,
      "tooLarge": 4,
      "credentials": 1,
      "unreadable": 0
    },
    "folders": [
      {
        "path": "services",
        "sourceFiles": 900,
        "indexed": 900,
        "examined": 240
      }
    ],
    "components": [
      {
        "path": "services/api",
        "kind": "manifest",
        "exposureRank": 1,
        "sourceFiles": 900,
        "indexed": 900,
        "examined": 240,
        "outcome": "partly-examined",
        "reason": "the run's allowance was used on more exposed code first"
      }
    ],
    "componentCount": 212,
    "graphs": 1,
    "crossComponent": {
      "files": 2400,
      "examined": 60,
      "outcome": "completed",
      "reason": "the parser ran out of memory"
    },
    "gaps": [
      {
        "component": "services/search",
        "reason": "the parser ran out of memory on this component"
      }
    ],
    "resumed": 0
  },
  "proofEnvironment": {
    "verdict": "limited",
    "summary": "The code builds in the sandbox. It needs PostgreSQL to run, which the sandbox cannot start: flaws that only show against the running application are confirmed by review, not by reproduction.",
    "parts": [
      {
        "label": "Go modules",
        "path": ".",
        "state": "ready",
        "reason": "a dependency is hosted outside the public package registries the sandbox may reach (repo.example.com)"
      }
    ],
    "services": [
      {
        "name": "PostgreSQL",
        "available": false,
        "evidence": "docker-compose.yml"
      }
    ],
    "toolchains": [
      {
        "name": "Node.js",
        "wanted": "22 (.nvmrc)",
        "have": "26.13.1",
        "relation": "newer"
      }
    ],
    "checkedAt": "2026-11-16T09:30:00.000Z",
    "seconds": 95
  },
  "accessMatrix": [
    {
      "target": "https://staging.shop.acme.example",
      "identities": [
        {
          "id": "id2",
          "label": "Tenant B user",
          "level": "user"
        }
      ],
      "rows": [
        {
          "method": "GET",
          "path": "/api/notes/{id}",
          "owner": "id1",
          "cells": {},
          "findingId": "fr_3c9d2a7e1b40",
          "note": "Not counted as a leak: an independent reviewer did not accept the demonstration."
        }
      ],
      "requests": 48,
      "truncated": false,
      "note": "The application returned repeated errors, so the replay was stopped."
    }
  ]
}

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.

#Get a pentest's log

GET /api/orgs/{org}/pentests/{id}/logs

Returns the progress log of one pentest, oldest line first, as a plain list. The list is empty when the pentest has not written anything yet.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/logs"

Answer (200, application/json)

The log lines, oldest first.

An array of LogLine.

[
  {
    "at": "2026-11-16T09:30:00.000Z",
    "level": "info",
    "message": "Mapping the attack surface: 42 entry points"
  }
]

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.

#Get what a running pentest has found so far

GET /api/orgs/{org}/pentests/{id}/live

Returns the leads a pentest has raised so far and the stage each has reached: being checked, confirmed by an independent review, being proven, proven, or dismissed with the reason. These are preliminary and are not findings. Most leads are dismissed or merged before the report, and none is counted anywhere findings are counted (dashboard, security score, deadlines, reports, exports, webhooks, notifications, the merge gate, the findings list). Poll while the pentest runs, passing the previous response's cursor as after to get only what changed; a few seconds between calls is enough, as changes are stored in batches every two seconds. When the pentest completes the leads are removed and state is replaced: findingIds lists its findings and becameFinding says which lead became which finding. When it failed or was cancelled, state is unfinished and the leads stay as they were, still preliminary.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Query parameters

NameTypeRequiredDescription
afterintegernoReturn only leads that changed after this cursor (the cursor of an earlier response). Default 0: every lead.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/live"

Answer (200, application/json)

A PentestLive object.

{
  "pentestId": "pt_5b2e8c1d9f04",
  "state": "running",
  "preliminary": true,
  "counts": {
    "checking": 12,
    "confirmed": 3,
    "proven": 1,
    "dismissed": 7
  },
  "items": [
    {
      "id": "lv_3bfa9ad002f728aadbbf9571",
      "stage": "confirmed",
      "title": "SQL injection in order lookup",
      "severity": "high",
      "file": "src/orders/db.js",
      "line": 42,
      "weakness": "CWE-89",
      "reason": "Refuted by independent review (Nullgap AI): the id is cast to an integer before the query.",
      "mergedInto": "lv_9ac513cae63ee8c42fba9a6e",
      "evidence": [
        {
          "kind": "review",
          "summary": "Independent review (Nullgap AI) could not refute it",
          "detail": "string"
        }
      ],
      "firstSeenAt": "2026-11-16T09:30:00.000Z",
      "updatedAt": "2026-11-16T09:30:00.000Z",
      "seq": 17
    }
  ],
  "cursor": 42,
  "notListed": 0,
  "findingIds": [
    "f_8a1c2e9b"
  ],
  "becameFinding": {}
}

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.

#Cancel a pentest

POST /api/orgs/{org}/pentests/{id}/cancel

Stops a queued or running pentest. Its status becomes cancelled and the work is stopped. It is charged for the share of its work done before it stopped, never more than its price, and the rest of what was taken for it is returned; chargedForWork on the pentest says what it was charged once the run has stopped. A pentest that had not started is not charged. Takes no body. What the pentest had finished is kept for a limited time (seven days unless your Nullgap operator has set another period), so it can be resumed from where it stopped: resumableUntil on the pentest says until when, once the work has stopped.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/cancel"

Answer (200, application/json)

A Pentest object.

{
  "id": "pen_7c2e9a41b6d0",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "repoFullName": "acme/shop",
  "applicationId": "app_2d8f1c63a9e4",
  "ref": "main",
  "paths": [
    "services/api"
  ],
  "dynamicTarget": {
    "url": "https://staging.shop.acme.example/",
    "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
    "hasCredentials": true,
    "hasSecondAccount": true,
    "identities": [
      {
        "label": "Tenant B user",
        "level": "user",
        "hasSecret": true
      }
    ]
  },
  "dynamicTargets": [
    {
      "url": "https://staging.shop.acme.example/",
      "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
      "hasCredentials": true,
      "hasSecondAccount": true,
      "identities": [
        {
          "label": "Tenant B user",
          "level": "user",
          "hasSecret": true
        }
      ]
    }
  ],
  "liveStateChanging": true,
  "context": "Payments service. Coupons are new and untested.",
  "linesOfCode": 48210,
  "priceUsd": 0,
  "covered": "agreement",
  "chargedForWork": 12.5,
  "workChargeSoFarUsd": 3.2,
  "status": "running",
  "phase": "testing",
  "findingsCount": 4,
  "createdBy": "dana@acme.example",
  "privacy": {
    "zeroRetention": true,
    "identifiersMasked": 14
  },
  "createdAt": "2026-11-16T09:30:00.000Z",
  "startedAt": "2026-11-16T09:30:20.000Z",
  "finishedAt": "2026-11-16T11:02:41.000Z",
  "advisoryCount": 3,
  "validation": {
    "pending": 1,
    "done": 3,
    "completedAt": "2026-11-17T14:10:00.000Z"
  },
  "retestOf": "pen_1a5d3e7f9b2c",
  "retestId": "pen_e83b6f20d4a1",
  "retest": {
    "fixed": 3,
    "stillOpen": 1,
    "added": 0
  },
  "suppressedCount": 0,
  "completedWithGaps": false,
  "creditsCharged": 0,
  "refunded": false,
  "failureReason": "The repository was removed",
  "cancelledBy": "dana@acme.example",
  "resumableUntil": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.
409not_runningThe pentest is neither queued nor running: it has already finished, failed or been cancelled.

#See whether a stopped pentest can be resumed

GET /api/orgs/{org}/pentests/{id}/resume

Returns what a person needs before resuming a cancelled or failed pentest: how far it got (files examined, leads raised), until when it can be resumed, the price, and whether a resume would be accepted now. When it cannot be resumed, reason says why. Reading this changes nothing and charges nothing. Whether the commit the pentest was examining can still be fetched is checked only by the resume itself.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/resume"

Answer (200, application/json)

A PentestResume object.

{
  "pentestId": "pt_5b2e8c1d9f04",
  "resumable": true,
  "reason": {
    "code": "expired",
    "message": "The time in which this pentest could be resumed has passed. Run it again to start from the beginning."
  },
  "resumableUntil": "2026-11-16T09:30:00.000Z",
  "progress": {
    "filesExamined": 59,
    "filesTotal": 112,
    "leads": 14
  },
  "priceUsd": 480,
  "creditsToCharge": 480,
  "canStart": true,
  "blocked": {
    "code": "payment_required",
    "message": "Add a payment method or pentest credits first."
  }
}

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.

#Resume a stopped pentest

POST /api/orgs/{org}/pentests/{id}/resume

Continues a cancelled or failed pentest from where it stopped, instead of starting again. It is the same pentest, with the same id: it goes back to queued, examines the commit it was examining before (even if the branch has moved on), with the same scope and settings, and does not examine again the files it had finished. Its findings and reports are written once, when it ends. Leads keep the results they had, with one exception: proofs that could not be tested or did not complete in the stopped part are tried again, because what stopped them may have been put right since. What was proven stays proven, and what a working probe tested and did not reproduce stays as it was. Charging. The pentest was refunded when it stopped. Resuming charges its price again, by the rules a start is charged by, so a pentest that is stopped and resumed is paid for once; if it is cancelled or fails again it is refunded again. Call GET on this path first to show the price, and send it back as maxPriceUsd. The time a pentest sat stopped does not count against the time it may take. The body is optional.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
maxPriceUsdnumbernoA ceiling, in US dollars. When the price is above it, nothing is resumed and nothing is charged.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxPriceUsd":480}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/resume"

Answer (200, application/json)

A Pentest object.

{
  "id": "pen_7c2e9a41b6d0",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "repoFullName": "acme/shop",
  "applicationId": "app_2d8f1c63a9e4",
  "ref": "main",
  "paths": [
    "services/api"
  ],
  "dynamicTarget": {
    "url": "https://staging.shop.acme.example/",
    "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
    "hasCredentials": true,
    "hasSecondAccount": true,
    "identities": [
      {
        "label": "Tenant B user",
        "level": "user",
        "hasSecret": true
      }
    ]
  },
  "dynamicTargets": [
    {
      "url": "https://staging.shop.acme.example/",
      "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
      "hasCredentials": true,
      "hasSecondAccount": true,
      "identities": [
        {
          "label": "Tenant B user",
          "level": "user",
          "hasSecret": true
        }
      ]
    }
  ],
  "liveStateChanging": true,
  "context": "Payments service. Coupons are new and untested.",
  "linesOfCode": 48210,
  "priceUsd": 0,
  "covered": "agreement",
  "chargedForWork": 12.5,
  "workChargeSoFarUsd": 3.2,
  "status": "running",
  "phase": "testing",
  "findingsCount": 4,
  "createdBy": "dana@acme.example",
  "privacy": {
    "zeroRetention": true,
    "identifiersMasked": 14
  },
  "createdAt": "2026-11-16T09:30:00.000Z",
  "startedAt": "2026-11-16T09:30:20.000Z",
  "finishedAt": "2026-11-16T11:02:41.000Z",
  "advisoryCount": 3,
  "validation": {
    "pending": 1,
    "done": 3,
    "completedAt": "2026-11-17T14:10:00.000Z"
  },
  "retestOf": "pen_1a5d3e7f9b2c",
  "retestId": "pen_e83b6f20d4a1",
  "retest": {
    "fixed": 3,
    "stillOpen": 1,
    "added": 0
  },
  "suppressedCount": 0,
  "completedWithGaps": false,
  "creditsCharged": 0,
  "refunded": false,
  "failureReason": "The repository was removed",
  "cancelledBy": "dana@acme.example",
  "resumableUntil": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.
400bad_requestmaxPriceUsd is not a number of dollars, zero or more.
409not_stoppedThe pentest is queued, running or completed: there is nothing to resume.
409still_stoppingThe pentest was cancelled a moment ago and its work has not stopped yet. Try again shortly.
409no_checkpointThe pentest stopped before it had recorded any progress. Start a new one.
409expiredThe time in which the pentest could be resumed has passed. Start a new one.
409repository_goneThe repository of the pentest, or its code-host connection, was removed.
409commit_goneThe commit the pentest was examining can no longer be fetched from the code host. Nothing was charged. Start a new pentest to test the current code.
409supersededThe pentest is a retest, and another retest of the same pentest was started after it stopped.
402usage_limitThe workspace has reached its monthly usage limit.
402payment_requiredThe workspace has no payment method on file and not enough pentest credits for the price of this pentest.
402over_capThe price is above the maxPriceUsd sent. Nothing was resumed or charged.

#Start the free retest

POST /api/orgs/{org}/pentests/{id}/retest

Starts the retest that every completed pentest includes: the same code again, on the same branch or tag as the original, with the same folders, context, application and live-testing targets (with the stored test accounts, unless liveTesting is false), at the version that now holds your fixes. It answers with a new pentest whose retestOf names the original; when that finishes, its retest says how many of the original's findings are fixed, still open, and new. It is free while the code has grown by no more than a quarter of the original's counted lines; past that, it costs the difference between the price of its size and what the original cost (retestExtraUsd). Ask the retest estimate first and send that amount as maxPriceUsd. There is one retest per pentest, used up as soon as it starts, even if it is then cancelled. A retest that failed on Nullgap's side, or that Nullgap stopped, does not count, and another can be started. Live-testing targets are checked again before it starts.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
refstringnoOptional, and only the original's own ref: the free retest tests the same branch or tag. Any other value is refused with retest_ref.
maxPriceUsdnumbernoThe most the retest may cost on top of the original, in US dollars: the extraUsd the retest estimate gave. Above it nothing starts and nothing is charged.
liveTestingbooleannoWhether to repeat the original's live testing, against the same targets with the stored test accounts (and with requests that change data, when the original allowed them). Default true. Send false to retest from the code alone.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"main","maxPriceUsd":0,"liveTesting":true}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/retest"

Answer (200, application/json)

A Pentest object.

{
  "id": "pen_7c2e9a41b6d0",
  "orgId": "org_5b1e7a90c3d2",
  "repoId": "repo_a41c09be77d3",
  "repoFullName": "acme/shop",
  "applicationId": "app_2d8f1c63a9e4",
  "ref": "main",
  "paths": [
    "services/api"
  ],
  "dynamicTarget": {
    "url": "https://staging.shop.acme.example/",
    "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
    "hasCredentials": true,
    "hasSecondAccount": true,
    "identities": [
      {
        "label": "Tenant B user",
        "level": "user",
        "hasSecret": true
      }
    ]
  },
  "dynamicTargets": [
    {
      "url": "https://staging.shop.acme.example/",
      "signInSteps": "Open /login, enter the e-mail address and password, press Sign in.",
      "hasCredentials": true,
      "hasSecondAccount": true,
      "identities": [
        {
          "label": "Tenant B user",
          "level": "user",
          "hasSecret": true
        }
      ]
    }
  ],
  "liveStateChanging": true,
  "context": "Payments service. Coupons are new and untested.",
  "linesOfCode": 48210,
  "priceUsd": 0,
  "covered": "agreement",
  "chargedForWork": 12.5,
  "workChargeSoFarUsd": 3.2,
  "status": "running",
  "phase": "testing",
  "findingsCount": 4,
  "createdBy": "dana@acme.example",
  "privacy": {
    "zeroRetention": true,
    "identifiersMasked": 14
  },
  "createdAt": "2026-11-16T09:30:00.000Z",
  "startedAt": "2026-11-16T09:30:20.000Z",
  "finishedAt": "2026-11-16T11:02:41.000Z",
  "advisoryCount": 3,
  "validation": {
    "pending": 1,
    "done": 3,
    "completedAt": "2026-11-17T14:10:00.000Z"
  },
  "retestOf": "pen_1a5d3e7f9b2c",
  "retestId": "pen_e83b6f20d4a1",
  "retest": {
    "fixed": 3,
    "stillOpen": 1,
    "added": 0
  },
  "suppressedCount": 0,
  "completedWithGaps": false,
  "creditsCharged": 0,
  "refunded": false,
  "failureReason": "The repository was removed",
  "cancelledBy": "dana@acme.example",
  "resumableUntil": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.
409is_retestThe pentest named is itself a retest. Start a new pentest to test again.
409not_completedThe pentest named has not completed: it is still going, or it failed or was cancelled.
409retest_usedThe free retest of this pentest has already been started and is queued, running or completed.
409repository_goneThe repository of the pentest is no longer connected.
400retest_refref names a different branch or tag from the original's. Start a new pentest to test it.
400access_check_failedA live-testing address did not answer or the sign-in did not work. Every target is checked before anything is priced or charged; the message names the host and says why.
402usage_limitThe workspace has reached its monthly usage limit.
400custom_quoteThe code in scope is large enough to need a custom quote (the estimate answers priceUsd: null), and the workspace is billed per run. The message gives the number of lines and the limit. Narrow paths so that each run is under the limit, or contact Nullgap.

#Estimate the free retest

POST /api/orgs/{org}/pentests/{id}/retest/estimate

Counts the lines of the original's scope on its branch or tag now, and says whether the free retest is still available, up to how many lines it stays free, and what it would cost on top of the original when the code grew past that. Starts and charges nothing. Takes no body.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/retest/estimate"

Answer (200, application/json)

The free retest before it starts.

FieldTypeAlways presentDescription
refstringyesThe branch or tag the retest tests: the original's.
linesOfCodeintegeryesLines of code in scope now.
originalLinesOfCodeintegeryesLines the original counted.
freeUpToLinesintegeryesUp to this many lines the retest is free: the original's plus a quarter.
extraUsdnumber or nullyesWhat the retest would cost on top of the original, in US dollars: 0 within the allowance. Null when the code grew past what a single pentest is priced for.
availablebooleanyesWhether the free retest of this pentest has not been used yet.
canStartbooleanyesWhether it could start now, by the start's own checks.
blockedobject or nullyesWhy it could not start now.
blocked.codestringyesWhy not.
blocked.messagestringyesIn words.
{
  "ref": "main",
  "linesOfCode": 13100,
  "originalLinesOfCode": 12000,
  "freeUpToLines": 15000,
  "extraUsd": 0,
  "available": true,
  "canStart": true,
  "blocked": {
    "code": "payment_required",
    "message": "Add pentest credits first."
  }
}

Errors specific to this call

StatusCodeWhen
404not_foundNo pentest of this organisation has that id.
409is_retestThe pentest named is itself a retest.

#Objects

The objects the operations above take and return.

#PentestEstimate

The size and price of a pentest, worked out without starting one.

FieldTypeAlways presentDescription
linesOfCodeintegeryesLines of code in scope.
priceUsdnumber or nullyesThe price of this run, as agreed for your workspace. Null when the code is large enough to need a custom quote.
quoteWaivedbooleannoPresent and true when the code is past the price list but this workspace is not billed per run, so the pentest may start anyway.
coveredbooleannoPresent and true when this workspace is not billed per run: nothing is charged for the pentest, whatever its price.
canStartbooleannoWhether this workspace could start the pentest now, by the same checks the start makes: not suspended, under the usage limit, priced (or not billed per run), and a payment method or enough pentest credits. The start checks again.
blockedobject or nullnoWhy the pentest could not start now. Null when canStart is true.
blocked.codestringyesThe error code the start would answer with. One of: org_suspended, usage_limit, custom_quote, payment_required.
blocked.messagestringyesWhat the start would say, with what to do about it.

#Pentest

A penetration test of a repository at one version.

FieldTypeAlways presentDescription
idstringyesThe pentest id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository that was tested.
repoFullNamestringyesThe repository as owner/name.
applicationIdstring or nullyesThe application whose threat model and rules were used, when one was chosen.
refstringyesThe branch, tag or commit that was tested.
pathsarray of stringyesThe folders in scope. Empty means the whole repository.
dynamicTargetLiveTarget or nullyes
dynamicTargetsarray of LiveTargetnoEvery running application this pentest tests findings against. Absent when there is no live testing. dynamicTarget is the first of these.
liveStateChangingbooleannoPresent and true when the pentest may send requests that change data on the live targets, which the organisation confirmed are disposable. Absent otherwise.
contextstringyesThe notes given when it was started (architecture, what matters). Empty when none were given.
linesOfCodeintegeryesLines of code in scope, counted when the pentest was started.
priceUsdnumber or nullyesThe price of this run, as agreed for your workspace. Null when the code is past the price list and the run is covered by your agreement.
coveredstringnoPresent when the run is not charged per run, and why: agreement (your workspace is not billed per run) or retest (the free retest of an earlier pentest). Shown instead of a price.
chargedForWorknumbernoA cancelled pentest: what it was charged for the work done before it stopped, never more than its price. Absent when it was not charged that way.
workChargeSoFarUsdnumbernoA queued or running pentest, on a single pentest only: about what cancelling it now would charge for the work done so far.
statusstringyesWhere the pentest stands. A pentest is never skipped.
phasestring or nullyesWhat a running pentest is doing now. Null while it is queued. One of: creating-environment, building-call-graph, mapping-attack-surface, tracing-data-flow, testing, reporting, null.
findingsCountintegeryesHow many findings this pentest raised so far.
createdBystringyesWho started it: a person's e-mail address, api-key: followed by the name of an API key, or schedule.
privacyRunPrivacy or nullyes
createdAtstringyesWhen it was started.
startedAtstring or nullyesWhen work on it began. Null while it is queued.
finishedAtstring or nullyesWhen it finished, failed or was cancelled. Null until then.
advisoryCountintegernoHow many published advisories list a package version the code pins. These are not findings. The advisories themselves are on the single pentest, in advisories.
validationobjectnoResearcher validation of this pentest's findings. Present only for workspaces that have researcher validation.
validation.pendingintegeryesFindings still waiting for a researcher.
validation.doneintegeryesFindings a researcher has decided.
validation.completedAtstring or nullyesWhen the last finding was decided. Null while any is pending.
retestOfstring or nullnoOn a retest: the id of the pentest whose findings it checks again. Null on an ordinary pentest.
retestIdstring or nullnoOn the original: the id of its retest, once one has been requested. Absent until then.
retestobject or nullnoOn a finished retest: what it found about the original's findings. Absent on an ordinary pentest and until the retest has finished.
retest.fixedintegeryesFindings of the original that are fixed: the flagged code is gone and the retest did not find them again.
retest.stillOpenintegeryesFindings of the original that are still there, or whose code is unchanged.
retest.addedintegeryesFindings the retest raised that the original did not have.
suppressedCountintegernoHow many findings this pentest produced and did not raise because of an earlier decision. They are listed on the single pentest, in suppressed.
completedWithGapsbooleannoOn a finished pentest: true when part of the scope could not be assessed because a component failed. status is still completed, and the findings and reports stand; coverage.gaps on the single pentest names what is missing. Absent on pentests that finished before coverage was recorded.
creditsChargednumbernoPentest credits taken for this run, in US dollars. 0 for a retest (included in the original's price) and for a workspace billed by payment method or whose plan covers pentests.
refundedbooleannoTrue once the credits taken for a failed or cancelled run have been returned.
failureReasonstring or nullnoOn a failed pentest: why it stopped. Null otherwise.
cancelledBystring or nullnoOn a cancelled pentest: who cancelled it, in the same form as createdBy. finishedAt says when. Absent on pentests cancelled before this was recorded.
resumableUntilstring or nullnoOn a cancelled or failed pentest that had recorded progress: until when it can be resumed from where it stopped. A time in the past means that time has run out. Null when it stopped with nothing to continue from, when it has been resumed, and on every pentest that is not cancelled or failed.

#PentestDetail

One pentest with what it found.

FieldTypeAlways presentDescription
idstringyesThe pentest id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository that was tested.
repoFullNamestringyesThe repository as owner/name.
applicationIdstring or nullyesThe application whose threat model and rules were used, when one was chosen.
refstringyesThe branch, tag or commit that was tested.
pathsarray of stringyesThe folders in scope. Empty means the whole repository.
dynamicTargetLiveTarget or nullyes
dynamicTargetsarray of LiveTargetnoEvery running application this pentest tests findings against. Absent when there is no live testing. dynamicTarget is the first of these.
liveStateChangingbooleannoPresent and true when the pentest may send requests that change data on the live targets, which the organisation confirmed are disposable. Absent otherwise.
contextstringyesThe notes given when it was started (architecture, what matters). Empty when none were given.
linesOfCodeintegeryesLines of code in scope, counted when the pentest was started.
priceUsdnumber or nullyesThe price of this run, as agreed for your workspace. Null when the code is past the price list and the run is covered by your agreement.
coveredstringnoPresent when the run is not charged per run, and why: agreement (your workspace is not billed per run) or retest (the free retest of an earlier pentest). Shown instead of a price.
chargedForWorknumbernoA cancelled pentest: what it was charged for the work done before it stopped, never more than its price. Absent when it was not charged that way.
workChargeSoFarUsdnumbernoA queued or running pentest, on a single pentest only: about what cancelling it now would charge for the work done so far.
statusstringyesWhere the pentest stands. A pentest is never skipped.
phasestring or nullyesWhat a running pentest is doing now. Null while it is queued. One of: creating-environment, building-call-graph, mapping-attack-surface, tracing-data-flow, testing, reporting, null.
findingsCountintegeryesHow many findings this pentest raised so far.
createdBystringyesWho started it: a person's e-mail address, api-key: followed by the name of an API key, or schedule.
privacyRunPrivacy or nullyes
createdAtstringyesWhen it was started.
startedAtstring or nullyesWhen work on it began. Null while it is queued.
finishedAtstring or nullyesWhen it finished, failed or was cancelled. Null until then.
advisoryCountintegernoHow many published advisories list a package version the code pins. These are not findings. The advisories themselves are on the single pentest, in advisories.
validationobjectnoResearcher validation of this pentest's findings. Present only for workspaces that have researcher validation.
validation.pendingintegeryesFindings still waiting for a researcher.
validation.doneintegeryesFindings a researcher has decided.
validation.completedAtstring or nullyesWhen the last finding was decided. Null while any is pending.
retestOfstring or nullnoOn a retest: the id of the pentest whose findings it checks again. Null on an ordinary pentest.
retestIdstring or nullnoOn the original: the id of its retest, once one has been requested. Absent until then.
retestobject or nullnoOn a finished retest: what it found about the original's findings. Absent on an ordinary pentest and until the retest has finished.
retest.fixedintegeryesFindings of the original that are fixed: the flagged code is gone and the retest did not find them again.
retest.stillOpenintegeryesFindings of the original that are still there, or whose code is unchanged.
retest.addedintegeryesFindings the retest raised that the original did not have.
suppressedCountintegernoHow many findings this pentest produced and did not raise because of an earlier decision. They are listed on the single pentest, in suppressed.
completedWithGapsbooleannoOn a finished pentest: true when part of the scope could not be assessed because a component failed. status is still completed, and the findings and reports stand; coverage.gaps on the single pentest names what is missing. Absent on pentests that finished before coverage was recorded.
creditsChargednumbernoPentest credits taken for this run, in US dollars. 0 for a retest (included in the original's price) and for a workspace billed by payment method or whose plan covers pentests.
refundedbooleannoTrue once the credits taken for a failed or cancelled run have been returned.
failureReasonstring or nullnoOn a failed pentest: why it stopped. Null otherwise.
cancelledBystring or nullnoOn a cancelled pentest: who cancelled it, in the same form as createdBy. finishedAt says when. Absent on pentests cancelled before this was recorded.
resumableUntilstring or nullnoOn a cancelled or failed pentest that had recorded progress: until when it can be resumed from where it stopped. A time in the past means that time has run out. Null when it stopped with nothing to continue from, when it has been resumed, and on every pentest that is not cancelled or failed.
advisoriesarray of DependencyAdvisoryyesPublished advisories against the package versions the code pins, most severe first. They are not findings. Empty when there are none.
supplyChainarray of SupplyChainPackageyesMalicious, suspicious and vulnerable packages in one list. Empty when there are none.
findingsarray of FindingRecordyesThe findings this pentest raised.
suppressedarray of SuppressedFindingyesWhat this pentest produced and did not raise, each with the decision it rests on.
reportsarray of ReportyesThe reports written for this pentest, oldest first. Empty until it has finished.
coveragePentestCoverageno
proofEnvironmentProofEnvironmentno
accessMatrixarray of AccessMatrixnoWho could read what across the test identities, one per live target that was reached. Present on a finished pentest with live testing.

#LogLine

One line of a run's progress log.

FieldTypeAlways presentDescription
atstringyesWhen the line was written.
levelstringyesHow serious the line is. One of: info, warn, error.
messagestringyesWhat happened, in plain words.

#PentestLive

What a pentest has come across so far. Preliminary: never counted as findings.

FieldTypeAlways presentDescription
pentestIdstringyesThe pentest.
statestringyesrunning: the list grows and changes. unfinished: the pentest failed or was cancelled; the list is what it had reached. replaced: the pentest completed and its findings took the list's place. none: nothing recorded.
preliminarybooleanyesAlways true: nothing here is a finding.
countsobjectyesLeads by stage. Merged leads are in none of these.
counts.checkingintegeryesLeads still being checked, including ones held for a person.
counts.confirmedintegeryesConfirmed by the independent review, including ones being proven and ones whose proof did not reproduce them, could not run or did not complete.
counts.provenintegeryesReproduced in the sandbox.
counts.dismissedintegeryesDismissed by the independent review.
itemsarray of LiveItemyesThe leads, in the order they last changed. With after, only those that changed since.
cursorintegeryesPass as after on the next request.
notListedintegeryesLeads past the most kept for one run (1,000): counted, not listed.
findingIdsarray of stringnoFor replaced: the findings of the completed pentest.
becameFindingobjectnoFor replaced: lead id to the finding it became. A lead not named was dismissed or merged before the report.

#PentestResume

What to show a person before they resume a stopped pentest: how far it got, until when it can be resumed, and what it costs.

FieldTypeAlways presentDescription
pentestIdstringyesThe pentest.
resumablebooleanyesWhether there is something to continue from: the pentest is cancelled or failed, its recorded progress is still kept, and its repository is still connected. canStart adds whether the workspace could pay for it now.
reasonobject or nullyesWhy the pentest cannot be resumed. Null when resumable is true.
reason.codestringyesWhy it cannot be resumed. not_stopped: it is queued, running or completed. still_stopping: its work has been told to stop and has not stopped yet; ask again in a moment. no_checkpoint: it stopped before recording any progress. expired: the time in which it could be resumed has passed. repository_gone: the repository or its code-host connection was removed. commit_gone: the commit it was examining can no longer be fetched (only the resume itself finds this out). superseded: it is a retest, and another retest of the same pentest was started since.
reason.messagestringyesThe same, in words, with what to do instead.
resumableUntilstring or nullyesUntil when it can be resumed. Null when it never could be.
progressobjectyesHow far the pentest got before it stopped.
progress.filesExaminedinteger or nullyesFiles examined in depth before it stopped. Null when that is no longer on record.
progress.filesTotalinteger or nullyesFiles the run had set out to examine. Null when the run had not worked that out yet (a codebase assessed in several parts) or it is no longer on record.
progress.leadsintegeryesLeads it had raised so far. Preliminary: these are not findings.
priceUsdnumberyesWhat resuming costs, in US dollars: the price, less what a cancel already charged for the work done (a failed pentest was refunded, so it is the whole price). A pentest that is stopped and resumed is never charged more than its price in all.
creditsToChargenumberyesPentest credits a resume would take now. 0 for a retest, and for a workspace billed by payment method or whose plan covers pentests.
canStartbooleanyesWhether a resume would be accepted now: resumable is true and the workspace passes the checks a start makes (not suspended, under the usage limit, a payment method or enough pentest credits). The resume checks again.
blockedobject or nullyesWhy the workspace could not resume it now although there is something to continue from. Null otherwise.
blocked.codestringyesThe error code the resume would answer with. One of: org_suspended, usage_limit, custom_quote, payment_required.
blocked.messagestringyesWhat the resume would say, with what to do about it.

#LiveTarget

A running application that findings are tested against.

FieldTypeAlways presentDescription
urlstringyesThe address of the running application.
signInStepsstringyesHow to sign in, as given when the pentest was started. Empty when nothing was given.
hasCredentialsbooleannoPresent and true when a test account was given. The account itself is stored encrypted and never returned.
hasSecondAccountbooleannoPresent and true when two or more test identities were given, for access-control checks. Kept for older clients: read identities.
identitiesarray of LiveIdentitynoThe test identities, by label and access level. Their passwords and tokens are stored encrypted and never returned. Absent when none were given.

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

#DependencyAdvisory

A published advisory that lists a package version the code depends on. It says the package has a known flaw, not that this application can be attacked through it, so it is kept apart from findings.

FieldTypeAlways presentDescription
idstringyesThe advisory id.
cvearray of stringyesThe CVE ids the advisory carries. May be empty.
packagestringyesThe package name.
versionstringyesThe version the code pins.
ecosystemstringyesThe package ecosystem.
fixedVersionstring or nullyesThe first version without the flaw, when the advisory names one.
severitystringyesThe severity the advisory states. One of: critical, high, medium, low, info.
summarystringyesWhat the advisory says, in one line.
manifeststring or nullyesThe manifest or lockfile that pins the package.
directboolean or nullyesTrue when the code depends on the package directly, false when through another package, null when that is not known.
usagestringnoWhether the project's own source imports the package. not-imported: a direct dependency no source file imports. unknown: it could not be decided. This is about imports, not about whether the flawed part is reached.
usedInarray of stringnoUp to five places that import the package.

#SupplyChainPackage

One package in the supply-chain list of a review or a pentest.

FieldTypeAlways presentDescription
ecosystemstringyesThe package ecosystem.
namestringyesThe package name.
versionstringyesThe version the code pins.
verdictstringyesThe verdict on this version. A clean package is listed only when an organisation rule blocks it; unknown ones are listed because unknown is not clean.
reasonsarray of SupplyChainReasonyesEvery signal found, strongest first. May be empty.
advisoriesarray of PackageAdvisoryyesThe advisories that list this version. May be empty.
fixedVersionstring or nullnoThe first version without the flaw, when an advisory names one.
manifeststring or nullyesThe manifest or lockfile that pins the package.
directboolean or nullyesTrue when the code depends on the package directly, false when through another package, null when that is not known.
policyPolicyMatchno
findingIdstringnoThe finding raised for this package, when there is one.

#FindingRecord

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

FieldTypeAlways presentDescription
idstringyesThe id of the finding. Use it in every route that takes a finding id.
orgIdstringyesThe organisation it belongs to.
repoIdstringyesThe repository it was found in.
repoFullNamestringyesThe name of that repository.
sourcestringyesWhat kind of run first reported it. One of: review, pentest.
sourceIdstringyesThe id of that review or pentest.
prNumberinteger or nullyesThe pull request it was found on. null when it did not come from a pull request.
findingFindingyesThe flaw itself. finding.status says how far it was checked.
statestringyesWhat the team has decided about it. open: to be dealt with. patched: fixed. accepted_risk: real, and accepted. false_positive: not a real issue. This is separate from finding.status, which says how far Nullgap checked it.
stateReasonstring or nullyesThe reason given with the last decision.
stateBystring or nullyesWho last changed the state: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when nobody has.
firstSeenAtstringyesWhen it was first reported.
resolvedAtstring or nullyesWhen it last left the open state. null while open.
remediationobject or nullyesThe latest fix run for this finding. null when none was started.
remediation.runIdstringyesThe id of the fix run.
remediation.statusstringyesWhere that run stands. One of: queued, running, completed, failed, skipped, cancelled.
remediation.outcomestring or nullyesHow it ended. null until it has. unverified means a fix was proposed as a draft pull request but was not proven by reproducing the flaw: it is not a verified fix.
remediation.prUrlstring or nullyesThe pull request the run opened, when it opened one.
externalIssueUrlstring or nullyesThe issue filed for it in your tracker, when one was.
notesarray of FindingNotenoReplies and comments about this finding, oldest first. The latest 100 are kept. Absent when there are none.
resolvedInShastring or nullnoThe commit in which the flagged code was no longer present. Set when a review closed the finding as patched; absent or null otherwise.
validationFindingValidationnoThe check by a Nullgap researcher, for workspaces that have it. Absent when the finding is not subject to it.
priorityPriorityyesHow urgent it is. Always present in answers: records stored before priorities existed get theirs worked out on the way out.
sightingsarray of FindingSightingnoEvery run that reported this flaw, oldest first, up to the latest 50. One flaw is one finding, however often and by whichever route it is found. Absent on findings reported once before sightings were recorded.
riskReviewAtstring or nullnoAccepted risks only: the date the acceptance is to be looked at again. After it the finding is raised again when found.
earlierDecisionobject or nullnoSet when this finding resembles one the team dismissed earlier but was raised all the same, with the rule that required it. Cleared as soon as someone decides about this finding.
earlierDecision.findingIdstringyesThe finding that was dismissed earlier.
earlierDecision.decisionstringyesWhat was decided about it. One of: false_positive, accepted_risk.
earlierDecision.notestringyesWhy this one was raised all the same.
stateHistoryarray of FindingStateChangenoEvery change of state, oldest first, the latest 50 kept. state, stateBy and stateReason hold the latest only. Absent when the state has not changed since the trail was introduced.
fixRunsarray of FindingFixRunnoThe fix runs started for this finding, oldest first, the latest 20 kept. Absent when none was recorded.
traceFindingTracenoWhat backs the finding, laid out for a reader: the data-flow path, the call path, a diagram, the proof, the verdict and the history. Present when one finding is read (GET /findings/{id}); lists leave it out.

#SuppressedFinding

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

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

#Report

A report issued for a finished pentest. It is a record: it shows the findings as they were when it was issued, whatever was decided about them later.

FieldTypeAlways presentDescription
idstringyesThe report id.
orgIdstringyesThe organisation it belongs to.
pentestIdstringyesThe pentest it reports on.
kindstringyesfull: every finding with its evidence. executive: a summary for people who do not read code. attestation: a short statement that the test took place and what it covered.
titlestringyesThe report title.
shareTokenstring or nullyesThe secret part of the public link, /share/reports/{shareToken}. Anyone who has the link can read the report. Null while the report is not shared, and always null for a member or a read-only key: only an admin or owner (or a key with the admin scope), who can switch the link on and off, is given it. shared says whether a link exists.
sharedbooleanyesWhether the report has a public link. Given to everyone who can read the report, unlike the link itself.
createdAtstringyesWhen the report was issued.
snapshotIdstring or nullnoThe stored record the report is produced from: the pentest and its findings as they were when the report was issued. The three reports of one pentest share it. Absent or null on a report issued before records were kept; such a report is produced from the findings as they are today and says so in its first line.
revisedAtstring or nullnoSet when the report was revised, which happens once and only where Nullgap researchers review the findings after the pentest: when the last finding has been reviewed. Absent or null otherwise.

#PentestCoverage

What one pentest read and what it did not, in counts of files.

FieldTypeAlways presentDescription
outcomestringyesgaps when a component failed, so part of the scope was not assessed. Files left unexamined because the run went to more exposed code first are not a gap: they are counted in notExamined.
sourceFilesintegeryesSource files in scope, after the exclusions.
indexedintegeryesHow many of them the code index held.
examinedintegeryesHow many of them were examined in depth.
notExaminedintegeryesSource files in scope that were not examined in depth: sourceFiles minus examined.
excludedobjectyesSource-like files left out before ranking, by reason. A folder named in paths is never left out as vendored or as tests.
excluded.vendoredintegeryesFiles in vendored and build-output folders.
excluded.testsintegeryesFiles in test and fixture folders, and test files.
excluded.generatedintegeryesGenerated files.
excluded.minifiedintegeryesMinified files.
excluded.binaryintegeryesFiles with binary content.
excluded.tooLargeintegeryesFiles over the size limit.
excluded.credentialsintegeryesCredential files. They are never opened.
excluded.unreadableintegeryesFiles that could not be read.
foldersarray of CoverageRowyesThe counts by top-level folder, largest first. At most sixty rows and one that sums the rest.
componentsarray of ComponentCoverageyesComponents, most exposed first. At most 150: every one with a gap, then the most exposed. componentCount is the true number.
componentCountintegeryesHow many components the codebase was cut into.
graphsintegeryesHow many code graphs the run built. More than one means the scope was too large for a single graph and was assessed in parts.
crossComponentobject or nullyesThe final pass over entry points and the interfaces between components, in a run that was assessed in parts. Null when one code graph covered the whole scope.
crossComponent.filesintegeryesEntry-point and interface files the pass indexed.
crossComponent.examinedintegeryesFiles it examined in depth.
crossComponent.outcomestringyesWhether the pass ran to the end. One of: completed, failed, not-run.
crossComponent.reasonstringnoWhy it failed. Absent otherwise.
gapsarray of objectyesWhat could not be assessed, with the reason. Empty when outcome is complete.
gaps[].componentstringyesThe component, or (across components) for the final pass.
gaps[].reasonstringyesWhy it was not assessed.
resumedintegeryesHow many times the run continued from a checkpoint after its worker stopped or it reached its time limit. Nothing is charged or reported twice.

#ProofEnvironment

Whether the code of a pentest could be built and run in the sandbox. It is checked in the first minutes of a run and decides whether findings can be reproduced by running the code or only confirmed by independent review.

FieldTypeAlways presentDescription
verdictstringyesThe answer in one word. ready: findings can be reproduced by building and running the code. limited: part of it works; parts, services and toolchains say what does not. unavailable: the code cannot be built in the sandbox, so findings are confirmed by independent review only. not-needed: the code has no dependencies to install. not-checked: nothing was checked.
summarystringyesOne sentence that says the same, for display.
partsarray of objectyesOne entry per kind of dependency and folder.
parts[].labelstringyesWhat it is.
parts[].pathstringyesFolder relative to the repository root; . for the root.
parts[].statestringyesready: dependencies are in place and the code compiled. dependencies-failed: the dependencies could not be installed. build-failed: they are in place but the code does not compile in the sandbox. not-checked: they are in place and no compile check was made.
parts[].reasonstringnoWhy, when the state is not ready.
servicesarray of objectyesDatabases, caches and queues the code needs running before it can be started.
services[].namestringyesThe service.
services[].availablebooleanyesWhether the sandbox can start a throw-away one for a proof.
services[].evidencestringyesWhat in the repository says the code needs it.
toolchainsarray of objectyesLanguage versions the project asks for that differ from the sandbox. Empty when they match.
toolchains[].namestringyesThe language or tool.
toolchains[].wantedstringyesWhat the project asks for, and where.
toolchains[].havestringyesWhat the sandbox has.
toolchains[].relationstringyesolder: the sandbox has an older version than asked for, so the code may not build. newer: it usually still does.
checkedAtstringyesWhen the check finished.
secondsintegeryesHow long it took.

#AccessMatrix

Who could read what across the test identities of one live target.

FieldTypeAlways presentDescription
targetstringyesThe origin of the running application.
identitiesarray of objectyesThe columns: every test identity, then the signed-out visitor.
identities[].idstringyesA stable id for the column (id1 to id5, or anonymous for a request with no session).
identities[].labelstringyesThe identity's label, or "Signed out".
identities[].levelstringyesThe access level. One of: admin, user, readonly, anonymous.
rowsarray of objectyesOne row per endpoint replayed.
rows[].methodstringyesThe HTTP method. Only read-only requests are replayed.
rows[].pathstringyesThe path, with id-like parts shown as {id} and query values left out.
rows[].ownerstringnoThe id of the identity whose data the endpoint returned, when that could be told from the responses.
rows[].cellsobjectyesColumn id to outcome. leaked means the identity received the owner's data, reproduced twice with clean controls and accepted by an independent review; a status code alone never counts. allowed means it got an answer it may be entitled to, denied that it got no answer or none with the owner's data, not-tried that the budget or a failed sign-in left it out.
rows[].findingIdstringnoFor a row with a leaked cell: the proven finding it rests on.
rows[].notestringnoWhy a replay was not counted, or that the budget ran out.
requestsintegeryesRequests the replay spent on this target.
truncatedbooleanyesTrue when the endpoint or request budget cut the matrix short.
notestringnoWhy the replay did not run or stopped early.

#LiveItem

One lead of a running pentest. Preliminary: not a finding.

FieldTypeAlways presentDescription
idstringyesThe lead's id: the same for the whole run and after a restart of it.
stagestringyeschecking: raised, not yet confirmed. merged: the same flaw as another lead (mergedInto). dismissed: the independent review refuted it or set it aside as hardening advice (reason). held: the independent review could not complete; kept for a person. confirmed: the independent review could not refute it. proving: a probe is being run in the sandbox. proven: the probe reproduced it. not-reproduced: confirmed; a working probe ran and the code behaved safely. could-not-test: confirmed; the sandbox could not build or run the project, so no probe ran (reason says what was missing). proof-incomplete: confirmed; the proof stopped before a result, at the time or token limit or because no working probe was produced (reason).
titlestringyesWhat the lead says, as raised.
severitystringyesSeverity as estimated at this stage; the review may change it. One of: critical, high, medium, low.
filestringnoFile the lead points at, relative to the repository root.
lineintegernoLine in that file.
weaknessstringnoWeakness class, when one was named.
reasonstringnoWhy it was dismissed, held, not reproduced, could not be tested, or why its proof did not complete.
mergedIntostringnoFor merged: the lead it was folded into.
evidencearray of objectnoFor confirmed and later stages: what supports it so far.
evidence[].kindstringyesWhich step it comes from. One of: review, proof.
evidence[].summarystringyesOne line.
evidence[].detailstringnoMore detail, shortened.
firstSeenAtstringyesWhen the lead was first raised.
updatedAtstringyesWhen it last changed stage.
seqintegeryesPosition in the run's sequence of changes.

#LiveIdentity

One test identity of a live-testing target, without its secret.

FieldTypeAlways presentDescription
labelstringyesWhat the identity was called when the pentest was started. Unique within the target.
levelstringyesThe access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only).
hasSecretbooleanyesAlways true: a password or token was given for it. The value itself is never returned.

#SupplyChainReason

One reason a package is worth a look. A reason is a signal, not a verdict.

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

#PackageAdvisory

A published advisory that lists this package version.

FieldTypeAlways presentDescription
idstringyesThe advisory id.
summarystringyesWhat the advisory says, in one line.
severitystringyesThe severity the advisory states.
kindstringyesWhether the advisory reports malicious code in the package or a flaw in it. One of: malware, vulnerability.

#PolicyMatch

The organisation rule that decided a package, and why.

FieldTypeAlways presentDescription
actionstringyesblock: the organisation does not permit this package. allow: the organisation exempted it.
rulestringyesWhich of the organisation's rules matched. One of: blocked-package, allowed-package, min-age, install-script, registry.
detailstringyesThe rule and why it matched, in plain words.

#Finding

A flaw as the engine reported it: what it is, where, how serious, and what backs it. Text in evidence[].summary never names the AI behind it other than as Nullgap AI.

FieldTypeAlways presentDescription
idstringyesThe id the engine gave this finding. To address a finding in the API use the id of the record that carries it (fnd_…), not this one.
modulestringyesThe part of Nullgap that produced it: code, deps (dependencies), redteam or another.
ruleIdstringyesThe rule or check that raised it.
titlestringyesA one-line name for the flaw.
descriptionstringyesWhat is wrong and why it matters.
severitystringyesHow serious the flaw is if exploited. One of: critical, high, medium, low, info.
confidencenumberyesHow confident the engine is that the finding is real, from 0 to 1.
cwearray of stringnoThe weakness classes it belongs to.
cvearray of stringnoPublished vulnerabilities it corresponds to, mostly on dependency findings.
locationLocationnoWhere in the code it is. Absent on findings that are not about a line of code.
packagePackageRefnoThe package concerned, on dependency findings.
sourcestringyesA label for the check that raised it. Findings that are another place of an already proven flaw carry variant; a finding raised by a skill carries llm-skill: followed by the skill id.
statusstringyesHow far the finding was checked. The product shows this as one of three assurance levels: proven and fixed are proven (a probe reproduced the flaw; fixed adds that a patch exists and passed verification on a fresh checkout), verified is verified (an independent review of the code could not refute it, but it was not reproduced), and candidate is unverified (flagged, the independent review did not complete, not reproduced: a lead to confirm). rejected (an independent check called it a false positive) is never stored, so it does not appear in answers.
evidencearray of EvidenceyesThe reasoning and checks recorded for the finding, in order.
remediationstringnoHow to fix it, in words.
patchPatchnoThe fix written for it, when one has been.
fingerprintstringyesA value that stays the same for this flaw across runs.
triageFindingTriagenoThe shape of the flagged code and how exposed it is.
triageVerdictTriageVerdictnoThe independent check's verdict in a fixed shape: true or false positive, how sure, the severity it settled on and why. Absent on findings raised before verdicts were kept and on those the check did not reach.

#FindingNote

A reply or comment about a finding.

FieldTypeAlways presentDescription
authorstringyesWho wrote it: an email address, a code host login, or api-key:<name> for a note added with an API key.
textstringyesThe note, up to 2000 characters.
atstringyesWhen it was written.
viastringyesWhere it was written. code-host: a reply on the pull request. console: the console or this API. researcher: by a Nullgap security researcher during an expert review; author is then always Nullgap researcher.

#FindingValidation

A check of the finding by a Nullgap researcher, on top of the automated ones. Who the researcher is is not disclosed.

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

#Priority

How urgent a finding is: its severity, moved by what is known about exposure. Up one step when the code is reachable from an internet-facing entry point that needs no sign-in, or is proven and reachable from an internet-facing entry point. Down two steps for test-only code; down one step each when it is only reached through a command-line, internal or administration entry point, when no call chain leads to it, and when the value is not under an attacker’s control (two steps down at most). A proven finding is never placed below what its severity gives.

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

#FindingSighting

One run that reported a finding.

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

#FindingStateChange

One change of a finding's state.

FieldTypeAlways presentDescription
atstringyesWhen the state changed.
bystring or nullyesWho changed it: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when not known.
fromstring or nullyesThe state before. null when the finding came into being with this change (brought back from the held-back list). One of: open, patched, accepted_risk, false_positive, null.
tostringyesThe state after. One of: open, patched, accepted_risk, false_positive.
reasonstring or nullyesThe reason given with the change.
reviewAtstring or nullyesAccepted risks: the review date set with the decision.
viastring or nullyesHow the change came about when it was not a single decision in the console.

#FindingFixRun

One fix run started for a finding.

FieldTypeAlways presentDescription
runIdstringyesThe id of the fix run.
startedAtstringyesWhen it was started.
finishedAtstring or nullyesWhen it ended. null while it runs.
statusstringyesWhere that run stands. One of: queued, running, completed, failed, skipped, cancelled.
outcomestring or nullyesHow it ended for this finding. null until it has. One of: fixed, unverified, no_fix_needed, false_positive, failed, null.
prUrlstring or nullyesThe pull request the run opened, when it opened one.

#FindingTrace

What backs one finding, laid out for a reader. Every part is read from what was recorded when the finding was raised and checked; nothing is worked out afresh.

FieldTypeAlways presentDescription
dataFlowobject or nullyesThe data-flow path. Null when none was recorded.
dataFlow.stepsarray of TraceStepyesThe path, entry point first and sink last.
dataFlow.entryPointstring or nullyesWhere the data comes in.
dataFlow.sinkstring or nullyesWhere it does harm.
dataFlow.confirmedBystringyesindependent-check: the path the independent check confirmed. finder: the path as first reported, not confirmed hop by hop.
callPathobject or nullyesThe call path from an entry point to the flagged code. Null when none was recorded.
callPath.stepsarray of TraceStepyesThe calls, entry point first.
callPath.basisstringyesHow the path was worked out and what it cannot see.
diagramstring or nullyesA Mermaid flowchart of the data flow, or of the call path when there is no data flow. Null when the path has fewer than two steps.
proofobject or nullyesThe proof on record. Null when the finding was not reproduced.
proof.kindstringyessandbox: a probe run in the sandbox. live: a request against a running application in the live-testing scope.
proof.summarystringyesWhat the proof showed. Up to 400 characters.
proof.reproducedbooleanyesWhether the flaw was reproduced.
proof.outcomestringnoFor sandbox: the proof's outcome. Only not_reproduced means a probe ran and the code behaved safely; environment_missing, budget_exhausted, no_probe and probe_broken mean it was not tested.
occurrencesintegeryesHow many times runs have raised this finding. 1 when the count was not recorded.
skillstring or nullyesThe skill that raised it, when one did.
verdictTriageVerdict or nullyes
historyarray of objectyesDecisions and notes on the finding, oldest first; entries without a time come last.
history[].atstring or nullyesWhen. Null when the time was not recorded.
history[].bystring or nullyesWho: a member, independent check, researcher, or null when it was the system.
history[].whatstringyesWhat happened.
history[].detailstringnoMore, when there is more. Up to 500 characters.
missingarray of stringyesEach part that was not recorded for this finding, in a sentence. Quote these instead of filling the gap.

#CoverageRow

File counts for one top-level folder.

FieldTypeAlways presentDescription
pathstringyesThe folder, relative to the repository root. . for files at the root; (other folders) sums the folders beyond the sixty largest.
sourceFilesintegeryesSource files in scope, after the exclusions.
indexedintegeryesHow many of them the code index held.
examinedintegeryesHow many of them were examined in depth.

#ComponentCoverage

How one component of the codebase (a service or package) fared in a run.

FieldTypeAlways presentDescription
pathstringyesThe folder of the component, relative to the repository root. . for files at the root. A path ending in /* gathers the less exposed folders of that folder.
kindstringyesHow the component was found: from a manifest or build file in its folder, or from the folder structure. One of: manifest, folder.
exposureRankintegeryes1 is the most exposed component of the run.
sourceFilesintegeryesSource files in scope, after the exclusions.
indexedintegeryesHow many of them the code index held.
examinedintegeryesHow many of them were examined in depth.
outcomestringyesHow the component fared. partly-examined is the usual outcome in a large codebase: its most exposed files were examined and the rest were not.
reasonstringnoWhy it failed, or why nothing in it was examined. Absent otherwise.

#Location

Where in the code a finding is.

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

#PackageRef

The package a dependency finding is about.

FieldTypeAlways presentDescription
ecosystemstringyesThe package registry: npm, PyPI, crates.io or another.
namestringyesThe package name.
versionstringyesThe version in use.
fixedVersionstringnoThe first version without the problem, when one is known.
manifeststringnoThe manifest or lockfile the package was found in, relative to the repository root.
directbooleannoTrue when the project depends on it directly, false when it comes in through another package.

#Evidence

One step in the chain that backs a finding. The steps are listed in the order they happened.

FieldTypeAlways presentDescription
kindstringyesWhat sort of evidence this is. engine: a static rule matched. reasoning: the written analysis of the code. probe: a reproduction attempt in the sandbox. transcript: a recorded exchange. verification: the independent check of the finding. dynamic: a test against the running application.
summarystringyesOne or two sentences saying what this step showed.
detailstringnoThe longer text of the step. On probe evidence these are the probe files.
commandstringnoThe command that was run, on evidence that ran one.
exitCodeintegernoWhat the command exited with.
outputstringnoWhat the command printed.
proofProofRecordnoOn probe evidence written by the proof step: how the reproduction went.

#Patch

A fix written for a finding.

FieldTypeAlways presentDescription
diffstringyesA unified diff, applicable with git apply from the repository root.
descriptionstringyesWhat the patch changes, in plain words.
verifiedbooleanyesTrue when the patch passed its checks on a fresh checkout.
verificationPatchVerificationnoHow it was checked, when it was.
attemptsarray of PatchAttemptnoEvery attempt made, oldest first. diff is the last one.
unprovenobjectnoPresent only on a patch written without reproducing the flaw. Such a patch is never verified.
unproven.reasonstringyesWhy the flaw was not reproduced.
unproven.proofstringyesWhat the reproduction attempt recorded. Never reproduced, and never not_reproduced: when the code behaved safely no patch is written.
unproven.acceptedbooleanyesTrue when every check that needs no probe ran without failing and the independent review accepted the change. Only then was it offered, as a proposal.
unproven.independentReviewerbooleanyesTrue when the review was done by a different Nullgap AI model from the one that wrote the change.

#FindingTriage

Facts for triage, worked out from the code: the shape of the flagged code and how exposed it is. Absent on findings from before this existed and on package advisories.

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

#TriageVerdict

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

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

#TraceStep

One step of a path through the code.

FieldTypeAlways presentDescription
nintegeryesIts position on the path, from 1.
textstringyesWhat happens at this step. Up to 400 characters.
filestringnoThe file, when the step names one.
lineintegernoThe line, when the step names one.

#ProofRecord

The record of one attempt to reproduce a finding. It lets a reader tell "it was run and did not reproduce" from "it could not be run here".

FieldTypeAlways presentDescription
outcomestringyesWhat happened when the finding was sent for reproduction. reproduced: the probe showed the flaw and its harmless control behaved safely. not_reproduced: the probe ran correctly and the code behaved safely. probe_broken: no trustworthy probe (it errored, timed out, or its control did not hold). no_probe: no probe was produced. environment_missing: the code cannot run in the sandbox as it is (see missing). budget_exhausted: the limit for one proof ran out first.
attemptsintegeryesHow many probe attempts were made, 1 or 2.
missingstringnoFor environment_missing: what the sandbox lacked, in a few words.
dependenciesstringyesWhether the project's dependencies were in place before the probe ran. One of: installed, present, not_installed, not_needed.
controlHeldbooleannoThe harmless control run behaved safely. Absent when no control was run.
repeatablebooleannoThe probe gave the same result when run a second time. Set when the outcome is reproduced.
auditedbooleannoAn independent reviewer read the probe and accepted that it exercises the project's own code and observes the unsafe effect. False when the run had no such reviewer.
variantHeldbooleannoA second, different input for the same flaw also reproduced on the unpatched code. False: one was supplied and did not reproduce. Absent: none was supplied.
modelsAskedintegernoPresent only when writing the probe was declined at least once: how many Nullgap AI models were asked to write it. Each was sent the same request, unchanged.
declinedintegernoPresent only when writing the probe was declined at least once: how many of the models asked declined.

#PatchVerification

How a patch was checked.

FieldTypeAlways presentDescription
probePassedbooleanyesThe probe no longer reproduces the flaw on a fresh, patched checkout.
testsPassedboolean or nullyesWhether the project’s own tests pass with the patch. null when the project has no test command.
logstringyesThe output of the verification run.
checksarray of FixChecknoEvery check, in the order it ran. Absent on patches recorded before checks were itemised.
refusedarray of stringnoWhy the patch was refused, one sentence per reason. Empty or absent when it was not refused.

#PatchAttempt

One try at writing a fix. A run makes a bounded number of them, each told why the previous one failed.

FieldTypeAlways presentDescription
attemptintegeryesWhich try this was, counted from 1.
verifiedbooleanyesWhether this attempt passed every check.
reasonstringnoWhy this attempt was not accepted. Absent when it was.
proposedbooleannoOnly on a fix written without reproducing the flaw: this attempt passed every check that needs no probe and was accepted as a proposal. verified is still false.
filesarray of stringyesThe files this attempt changed.

#FlawShape

What the flagged code looks like, in a form that survives renames and moved lines. Nullgap uses it to recognise code the team has already decided about. Treat the hashes as opaque; family is the one value worth comparing.

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

#Exposure

What is known about how the flawed code can be reached. It is worked out from the code alone. A fact that could not be established is not_determined and never moves the priority in either direction.

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

#FixCheck

One named check a fix went through.

FieldTypeAlways presentDescription
namestringyesWhich check. applies: the patch applies to a fresh checkout. scope: the patch widens no risk and stays on files related to the finding. probe: the probe that reproduced the flaw no longer does. variant: a second input for the same flaw no longer reproduces either. control: ordinary use still works. tests: the project’s own tests pass. For a fix proposed without reproducing the flaw (outcome unverified), the three probe runs are not_run and two more checks are made: build (the changed files still parse) and review (an independent review of the change accepted that it closes the flaw without changing other behaviour). For a dependency fix, in place of the three probe runs: lockfile (the lockfile was regenerated from the edited manifest in the sandbox, with install scripts off) and resolved (the affected version is no longer in the manifest or the lockfile).
statusstringyesnot_run is never a pass: the check could not be made, and detail says why.
detailstringyesOne plain sentence: what was seen, or why the check could not run.
placestringnoFor a fix that covers several places: the one this check belongs to, as file:line.

Nullgap documentation