版本 2.4.8 · 最新
WAF 设置 waf-settings
平台级 WAF 全网总开关、缺省拦截阈值与请求体检查上限,仅管理员可改;站点各自的观察/拦截与例外在站点配置 waf 里。
点击任一接口,右侧显示对应的调用示例。
防护鉴权: 仅管理员2 个接口
鉴权
请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。
X-API-Key
鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。
约定
分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。
时间一律 RFC 3339(UTC);金额单位为分。
写操作成功回 200/201/204;重复提交按资源唯一键回 409。
GET
/api/v2/waf-settings获取 WAF 设置
鉴权: 仅管理员
PUT
/api/v2/waf-settings修改 WAF 设置
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
body_max_kb必填 | integer | 请求体只查前多少 KiB;0 = 不查请求体。 |
enabled必填 | boolean | 全网总开关;false = 所有站点都不查。 |
engine_unavailable_nodes | integer | 在线主节点里报 WAF 引擎(libinjection)不可用的台数(缺库时 sqli/xss 规则不生效);修改时忽略。 |
enhanced | string | WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;标准/严格等级与语义检测照常生效但只读)、basic 未开通或缓冲已过(不生效,设置保留);修改时忽略。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(即配置 node.global 的版本,CC/WAF 设置与该键共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
intel_share | boolean | 威胁情报共享:把自动封禁的高危 IP、上传扫描命中/误报与新出现的文件指纹匿名上报服务商(记录见 GET /intel-reports)。不带 = 保持原值,没设过为开(默认开启,可随时关闭,关闭后立即停止上报)。 |
level | string | 全网缺省防护等级(站点没单独选时用它);standard/strict 属 WAF 增强,改动过增强门(到期只读期与未开通只许调低,调高拒)。不带 = 保持原值,没设过为 basic。 |
observe_days | integer | 新规则/新等级的观察天数(只记录不拦);0 = 不观察。不带 = 保持原值,没设过为 3。 |
rule_lib | WafRuleLib | 规则库对照表(只读,修改时忽略):付费项 rules_update 是否开通、规则包版本与各类条数、节点对齐;没开通时用节点内置 23 条。明细见 GET /waf-protections。 |
scanner | WafScanner | 扫描器拦截(内置防护 protect.builtin_guard 的 scan 段):总开关、处置与封禁时长,以及「判定(满足任一)」五项各自的勾选与阈值/自定义名单。任一项关掉即不判该项;自定义路径保存在主控,换规则版本不受影响。 |
semantic | WafSemantic | 语义检测(WAF 增强):在规则打分之外再按语义判攻击;节点按观察期只记不拦、过期后拦截。 |
threshold必填 | integer | 缺省拦截阈值(命中规则的异常分累计);站点 waf.threshold 非 0 时以站点为准。 |
trunc_action | string | 请求内容有一部分没查到时的处置(规则号 920901):参数超 1024 个、请求头超 256 个、JSON/XML 条目超上限、表单字段超预算、非二进制请求体超 body_max_kb;能补查的先补查,仍有漏的才按此处置。log 只记录(事件标 body_trunc)不拦;strict_block 严格档拦、基础与标准档只记录;block 各档都拦。缺省 strict_block,即严格档下超过 body_max_kb(缺省 64KB)的非二进制请求体(如大 JSON)会被 920901 拦,可调大 body_max_kb、改为 log 或在站点 WAF 例外放行 920901。注意 920901 计入连续命中封禁(站点 waf.ban_on_repeat),网站开了它时经常发大 JSON 的客户端 IP 会被封。观察模式的站点只记不拦。不带 = 保持原值,没设过为 strict_block。 |
updated_at | string | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略,乐观锁用 expected_updated_at。 |
WAF 设置对象
| 字段 | 类型 | 说明 |
|---|---|---|
body_max_kb | integer | 请求体只查前多少 KiB;0 = 不查请求体。 |
enabled | boolean | 全网总开关;false = 所有站点都不查。 |
engine_unavailable_nodes | integer | 在线主节点里报 WAF 引擎(libinjection)不可用的台数(缺库时 sqli/xss 规则不生效);修改时忽略。 |
enhanced | string | WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;标准/严格等级与语义检测照常生效但只读)、basic 未开通或缓冲已过(不生效,设置保留);修改时忽略。 |
expected_updated_at | string | 乐观锁:调用方读到的 updated_at(即配置 node.global 的版本,CC/WAF 设置与该键共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
intel_share | boolean | 威胁情报共享:把自动封禁的高危 IP、上传扫描命中/误报与新出现的文件指纹匿名上报服务商(记录见 GET /intel-reports)。不带 = 保持原值,没设过为开(默认开启,可随时关闭,关闭后立即停止上报)。 |
level | string | 全网缺省防护等级(站点没单独选时用它);standard/strict 属 WAF 增强,改动过增强门(到期只读期与未开通只许调低,调高拒)。不带 = 保持原值,没设过为 basic。 |
observe_days | integer | 新规则/新等级的观察天数(只记录不拦);0 = 不观察。不带 = 保持原值,没设过为 3。 |
rule_lib | WafRuleLib | 规则库对照表(只读,修改时忽略):付费项 rules_update 是否开通、规则包版本与各类条数、节点对齐;没开通时用节点内置 23 条。明细见 GET /waf-protections。 |
scanner | WafScanner | 扫描器拦截(内置防护 protect.builtin_guard 的 scan 段):总开关、处置与封禁时长,以及「判定(满足任一)」五项各自的勾选与阈值/自定义名单。任一项关掉即不判该项;自定义路径保存在主控,换规则版本不受影响。 |
semantic | WafSemantic | 语义检测(WAF 增强):在规则打分之外再按语义判攻击;节点按观察期只记不拦、过期后拦截。 |
threshold | integer | 缺省拦截阈值(命中规则的异常分累计);站点 waf.threshold 非 0 时以站点为准。 |
trunc_action | string | 请求内容有一部分没查到时的处置(规则号 920901):参数超 1024 个、请求头超 256 个、JSON/XML 条目超上限、表单字段超预算、非二进制请求体超 body_max_kb;能补查的先补查,仍有漏的才按此处置。log 只记录(事件标 body_trunc)不拦;strict_block 严格档拦、基础与标准档只记录;block 各档都拦。缺省 strict_block,即严格档下超过 body_max_kb(缺省 64KB)的非二进制请求体(如大 JSON)会被 920901 拦,可调大 body_max_kb、改为 log 或在站点 WAF 例外放行 920901。注意 920901 计入连续命中封禁(站点 waf.ban_on_repeat),网站开了它时经常发大 JSON 的客户端 IP 会被封。观察模式的站点只记不拦。不带 = 保持原值,没设过为 strict_block。 |
updated_at | string | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略,乐观锁用 expected_updated_at。 |
返回与错误
成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。
成功
{
"id": 1,
"name": "example"
}列表
{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}失败
{
"code": "validation_failed",
"detail": "请求参数不合法",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name 必填"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}