接口详情
GET /v1/security-policies
列出 WAF 规则库、CC 与访问控制策略
- operationId
listSecurityPolicies- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
说明
需要 security_policies.read 权限。租户身份只看到当前作用域内的策略，响应里没有 owner 信息； owner 参数只对平台身份生效，可跨租户筛选。
说明（契约原文）
Requires security_policies.read. Tenant identities see only their active scope and never receive owner metadata; platform identities may filter across tenant owners.
参数
listSecurityPolicies 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | 页码，从 1 开始 |
|---|
limit | query | integer | 否 | 每页条数，1–100 |
|---|
kind | query | string: waf / cc / acl | 否 | 策略类型；不传表示全部类型 |
|---|
status | query | string: enabled / disabled | 否 | 按启用状态筛选 |
|---|
name | query | string | 否 | 按名称筛选 |
|---|
id | query | string(uuid) | 否 | 按策略 UUID 精确筛选 |
|---|
owner | query | string | 否 | 只对平台身份生效：按所属用户的名称、用户名或 UUID 筛选 |
|---|
scope | query | string: global / site / system | 否 | 只用于 WAF 规则库，必须同时传 kind=waf，否则返回 400。system：订阅的平台规则库副本； site：已绑定到站点的自有规则库；global：没有绑定任何站点的自有规则库。总数与统计按该筛选计算。 |
|---|
响应
listSecurityPolicies 响应| 状态码 | 说明 |
|---|
200 | 按创建时间从新到旧的稳定分页结果。 字段：items: array<SecurityPolicy> total: integer(int64) page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/security-policies
创建带版本的 WAF 规则库、CC 或访问控制策略
- operationId
createSecurityPolicy- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明
需要 security_policies.manage 权限。平台身份必须提供有效租户的 target_scope_id 与 owner_id；租户身份固定为当前作用域和身份。 规则 ID 由服务端生成，同一幂等请求重放返回原 ID。创建只保存配置，不代表已发布到节点或已生效。
说明（契约原文）
Requires security_policies.manage. Platform identities must provide an active tenant target_scope_id and owner_id; tenant identities are fixed to their current scope and identity. Rule IDs are server-generated and identical idempotent replay returns the original IDs. This control-plane slice does not claim edge publication or enforcement.
参数
createSecurityPolicy 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createSecurityPolicy 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
kind | string: waf / cc / acl | 是 | waf 为 WAF 规则库，cc 为 CC 防护，acl 为访问控制。 |
|---|
name | string | 是 | — |
|---|
description | string | 是 | — |
|---|
enabled | boolean | 是 | — |
|---|
default_action | string: allow / block | 是 | — |
|---|
rules | array<SecurityPolicyRuleInput> | 是 | — |
|---|
cc_settings | SecurityPolicyCCSettings | 否 | CC only. Site-level ban/pass durations (override every rule's) and the auto switch (自动切换). Omitted keeps the rules' own values. |
|---|
waf_settings | SecurityPolicyWAFSettings | 否 | WAF only (node CAPABILITY_NAME_WAF v2). Omitted (or defend mode without auto_block) is stored as absent. |
|---|
target_scope_id | string(uuid) | 否 | — |
|---|
owner_id | string(uuid) | 否 | — |
|---|
响应
createSecurityPolicy 响应| 状态码 | 说明 |
|---|
201 | 已创建策略及其不可变的第 1 版快照，或重放了相同请求。 字段：kind: string: waf / cc / acl name: string description: string enabled: boolean default_action: string: allow / block rules: array<SecurityPolicyRuleInput> cc_settings?: SecurityPolicyCCSettings waf_settings?: SecurityPolicyWAFSettings id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null version: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/security-policies/batch
逐项启用、停用或删除选中的 WAF 规则库
- operationId
batchSecurityPolicies- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明
需要 security_policies.manage 权限。每一项单独按版本号校验后写入，幂等键按 Idempotency-Key 逐项派生，重试同一批次会重放已写入的项。 结果按请求顺序逐项返回；版本冲突、系统规则库、不存在、使用中等拒绝都作为该项结果，不中断整批。存储失败时该项为 error，其余为 not_attempted。 平台（系统）规则库永远不会被修改。
说明（契约原文）
Requires security_policies.manage. Each item is written on its own with a version check (CAS) under an item key derived from Idempotency-Key, so retrying the same batch replays written items. Results come back in request order, one per item; refusals (version conflict, system library, not found, in use, ...) are item results and do not stop the batch. A store failure marks that item error and the rest not_attempted. System (platform) libraries are never modified.
参数
batchSecurityPolicies 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
batchSecurityPolicies 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
action | string: enable / disable / delete | 是 | — |
|---|
items | array<object> | 是 | — |
|---|
响应
batchSecurityPolicies 响应| 状态码 | 说明 |
|---|
200 | 每项一个结果，按请求顺序。 字段：items: array<object> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/security-policies/filters
列出 CC 过滤器
- operationId
listSecurityPolicyFilters- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
说明
需要 security_policies.read 权限。过滤器资源上线前的数据由现有 CC 规则动作投影得到；之后新建的是独立的带版本资源。租户身份只看到当前作用域，响应里没有 owner 信息。
说明（契约原文）
Requires security_policies.read. Rows created before the filter resource was introduced are materialized from real CC rule actions; newly created rows are independent versioned resources. Tenant identities see only their active scope and never receive owner metadata.
参数
listSecurityPolicyFilters 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
status | query | string: enabled / disabled | 否 | — |
|---|
type | query | string | 否 | — |
|---|
name | query | string | 否 | — |
|---|
id | query | string(uuid) | 否 | — |
|---|
owner | query | string | 否 | Platform-only owner filter. |
|---|
响应
listSecurityPolicyFilters 响应| 状态码 | 说明 |
|---|
200 | 过滤器列表。 字段：items: array<SecurityPolicyReference> total: integer page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/security-policies/filters
创建带版本的 CC 过滤器
- operationId
createSecurityPolicyFilter- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明
需要 security_policies.manage 权限。平台身份必须提供 target_scope_id 与 owner_id；租户身份固定为当前作用域。
说明（契约原文）
Requires security_policies.manage. Platform identities must provide target_scope_id and owner_id; tenant identities are fixed to their current scope.
参数
createSecurityPolicyFilter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createSecurityPolicyFilter 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
description | string | 是 | — |
|---|
enabled | boolean | 是 | — |
|---|
type | string | 是 | — |
|---|
parameters | object | 是 | — |
|---|
target_scope_id | string(uuid) | 否 | — |
|---|
owner_id | string(uuid) | 否 | — |
|---|
响应
createSecurityPolicyFilter 响应| 状态码 | 说明 |
|---|
201 | — 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
GET /v1/security-policies/filters/{id}
读取一个 CC 过滤器
- operationId
getSecurityPolicyFilter- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
参数
getSecurityPolicyFilter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getSecurityPolicyFilter 响应| 状态码 | 说明 |
|---|
200 | — 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。
↑ 回到列表
PATCH /v1/security-policies/filters/{id}
按版本号整体替换 CC 过滤器
- operationId
updateSecurityPolicyFilter- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
updateSecurityPolicyFilter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updateSecurityPolicyFilter 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
description | string | 是 | — |
|---|
enabled | boolean | 是 | — |
|---|
type | string | 是 | — |
|---|
parameters | object | 是 | — |
|---|
响应
updateSecurityPolicyFilter 响应| 状态码 | 说明 |
|---|
200 | — 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
DELETE /v1/security-policies/filters/{id}
删除 CC 过滤器（软删除）
- operationId
deleteSecurityPolicyFilter- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
deleteSecurityPolicyFilter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
deleteSecurityPolicyFilter 响应| 状态码 | 说明 |
|---|
204 | 已删除，或重放了相同请求。 |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
POST /v1/security-policies/filters/{id}/disable
停用 CC 过滤器
- operationId
disableSecurityPolicyFilter- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
disableSecurityPolicyFilter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
disableSecurityPolicyFilter 响应| 状态码 | 说明 |
|---|
200 | 已停用。 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
POST /v1/security-policies/filters/{id}/enable
启用 CC 过滤器
- operationId
enableSecurityPolicyFilter- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
enableSecurityPolicyFilter 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
enableSecurityPolicyFilter 响应| 状态码 | 说明 |
|---|
200 | 已启用。 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
GET /v1/security-policies/matchers
列出 CC 匹配器
- operationId
listSecurityPolicyMatchers- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
说明
需要 security_policies.read 权限。匹配器资源上线前的数据由现有 CC 规则投影得到；之后新建的是独立的带版本资源。租户身份只看到当前作用域，响应里没有 owner 信息。
说明（契约原文）
Requires security_policies.read. Rows created before the matcher resource was introduced are materialized from the existing CC rules; newly created rows are independent versioned resources. Tenant identities see only their active scope and never receive owner metadata.
参数
listSecurityPolicyMatchers 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
status | query | string: enabled / disabled | 否 | — |
|---|
name | query | string | 否 | — |
|---|
id | query | string(uuid) | 否 | — |
|---|
owner | query | string | 否 | Platform-only owner filter. |
|---|
响应
listSecurityPolicyMatchers 响应| 状态码 | 说明 |
|---|
200 | 匹配器列表。 字段：items: array<SecurityPolicyReference> total: integer page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/security-policies/matchers
创建带版本的 CC 匹配器
- operationId
createSecurityPolicyMatcher- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明
需要 security_policies.manage 权限。平台身份必须提供 target_scope_id 与 owner_id；租户身份固定为当前作用域。
说明（契约原文）
Requires security_policies.manage. Platform identities must provide target_scope_id and owner_id; tenant identities are fixed to their current scope.
参数
createSecurityPolicyMatcher 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createSecurityPolicyMatcher 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
description | string | 是 | — |
|---|
enabled | boolean | 是 | — |
|---|
field | string | 是 | — |
|---|
operator | string | 是 | — |
|---|
key | string | 否 | — |
|---|
values | array<string> | 是 | — |
|---|
target_scope_id | string(uuid) | 否 | — |
|---|
owner_id | string(uuid) | 否 | — |
|---|
响应
createSecurityPolicyMatcher 响应| 状态码 | 说明 |
|---|
201 | 已创建第 1 版匹配器，或重放了相同请求。 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/security-policies/matchers/{id}
读取一个 CC 匹配器
- operationId
getSecurityPolicyMatcher- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
参数
getSecurityPolicyMatcher 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getSecurityPolicyMatcher 响应| 状态码 | 说明 |
|---|
200 | — 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。
↑ 回到列表
PATCH /v1/security-policies/matchers/{id}
按版本号整体替换 CC 匹配器
- operationId
updateSecurityPolicyMatcher- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
updateSecurityPolicyMatcher 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updateSecurityPolicyMatcher 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
description | string | 是 | — |
|---|
enabled | boolean | 是 | — |
|---|
field | string | 是 | — |
|---|
operator | string | 是 | — |
|---|
key | string | 否 | — |
|---|
values | array<string> | 是 | — |
|---|
响应
updateSecurityPolicyMatcher 响应| 状态码 | 说明 |
|---|
200 | — 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
DELETE /v1/security-policies/matchers/{id}
删除 CC 匹配器（软删除）
- operationId
deleteSecurityPolicyMatcher- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
deleteSecurityPolicyMatcher 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
deleteSecurityPolicyMatcher 响应| 状态码 | 说明 |
|---|
204 | 已删除，或重放了相同请求。 |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
POST /v1/security-policies/matchers/{id}/disable
停用 CC 匹配器
- operationId
disableSecurityPolicyMatcher- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
disableSecurityPolicyMatcher 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
disableSecurityPolicyMatcher 响应| 状态码 | 说明 |
|---|
200 | 已停用。 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
POST /v1/security-policies/matchers/{id}/enable
启用 CC 匹配器
- operationId
enableSecurityPolicyMatcher- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
enableSecurityPolicyMatcher 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
enableSecurityPolicyMatcher 响应| 状态码 | 说明 |
|---|
200 | 已启用。 字段：id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null name: string system_rule: boolean system_rule_id?: string system_rule_key?: string status: string: enabled / disabled type?: string sort?: integer created_at: string(date-time) updated_at?: string(date-time) description?: string version: integer(int64) policy_id?: string(uuid) rule_id?: string(uuid) field?: string operator?: string key?: string values?: array<string> parameters?: object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
GET /v1/security-policies/{id}
读取一个策略
- operationId
getSecurityPolicy- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
参数
getSecurityPolicy 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getSecurityPolicy 响应| 状态码 | 说明 |
|---|
200 | 策略当前内容；租户身份不返回 owner。 字段：kind: string: waf / cc / acl name: string description: string enabled: boolean default_action: string: allow / block rules: array<SecurityPolicyRuleInput> cc_settings?: SecurityPolicyCCSettings waf_settings?: SecurityPolicyWAFSettings id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null version: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/security-policies/{id}
按版本号整体替换策略字段
- operationId
updateSecurityPolicy- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
说明
需要 security_policies.manage 权限。已有规则 ID 必须属于该策略，不带 ID 的规则新建；每次成功更新追加一个不可变的版本快照。
说明（契约原文）
Requires security_policies.manage. Existing rule IDs must belong to this policy; omitted IDs create new rules. A successful update appends one immutable revision snapshot.
参数
updateSecurityPolicy 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updateSecurityPolicy 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
kind | string: waf / cc / acl | 是 | waf 为 WAF 规则库，cc 为 CC 防护，acl 为访问控制。 |
|---|
name | string | 是 | — |
|---|
description | string | 是 | — |
|---|
enabled | boolean | 是 | — |
|---|
default_action | string: allow / block | 是 | — |
|---|
rules | array<SecurityPolicyRuleInput> | 是 | — |
|---|
cc_settings | SecurityPolicyCCSettings | 否 | CC only. Site-level ban/pass durations (override every rule's) and the auto switch (自动切换). Omitted keeps the rules' own values. |
|---|
waf_settings | SecurityPolicyWAFSettings | 否 | WAF only (node CAPABILITY_NAME_WAF v2). Omitted (or defend mode without auto_block) is stored as absent. |
|---|
响应
updateSecurityPolicy 响应| 状态码 | 说明 |
|---|
200 | 已替换并递增版本，或重放了相同请求。 字段：kind: string: waf / cc / acl name: string description: string enabled: boolean default_action: string: allow / block rules: array<SecurityPolicyRuleInput> cc_settings?: SecurityPolicyCCSettings waf_settings?: SecurityPolicyWAFSettings id: string(uuid) scope_id: string(uuid) owner?: SecurityPolicyOwner | null version: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/security-policies/{id}
按版本号删除策略（软删除）
- operationId
deleteSecurityPolicy- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.manage
参数
deleteSecurityPolicy 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
deleteSecurityPolicy 响应| 状态码 | 说明 |
|---|
204 | 已删除，或重放了相同请求。 |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/security-policies/{id}/evaluate
预览策略对一次请求的判定结果
- operationId
evaluateSecurityPolicy- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：security_policies.read
说明
需要 security_policies.read 权限，并用 If-Match 指定准确版本。同一规则内的条件取“且”；规则按优先级升序、再按 UUID 排序。continue 保留当前判定继续评估，stop 返回最终判定，没有规则命中时才用策略默认动作。预览不发布配置，也不代表节点已生效。
说明（契约原文）
Requires security_policies.read and an exact If-Match version. Conditions within a rule are ANDed; rules are ordered by ascending priority and UUID. continue preserves the current decision while evaluation continues, stop returns the terminal decision, and the policy default applies only when no rule matches. Preview does not publish configuration or prove edge enforcement.
参数
evaluateSecurityPolicy 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
evaluateSecurityPolicy 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
client_ip | any | any | 是 | — |
|---|
host | string | 是 | — |
|---|
path | string | 是 | — |
|---|
method | string | 是 | — |
|---|
headers | object | 是 | Header names are case-insensitive; arrays preserve repeated field values. Scalar values remain accepted for legacy clients. |
|---|
country | string | 是 | — |
|---|
asn | integer | 是 | — |
|---|
ja4 | string | 是 | — |
|---|
port | integer | 是 | — |
|---|
distinct_user_agents | integer | 是 | — |
|---|
status_404_count | integer | 是 | — |
|---|
响应
evaluateSecurityPolicy 响应| 状态码 | 说明 |
|---|
200 | 指定版本策略的确定性预览结果。 字段：policy_id: string(uuid) policy_version: integer(int64) action: string: allow / block / rate_limit / challenge / log / ban matched_rule_ids: array<string(uuid)> terminal_rule_id?: string(uuid) used_default: boolean |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表