API Reference

Vulnerability Scanner

Scans

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create Scan

client.vulnerabilityScanner.scans.create(ScanCreateParams { account_id, credential_sets, open_api, 2 more } params, RequestOptionsoptions?): ScanCreateResponse { id, scan_type, status, 2 more }

POST/accounts/{account_id}/vuln_scanner/scans

Creates and starts a new vulnerability scan. The response may include non-fatal warnings in the messages array.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

ParametersExpand Collapse

params: ScanCreateParams { account_id, credential_sets, open_api, 2 more }

account_id?: string

Path param: Identifier.

maxLength32

credential_sets: CredentialSets

Body param: Credential set references for a BOLA scan. The scanner uses the owner credentials for legitimate requests and the attacker credentials to attempt unauthorized access.

attacker: string

Credential set ID for the attacker.

formatuuid

owner: string

Credential set ID for the resource owner.

formatuuid

open_api: string

Body param: OpenAPI schema definition for the API under test. The scanner uses this to discover endpoints and construct requests.

scan_type: "bola"

Body param

target_environment_id: string

Body param: The target environment to scan.

formatuuid

ReturnsExpand Collapse

ScanCreateResponse { id, scan_type, status, 2 more }

id: string

Scan identifier.

formatuuid

scan_type: "bola"

The type of vulnerability scan.

status: "created" | "scheduled" | "planning" | 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?: Report | null

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

report: Report { summary, tests }

Version 1 of the BOLA vulnerability scan report.

summary: Summary { verdict }

Summary of all steps and findings.

verdict: "ok" | "warning" | "inconclusive"

Overall verdict of the vulnerability scan.

One of the following:

"ok"

"warning"

"inconclusive"

tests: Array<Test>

List of tests that were run.

steps: Array<Step>

Steps that were executed.

assertions: Array<Assertion>

Assertions that were made against the received response.

description: string

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

kind: Kind { parameters, type }

Kind of assertion.

parameters: 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 | null

Observed value on which the assertion was made.

outcome: "ok" | "fail" | "inconclusive"

Outcome of the assertion.

One of the following:

"ok"

"fail"

"inconclusive"

errors?: Array<Error>

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

description: string

Human-readable error description.

error_code?: number | null

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

formatuint32

minimum0

request?: Request | null

HTTP request that was made, if any.

credential_set: CredentialSet { id, role }

Credential set that was used.

id: string

ID of the credential set.

formatuuid

role: "owner" | "attacker"

Role of the credential set.

One of the following:

"owner"

"attacker"

header_names: Array<string>

Names of headers that were sent.

method: "GET" | "DELETE" | "PATCH" | 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<VariableCapture>

Variable captures requested for this step.

json_path: string

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

name: string

Variable name, e.g. "resource_id".

body?: unknown

Request body, if any.

response?: Response | null

HTTP response that was received, if any.

body: Kind { kind } | UnionMember1 { contents, kind, truncated } | UnionMember2 { contents, kind, truncated } | UnionMember3 { contents, kind, truncated }

HTTP response body.

One of the following:

Kind { kind }

No body was received.

kind: "not_found"

UnionMember1 { contents, kind, truncated }

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

contents: string

kind: "bytes"

truncated: boolean

UnionMember2 { contents, kind, truncated }

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

contents: string

kind: "text"

truncated: boolean

UnionMember3 { contents, kind, truncated }

Body received as valid JSON.

contents: string

kind: "json"

truncated: boolean

header_names: Array<string>

Names of headers that were received.

status: number

HTTP status code.

maximum65535

minimum0

status_text?: string | null

HTTP status text, if available for the status code.

verdict: "ok" | "warning" | "inconclusive"

Verdict of this single test.

One of the following:

"ok"

"warning"

"inconclusive"

preflight_errors?: Array<PreflightError>

Errors that prevented step execution.

description: string

Human-readable error description.

error_code?: number | null

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

formatuint32

minimum0

report_schema_version: "v1"

Version of the report schema.

Create Scan

TypeScript

HTTP

TypeScript

Python

Go

Terraform

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

const scan = await client.vulnerabilityScanner.scans.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  credential_sets: {
    attacker: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
    owner: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  },
  open_api: 'open_api',
  scan_type: 'bola',
  target_environment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});

console.log(scan.id);

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "scan_type": "bola",
    "status": "created",
    "target_environment_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "report": {
      "report": {
        "summary": {
          "verdict": "ok"
        },
        "tests": [
          {
            "steps": [
              {
                "assertions": [
                  {
                    "description": "description",
                    "kind": {
                      "parameters": {
                        "max": 0,
                        "min": 0
                      },
                      "type": "http_status_within_range"
                    },
                    "observed": 0,
                    "outcome": "ok"
                  }
                ],
                "errors": [
                  {
                    "description": "description",
                    "error_code": 0
                  }
                ],
                "request": {
                  "credential_set": {
                    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
                    "role": "owner"
                  },
                  "header_names": [
                    "string"
                  ],
                  "method": "GET",
                  "url": "https://example.com",
                  "variable_captures": [
                    {
                      "json_path": "json_path",
                      "name": "name"
                    }
                  ],
                  "body": {}
                },
                "response": {
                  "body": {
                    "kind": "not_found"
                  },
                  "header_names": [
                    "string"
                  ],
                  "status": 0,
                  "status_text": "status_text"
                }
              }
            ],
            "verdict": "ok",
            "preflight_errors": [
              {
                "description": "description",
                "error_code": 0
              }
            ]
          }
        ]
      },
      "report_schema_version": "v1"
    }
  },
  "result_info": {}
}

Returns Examples

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "scan_type": "bola",
    "status": "created",
    "target_environment_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "report": {
      "report": {
        "summary": {
          "verdict": "ok"
        },
        "tests": [
          {
            "steps": [
              {
                "assertions": [
                  {
                    "description": "description",
                    "kind": {
                      "parameters": {
                        "max": 0,
                        "min": 0
                      },
                      "type": "http_status_within_range"
                    },
                    "observed": 0,
                    "outcome": "ok"
                  }
                ],
                "errors": [
                  {
                    "description": "description",
                    "error_code": 0
                  }
                ],
                "request": {
                  "credential_set": {
                    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
                    "role": "owner"
                  },
                  "header_names": [
                    "string"
                  ],
                  "method": "GET",
                  "url": "https://example.com",
                  "variable_captures": [
                    {
                      "json_path": "json_path",
                      "name": "name"
                    }
                  ],
                  "body": {}
                },
                "response": {
                  "body": {
                    "kind": "not_found"
                  },
                  "header_names": [
                    "string"
                  ],
                  "status": 0,
                  "status_text": "status_text"
                }
              }
            ],
            "verdict": "ok",
            "preflight_errors": [
              {
                "description": "description",
                "error_code": 0
              }
            ]
          }
        ]
      },
      "report_schema_version": "v1"
    }
  },
  "result_info": {}
}