## WAF 设置 (`waf-settings`)

平台级 WAF 全网总开关、缺省拦截阈值与请求体检查上限,仅管理员可改;站点各自的观察/拦截与例外在站点配置 waf 里。

鉴权: 仅管理员 · 文档: https://www-demo.kuxitong.com/zh/docs/api/waf-settings

### GET `/api/v2/waf-settings`

获取 WAF 设置 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/waf-settings" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/waf-settings`

修改 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 未开通或缓冲已过(不生效,设置保留);修改时忽略。 可选值: ["full","readonly","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。 可选值: ["basic","standard","strict"] |
| `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。 可选值: ["log","strict_block","block"] |
| `updated_at` | string |  | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略,乐观锁用 expected_updated_at。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/waf-settings" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body_max_kb":64,"enabled":true,"intel_share":true,"level":"basic","observe_days":3,"scanner":{"action":"ban","ban_s":1800,"by_app_enabled":true,"decoys":{"enabled":true,"paths":[]},"enabled":true,"not_found":{"enabled":true,"max":30,"window_s":60},"sensitive":{"enabled":true,"extra_paths":[],"max":3},"ua_enabled":true},"semantic":{"enabled":false,"items":["sqli","xss"],"observe_days":3,"relation":"rules_first","sensitivity":"mid"},"threshold":5,"trunc_action":"strict_block"}'
```

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 未开通或缓冲已过(不生效,设置保留);修改时忽略。 可选值: ["full","readonly","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。 可选值: ["basic","standard","strict"] |
| `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。 可选值: ["log","strict_block","block"] |
| `updated_at` | string |  | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略,乐观锁用 expected_updated_at。 (只读) |