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.New(ctx, params) (*ScanNewResponse, error)

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 ScanNewParams

AccountID param.Field[string]Optional

Path param: Identifier.

maxLength32

CredentialSets param.Field[ScanNewParamsCredentialSets]

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

OpenAPI param.Field[string]

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

ScanType param.Field[ScanNewParamsScanType]

Body param

const ScanNewParamsScanTypeBOLA ScanNewParamsScanType = "bola"

TargetEnvironmentID param.Field[string]

Body param: The target environment to scan.

formatuuid

ReturnsExpand Collapse

type ScanNewResponse struct{…}

ID string

Scan identifier.

formatuuid

ScanType ScanNewResponseScanType

The type of vulnerability scan.

Status ScanNewResponseStatus

Current lifecycle status of the scan.

One of the following:

const ScanNewResponseStatusCreated ScanNewResponseStatus = "created"

const ScanNewResponseStatusScheduled ScanNewResponseStatus = "scheduled"

const ScanNewResponseStatusPlanning ScanNewResponseStatus = "planning"

const ScanNewResponseStatusRunning ScanNewResponseStatus = "running"

const ScanNewResponseStatusFinished ScanNewResponseStatus = "finished"

const ScanNewResponseStatusFailed ScanNewResponseStatus = "failed"

TargetEnvironmentID string

The target environment this scan runs against.

formatuuid

Report ScanNewResponseReportOptional

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

Report ScanNewResponseReportReport

Version 1 of the BOLA vulnerability scan report.

Summary ScanNewResponseReportReportSummary

Summary of all steps and findings.

Verdict ScanNewResponseReportReportSummaryVerdict

Overall verdict of the vulnerability scan.

One of the following:

const ScanNewResponseReportReportSummaryVerdictOk ScanNewResponseReportReportSummaryVerdict = "ok"

const ScanNewResponseReportReportSummaryVerdictWarning ScanNewResponseReportReportSummaryVerdict = "warning"

const ScanNewResponseReportReportSummaryVerdictInconclusive ScanNewResponseReportReportSummaryVerdict = "inconclusive"

Tests []ScanNewResponseReportReportTest

List of tests that were run.

Steps []ScanNewResponseReportReportTestsStep

Steps that were executed.

Assertions []ScanNewResponseReportReportTestsStepsAssertion

Assertions that were made against the received response.

Description string

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

Kind ScanNewResponseReportReportTestsStepsAssertionsKind

Kind of assertion.

Parameters ScanNewResponseReportReportTestsStepsAssertionsKindParameters

Range of HTTP status codes.

Max int64

Maximum (inclusive) status code of the range.

maximum65535

minimum0

Min int64

Minimum (inclusive) status code of the range.

maximum65535

minimum0

Type ScanNewResponseReportReportTestsStepsAssertionsKindType

Observed int64

Observed value on which the assertion was made.

Outcome ScanNewResponseReportReportTestsStepsAssertionsOutcome

Outcome of the assertion.

One of the following:

const ScanNewResponseReportReportTestsStepsAssertionsOutcomeOk ScanNewResponseReportReportTestsStepsAssertionsOutcome = "ok"

const ScanNewResponseReportReportTestsStepsAssertionsOutcomeFail ScanNewResponseReportReportTestsStepsAssertionsOutcome = "fail"

const ScanNewResponseReportReportTestsStepsAssertionsOutcomeInconclusive ScanNewResponseReportReportTestsStepsAssertionsOutcome = "inconclusive"

Errors []ScanNewResponseReportReportTestsStepsErrorOptional

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

Description string

Human-readable error description.

ErrorCode int64Optional

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

formatuint32

minimum0

Request ScanNewResponseReportReportTestsStepsRequestOptional

HTTP request that was made, if any.

CredentialSet ScanNewResponseReportReportTestsStepsRequestCredentialSet

Credential set that was used.

ID string

ID of the credential set.

formatuuid

Role ScanNewResponseReportReportTestsStepsRequestCredentialSetRole

Role of the credential set.

One of the following:

const ScanNewResponseReportReportTestsStepsRequestCredentialSetRoleOwner ScanNewResponseReportReportTestsStepsRequestCredentialSetRole = "owner"

const ScanNewResponseReportReportTestsStepsRequestCredentialSetRoleAttacker ScanNewResponseReportReportTestsStepsRequestCredentialSetRole = "attacker"

HeaderNames []string

Names of headers that were sent.

Method ScanNewResponseReportReportTestsStepsRequestMethod

HTTP method.

One of the following:

const ScanNewResponseReportReportTestsStepsRequestMethodGet ScanNewResponseReportReportTestsStepsRequestMethod = "GET"

const ScanNewResponseReportReportTestsStepsRequestMethodDelete ScanNewResponseReportReportTestsStepsRequestMethod = "DELETE"

const ScanNewResponseReportReportTestsStepsRequestMethodPatch ScanNewResponseReportReportTestsStepsRequestMethod = "PATCH"

const ScanNewResponseReportReportTestsStepsRequestMethodPost ScanNewResponseReportReportTestsStepsRequestMethod = "POST"

const ScanNewResponseReportReportTestsStepsRequestMethodPut ScanNewResponseReportReportTestsStepsRequestMethod = "PUT"

URL string

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

formaturi

VariableCaptures []ScanNewResponseReportReportTestsStepsRequestVariableCapture

Variable captures requested for this step.

JsonPath string

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

Name string

Variable name, e.g. "resource_id".

Body unknownOptional

Request body, if any.

Response ScanNewResponseReportReportTestsStepsResponseOptional

HTTP response that was received, if any.

Body ScanNewResponseReportReportTestsStepsResponseBody

HTTP response body.

One of the following:

type ScanNewResponseReportReportTestsStepsResponseBodyKind struct{…}

No body was received.

Kind ScanNewResponseReportReportTestsStepsResponseBodyKindKind

type ScanNewResponseReportReportTestsStepsResponseBodyObject struct{…}

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

Contents string

Kind ScanNewResponseReportReportTestsStepsResponseBodyObjectKind

Truncated bool

type ScanNewResponseReportReportTestsStepsResponseBodyObject struct{…}

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

Contents string

Kind ScanNewResponseReportReportTestsStepsResponseBodyObjectKind

Truncated bool

type ScanNewResponseReportReportTestsStepsResponseBodyObject struct{…}

Body received as valid JSON.

Contents string

Kind ScanNewResponseReportReportTestsStepsResponseBodyObjectKind

Truncated bool

HeaderNames []string

Names of headers that were received.

Status int64

HTTP status code.

maximum65535

minimum0

StatusText stringOptional

HTTP status text, if available for the status code.

Verdict ScanNewResponseReportReportTestsVerdict

Verdict of this single test.

One of the following:

const ScanNewResponseReportReportTestsVerdictOk ScanNewResponseReportReportTestsVerdict = "ok"

const ScanNewResponseReportReportTestsVerdictWarning ScanNewResponseReportReportTestsVerdict = "warning"

const ScanNewResponseReportReportTestsVerdictInconclusive ScanNewResponseReportReportTestsVerdict = "inconclusive"

PreflightErrors []ScanNewResponseReportReportTestsPreflightErrorOptional

Errors that prevented step execution.

Description string

Human-readable error description.

ErrorCode int64Optional

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

formatuint32

minimum0

ReportSchemaVersion ScanNewResponseReportReportSchemaVersion

Version of the report schema.

Create Scan

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/option"
  "github.com/cloudflare/cloudflare-go/vulnerability_scanner"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  scan, err := client.VulnerabilityScanner.Scans.New(context.TODO(), vulnerability_scanner.ScanNewParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    CredentialSets: cloudflare.F(vulnerability_scanner.ScanNewParamsCredentialSets{
      Attacker: cloudflare.F("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"),
      Owner: cloudflare.F("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"),
    }),
    OpenAPI: cloudflare.F("open_api"),
    ScanType: cloudflare.F(vulnerability_scanner.ScanNewParamsScanTypeBOLA),
    TargetEnvironmentID: cloudflare.F("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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": {}
}