Scans

List Scans

GET/accounts/{account_id}/vuln_scanner/scans

Create Scan

POST/accounts/{account_id}/vuln_scanner/scans

Get Scan

GET/accounts/{account_id}/vuln_scanner/scans/{scan_id}

ModelsExpand Collapse

ScanListResponse { id, scan_type, status, 2 more }

id: string

Scan identifier.

formatuuid

scan_type: "bola"

The type of vulnerability scan.

status: "created" or "scheduled" or "planning" or 3 more

Current lifecycle status of the scan.

One of the following:

"created"

"scheduled"

"planning"

"running"

"finished"

"failed"

target_environment_id: string

The target environment this scan runs against.

formatuuid

report: optional { report, report_schema_version }

Vulnerability report produced after the scan completes. The shape depends on the scan type. Present only for finished scans.

report: { summary, tests }

Version 1 of the BOLA vulnerability scan report.

summary: { verdict }

Summary of all steps and findings.

verdict: "ok" or "warning" or "inconclusive"

Overall verdict of the vulnerability scan.

One of the following:

"ok"

"warning"

"inconclusive"

tests: array of { steps, verdict, preflight_errors }

List of tests that were run.

steps: array of { assertions, errors, request, response }

Steps that were executed.

assertions: array of { description, kind, observed, outcome }

Assertions that were made against the received response.

description: string

Human-readable description of the assertion, explaining what was checked.

kind: { parameters, type }

Kind of assertion.

parameters: { max, min }

Range of HTTP status codes.

max: number

Maximum (inclusive) status code of the range.

maximum65535

minimum0

min: number

Minimum (inclusive) status code of the range.

maximum65535

minimum0

type: "http_status_within_range"

observed: number

Observed value on which the assertion was made.

outcome: "ok" or "fail" or "inconclusive"

Outcome of the assertion.

One of the following:

"ok"

"fail"

"inconclusive"

errors: optional array of { description, error_code }

Errors the step encountered that may explain absent or incomplete fields.

description: string

Human-readable error description.

error_code: optional number

Numeric error code identifying the class of error, if available.

formatuint32

minimum0

request: optional { credential_set, header_names, method, 3 more }

HTTP request that was made, if any.

credential_set: { id, role }

Credential set that was used.

id: string

ID of the credential set.

formatuuid

role: "owner" or "attacker"

Role of the credential set.

One of the following:

"owner"

"attacker"

header_names: array of string

Names of headers that were sent.

method: "GET" or "DELETE" or "PATCH" or 2 more

HTTP method.

One of the following:

"GET"

"DELETE"

"PATCH"

"POST"

"PUT"

url: string

Exact and full URL (including host, query parameters) that was requested.

formaturi

variable_captures: array of { json_path, name }

Variable captures requested for this step.

json_path: string

JSONPath expression used for capture, e.g. "$.id".

Variable name, e.g. "resource_id".

body: optional unknown

Request body, if any.

response: optional { body, header_names, status, status_text }

HTTP response that was received, if any.

body: { kind } or { contents, kind, truncated } or { contents, kind, truncated } or { contents, kind, truncated }

HTTP response body.

One of the following:

Kind { kind }

No body was received.

kind: "not_found"

{ contents, kind, truncated }

Body received but unable to read as UTF-8. Raw bytes, base64-encoded.

contents: string

kind: "bytes"

truncated: boolean

{ contents, kind, truncated }

Body received as valid UTF-8 text but not valid JSON.

contents: string

kind: "text"

truncated: boolean

{ contents, kind, truncated }

Body received as valid JSON.

contents: string

kind: "json"

truncated: boolean

header_names: array of string

Names of headers that were received.

status: number

HTTP status code.

maximum65535

minimum0

status_text: optional string

HTTP status text, if available for the status code.

verdict: "ok" or "warning" or "inconclusive"

Verdict of this single test.

One of the following:

"ok"

"warning"

"inconclusive"

preflight_errors: optional array of { description, error_code }

Errors that prevented step execution.

description: string

Human-readable error description.

error_code: optional number

Numeric error code identifying the class of error, if available.

formatuint32

minimum0

report_schema_version: "v1"

Version of the report schema.

ScanCreateResponse { id, scan_type, status, 2 more }

id: string

Scan identifier.

formatuuid

scan_type: "bola"

The type of vulnerability scan.

status: "created" or "scheduled" or "planning" or 3 more

Current lifecycle status of the scan.

One of the following:

"created"

"scheduled"

"planning"

"running"

"finished"

"failed"

target_environment_id: string

The target environment this scan runs against.

formatuuid

report: optional { report, report_schema_version }

Vulnerability report produced after the scan completes. The shape depends on the scan type. Present only for finished scans.

report: { summary, tests }

Version 1 of the BOLA vulnerability scan report.

summary: { verdict }

Summary of all steps and findings.

verdict: "ok" or "warning" or "inconclusive"

Overall verdict of the vulnerability scan.

One of the following:

"ok"

"warning"

"inconclusive"

tests: array of { steps, verdict, preflight_errors }

List of tests that were run.

steps: array of { assertions, errors, request, response }

Steps that were executed.

assertions: array of { description, kind, observed, outcome }

Assertions that were made against the received response.

description: string

Human-readable description of the assertion, explaining what was checked.

kind: { parameters, type }

Kind of assertion.

parameters: { max, min }

Range of HTTP status codes.

max: number

Maximum (inclusive) status code of the range.

maximum65535

minimum0

min: number

Minimum (inclusive) status code of the range.

maximum65535

minimum0

type: "http_status_within_range"

observed: number

Observed value on which the assertion was made.

outcome: "ok" or "fail" or "inconclusive"

Outcome of the assertion.

One of the following:

"ok"

"fail"

"inconclusive"

errors: optional array of { description, error_code }

Errors the step encountered that may explain absent or incomplete fields.

description: string

Human-readable error description.

error_code: optional number

Numeric error code identifying the class of error, if available.

formatuint32

minimum0

request: optional { credential_set, header_names, method, 3 more }

HTTP request that was made, if any.

credential_set: { id, role }

Credential set that was used.

id: string

ID of the credential set.

formatuuid

role: "owner" or "attacker"

Role of the credential set.

One of the following:

"owner"

"attacker"

header_names: array of string

Names of headers that were sent.

method: "GET" or "DELETE" or "PATCH" or 2 more

HTTP method.

One of the following:

"GET"

"DELETE"

"PATCH"

"POST"

"PUT"

url: string

Exact and full URL (including host, query parameters) that was requested.

formaturi

variable_captures: array of { json_path, name }

Variable captures requested for this step.

json_path: string

JSONPath expression used for capture, e.g. "$.id".

Variable name, e.g. "resource_id".

body: optional unknown

Request body, if any.

response: optional { body, header_names, status, status_text }

HTTP response that was received, if any.

body: { kind } or { contents, kind, truncated } or { contents, kind, truncated } or { contents, kind, truncated }

HTTP response body.

One of the following:

Kind { kind }

No body was received.

kind: "not_found"

{ contents, kind, truncated }

Body received but unable to read as UTF-8. Raw bytes, base64-encoded.

contents: string

kind: "bytes"

truncated: boolean

{ contents, kind, truncated }

Body received as valid UTF-8 text but not valid JSON.

contents: string

kind: "text"

truncated: boolean

{ contents, kind, truncated }

Body received as valid JSON.

contents: string

kind: "json"

truncated: boolean

header_names: array of string

Names of headers that were received.

status: number

HTTP status code.

maximum65535

minimum0

status_text: optional string

HTTP status text, if available for the status code.

verdict: "ok" or "warning" or "inconclusive"

Verdict of this single test.

One of the following:

"ok"

"warning"

"inconclusive"

preflight_errors: optional array of { description, error_code }

Errors that prevented step execution.

description: string

Human-readable error description.

error_code: optional number

Numeric error code identifying the class of error, if available.

formatuint32

minimum0

report_schema_version: "v1"

Version of the report schema.

ScanGetResponse { id, scan_type, status, 2 more }

id: string

Scan identifier.

formatuuid

scan_type: "bola"

The type of vulnerability scan.

status: "created" or "scheduled" or "planning" or 3 more

Current lifecycle status of the scan.

One of the following:

"created"

"scheduled"

"planning"

"running"

"finished"

"failed"

target_environment_id: string

The target environment this scan runs against.

formatuuid

report: optional { report, report_schema_version }

Vulnerability report produced after the scan completes. The shape depends on the scan type. Present only for finished scans.

report: { summary, tests }

Version 1 of the BOLA vulnerability scan report.

summary: { verdict }

Summary of all steps and findings.

verdict: "ok" or "warning" or "inconclusive"

Overall verdict of the vulnerability scan.

One of the following:

"ok"

"warning"

"inconclusive"

tests: array of { steps, verdict, preflight_errors }

List of tests that were run.

steps: array of { assertions, errors, request, response }

Steps that were executed.

assertions: array of { description, kind, observed, outcome }

Assertions that were made against the received response.

description: string

Human-readable description of the assertion, explaining what was checked.

kind: { parameters, type }

Kind of assertion.

parameters: { max, min }

Range of HTTP status codes.

max: number

Maximum (inclusive) status code of the range.

maximum65535

minimum0

min: number

Minimum (inclusive) status code of the range.

maximum65535

minimum0

type: "http_status_within_range"

observed: number

Observed value on which the assertion was made.

outcome: "ok" or "fail" or "inconclusive"

Outcome of the assertion.

One of the following:

"ok"

"fail"

"inconclusive"

errors: optional array of { description, error_code }

Errors the step encountered that may explain absent or incomplete fields.

description: string

Human-readable error description.

error_code: optional number

Numeric error code identifying the class of error, if available.

formatuint32

minimum0

request: optional { credential_set, header_names, method, 3 more }

HTTP request that was made, if any.

credential_set: { id, role }

Credential set that was used.

id: string

ID of the credential set.

formatuuid

role: "owner" or "attacker"

Role of the credential set.

One of the following:

"owner"

"attacker"

header_names: array of string

Names of headers that were sent.

method: "GET" or "DELETE" or "PATCH" or 2 more

HTTP method.

One of the following:

"GET"

"DELETE"

"PATCH"

"POST"

"PUT"

url: string

Exact and full URL (including host, query parameters) that was requested.

formaturi

variable_captures: array of { json_path, name }

Variable captures requested for this step.

json_path: string

JSONPath expression used for capture, e.g. "$.id".

Variable name, e.g. "resource_id".

body: optional unknown

Request body, if any.

response: optional { body, header_names, status, status_text }

HTTP response that was received, if any.

body: { kind } or { contents, kind, truncated } or { contents, kind, truncated } or { contents, kind, truncated }

HTTP response body.

One of the following:

Kind { kind }

No body was received.

kind: "not_found"

{ contents, kind, truncated }

Body received but unable to read as UTF-8. Raw bytes, base64-encoded.

contents: string

kind: "bytes"

truncated: boolean

{ contents, kind, truncated }

Body received as valid UTF-8 text but not valid JSON.

contents: string

kind: "text"

truncated: boolean

{ contents, kind, truncated }

Body received as valid JSON.

contents: string

kind: "json"

truncated: boolean

header_names: array of string

Names of headers that were received.

status: number

HTTP status code.

maximum65535

minimum0

status_text: optional string

HTTP status text, if available for the status code.

verdict: "ok" or "warning" or "inconclusive"

Verdict of this single test.

One of the following:

"ok"

"warning"

"inconclusive"

preflight_errors: optional array of { description, error_code }

Errors that prevented step execution.

description: string

Human-readable error description.

error_code: optional number

Numeric error code identifying the class of error, if available.

formatuint32

minimum0

report_schema_version: "v1"

Version of the report schema.