API Reference

Vulnerability Scanner

Scans

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Scans

vulnerability_scanner.scans.list(ScanListParams**kwargs) -> SyncV4PagePaginationArray[ScanListResponse]

GET/accounts/{account_id}/vuln_scanner/scans

Returns all scans for the account.

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

account_id: Optional[str]

Identifier.

maxLength32

page: Optional[int]

Page number of paginated results.

minimum1

per_page: Optional[int]

Number of results per page.

maximum50

minimum5

ReturnsExpand Collapse

class ScanListResponse: …

id: str

Scan identifier.

formatuuid

scan_type: Literal["bola"]

The type of vulnerability scan.

status: Literal["created", "scheduled", "planning", 3 more]

Current lifecycle status of the scan.

One of the following:

"created"

"scheduled"

"planning"

"running"

"finished"

"failed"

target_environment_id: str

The target environment this scan runs against.

formatuuid

report: Optional[Report]

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

report: ReportReport

Version 1 of the BOLA vulnerability scan report.

summary: ReportReportSummary

Summary of all steps and findings.

verdict: Literal["ok", "warning", "inconclusive"]

Overall verdict of the vulnerability scan.

One of the following:

"ok"

"warning"

"inconclusive"

tests: List[ReportReportTest]

List of tests that were run.

steps: List[ReportReportTestStep]

Steps that were executed.

assertions: List[ReportReportTestStepAssertion]

Assertions that were made against the received response.

description: str

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

kind: ReportReportTestStepAssertionKind

Kind of assertion.

parameters: ReportReportTestStepAssertionKindParameters

Range of HTTP status codes.

max: int

Maximum (inclusive) status code of the range.

maximum65535

minimum0

min: int

Minimum (inclusive) status code of the range.

maximum65535

minimum0

type: Literal["http_status_within_range"]

observed: Optional[int]

Observed value on which the assertion was made.

outcome: Literal["ok", "fail", "inconclusive"]

Outcome of the assertion.

One of the following:

"ok"

"fail"

"inconclusive"

errors: Optional[List[ReportReportTestStepError]]

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

description: str

Human-readable error description.

error_code: Optional[int]

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

formatuint32

minimum0

request: Optional[ReportReportTestStepRequest]

HTTP request that was made, if any.

credential_set: ReportReportTestStepRequestCredentialSet

Credential set that was used.

id: str

ID of the credential set.

formatuuid

role: Literal["owner", "attacker"]

Role of the credential set.

One of the following:

"owner"

"attacker"

header_names: List[str]

Names of headers that were sent.

method: Literal["GET", "DELETE", "PATCH", 2 more]

HTTP method.

One of the following:

"GET"

"DELETE"

"PATCH"

"POST"

"PUT"

url: str

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

formaturi

variable_captures: List[ReportReportTestStepRequestVariableCapture]

Variable captures requested for this step.

json_path: str

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

name: str

Variable name, e.g. "resource_id".

body: Optional[object]

Request body, if any.

response: Optional[ReportReportTestStepResponse]

HTTP response that was received, if any.

body: ReportReportTestStepResponseBody

HTTP response body.

One of the following:

class ReportReportTestStepResponseBodyKind: …

No body was received.

kind: Literal["not_found"]

class ReportReportTestStepResponseBodyUnionMember1: …

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

contents: str

kind: Literal["bytes"]

truncated: bool

class ReportReportTestStepResponseBodyUnionMember2: …

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

contents: str

kind: Literal["text"]

truncated: bool

class ReportReportTestStepResponseBodyUnionMember3: …

Body received as valid JSON.

contents: str

kind: Literal["json"]

truncated: bool

header_names: List[str]

Names of headers that were received.

status: int

HTTP status code.

maximum65535

minimum0

status_text: Optional[str]

HTTP status text, if available for the status code.

verdict: Literal["ok", "warning", "inconclusive"]

Verdict of this single test.

One of the following:

"ok"

"warning"

"inconclusive"

preflight_errors: Optional[List[ReportReportTestPreflightError]]

Errors that prevented step execution.

description: str

Human-readable error description.

error_code: Optional[int]

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

formatuint32

minimum0

report_schema_version: Literal["v1"]

Version of the report schema.

List Scans

Python

HTTP

TypeScript

Python

Go

Terraform

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.vulnerability_scanner.scans.list(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
page = page.result[0]
print(page.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": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000,
    "total_pages": 100
  }
}

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": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000,
    "total_pages": 100
  }
}