跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

通过 API 配置漏洞扫描器

最后更新 查看 MarkdownAgent 设置

使用 Cloudflare 漏洞扫描器 (Vulnerability Scanner) 测试您的 API 端点是否存在漏洞,例如对象级别授权失效 (BOLA)。本指南介绍如何使用 Cloudflare API 运行您的第一次漏洞扫描。

前提条件

您必须拥有:

  • 账户中至少有一个区域 (zone)。
  • 描述您要扫描的 API 的 OpenAPI 架构。
  • 目标 API 凭据。扫描器需要以不同用户的身份进行身份验证,以测试 BOLA 漏洞。

过程

创建 API 令牌

所有 API 请求都使用基准 URL https://api.cloudflare.com/client/v4/,并在 Authorization 标头中通过 Bearer 令牌进行身份验证。

在 Cloudflare 仪表板中创建 API 令牌,并在目标账户的范围内指定以下权限:Account(账户) > API Gateway > Edit(编辑)

在 Cloudflare 仪表板中从您账户的 Overview(概述) 页面保存您的 API 令牌和账户 ID (Account Tag),并将其导出为环境变量,以便在以下命令中使用。

export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"

创建目标环境

目标环境定义了扫描器应该扫描的内容。目前,唯一支持的目标类型是区域 (zone)。

在 Cloudflare 仪表板中的区域 Overview(概述) 页面上找到您的区域 ID (Zone Tag) 并将其导出。

export ZONE_TAG="<YOUR_ZONE_TAG>"

使用以下 POST 请求创建目标环境。

cURL commandbash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/target_environments" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Production API",
    "description": "Main production zone for API scanning",
    "target": {
      "type": "zone",
      "zone_tag": "'"${ZONE_TAG}"'"
    }
  }'

从响应中将目标环境 ID 保存到变量 TARGET_ENV_ID 中。

(可选)您可以通过向以下 URL 发送 GET 请求来验证您的目标环境。

https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/target_environments/${TARGET_ENV_ID}

创建凭证集

目前,扫描器支持 BOLA 扫描。这需要两组凭证:

  • 所有者 (Owner):拥有被测试资源的合法用户。
  • 攻击者 (Attacker):不应有权访问所有者资源的其他合法用户。

扫描器分别以这两个用户的身份进行身份验证,并检查攻击者是否可以访问所有者的资源。每组凭据组织成一个包含一个或多个凭据的凭证集 (credential set)。

使用以下 POST 请求创建一个所有者凭证集和一个攻击者凭证集。

Owner credential setbash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Owner Credentials" }'

# Export the ID from the response
export OWNER_CRED_SET_ID="<OWNER_CRED_SET_ID>"
Attacker credential setbash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Attacker Credentials" }'

# Export the ID from the response
export ATTACKER_CRED_SET_ID="<ATTACKER_CRED_SET_ID>"

向每个凭据集添加凭据

凭据描述了扫描器附加到其请求中的单个身份验证令牌或会话值。

使用以下 POST 请求向每个集合中添加所有者和攻击者的凭据。

Owner's credential (Header)bash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets/${OWNER_CRED_SET_ID}/credentials" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Owner Bearer Token",
    "location": "header",
    "location_name": "authorization",
    "value": "Bearer eyJhbGciOiJSUzI1NiIs...owner-token"
  }'
Attacker's credential (Cookie)bash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets/${ATTACKER_CRED_SET_ID}/credentials" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Attacker Session Cookie",
    "location": "cookie",
    "location_name": "session_id",
    "value": "attacker-session-token-value"
  }'

(可选)您可以使用向以下 URL 发送 GET 请求来列出集合中的所有凭据。

https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/credential_sets/<CRED_SET_ID>/credentials

开始扫描

准备好您的目标环境和两个凭据集后,您就可以开始 BOLA 扫描。

确保您的 OpenAPI 架构已格式化为字符串。例如,使用 jq。

OPEN_API_SCHEMA=$(jq -c . < openapi.json)

使用以下 POST 请求发起扫描。

cURL commandbash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data "$(jq -n \
    --arg te_id "$TARGET_ENV_ID" \
    --arg schema "$OPEN_API_SCHEMA" \
    --arg owner "$OWNER_CRED_SET_ID" \
    --arg attacker "$ATTACKER_CRED_SET_ID" \
    '{
      target_environment_id: $te_id,
      scan_type: "bola",
      open_api: $schema,
      credential_sets: { owner: $owner, attacker: $attacker }
    }')"

从响应中保存扫描 ID。

export SCAN_ID="<SCAN_ID>"

您可以使用 GET 请求检查扫描的状态。

cURL commandbash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"

获取扫描报告

一旦扫描状态变为 completed,报告就可用,其中包含所测试漏洞的详细发现。

cURL commandbash
curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"

您可能会发现使用 jq 汇总报告结果更容易。

curl "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" | jq '
    .result.report.report.tests[] |
    {
      test_verdict: .verdict,
      steps: [
        .steps
        | to_entries[]
        | {
            step: (.key + 1),
            method: .value.request.method,
            url: .value.request.url,
            role: .value.request.credential_set.role,
            response_status: .value.response.status,
            assertions: [
              .value.assertions[]
              | {
                  description: .description,
                  expected_status_min: .kind.parameters.min,
                  expected_status_max: .kind.parameters.max,
                  observed_status: .observed,
                  outcome: .outcome
                }
            ],
            errors: (.value.errors // [])
          }
      ]
    }
  '

添加 jq 命令可以汇总每个响应及其断言。在下面示例的第 3 步,扫描器记录攻击者的 DELETE 请求已完成,并收到 204 响应。预期返回 4xx 响应的断言失败,因此得出 warning 判定。

{
	"test_verdict": "warning",
	"steps": [
		{
			"step": 1,
			"method": "POST",
			"url": "https://api.example.com/v1/orders",
			"role": "owner",
			"response_status": 201,
			"assertions": [
				{
					"description": "Owner must successfully create resource.",
					"expected_status_min": 200,
					"expected_status_max": 299,
					"observed_status": 201,
					"outcome": "ok"
				}
			],
			"errors": []
		},
		{
			"step": 2,
			"method": "GET",
			"url": "https://api.example.com/v1/orders",
			"role": "attacker",
			"response_status": 403,
			"assertions": [
				{
					"description": "Attacker should not be able to retrieve resource.",
					"expected_status_min": 400,
					"expected_status_max": 499,
					"observed_status": 403,
					"outcome": "ok"
				}
			],
			"errors": []
		},
		{
			"step": 3,
			"method": "DELETE",
			"url": "https://api.example.com/v1/orders/bdc64e8a-deec-4374-92c0-4fe91d1650bb",
			"role": "attacker",
			"response_status": 204,
			"assertions": [
				{
					"description": "Attacker should not be able to delete resource.",
					"expected_status_min": 400,
					"expected_status_max": 499,
					"observed_status": 204,
					"outcome": "fail"
				}
			],
			"errors": []
		}
	]
}

轮询模式示例

一种常见的模式是轮询扫描状态直至其完成,然后获取报告。

Examplebash
while true; do
  STATUS=$(curl --silent \
    "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}" \
    --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" | jq -r '.result.status // empty')

  echo "Scan status: ${STATUS:-unknown}"

  case "$STATUS" in
    completed) echo "Scan finished. Fetching report..."; break ;;
    failed)    echo "Scan failed." >&2; exit 1 ;;
    *)         sleep 10 ;;
  esac
done

curl --silent \
"https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/vuln_scanner/scans/${SCAN_ID}/report" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" | jq .

限制

在公开 Beta 期间,你可以按用例将大型 OpenAPI 架构拆分为较小的文件。例如,如果应用程序支持修改账户、社交分享和收藏,可以为每个用例分别创建 OpenAPI 文件。


可用性

漏洞扫描器目前仅适用于订阅了 API Shield 的企业版客户。Cloudflare 将在未来添加更多扫描类型,并届时增加扫描器的可用性。


参考

凭据位置

创建凭据时,location 字段确定扫描器在请求期间将凭据附加在何处。

位置 location_name 示例用例
请求头 HTTP 标头名称 带有 Bearer 令牌的 Authorization 标头。
Cookie Cookie 名称 带有会话令牌的 session_id cookie。

一个凭据集可以包含多个凭据。例如,如果一个 API 既要求在 Authorization 标头中传递 Bearer 令牌,又要求在 X-CSRF-Token 标头中传递 CSRF 令牌,则在其集合中将配置两个单独的凭据。

这篇文档对您有帮助吗?