客户端安全 API

您可以使用客户端安全 API（前身称为 Page Shield API）来启用和禁用客户端安全的资源监控、配置设置以及获取关于检测到的脚本和连接的信息。

要对 API 请求进行身份验证，您需要一个 API 令牌。有关所需的 API 令牌权限的更多信息，请参阅角色和权限。

端点 (Endpoints)

您可以通过将客户端安全 API 端点附加到 Cloudflare API 基础 URL 来获取完整的端点：

https://api.cloudflare.com/client/v4

{zone_id} 参数是区域 ID（十六进制字符串）。您可以在 Cloudflare 仪表板中找到此值，或者使用 Cloudflare API 的 /zones 端点。

{script_id} 参数是脚本 ID（十六进制字符串）。对于每个被检测到的脚本，该值都包含在列出客户端安全脚本操作的响应中。

{connection_id} 参数是连接 ID（十六进制字符串）。对于每个被检测到的连接，该值都包含在列出客户端安全连接 API 操作的响应中。

下表总结了可用的操作：

操作	方法 + URL 存根	注意
获取客户端安全设置	`GET zones/{zone_id}/page_shield`	获取客户端安全设置（包括状态）。
更新客户端安全设置	`PUT zones/{zone_id}/page_shield`	更新客户端安全设置。
列出客户端安全脚本	`GET zones/{zone_id}/page_shield/scripts`	获取检测到的脚本的列表。
获取客户端安全脚本	`GET zones/{zone_id}/page_shield/scripts/{script_id}`	获取脚本的详细信息。
列出客户端安全连接	`GET zones/{zone_id}/page_shield/connections`	获取检测到的连接的列表。
获取客户端安全连接	`GET zones/{zone_id}/page_shield/connections/{connection_id}`	获取连接的详细信息。
列出客户端安全 Cookie	`GET zones/{zone_id}/page_shield/cookies`	获取检测到的 Cookie 的列表。
获取客户端安全 Cookie	`GET zones/{zone_id}/page_shield/cookies/{cookie_id}`	获取 Cookie 的详细信息。
列出内容安全规则	`GET zones/{zone_id}/page_shield/policies`	获取所有配置的内容安全规则列表。
获取内容安全规则	`GET zones/{zone_id}/page_shield/policies/{policy_id}`	获取内容安全规则的详细信息。
创建内容安全规则	`POST zones/{zone_id}/page_shield/policies`	使用提供的配置创建内容安全规则。
更新内容安全规则	`PUT zones/{zone_id}/page_shield/policies/{policy_id}`	更新现有的内容安全规则。
删除内容安全规则	`DELETE zones/{zone_id}/page_shield/policies/{policy_id}`	删除现有的内容安全规则。

API 说明

恶意脚本分类（Malicious 或 Not malicious）无法在 API 中直接获取。要确定此分类，请将脚本的 js_integrity_score 值与当前设置为 10 的分类阈值进行比较。得分低于阈值的脚本被视为恶意脚本。

常见 API 调用

获取客户端安全设置

此示例获取 Cloudflare 客户端安全的当前设置，包括状态（启用/禁用）。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Get Page Shield settingsbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"enabled": true,
		"updated_at": "2023-05-14T11:47:55.677555Z",
		"use_cloudflare_reporting_endpoint": true,
		"use_connection_url_path": false
	},
	"success": true,
	"errors": [],
	"messages": []
}

启用客户端安全

此示例在指定的区域中启用 Cloudflare 的客户端安全。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield
Zone Settings Write

Update Page Shield settingsbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield" \
	--request PUT \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
	--json '{
		"enabled": true
	}'

{
	"result": {
		"enabled": true,
		"updated_at": "2023-05-14T11:50:41.756996Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}

获取检测到的脚本列表

此 GET 请求获取 Cloudflare 的客户端安全在主机名 example.net 上检测到的脚本列表，请求第一页，每页 15 个项目。URL 查询字符串包含筛选和分页参数。

默认情况下，当您未在 URL 查询字符串中指定 status 筛选参数时，响应将仅包含处于 active 状态的脚本。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

List Page Shield scriptsbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/scripts?hosts=example.net&page=1&per_page=15" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "8337233faec2357ff84465a919534e4d",
			"url": "https://malicious.example.com/badscript.js",
			"added_at": "2023-05-18T10:51:10.09615Z",
			"first_seen_at": "2023-05-18T10:51:08Z",
			"last_seen_at": "2023-05-22T09:57:54Z",
			"host": "example.net",
			"domain_reported_malicious": false,
			"url_reported_malicious": true,
			"malicious_url_categories": ["Malware"],
			"first_page_url": "http://malicious.example.com/page_one.html",
			"status": "active",
			"url_contains_cdn_cgi_path": false,
			"hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
			"js_integrity_score": 10,
			"obfuscation_score": 10,
			"dataflow_score": 8,
			"malware_score": 8,
			"cryptomining_score": 9,
			"magecart_score": 8,
			"fetched_at": "2023-05-21T16:58:07Z"
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 24,
		"total_pages": 2
	}
}

示例响应中显示的某些字段可能不可用，具体取决于您的 Cloudflare 计划。

有关可用筛选、分页和排序参数的详细信息，请参阅 API 参考。

获取报告频率较低的脚本列表

此 GET 请求获取主机名 example.net 上报告频率较低（infrequently reported）的脚本列表，请求第一页，每页 15 个项目。URL 查询字符串包含筛选和分页参数。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

List Page Shield scriptsbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/scripts?hosts=example.net&page=1&per_page=15&status=infrequent" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "83c8da2267394ce8465b74c299658fea",
			"url": "https://scripts.example.com/anotherbadscript.js",
			"added_at": "2023-05-17T13:16:03.419619Z",
			"first_seen_at": "2023-05-17T13:15:23Z",
			"last_seen_at": "2023-05-18T09:05:20Z",
			"host": "example.net",
			"domain_reported_malicious": false,
			"url_reported_malicious": false,
			"first_page_url": "http://malicious.example.com/page_one.html",
			"status": "infrequent",
			"url_contains_cdn_cgi_path": false,
			"hash": "9245aad577e846dd9b990b1b32425a3fae4aad8b8a28441a8b80084b6bb75a45",
			"js_integrity_score": 48,
			"obfuscation_score": 49,
			"dataflow_score": 45,
			"malware_score": 45,
			"cryptomining_score": 37,
			"magecart_score": 49,
			"fetched_at": "2023-05-18T03:58:07Z"
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 17,
		"total_pages": 2
	}
}

示例响应中显示的某些字段可能不可用，具体取决于您的 Cloudflare 计划。

有关可用筛选、分页和排序参数的详细信息，请参阅 API 参考。

获取被检测到脚本的详细信息

此 GET 请求获取由 Cloudflare 客户端安全检测到的脚本 ID 为 8337233faec2357ff84465a919534e4d 的脚本的详细信息。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Get a Page Shield scriptbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/scripts/8337233faec2357ff84465a919534e4d" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"id": "8337233faec2357ff84465a919534e4d",
		"url": "https://malicious.example.com/badscript.js",
		"added_at": "2023-05-18T10:51:10.09615Z",
		"first_seen_at": "2023-05-18T10:51:08Z",
		"last_seen_at": "2023-05-22T09:57:54Z",
		"host": "example.net",
		"domain_reported_malicious": false,
		"url_reported_malicious": true,
		"malicious_url_categories": ["Malware"],
		"first_page_url": "http://malicious.example.com/page_one.html",
		"status": "active",
		"url_contains_cdn_cgi_path": false,
		"hash": "9245aad577e846dd9b990b1b32425a3fae4aad8b8a28441a8b80084b6bb75a45",
		"js_integrity_score": 48,
		"obfuscation_score": 49,
		"dataflow_score": 45,
		"malware_score": 42,
		"cryptomining_score": 32,
		"magecart_score": 44,
		"fetched_at": "2023-05-21T16:58:07Z",
		"page_urls": [
			"http://malicious.example.com/page_two.html",
			"http://malicious.example.com/page_three.html",
			"http://malicious.example.com/page_four.html"
		],
		"versions": [
			{
				"hash": "9245aad577e846dd9b990b1b32425a3fae4aad8b8a28441a8b80084b6bb75a45",
				"js_integrity_score": 48,
				"obfuscation_score": 49,
				"dataflow_score": 45,
				"malware_score": 42,
				"cryptomining_score": 32,
				"magecart_score": 44,
				"fetched_at": "2023-05-21T16:58:07Z"
			}
		]
	},
	"success": true,
	"errors": [],
	"messages": []
}

示例响应中显示的某些字段可能不可用，具体取决于您的 Cloudflare 计划。

获取检测到的连接列表

此 GET 请求获取由 Cloudflare 客户端安全检测到的连接列表，请求第一页，每页 15 个项目。

默认情况下，当您未在 URL 查询字符串中指定 status 筛选参数时，响应将仅包含处于 active 状态的连接。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

List Page Shield connectionsbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/connections?page=1&per_page=15" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "0a7bb628776f4e50a50d8594c4a01740",
			"url": "https://malicious.example.com",
			"added_at": "2022-09-18T10:51:10.09615Z",
			"first_seen_at": "2022-09-18T10:51:08Z",
			"last_seen_at": "2022-09-02T09:57:54Z",
			"host": "example.net",
			"domain_reported_malicious": true,
			"malicious_domain_categories": ["Malware", "Spyware"],
			"url_reported_malicious": false,
			"malicious_url_categories": [],
			"first_page_url": "https://example.net/one.html",
			"status": "active",
			"url_contains_cdn_cgi_path": false
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 16,
		"total_pages": 2
	}
}

有关可用筛选、分页和排序参数的详细信息，请参阅 API 参考。

获取被检测到连接的详细信息

此 GET 请求获取由 Cloudflare 客户端安全检测到的连接 ID 为 0a7bb628776f4e50a50d8594c4a01740 的连接详细信息。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Get a Page Shield connectionbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/connections/0a7bb628776f4e50a50d8594c4a01740" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"id": "0a7bb628776f4e50a50d8594c4a01740",
		"url": "https://malicious.example.com",
		"added_at": "2022-09-18T10:51:10.09615Z",
		"first_seen_at": "2022-09-18T10:51:08Z",
		"last_seen_at": "2022-09-02T09:57:54Z",
		"host": "example.net",
		"domain_reported_malicious": true,
		"malicious_domain_categories": ["Malware", "Spyware"],
		"url_reported_malicious": false,
		"malicious_url_categories": [],
		"first_page_url": "https://example.net/one.html",
		"status": "active",
		"url_contains_cdn_cgi_path": false
	},
	"success": true,
	"errors": [],
	"messages": []
}

此 GET 请求获取由 Cloudflare 客户端安全检测到的 Cookie 列表，请求第一页，每页 15 个项目。

默认情况下，当您未在 URL 查询字符串中指定 status 筛选参数时，响应将仅包含处于 active 状态的 Cookie。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

List Page Shield Cookiesbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/cookies?page=1&per_page=15" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": [
		{
			"id": "beee03ada7e047e79f076785d8cd8b8e",
			"type": "first_party",
			"name": "PHPSESSID",
			"host": "example.net",
			"domain_attribute": "example.net",
			"expires_attribute": "2024-10-21T12:28:20Z",
			"http_only_attribute": true,
			"max_age_attribute": null,
			"path_attribute": "/store",
			"same_site_attribute": "strict",
			"secure_attribute": true,
			"first_seen_at": "2024-05-06T10:51:08Z",
			"last_seen_at": "2024-05-07T11:56:01Z",
			"first_page_url": "example.net/store/products",
			"page_urls": ["example.net/store/products/1"]
		}
		// (...)
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"page": 1,
		"per_page": 15,
		"count": 15,
		"total_count": 16,
		"total_pages": 2
	}
}

有关可用筛选、分页和排序参数的详细信息，请参阅发起 API 调用。

此 GET 请求获取由 Cloudflare 客户端安全检测到的 ID 为 beee03ada7e047e79f076785d8cd8b8e 的 Cookie 详细信息。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield Read
Domain Page Shield
Page Shield Read
Zone Settings Write
Zone Settings Read

Get a Page Shield cookiebash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/cookies/beee03ada7e047e79f076785d8cd8b8e" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"id": "beee03ada7e047e79f076785d8cd8b8e",
		"type": "first_party",
		"name": "PHPSESSID",
		"host": "example.net",
		"domain_attribute": "example.net",
		"expires_attribute": "2024-10-21T12:28:20Z",
		"http_only_attribute": true,
		"max_age_attribute": null,
		"path_attribute": "/store",
		"same_site_attribute": "strict",
		"secure_attribute": true,
		"first_seen_at": "2024-05-06T10:51:08Z",
		"last_seen_at": "2024-05-07T11:56:01Z",
		"first_page_url": "example.net/store/products",
		"page_urls": ["example.net/store/products/1"]
	},
	"success": true,
	"errors": [],
	"messages": []
}

创建内容安全规则

此 POST 请求使用 Log 操作创建一条内容安全规则（以前称为策略），该规则根据以下脚本的托管位置来定义允许的脚本：

托管在 myapp.example.com 上的脚本（不包括 example.com 上的脚本）。
托管在 cdnjs.cloudflare.com 上的脚本。
使用其完整 URL 的 Google Analytics 脚本。
同一源（具有相同的 HTTP 或 HTTPS 协议以及主机名）上的所有脚本。

所有其他脚本都将触发规则违规行为，但这些脚本不会被阻止。

有关内容安全策略 (CSP)指令和值的更多信息，请参阅 MDN 文档 ↗。

Required API token permissions

At least one of the following token permissions is required:

Page Shield
Domain Page Shield
Zone Settings Write

Create a Page Shield policybash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/page_shield/policies" \
	--request POST \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
	--json '{
		"description": "My first content security rule in log mode",
		"action": "log",
		"expression": "http.host eq \"myapp.example.com\"",
		"enabled": "true",
		"value": "script-src myapp.example.com cdnjs.cloudflare.com https://www.google-analytics.com/analytics.js '\''self'\''"
	}'

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"id": "<RULE_ID>",
		"description": "My first content security rule in log mode",
		"action": "log",
		"expression": "http.host eq \"myapp.example.com\"",
		"enabled": "true",
		"value": "script-src myapp.example.com cdnjs.cloudflare.com https://www.google-analytics.com/analytics.js 'self'"
	}
}

要创建具有 Allow 操作而不是 Log 的内容安全规则，请在请求体中使用 "action": "allow"。如果实施了此类规则，所有未被该规则允许的脚本都将被阻止。

客户端安全 API

端点 (Endpoints)

API 说明

常见 API 调用

获取客户端安全设置

启用客户端安全

获取检测到的脚本列表

获取报告频率较低的脚本列表

获取被检测到脚本的详细信息

获取检测到的连接列表

获取被检测到连接的详细信息

获取检测到的 Cookie 列表

获取被检测到 Cookie 的详细信息

创建内容安全规则