## 上传防护设置 (`upload-scan-settings`)

平台级上传文件扫描(只查 multipart 表单上传的文件):总开关、危险扩展名、双扩展名、伪装文件、木马特征、病毒库、单文件上限、扫描超时、处置与例外,仅管理员可改;木马特征、病毒库与 sha256 黑名单属付费功能 WAF 增强。

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

### GET `/api/v2/upload-scan-settings`

获取上传防护设置 · 鉴权: 仅管理员

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

### PUT `/api/v2/upload-scan-settings`

修改上传防护设置 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `action` | string |  | 命中后:block 拦截、log 只记录、observe 先观察 3 天(期间只记录,之后拦截);危险文件不设观察期。 可选值: ["block","log","observe"] |
| `disguise` | boolean |  | 伪装文件检测(扩展名为图片、文件头魔数为脚本或可执行程序)。 |
| `double_ext` | boolean |  | 双扩展名检测(如 a.php.jpg、a.asp;.jpg)。 |
| `enabled` | boolean |  | 总开关;false = 所有站点都不扫描。 |
| `enhanced` | string |  | WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;增强项照常生效但只读)、basic 未开通或缓冲已过(增强项不生效,设置保留);修改时忽略。 可选值: ["full","readonly","basic"] |
| `exceptions` | UploadScanException[] |  | 例外:网站与路径前缀命中时跳过该特征(sig 空 = 该路径不扫描)。租户标记误报加的条目(source=false_positive)整体替换时请原样带回,否则被覆盖。 |
| `expected_updated_at` | string |  | 乐观锁:调用方读到的 updated_at(配置 node.global 的版本,与 CC/WAF 设置共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
| `exts` | string[] |  | 危险扩展名(小写、不带点);没带回缺省 php phtml jsp jspx asp aspx ashx cer war sh cgi。站点 waf.upload_exts 可覆盖。 |
| `max_file_mb` | integer |  | 单个文件扫描上限(MB,缺省 20);超出的只查扩展名,按 oversize 处置。 |
| `observe_until` | string |  | 观察期截止(action 为 observe 时有值);修改时忽略,由服务端写。 |
| `on_parse_error` | string |  | multipart 解析出错(定界符不对、头过大、体被截断、段数超限等)时:block 拦截、allow 放行并记录(缺省 block)。 可选值: ["allow","block"] |
| `on_timeout` | string |  | 扫描超时(或读请求体失败)时:allow 放行并记录、block 拦截(缺省 allow)。 可选值: ["allow","block"] |
| `oversize` | string |  | 超过单文件上限:allow 放行并记录、block 拦截。 可选值: ["allow","block"] |
| `sha256` | object[] |  | 本主控 sha256 黑名单(WAF 增强)。 |
| `sig` | boolean |  | 木马 / Webshell 特征(WAF 增强)。 |
| `timeout_s` | integer |  | 每个请求的扫描超时(秒,缺省 2)。 |
| `updated_at` | string |  | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略。 |
| `virus` | string |  | 病毒库(ClamAV,WAF 增强):off 关、mem4g 内存 ≥4GB 的节点、all 所有节点。 可选值: ["off","mem4g","all"] |

```sh
curl -X PUT "https://panel.example.com/api/v2/upload-scan-settings" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"block","disguise":true,"double_ext":true,"enabled":true,"exceptions":[{"path":"/upload/avatar/","sig":"","site_id":0}],"exts":["php","jsp"],"max_file_mb":20,"on_parse_error":"block","on_timeout":"allow","oversize":"allow","sig":true,"timeout_s":2,"virus":"mem4g"}'
```

上传防护设置对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `action` | string |  | 命中后:block 拦截、log 只记录、observe 先观察 3 天(期间只记录,之后拦截);危险文件不设观察期。 可选值: ["block","log","observe"] |
| `disguise` | boolean |  | 伪装文件检测(扩展名为图片、文件头魔数为脚本或可执行程序)。 |
| `double_ext` | boolean |  | 双扩展名检测(如 a.php.jpg、a.asp;.jpg)。 |
| `enabled` | boolean |  | 总开关;false = 所有站点都不扫描。 |
| `enhanced` | string |  | WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;增强项照常生效但只读)、basic 未开通或缓冲已过(增强项不生效,设置保留);修改时忽略。 可选值: ["full","readonly","basic"] (只读) |
| `exceptions` | UploadScanException[] |  | 例外:网站与路径前缀命中时跳过该特征(sig 空 = 该路径不扫描)。租户标记误报加的条目(source=false_positive)整体替换时请原样带回,否则被覆盖。 |
| `expected_updated_at` | string |  | 乐观锁:调用方读到的 updated_at(配置 node.global 的版本,与 CC/WAF 设置共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。 |
| `exts` | string[] |  | 危险扩展名(小写、不带点);没带回缺省 php phtml jsp jspx asp aspx ashx cer war sh cgi。站点 waf.upload_exts 可覆盖。 |
| `max_file_mb` | integer |  | 单个文件扫描上限(MB,缺省 20);超出的只查扩展名,按 oversize 处置。 |
| `observe_until` | string |  | 观察期截止(action 为 observe 时有值);修改时忽略,由服务端写。 (只读) |
| `on_parse_error` | string |  | multipart 解析出错(定界符不对、头过大、体被截断、段数超限等)时:block 拦截、allow 放行并记录(缺省 block)。 可选值: ["allow","block"] |
| `on_timeout` | string |  | 扫描超时(或读请求体失败)时:allow 放行并记录、block 拦截(缺省 allow)。 可选值: ["allow","block"] |
| `oversize` | string |  | 超过单文件上限:allow 放行并记录、block 拦截。 可选值: ["allow","block"] |
| `sha256` | object[] |  | 本主控 sha256 黑名单(WAF 增强)。 |
| `sig` | boolean |  | 木马 / Webshell 特征(WAF 增强)。 |
| `timeout_s` | integer |  | 每个请求的扫描超时(秒,缺省 2)。 |
| `updated_at` | string |  | 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略。 (只读) |
| `virus` | string |  | 病毒库(ClamAV,WAF 增强):off 关、mem4g 内存 ≥4GB 的节点、all 所有节点。 可选值: ["off","mem4g","all"] |