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.
| Operation | Method and path | Who may call it |
|---|---|---|
| Check live-testing access | POST /api/orgs/{org}/pentests/verify-access | admin |
| Estimate a pentest | POST /api/orgs/{org}/pentests/estimate | read |
| Start a pentest | POST /api/orgs/{org}/pentests | admin |
| List pentests | GET /api/orgs/{org}/pentests | read |
| Get a pentest | GET /api/orgs/{org}/pentests/{id} | read |
| Get a pentest's log | GET /api/orgs/{org}/pentests/{id}/logs | read |
| Get what a running pentest has found so far | GET /api/orgs/{org}/pentests/{id}/live | read |
| Cancel a pentest | POST /api/orgs/{org}/pentests/{id}/cancel | admin |
| See whether a stopped pentest can be resumed | GET /api/orgs/{org}/pentests/{id}/resume | read |
| Resume a stopped pentest | POST /api/orgs/{org}/pentests/{id}/resume | admin |
| Start the free retest | POST /api/orgs/{org}/pentests/{id}/retest | admin |
| Estimate the free retest | POST /api/orgs/{org}/pentests/{id}/retest/estimate | write |
#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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | The 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. |
signInSteps | string | no | How to sign in, in plain words. Up to 5000 characters. |
username | string | no | The user name of a throwaway test account. Up to 200 characters. |
password | string | no | The password of that account. Up to 200 characters. Stored encrypted, never returned and never logged. |
secondUsername | string | no | The 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. |
secondPassword | string | no | The password of the second account. Up to 200 characters. |
identities | array of object | no | Up 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[].label | string | yes | What to call this identity, for example "Admin" or "Tenant B user". Unique within the target. Up to 60 characters. |
identities[].level | string | no | The access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only). Default user. |
identities[].username | string | no | The user name to sign in with. Up to 200 characters. |
identities[].password | string | no | Its password. Up to 200 characters. Stored encrypted, never returned and never logged. |
identities[].bearerToken | string | no | A 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)
| Field | Type | Always present | Description |
|---|---|---|---|
ok | boolean | yes | True when the address answered and every identity signed in. |
detail | string | yes | What was found, in plain words. Up to 300 characters. |
failedIdentity | string | no | When 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
| Status | Code | When |
|---|---|---|
| 400 | out_of_scope | A 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repoId | string | yes | The repository, by its id. |
ref | string | no | The branch, tag or commit to measure. Up to 200 characters. Default: the repository's default branch. |
paths | array of string | no | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repoId | string | yes | The repository, by its id. |
ref | string | no | The branch, tag or commit to test. Up to 200 characters. Default: the repository's default branch. |
paths | array of string | no | The 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. |
context | string | no | Notes for the testers: architecture, what matters most, what changed. Up to 20,000 characters. |
applicationId | string | no | An application of this repository. Its threat model and rules are handed to the run. |
dynamicTarget | object | no | One running application to test findings against. Ignored when dynamicTargets is sent as a list, even an empty one. |
dynamicTarget.url | string | yes | The 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.signInSteps | string | no | How to sign in, in plain words. Up to 5000 characters. |
dynamicTarget.username | string | no | The user name of a throwaway test account. Up to 200 characters. |
dynamicTarget.password | string | no | The password of that account. Up to 200 characters. Stored encrypted, never returned and never logged. |
dynamicTarget.secondUsername | string | no | The 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.secondPassword | string | no | The password of the second account. Up to 200 characters. |
dynamicTarget.identities | array of object | no | Up 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[].label | string | yes | What to call this identity, for example "Admin" or "Tenant B user". Unique within the target. Up to 60 characters. |
dynamicTarget.identities[].level | string | no | The access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only). Default user. |
dynamicTarget.identities[].username | string | no | The user name to sign in with. Up to 200 characters. |
dynamicTarget.identities[].password | string | no | Its password. Up to 200 characters. Stored encrypted, never returned and never logged. |
dynamicTarget.identities[].bearerToken | string | no | A token to send instead of signing in. Up to 4000 characters. Stored encrypted, never returned and never logged. |
dynamicTargets | array of object | no | Up 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[].url | string | yes | The 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[].signInSteps | string | no | How to sign in, in plain words. Up to 5000 characters. |
dynamicTargets[].username | string | no | The user name of a throwaway test account. Up to 200 characters. |
dynamicTargets[].password | string | no | The password of that account. Up to 200 characters. Stored encrypted, never returned and never logged. |
dynamicTargets[].secondUsername | string | no | The 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[].secondPassword | string | no | The password of the second account. Up to 200 characters. |
dynamicTargets[].identities | array of object | no | Up 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[].label | string | yes | What to call this identity, for example "Admin" or "Tenant B user". Unique within the target. Up to 60 characters. |
dynamicTargets[].identities[].level | string | no | The access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only). Default user. |
dynamicTargets[].identities[].username | string | no | The user name to sign in with. Up to 200 characters. |
dynamicTargets[].identities[].password | string | no | Its password. Up to 200 characters. Stored encrypted, never returned and never logged. |
dynamicTargets[].identities[].bearerToken | string | no | A token to send instead of signing in. Up to 4000 characters. Stored encrypted, never returned and never logged. |
liveStateChanging | boolean | no | Send 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. |
disposableConfirmed | boolean | no | Your 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. |
maxPriceUsd | number | no | A 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No repository of this organisation has the repoId sent, or applicationId is not an application of that repository. |
| 400 | bad_request | A 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. |
| 400 | out_of_scope | A live-testing address is a private or loopback address, or its host is not on the organisation's scope list. |
| 400 | confirmation_required | liveStateChanging is true and disposableConfirmed is not exactly true. |
| 400 | access_check_failed | A 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. |
| 402 | usage_limit | The workspace has reached its monthly usage limit. |
| 400 | custom_quote | The 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. |
| 402 | payment_required | The workspace has no payment method on file and not enough pentest credits for the price of this run. |
| 402 | over_cap | The price of this run is above the maxPriceUsd sent. Nothing was started or charged. |
| 409 | idempotency_key_reused | The Idempotency-Key header was used in the last 24 hours for a start with different fields. |
| 409 | idempotency_in_progress | An 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no | How many to return, 1 to 200. Default 50. |
offset | integer | no | How many to skip from the start. Default 0. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests?limit=20"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of Pentest | yes | Pentests, at most limit of them. |
total | integer | yes | How 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | integer | no | Return 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No pentest of this organisation has that id. |
| 409 | not_running | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
maxPriceUsd | number | no | A 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No pentest of this organisation has that id. |
| 400 | bad_request | maxPriceUsd is not a number of dollars, zero or more. |
| 409 | not_stopped | The pentest is queued, running or completed: there is nothing to resume. |
| 409 | still_stopping | The pentest was cancelled a moment ago and its work has not stopped yet. Try again shortly. |
| 409 | no_checkpoint | The pentest stopped before it had recorded any progress. Start a new one. |
| 409 | expired | The time in which the pentest could be resumed has passed. Start a new one. |
| 409 | repository_gone | The repository of the pentest, or its code-host connection, was removed. |
| 409 | commit_gone | The 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. |
| 409 | superseded | The pentest is a retest, and another retest of the same pentest was started after it stopped. |
| 402 | usage_limit | The workspace has reached its monthly usage limit. |
| 402 | payment_required | The workspace has no payment method on file and not enough pentest credits for the price of this pentest. |
| 402 | over_cap | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
ref | string | no | Optional, and only the original's own ref: the free retest tests the same branch or tag. Any other value is refused with retest_ref. |
maxPriceUsd | number | no | The 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. |
liveTesting | boolean | no | Whether 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No pentest of this organisation has that id. |
| 409 | is_retest | The pentest named is itself a retest. Start a new pentest to test again. |
| 409 | not_completed | The pentest named has not completed: it is still going, or it failed or was cancelled. |
| 409 | retest_used | The free retest of this pentest has already been started and is queued, running or completed. |
| 409 | repository_gone | The repository of the pentest is no longer connected. |
| 400 | retest_ref | ref names a different branch or tag from the original's. Start a new pentest to test it. |
| 400 | access_check_failed | A 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. |
| 402 | usage_limit | The workspace has reached its monthly usage limit. |
| 400 | custom_quote | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/ID/retest/estimate"
Answer (200, application/json)
The free retest before it starts.
| Field | Type | Always present | Description |
|---|---|---|---|
ref | string | yes | The branch or tag the retest tests: the original's. |
linesOfCode | integer | yes | Lines of code in scope now. |
originalLinesOfCode | integer | yes | Lines the original counted. |
freeUpToLines | integer | yes | Up to this many lines the retest is free: the original's plus a quarter. |
extraUsd | number or null | yes | What 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. |
available | boolean | yes | Whether the free retest of this pentest has not been used yet. |
canStart | boolean | yes | Whether it could start now, by the start's own checks. |
blocked | object or null | yes | Why it could not start now. |
blocked.code | string | yes | Why not. |
blocked.message | string | yes | In 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No pentest of this organisation has that id. |
| 409 | is_retest | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
linesOfCode | integer | yes | Lines of code in scope. |
priceUsd | number or null | yes | The price of this run, as agreed for your workspace. Null when the code is large enough to need a custom quote. |
quoteWaived | boolean | no | Present and true when the code is past the price list but this workspace is not billed per run, so the pentest may start anyway. |
covered | boolean | no | Present and true when this workspace is not billed per run: nothing is charged for the pentest, whatever its price. |
canStart | boolean | no | Whether 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. |
blocked | object or null | no | Why the pentest could not start now. Null when canStart is true. |
blocked.code | string | yes | The error code the start would answer with. One of: org_suspended, usage_limit, custom_quote, payment_required. |
blocked.message | string | yes | What the start would say, with what to do about it. |
#Pentest
A penetration test of a repository at one version.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The pentest id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository that was tested. |
repoFullName | string | yes | The repository as owner/name. |
applicationId | string or null | yes | The application whose threat model and rules were used, when one was chosen. |
ref | string | yes | The branch, tag or commit that was tested. |
paths | array of string | yes | The folders in scope. Empty means the whole repository. |
dynamicTarget | LiveTarget or null | yes | |
dynamicTargets | array of LiveTarget | no | Every running application this pentest tests findings against. Absent when there is no live testing. dynamicTarget is the first of these. |
liveStateChanging | boolean | no | Present and true when the pentest may send requests that change data on the live targets, which the organisation confirmed are disposable. Absent otherwise. |
context | string | yes | The notes given when it was started (architecture, what matters). Empty when none were given. |
linesOfCode | integer | yes | Lines of code in scope, counted when the pentest was started. |
priceUsd | number or null | yes | The 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. |
covered | string | no | Present 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. |
chargedForWork | number | no | A 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. |
workChargeSoFarUsd | number | no | A queued or running pentest, on a single pentest only: about what cancelling it now would charge for the work done so far. |
status | string | yes | Where the pentest stands. A pentest is never skipped. |
phase | string or null | yes | What 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. |
findingsCount | integer | yes | How many findings this pentest raised so far. |
createdBy | string | yes | Who started it: a person's e-mail address, api-key: followed by the name of an API key, or schedule. |
privacy | RunPrivacy or null | yes | |
createdAt | string | yes | When it was started. |
startedAt | string or null | yes | When work on it began. Null while it is queued. |
finishedAt | string or null | yes | When it finished, failed or was cancelled. Null until then. |
advisoryCount | integer | no | How many published advisories list a package version the code pins. These are not findings. The advisories themselves are on the single pentest, in advisories. |
validation | object | no | Researcher validation of this pentest's findings. Present only for workspaces that have researcher validation. |
validation.pending | integer | yes | Findings still waiting for a researcher. |
validation.done | integer | yes | Findings a researcher has decided. |
validation.completedAt | string or null | yes | When the last finding was decided. Null while any is pending. |
retestOf | string or null | no | On a retest: the id of the pentest whose findings it checks again. Null on an ordinary pentest. |
retestId | string or null | no | On the original: the id of its retest, once one has been requested. Absent until then. |
retest | object or null | no | On a finished retest: what it found about the original's findings. Absent on an ordinary pentest and until the retest has finished. |
retest.fixed | integer | yes | Findings of the original that are fixed: the flagged code is gone and the retest did not find them again. |
retest.stillOpen | integer | yes | Findings of the original that are still there, or whose code is unchanged. |
retest.added | integer | yes | Findings the retest raised that the original did not have. |
suppressedCount | integer | no | How many findings this pentest produced and did not raise because of an earlier decision. They are listed on the single pentest, in suppressed. |
completedWithGaps | boolean | no | On 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. |
creditsCharged | number | no | Pentest 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. |
refunded | boolean | no | True once the credits taken for a failed or cancelled run have been returned. |
failureReason | string or null | no | On a failed pentest: why it stopped. Null otherwise. |
cancelledBy | string or null | no | On a cancelled pentest: who cancelled it, in the same form as createdBy. finishedAt says when. Absent on pentests cancelled before this was recorded. |
resumableUntil | string or null | no | On 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The pentest id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository that was tested. |
repoFullName | string | yes | The repository as owner/name. |
applicationId | string or null | yes | The application whose threat model and rules were used, when one was chosen. |
ref | string | yes | The branch, tag or commit that was tested. |
paths | array of string | yes | The folders in scope. Empty means the whole repository. |
dynamicTarget | LiveTarget or null | yes | |
dynamicTargets | array of LiveTarget | no | Every running application this pentest tests findings against. Absent when there is no live testing. dynamicTarget is the first of these. |
liveStateChanging | boolean | no | Present and true when the pentest may send requests that change data on the live targets, which the organisation confirmed are disposable. Absent otherwise. |
context | string | yes | The notes given when it was started (architecture, what matters). Empty when none were given. |
linesOfCode | integer | yes | Lines of code in scope, counted when the pentest was started. |
priceUsd | number or null | yes | The 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. |
covered | string | no | Present 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. |
chargedForWork | number | no | A 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. |
workChargeSoFarUsd | number | no | A queued or running pentest, on a single pentest only: about what cancelling it now would charge for the work done so far. |
status | string | yes | Where the pentest stands. A pentest is never skipped. |
phase | string or null | yes | What 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. |
findingsCount | integer | yes | How many findings this pentest raised so far. |
createdBy | string | yes | Who started it: a person's e-mail address, api-key: followed by the name of an API key, or schedule. |
privacy | RunPrivacy or null | yes | |
createdAt | string | yes | When it was started. |
startedAt | string or null | yes | When work on it began. Null while it is queued. |
finishedAt | string or null | yes | When it finished, failed or was cancelled. Null until then. |
advisoryCount | integer | no | How many published advisories list a package version the code pins. These are not findings. The advisories themselves are on the single pentest, in advisories. |
validation | object | no | Researcher validation of this pentest's findings. Present only for workspaces that have researcher validation. |
validation.pending | integer | yes | Findings still waiting for a researcher. |
validation.done | integer | yes | Findings a researcher has decided. |
validation.completedAt | string or null | yes | When the last finding was decided. Null while any is pending. |
retestOf | string or null | no | On a retest: the id of the pentest whose findings it checks again. Null on an ordinary pentest. |
retestId | string or null | no | On the original: the id of its retest, once one has been requested. Absent until then. |
retest | object or null | no | On a finished retest: what it found about the original's findings. Absent on an ordinary pentest and until the retest has finished. |
retest.fixed | integer | yes | Findings of the original that are fixed: the flagged code is gone and the retest did not find them again. |
retest.stillOpen | integer | yes | Findings of the original that are still there, or whose code is unchanged. |
retest.added | integer | yes | Findings the retest raised that the original did not have. |
suppressedCount | integer | no | How many findings this pentest produced and did not raise because of an earlier decision. They are listed on the single pentest, in suppressed. |
completedWithGaps | boolean | no | On 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. |
creditsCharged | number | no | Pentest 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. |
refunded | boolean | no | True once the credits taken for a failed or cancelled run have been returned. |
failureReason | string or null | no | On a failed pentest: why it stopped. Null otherwise. |
cancelledBy | string or null | no | On a cancelled pentest: who cancelled it, in the same form as createdBy. finishedAt says when. Absent on pentests cancelled before this was recorded. |
resumableUntil | string or null | no | On 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. |
advisories | array of DependencyAdvisory | yes | Published advisories against the package versions the code pins, most severe first. They are not findings. Empty when there are none. |
supplyChain | array of SupplyChainPackage | yes | Malicious, suspicious and vulnerable packages in one list. Empty when there are none. |
findings | array of FindingRecord | yes | The findings this pentest raised. |
suppressed | array of SuppressedFinding | yes | What this pentest produced and did not raise, each with the decision it rests on. |
reports | array of Report | yes | The reports written for this pentest, oldest first. Empty until it has finished. |
coverage | PentestCoverage | no | |
proofEnvironment | ProofEnvironment | no | |
accessMatrix | array of AccessMatrix | no | Who 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.
| Field | Type | Always present | Description |
|---|---|---|---|
at | string | yes | When the line was written. |
level | string | yes | How serious the line is. One of: info, warn, error. |
message | string | yes | What happened, in plain words. |
#PentestLive
What a pentest has come across so far. Preliminary: never counted as findings.
| Field | Type | Always present | Description |
|---|---|---|---|
pentestId | string | yes | The pentest. |
state | string | yes | running: 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. |
preliminary | boolean | yes | Always true: nothing here is a finding. |
counts | object | yes | Leads by stage. Merged leads are in none of these. |
counts.checking | integer | yes | Leads still being checked, including ones held for a person. |
counts.confirmed | integer | yes | Confirmed by the independent review, including ones being proven and ones whose proof did not reproduce them, could not run or did not complete. |
counts.proven | integer | yes | Reproduced in the sandbox. |
counts.dismissed | integer | yes | Dismissed by the independent review. |
items | array of LiveItem | yes | The leads, in the order they last changed. With after, only those that changed since. |
cursor | integer | yes | Pass as after on the next request. |
notListed | integer | yes | Leads past the most kept for one run (1,000): counted, not listed. |
findingIds | array of string | no | For replaced: the findings of the completed pentest. |
becameFinding | object | no | For 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.
| Field | Type | Always present | Description |
|---|---|---|---|
pentestId | string | yes | The pentest. |
resumable | boolean | yes | Whether 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. |
reason | object or null | yes | Why the pentest cannot be resumed. Null when resumable is true. |
reason.code | string | yes | Why 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.message | string | yes | The same, in words, with what to do instead. |
resumableUntil | string or null | yes | Until when it can be resumed. Null when it never could be. |
progress | object | yes | How far the pentest got before it stopped. |
progress.filesExamined | integer or null | yes | Files examined in depth before it stopped. Null when that is no longer on record. |
progress.filesTotal | integer or null | yes | Files 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.leads | integer | yes | Leads it had raised so far. Preliminary: these are not findings. |
priceUsd | number | yes | What 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. |
creditsToCharge | number | yes | Pentest credits a resume would take now. 0 for a retest, and for a workspace billed by payment method or whose plan covers pentests. |
canStart | boolean | yes | Whether 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. |
blocked | object or null | yes | Why the workspace could not resume it now although there is something to continue from. Null otherwise. |
blocked.code | string | yes | The error code the resume would answer with. One of: org_suspended, usage_limit, custom_quote, payment_required. |
blocked.message | string | yes | What the resume would say, with what to do about it. |
#LiveTarget
A running application that findings are tested against.
| Field | Type | Always present | Description |
|---|---|---|---|
url | string | yes | The address of the running application. |
signInSteps | string | yes | How to sign in, as given when the pentest was started. Empty when nothing was given. |
hasCredentials | boolean | no | Present and true when a test account was given. The account itself is stored encrypted and never returned. |
hasSecondAccount | boolean | no | Present and true when two or more test identities were given, for access-control checks. Kept for older clients: read identities. |
identities | array of LiveIdentity | no | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
zeroRetention | boolean | yes | True when every Nullgap AI call in the run was confirmed as keeping no data afterwards. |
identifiersMasked | integer | yes | How many identifiers (names, e-mail addresses, numbers) were replaced with made-up values before Nullgap AI saw them. |
#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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The advisory id. |
cve | array of string | yes | The CVE ids the advisory carries. May be empty. |
package | string | yes | The package name. |
version | string | yes | The version the code pins. |
ecosystem | string | yes | The package ecosystem. |
fixedVersion | string or null | yes | The first version without the flaw, when the advisory names one. |
severity | string | yes | The severity the advisory states. One of: critical, high, medium, low, info. |
summary | string | yes | What the advisory says, in one line. |
manifest | string or null | yes | The manifest or lockfile that pins the package. |
direct | boolean or null | yes | True when the code depends on the package directly, false when through another package, null when that is not known. |
usage | string | no | Whether 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. |
usedIn | array of string | no | Up to five places that import the package. |
#SupplyChainPackage
One package in the supply-chain list of a review or a pentest.
| Field | Type | Always present | Description |
|---|---|---|---|
ecosystem | string | yes | The package ecosystem. |
name | string | yes | The package name. |
version | string | yes | The version the code pins. |
verdict | string | yes | The verdict on this version. A clean package is listed only when an organisation rule blocks it; unknown ones are listed because unknown is not clean. |
reasons | array of SupplyChainReason | yes | Every signal found, strongest first. May be empty. |
advisories | array of PackageAdvisory | yes | The advisories that list this version. May be empty. |
fixedVersion | string or null | no | The first version without the flaw, when an advisory names one. |
manifest | string or null | yes | The manifest or lockfile that pins the package. |
direct | boolean or null | yes | True when the code depends on the package directly, false when through another package, null when that is not known. |
policy | PolicyMatch | no | |
findingId | string | no | The finding raised for this package, when there is one. |
#FindingRecord
A finding as your organisation holds it: the flaw (finding), where it came from, what the team decided (state), and what was done about it. Internal details are left out of every answer: whether the pull request came from a fork, who opened it, and which researcher validated the finding.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id of the finding. Use it in every route that takes a finding id. |
orgId | string | yes | The organisation it belongs to. |
repoId | string | yes | The repository it was found in. |
repoFullName | string | yes | The name of that repository. |
source | string | yes | What kind of run first reported it. One of: review, pentest. |
sourceId | string | yes | The id of that review or pentest. |
prNumber | integer or null | yes | The pull request it was found on. null when it did not come from a pull request. |
finding | Finding | yes | The flaw itself. finding.status says how far it was checked. |
state | string | yes | What the team has decided about it. open: to be dealt with. patched: fixed. accepted_risk: real, and accepted. false_positive: not a real issue. This is separate from finding.status, which says how far Nullgap checked it. |
stateReason | string or null | yes | The reason given with the last decision. |
stateBy | string or null | yes | Who last changed the state: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when nobody has. |
firstSeenAt | string | yes | When it was first reported. |
resolvedAt | string or null | yes | When it last left the open state. null while open. |
remediation | object or null | yes | The latest fix run for this finding. null when none was started. |
remediation.runId | string | yes | The id of the fix run. |
remediation.status | string | yes | Where that run stands. One of: queued, running, completed, failed, skipped, cancelled. |
remediation.outcome | string or null | yes | How it ended. null until it has. unverified means a fix was proposed as a draft pull request but was not proven by reproducing the flaw: it is not a verified fix. |
remediation.prUrl | string or null | yes | The pull request the run opened, when it opened one. |
externalIssueUrl | string or null | yes | The issue filed for it in your tracker, when one was. |
notes | array of FindingNote | no | Replies and comments about this finding, oldest first. The latest 100 are kept. Absent when there are none. |
resolvedInSha | string or null | no | The commit in which the flagged code was no longer present. Set when a review closed the finding as patched; absent or null otherwise. |
validation | FindingValidation | no | The check by a Nullgap researcher, for workspaces that have it. Absent when the finding is not subject to it. |
priority | Priority | yes | How urgent it is. Always present in answers: records stored before priorities existed get theirs worked out on the way out. |
sightings | array of FindingSighting | no | Every run that reported this flaw, oldest first, up to the latest 50. One flaw is one finding, however often and by whichever route it is found. Absent on findings reported once before sightings were recorded. |
riskReviewAt | string or null | no | Accepted risks only: the date the acceptance is to be looked at again. After it the finding is raised again when found. |
earlierDecision | object or null | no | Set when this finding resembles one the team dismissed earlier but was raised all the same, with the rule that required it. Cleared as soon as someone decides about this finding. |
earlierDecision.findingId | string | yes | The finding that was dismissed earlier. |
earlierDecision.decision | string | yes | What was decided about it. One of: false_positive, accepted_risk. |
earlierDecision.note | string | yes | Why this one was raised all the same. |
stateHistory | array of FindingStateChange | no | Every change of state, oldest first, the latest 50 kept. state, stateBy and stateReason hold the latest only. Absent when the state has not changed since the trail was introduced. |
fixRuns | array of FindingFixRun | no | The fix runs started for this finding, oldest first, the latest 20 kept. Absent when none was recorded. |
trace | FindingTrace | no | What backs the finding, laid out for a reader: the data-flow path, the call path, a diagram, the proof, the verdict and the history. Present when one finding is read (GET /findings/{id}); lists leave it out. |
#SuppressedFinding
A finding that a run produced and Nullgap did not raise, because the team had already decided about it or about code that is the same. Nothing is held back silently: every one is listed here with why and whose decision it rests on, and anyone on the team can bring it back.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id of this held-back record. |
repoId | string | yes | The repository it was found in. |
repoFullName | string | yes | The name of that repository. |
finding | Finding | yes | The flaw that was found and not raised. |
priority | Priority | yes | How urgent it would be. Always present in answers. |
kind | string | yes | same_finding: the very finding that was dismissed, found again. pattern: other code that matches the dismissed code. |
decision | string | yes | The earlier decision it rests on. One of: false_positive, accepted_risk. |
decidedBy | string or null | yes | Who took that decision. |
decidedAt | string or null | yes | When that decision was taken. |
reason | string or null | yes | The reason given with that decision. |
dismissedFindingId | string | yes | The finding the decision was taken on. |
why | array of string | yes | Why it counts as the same, one statement per entry. |
similarity | number or null | yes | How alike the surrounding function is, from 0 to 1. null for same_finding. |
sightings | array of FindingSighting | yes | Every run that found it and held it back, oldest first. |
firstAt | string | yes | When it was first held back. |
lastAt | string | yes | When it was last found and held back. |
restoredAt | string or null | yes | When someone brought it back. null while it is held back. |
restoredBy | string or null | yes | Who brought it back. |
restoredFindingId | string or null | yes | The finding it became when it was brought back. |
#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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The report id. |
orgId | string | yes | The organisation it belongs to. |
pentestId | string | yes | The pentest it reports on. |
kind | string | yes | full: 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. |
title | string | yes | The report title. |
shareToken | string or null | yes | The 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. |
shared | boolean | yes | Whether the report has a public link. Given to everyone who can read the report, unlike the link itself. |
createdAt | string | yes | When the report was issued. |
snapshotId | string or null | no | The 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. |
revisedAt | string or null | no | Set 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.
| Field | Type | Always present | Description |
|---|---|---|---|
outcome | string | yes | gaps 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. |
sourceFiles | integer | yes | Source files in scope, after the exclusions. |
indexed | integer | yes | How many of them the code index held. |
examined | integer | yes | How many of them were examined in depth. |
notExamined | integer | yes | Source files in scope that were not examined in depth: sourceFiles minus examined. |
excluded | object | yes | Source-like files left out before ranking, by reason. A folder named in paths is never left out as vendored or as tests. |
excluded.vendored | integer | yes | Files in vendored and build-output folders. |
excluded.tests | integer | yes | Files in test and fixture folders, and test files. |
excluded.generated | integer | yes | Generated files. |
excluded.minified | integer | yes | Minified files. |
excluded.binary | integer | yes | Files with binary content. |
excluded.tooLarge | integer | yes | Files over the size limit. |
excluded.credentials | integer | yes | Credential files. They are never opened. |
excluded.unreadable | integer | yes | Files that could not be read. |
folders | array of CoverageRow | yes | The counts by top-level folder, largest first. At most sixty rows and one that sums the rest. |
components | array of ComponentCoverage | yes | Components, most exposed first. At most 150: every one with a gap, then the most exposed. componentCount is the true number. |
componentCount | integer | yes | How many components the codebase was cut into. |
graphs | integer | yes | How many code graphs the run built. More than one means the scope was too large for a single graph and was assessed in parts. |
crossComponent | object or null | yes | The 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.files | integer | yes | Entry-point and interface files the pass indexed. |
crossComponent.examined | integer | yes | Files it examined in depth. |
crossComponent.outcome | string | yes | Whether the pass ran to the end. One of: completed, failed, not-run. |
crossComponent.reason | string | no | Why it failed. Absent otherwise. |
gaps | array of object | yes | What could not be assessed, with the reason. Empty when outcome is complete. |
gaps[].component | string | yes | The component, or (across components) for the final pass. |
gaps[].reason | string | yes | Why it was not assessed. |
resumed | integer | yes | How 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.
| Field | Type | Always present | Description |
|---|---|---|---|
verdict | string | yes | The 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. |
summary | string | yes | One sentence that says the same, for display. |
parts | array of object | yes | One entry per kind of dependency and folder. |
parts[].label | string | yes | What it is. |
parts[].path | string | yes | Folder relative to the repository root; . for the root. |
parts[].state | string | yes | ready: 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[].reason | string | no | Why, when the state is not ready. |
services | array of object | yes | Databases, caches and queues the code needs running before it can be started. |
services[].name | string | yes | The service. |
services[].available | boolean | yes | Whether the sandbox can start a throw-away one for a proof. |
services[].evidence | string | yes | What in the repository says the code needs it. |
toolchains | array of object | yes | Language versions the project asks for that differ from the sandbox. Empty when they match. |
toolchains[].name | string | yes | The language or tool. |
toolchains[].wanted | string | yes | What the project asks for, and where. |
toolchains[].have | string | yes | What the sandbox has. |
toolchains[].relation | string | yes | older: the sandbox has an older version than asked for, so the code may not build. newer: it usually still does. |
checkedAt | string | yes | When the check finished. |
seconds | integer | yes | How long it took. |
#AccessMatrix
Who could read what across the test identities of one live target.
| Field | Type | Always present | Description |
|---|---|---|---|
target | string | yes | The origin of the running application. |
identities | array of object | yes | The columns: every test identity, then the signed-out visitor. |
identities[].id | string | yes | A stable id for the column (id1 to id5, or anonymous for a request with no session). |
identities[].label | string | yes | The identity's label, or "Signed out". |
identities[].level | string | yes | The access level. One of: admin, user, readonly, anonymous. |
rows | array of object | yes | One row per endpoint replayed. |
rows[].method | string | yes | The HTTP method. Only read-only requests are replayed. |
rows[].path | string | yes | The path, with id-like parts shown as {id} and query values left out. |
rows[].owner | string | no | The id of the identity whose data the endpoint returned, when that could be told from the responses. |
rows[].cells | object | yes | Column 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[].findingId | string | no | For a row with a leaked cell: the proven finding it rests on. |
rows[].note | string | no | Why a replay was not counted, or that the budget ran out. |
requests | integer | yes | Requests the replay spent on this target. |
truncated | boolean | yes | True when the endpoint or request budget cut the matrix short. |
note | string | no | Why the replay did not run or stopped early. |
#LiveItem
One lead of a running pentest. Preliminary: not a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The lead's id: the same for the whole run and after a restart of it. |
stage | string | yes | checking: 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). |
title | string | yes | What the lead says, as raised. |
severity | string | yes | Severity as estimated at this stage; the review may change it. One of: critical, high, medium, low. |
file | string | no | File the lead points at, relative to the repository root. |
line | integer | no | Line in that file. |
weakness | string | no | Weakness class, when one was named. |
reason | string | no | Why it was dismissed, held, not reproduced, could not be tested, or why its proof did not complete. |
mergedInto | string | no | For merged: the lead it was folded into. |
evidence | array of object | no | For confirmed and later stages: what supports it so far. |
evidence[].kind | string | yes | Which step it comes from. One of: review, proof. |
evidence[].summary | string | yes | One line. |
evidence[].detail | string | no | More detail, shortened. |
firstSeenAt | string | yes | When the lead was first raised. |
updatedAt | string | yes | When it last changed stage. |
seq | integer | yes | Position in the run's sequence of changes. |
#LiveIdentity
One test identity of a live-testing target, without its secret.
| Field | Type | Always present | Description |
|---|---|---|---|
label | string | yes | What the identity was called when the pentest was started. Unique within the target. |
level | string | yes | The access level it is meant to have: admin (Admin), user (Standard user) or readonly (Read-only). |
hasSecret | boolean | yes | Always 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The stable name of the rule that matched. |
category | string | yes | What kind of signal it is. One of: lockfile, confusion, typosquat, install-script, registry, content. |
strength | string | yes | strong: no honest explanation. notable: worth a person's look by itself. weak: common in honest packages, given as context. |
severity | string | yes | How serious the signal is. One of: critical, high, medium, low, info. |
summary | string | yes | The signal in plain words. |
file | string | no | A project file (for lockfile signals) or a path inside the package (for signals from its contents). |
line | integer | no | The line in file, when there is one. |
excerpt | string | no | A short piece of the text that matched, with secrets masked. |
#PackageAdvisory
A published advisory that lists this package version.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The advisory id. |
summary | string | yes | What the advisory says, in one line. |
severity | string | yes | The severity the advisory states. |
kind | string | yes | Whether the advisory reports malicious code in the package or a flaw in it. One of: malware, vulnerability. |
#PolicyMatch
The organisation rule that decided a package, and why.
| Field | Type | Always present | Description |
|---|---|---|---|
action | string | yes | block: the organisation does not permit this package. allow: the organisation exempted it. |
rule | string | yes | Which of the organisation's rules matched. One of: blocked-package, allowed-package, min-age, install-script, registry. |
detail | string | yes | The rule and why it matched, in plain words. |
#Finding
A flaw as the engine reported it: what it is, where, how serious, and what backs it. Text in evidence[].summary never names the AI behind it other than as Nullgap AI.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id the engine gave this finding. To address a finding in the API use the id of the record that carries it (fnd_…), not this one. |
module | string | yes | The part of Nullgap that produced it: code, deps (dependencies), redteam or another. |
ruleId | string | yes | The rule or check that raised it. |
title | string | yes | A one-line name for the flaw. |
description | string | yes | What is wrong and why it matters. |
severity | string | yes | How serious the flaw is if exploited. One of: critical, high, medium, low, info. |
confidence | number | yes | How confident the engine is that the finding is real, from 0 to 1. |
cwe | array of string | no | The weakness classes it belongs to. |
cve | array of string | no | Published vulnerabilities it corresponds to, mostly on dependency findings. |
location | Location | no | Where in the code it is. Absent on findings that are not about a line of code. |
package | PackageRef | no | The package concerned, on dependency findings. |
source | string | yes | A label for the check that raised it. Findings that are another place of an already proven flaw carry variant; a finding raised by a skill carries llm-skill: followed by the skill id. |
status | string | yes | How far the finding was checked. The product shows this as one of three assurance levels: proven and fixed are proven (a probe reproduced the flaw; fixed adds that a patch exists and passed verification on a fresh checkout), verified is verified (an independent review of the code could not refute it, but it was not reproduced), and candidate is unverified (flagged, the independent review did not complete, not reproduced: a lead to confirm). rejected (an independent check called it a false positive) is never stored, so it does not appear in answers. |
evidence | array of Evidence | yes | The reasoning and checks recorded for the finding, in order. |
remediation | string | no | How to fix it, in words. |
patch | Patch | no | The fix written for it, when one has been. |
fingerprint | string | yes | A value that stays the same for this flaw across runs. |
triage | FindingTriage | no | The shape of the flagged code and how exposed it is. |
triageVerdict | TriageVerdict | no | The independent check's verdict in a fixed shape: true or false positive, how sure, the severity it settled on and why. Absent on findings raised before verdicts were kept and on those the check did not reach. |
#FindingNote
A reply or comment about a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
author | string | yes | Who wrote it: an email address, a code host login, or api-key:<name> for a note added with an API key. |
text | string | yes | The note, up to 2000 characters. |
at | string | yes | When it was written. |
via | string | yes | Where it was written. code-host: a reply on the pull request. console: the console or this API. researcher: by a Nullgap security researcher during an expert review; author is then always Nullgap researcher. |
#FindingValidation
A check of the finding by a Nullgap researcher, on top of the automated ones. Who the researcher is is not disclosed.
| Field | Type | Always present | Description |
|---|---|---|---|
status | string | yes | pending: waiting for a researcher. confirmed: a researcher reproduced or accepted it. adjusted: confirmed with a different severity. rejected: a researcher found it is not a real issue, and the finding is closed as a false positive. |
at | string or null | yes | When the researcher decided. null while pending. |
note | string or null | yes | What the researcher wrote for you. |
severityBefore | string | no | The severity before an adjustment. Present only when status is adjusted. |
requestedAt | string | no | When your workspace asked for this expert review. Absent when the review came with a researcher-validation contract. |
requestedBy | string | no | The name of the person in your workspace who asked. |
scope | string | no | Whether the request was for this finding alone or for the whole pentest report. One of: finding, pentest. |
requestNote | string or null | no | What you asked the researcher to check. |
openedAt | string or null | no | When a researcher first opened the finding for this request. Once set, the request can no longer be cancelled. |
previous | object | no | The decision a new request for another look replaces. Restored if the request is cancelled. |
previous.status | string | yes | The earlier decision. One of: confirmed, adjusted, rejected. |
previous.at | string or null | yes | When it was made. |
previous.note | string or null | yes | What the researcher wrote. |
previous.severityBefore | string | no | The severity before that adjustment. |
#Priority
How urgent a finding is: its severity, moved by what is known about exposure. Up one step when the code is reachable from an internet-facing entry point that needs no sign-in, or is proven and reachable from an internet-facing entry point. Down two steps for test-only code; down one step each when it is only reached through a command-line, internal or administration entry point, when no call chain leads to it, and when the value is not under an attacker’s control (two steps down at most). A proven finding is never placed below what its severity gives.
| Field | Type | Always present | Description |
|---|---|---|---|
level | string | yes | How urgent the finding is, P0 being the most urgent. |
fromSeverity | string | yes | What the severity alone would give: critical P0, high P1, medium P2, low and info P3. |
proven | boolean | yes | True when the finding was reproduced, in the sandbox or against the running application. |
reasons | array of string | yes | Why it is this level, most important first, written to be shown to people as they are. |
#FindingSighting
One run that reported a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
source | string | yes | What kind of run reported it. One of: review, pentest. |
sourceId | string | yes | The id of that review or pentest. |
prNumber | integer or null | yes | The pull request, for a review. null for a pentest. |
at | string | yes | When that run reported it. |
#FindingStateChange
One change of a finding's state.
| Field | Type | Always present | Description |
|---|---|---|---|
at | string | yes | When the state changed. |
by | string or null | yes | Who changed it: an email address, api-key:<name>, or nullgap when Nullgap changed it itself. null when not known. |
from | string or null | yes | The state before. null when the finding came into being with this change (brought back from the held-back list). One of: open, patched, accepted_risk, false_positive, null. |
to | string | yes | The state after. One of: open, patched, accepted_risk, false_positive. |
reason | string or null | yes | The reason given with the change. |
reviewAt | string or null | yes | Accepted risks: the review date set with the decision. |
via | string or null | yes | How the change came about when it was not a single decision in the console. |
#FindingFixRun
One fix run started for a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
runId | string | yes | The id of the fix run. |
startedAt | string | yes | When it was started. |
finishedAt | string or null | yes | When it ended. null while it runs. |
status | string | yes | Where that run stands. One of: queued, running, completed, failed, skipped, cancelled. |
outcome | string or null | yes | How it ended for this finding. null until it has. One of: fixed, unverified, no_fix_needed, false_positive, failed, null. |
prUrl | string or null | yes | The pull request the run opened, when it opened one. |
#FindingTrace
What backs one finding, laid out for a reader. Every part is read from what was recorded when the finding was raised and checked; nothing is worked out afresh.
| Field | Type | Always present | Description |
|---|---|---|---|
dataFlow | object or null | yes | The data-flow path. Null when none was recorded. |
dataFlow.steps | array of TraceStep | yes | The path, entry point first and sink last. |
dataFlow.entryPoint | string or null | yes | Where the data comes in. |
dataFlow.sink | string or null | yes | Where it does harm. |
dataFlow.confirmedBy | string | yes | independent-check: the path the independent check confirmed. finder: the path as first reported, not confirmed hop by hop. |
callPath | object or null | yes | The call path from an entry point to the flagged code. Null when none was recorded. |
callPath.steps | array of TraceStep | yes | The calls, entry point first. |
callPath.basis | string | yes | How the path was worked out and what it cannot see. |
diagram | string or null | yes | A Mermaid flowchart of the data flow, or of the call path when there is no data flow. Null when the path has fewer than two steps. |
proof | object or null | yes | The proof on record. Null when the finding was not reproduced. |
proof.kind | string | yes | sandbox: a probe run in the sandbox. live: a request against a running application in the live-testing scope. |
proof.summary | string | yes | What the proof showed. Up to 400 characters. |
proof.reproduced | boolean | yes | Whether the flaw was reproduced. |
proof.outcome | string | no | For sandbox: the proof's outcome. Only not_reproduced means a probe ran and the code behaved safely; environment_missing, budget_exhausted, no_probe and probe_broken mean it was not tested. |
occurrences | integer | yes | How many times runs have raised this finding. 1 when the count was not recorded. |
skill | string or null | yes | The skill that raised it, when one did. |
verdict | TriageVerdict or null | yes | |
history | array of object | yes | Decisions and notes on the finding, oldest first; entries without a time come last. |
history[].at | string or null | yes | When. Null when the time was not recorded. |
history[].by | string or null | yes | Who: a member, independent check, researcher, or null when it was the system. |
history[].what | string | yes | What happened. |
history[].detail | string | no | More, when there is more. Up to 500 characters. |
missing | array of string | yes | Each part that was not recorded for this finding, in a sentence. Quote these instead of filling the gap. |
#CoverageRow
File counts for one top-level folder.
| Field | Type | Always present | Description |
|---|---|---|---|
path | string | yes | The folder, relative to the repository root. . for files at the root; (other folders) sums the folders beyond the sixty largest. |
sourceFiles | integer | yes | Source files in scope, after the exclusions. |
indexed | integer | yes | How many of them the code index held. |
examined | integer | yes | How many of them were examined in depth. |
#ComponentCoverage
How one component of the codebase (a service or package) fared in a run.
| Field | Type | Always present | Description |
|---|---|---|---|
path | string | yes | The 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. |
kind | string | yes | How the component was found: from a manifest or build file in its folder, or from the folder structure. One of: manifest, folder. |
exposureRank | integer | yes | 1 is the most exposed component of the run. |
sourceFiles | integer | yes | Source files in scope, after the exclusions. |
indexed | integer | yes | How many of them the code index held. |
examined | integer | yes | How many of them were examined in depth. |
outcome | string | yes | How the component fared. partly-examined is the usual outcome in a large codebase: its most exposed files were examined and the rest were not. |
reason | string | no | Why it failed, or why nothing in it was examined. Absent otherwise. |
#Location
Where in the code a finding is.
| Field | Type | Always present | Description |
|---|---|---|---|
file | string | yes | Path of the file, relative to the repository root, with forward slashes. |
startLine | integer | yes | The first flagged line, counted from 1. |
endLine | integer | no | The last flagged line, when the finding spans several. |
snippet | string | no | The flagged code. Keys, tokens and passwords in it are masked. |
#PackageRef
The package a dependency finding is about.
| Field | Type | Always present | Description |
|---|---|---|---|
ecosystem | string | yes | The package registry: npm, PyPI, crates.io or another. |
name | string | yes | The package name. |
version | string | yes | The version in use. |
fixedVersion | string | no | The first version without the problem, when one is known. |
manifest | string | no | The manifest or lockfile the package was found in, relative to the repository root. |
direct | boolean | no | True when the project depends on it directly, false when it comes in through another package. |
#Evidence
One step in the chain that backs a finding. The steps are listed in the order they happened.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | What sort of evidence this is. engine: a static rule matched. reasoning: the written analysis of the code. probe: a reproduction attempt in the sandbox. transcript: a recorded exchange. verification: the independent check of the finding. dynamic: a test against the running application. |
summary | string | yes | One or two sentences saying what this step showed. |
detail | string | no | The longer text of the step. On probe evidence these are the probe files. |
command | string | no | The command that was run, on evidence that ran one. |
exitCode | integer | no | What the command exited with. |
output | string | no | What the command printed. |
proof | ProofRecord | no | On probe evidence written by the proof step: how the reproduction went. |
#Patch
A fix written for a finding.
| Field | Type | Always present | Description |
|---|---|---|---|
diff | string | yes | A unified diff, applicable with git apply from the repository root. |
description | string | yes | What the patch changes, in plain words. |
verified | boolean | yes | True when the patch passed its checks on a fresh checkout. |
verification | PatchVerification | no | How it was checked, when it was. |
attempts | array of PatchAttempt | no | Every attempt made, oldest first. diff is the last one. |
unproven | object | no | Present only on a patch written without reproducing the flaw. Such a patch is never verified. |
unproven.reason | string | yes | Why the flaw was not reproduced. |
unproven.proof | string | yes | What the reproduction attempt recorded. Never reproduced, and never not_reproduced: when the code behaved safely no patch is written. |
unproven.accepted | boolean | yes | True when every check that needs no probe ran without failing and the independent review accepted the change. Only then was it offered, as a proposal. |
unproven.independentReviewer | boolean | yes | True when the review was done by a different Nullgap AI model from the one that wrote the change. |
#FindingTriage
Facts for triage, worked out from the code: the shape of the flagged code and how exposed it is. Absent on findings from before this existed and on package advisories.
| Field | Type | Always present | Description |
|---|---|---|---|
shape | FlawShape | no | What the flagged code looks like. Absent when the finding is not about code. |
exposure | Exposure | no | How the code can be reached, and by whom. |
#TriageVerdict
The independent check's verdict on a finding, in a fixed shape.
| Field | Type | Always present | Description |
|---|---|---|---|
verdict | string | yes | What the independent check concluded. One of: true_positive, false_positive. |
confidence | string | yes | How sure it is. A low verdict is left for a person: nothing is rejected or downgraded on it. |
severity | string | yes | The severity after weighing prerequisites, impact and difficulty. One of: critical, high, medium, low, info. |
severityBefore | string | no | The severity first claimed, present only when the check changed it. One of: critical, high, medium, low, info. |
severityReasons | array of string | yes | Why the severity is what it is. |
mitigations | array of string | yes | Controls found on the path (validation, authorisation, safe APIs, limits), whether or not they stop the flaw. |
weaknessFits | boolean or null | yes | Whether the weakness class named on the finding fits what the code does. Null when the check did not say. |
reasoning | string | yes | The check's reasoning, in plain words. |
confirmedPath | array of string | yes | The hops of the reported path that the check confirmed in the code. |
at | string | no | When the verdict was given. |
#TraceStep
One step of a path through the code.
| Field | Type | Always present | Description |
|---|---|---|---|
n | integer | yes | Its position on the path, from 1. |
text | string | yes | What happens at this step. Up to 400 characters. |
file | string | no | The file, when the step names one. |
line | integer | no | The line, when the step names one. |
#ProofRecord
The record of one attempt to reproduce a finding. It lets a reader tell "it was run and did not reproduce" from "it could not be run here".
| Field | Type | Always present | Description |
|---|---|---|---|
outcome | string | yes | What happened when the finding was sent for reproduction. reproduced: the probe showed the flaw and its harmless control behaved safely. not_reproduced: the probe ran correctly and the code behaved safely. probe_broken: no trustworthy probe (it errored, timed out, or its control did not hold). no_probe: no probe was produced. environment_missing: the code cannot run in the sandbox as it is (see missing). budget_exhausted: the limit for one proof ran out first. |
attempts | integer | yes | How many probe attempts were made, 1 or 2. |
missing | string | no | For environment_missing: what the sandbox lacked, in a few words. |
dependencies | string | yes | Whether the project's dependencies were in place before the probe ran. One of: installed, present, not_installed, not_needed. |
controlHeld | boolean | no | The harmless control run behaved safely. Absent when no control was run. |
repeatable | boolean | no | The probe gave the same result when run a second time. Set when the outcome is reproduced. |
audited | boolean | no | An independent reviewer read the probe and accepted that it exercises the project's own code and observes the unsafe effect. False when the run had no such reviewer. |
variantHeld | boolean | no | A second, different input for the same flaw also reproduced on the unpatched code. False: one was supplied and did not reproduce. Absent: none was supplied. |
modelsAsked | integer | no | Present only when writing the probe was declined at least once: how many Nullgap AI models were asked to write it. Each was sent the same request, unchanged. |
declined | integer | no | Present only when writing the probe was declined at least once: how many of the models asked declined. |
#PatchVerification
How a patch was checked.
| Field | Type | Always present | Description |
|---|---|---|---|
probePassed | boolean | yes | The probe no longer reproduces the flaw on a fresh, patched checkout. |
testsPassed | boolean or null | yes | Whether the project’s own tests pass with the patch. null when the project has no test command. |
log | string | yes | The output of the verification run. |
checks | array of FixCheck | no | Every check, in the order it ran. Absent on patches recorded before checks were itemised. |
refused | array of string | no | Why the patch was refused, one sentence per reason. Empty or absent when it was not refused. |
#PatchAttempt
One try at writing a fix. A run makes a bounded number of them, each told why the previous one failed.
| Field | Type | Always present | Description |
|---|---|---|---|
attempt | integer | yes | Which try this was, counted from 1. |
verified | boolean | yes | Whether this attempt passed every check. |
reason | string | no | Why this attempt was not accepted. Absent when it was. |
proposed | boolean | no | Only on a fix written without reproducing the flaw: this attempt passed every check that needs no probe and was accepted as a proposal. verified is still false. |
files | array of string | yes | The files this attempt changed. |
#FlawShape
What the flagged code looks like, in a form that survives renames and moved lines. Nullgap uses it to recognise code the team has already decided about. Treat the hashes as opaque; family is the one value worth comparing.
| Field | Type | Always present | Description |
|---|---|---|---|
v | integer | yes | The version of this description. Always 1. |
families | array of string | yes | The weakness families of the finding, sorted. |
file | string | yes | The file of the flagged line. |
fn | string or null | yes | The function that encloses the flagged line. null for code outside any named function. |
indexed | boolean | yes | True when the code index covered the file, so fn and callers are facts and not gaps. |
anchor | string | yes | The flagged statement, normalised. Empty when it carries too little to identify anything. |
sink | string | yes | The statement where the dangerous operation happens, normalised. Equal to anchor when the evidence names no other. |
ordinal | integer | yes | Which of several identical statements in the enclosing function this is. 0 is the first. |
source | string or null | yes | The line where the data comes in, normalised, when the evidence names it. |
entry | string or null | yes | The registration line of the entry point the code is reached from, normalised. |
near | string | yes | A hash of the code within a few lines of the flagged statement. |
wide | array of string | yes | A sketch of the whole enclosing function, used to score how alike two functions are. |
callers | array of string or null | yes | One entry per caller of the enclosing function. null when not known. |
family | string | yes | Findings with the same weakness family and the same sink statement share this key. It is what "findings like this one" means. |
#Exposure
What is known about how the flawed code can be reached. It is worked out from the code alone. A fact that could not be established is not_determined and never moves the priority in either direction.
| Field | Type | Always present | Description |
|---|---|---|---|
reachable | string | yes | Whether the flawed code is called from an entry point. One of: yes, no, not_determined. |
entryPoint | object or null | yes | The entry point, when the code is reachable from one. |
entryPoint.kind | string | yes | What sort of entry point it is. |
entryPoint.name | string | yes | Its name in the code. |
entryPoint.file | string | yes | The file it is registered in. |
entryPoint.line | integer | yes | The line it is registered on. |
entryPoint.method | string | no | For an HTTP entry point: the method. |
entryPoint.route | string | no | For an HTTP entry point: the route. |
authentication | string | yes | Whether that entry point asks for a signed-in caller. One of: required, none, not_determined. |
surface | string | yes | Who can get to the entry point. One of: internet, internal, admin, cli, test, not_determined. |
attackerControlled | string | yes | Whether the value that reaches the flaw comes from the caller. One of: yes, no, not_determined. |
basis | array of string | yes | How each fact above was established, one line each. |
#FixCheck
One named check a fix went through.
| Field | Type | Always present | Description |
|---|---|---|---|
name | string | yes | Which check. applies: the patch applies to a fresh checkout. scope: the patch widens no risk and stays on files related to the finding. probe: the probe that reproduced the flaw no longer does. variant: a second input for the same flaw no longer reproduces either. control: ordinary use still works. tests: the project’s own tests pass. For a fix proposed without reproducing the flaw (outcome unverified), the three probe runs are not_run and two more checks are made: build (the changed files still parse) and review (an independent review of the change accepted that it closes the flaw without changing other behaviour). For a dependency fix, in place of the three probe runs: lockfile (the lockfile was regenerated from the edited manifest in the sandbox, with install scripts off) and resolved (the affected version is no longer in the manifest or the lockfile). |
status | string | yes | not_run is never a pass: the check could not be made, and detail says why. |
detail | string | yes | One plain sentence: what was seen, or why the check could not run. |
place | string | no | For a fix that covers several places: the one this check belongs to, as file:line. |
Nullgap documentation