上传防护设置 upload-scan-settings

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

PUT/api/v2/upload-scan-settings修改上传防护设置

鉴权: 仅管理员

请求体 application/json

字段类型说明
actionstring 命中后:block 拦截、log 只记录、observe 先观察 3 天(期间只记录,之后拦截);危险文件不设观察期。
可选值 ["block","log","observe"]
disguiseboolean 伪装文件检测(扩展名为图片、文件头魔数为脚本或可执行程序)。
double_extboolean 双扩展名检测(如 a.php.jpg、a.asp;.jpg)。
enabledboolean 总开关;false = 所有站点都不扫描。
enhancedstring WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;增强项照常生效但只读)、basic 未开通或缓冲已过(增强项不生效,设置保留);修改时忽略。
可选值 ["full","readonly","basic"]
exceptionsUploadScanException[] 例外:网站与路径前缀命中时跳过该特征(sig 空 = 该路径不扫描)。租户标记误报加的条目(source=false_positive)整体替换时请原样带回,否则被覆盖。
expected_updated_atstring 乐观锁:调用方读到的 updated_at(配置 node.global 的版本,与 CC/WAF 设置共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。
extsstring[] 危险扩展名(小写、不带点);没带回缺省 php phtml jsp jspx asp aspx ashx cer war sh cgi shtml。按族展开(php 带 php3-8 pht phtml phar,asp 带 asa cdx cer,jsp 带 jspx jspf,shtml 带 shtm stm);点开头的名字(.php)按扩展名判;表非空时 .htaccess、.user.ini、web.config 也拦。站点 waf.upload_exts 可覆盖。
max_file_mbinteger 单个文件扫描上限(MB,缺省 20);超出的只查扩展名,按 oversize 处置。
observe_untilstring 观察期截止(action 为 observe 时有值);修改时忽略,由服务端写。
on_parse_errorstring multipart 解析出错(定界符不对、头过大、体被截断、段数超限等)时:block 拦截、allow 放行并记录(缺省 block)。
可选值 ["allow","block"]
on_timeoutstring 扫描超时(或读请求体失败)时:allow 放行并记录、block 拦截(缺省 allow)。
可选值 ["allow","block"]
on_virus_errorstring 病毒库扫描出错(clamd 连不上、读写超时、回包异常)时:allow 放行并记录、block 拦截(缺省 allow);clamd 没装/没起不扫不算出错。
可选值 ["allow","block"]
oversizestring 超过单文件上限:allow 放行并记录、block 拦截。
可选值 ["allow","block"]
sha256object[] 本主控 sha256 黑名单(WAF 增强)。
sigboolean 木马 / Webshell 特征(WAF 增强)。
timeout_sinteger 每个请求的扫描超时(秒,缺省 2)。
updated_atstring 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略。
virusstring 病毒库(ClamAV,WAF 增强):off 关、mem4g 内存 ≥4GB 的节点、all 所有节点。
可选值 ["off","mem4g","all"]

上传防护设置对象

字段类型说明
actionstring 命中后:block 拦截、log 只记录、observe 先观察 3 天(期间只记录,之后拦截);危险文件不设观察期。
可选值 ["block","log","observe"]
disguiseboolean 伪装文件检测(扩展名为图片、文件头魔数为脚本或可执行程序)。
double_extboolean 双扩展名检测(如 a.php.jpg、a.asp;.jpg)。
enabledboolean 总开关;false = 所有站点都不扫描。
enhancedstring WAF 增强判定档:full 已开通、readonly 到期只读缓冲内(License.readonly_days,缺省 7 天;增强项照常生效但只读)、basic 未开通或缓冲已过(增强项不生效,设置保留);修改时忽略。
只读可选值 ["full","readonly","basic"]
exceptionsUploadScanException[] 例外:网站与路径前缀命中时跳过该特征(sig 空 = 该路径不扫描)。租户标记误报加的条目(source=false_positive)整体替换时请原样带回,否则被覆盖。
expected_updated_atstring 乐观锁:调用方读到的 updated_at(配置 node.global 的版本,与 CC/WAF 设置共用;读到为空用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。
extsstring[] 危险扩展名(小写、不带点);没带回缺省 php phtml jsp jspx asp aspx ashx cer war sh cgi shtml。按族展开(php 带 php3-8 pht phtml phar,asp 带 asa cdx cer,jsp 带 jspx jspf,shtml 带 shtm stm);点开头的名字(.php)按扩展名判;表非空时 .htaccess、.user.ini、web.config 也拦。站点 waf.upload_exts 可覆盖。
max_file_mbinteger 单个文件扫描上限(MB,缺省 20);超出的只查扩展名,按 oversize 处置。
observe_untilstring 观察期截止(action 为 observe 时有值);修改时忽略,由服务端写。
只读
on_parse_errorstring multipart 解析出错(定界符不对、头过大、体被截断、段数超限等)时:block 拦截、allow 放行并记录(缺省 block)。
可选值 ["allow","block"]
on_timeoutstring 扫描超时(或读请求体失败)时:allow 放行并记录、block 拦截(缺省 allow)。
可选值 ["allow","block"]
on_virus_errorstring 病毒库扫描出错(clamd 连不上、读写超时、回包异常)时:allow 放行并记录、block 拦截(缺省 allow);clamd 没装/没起不扫不算出错。
可选值 ["allow","block"]
oversizestring 超过单文件上限:allow 放行并记录、block 拦截。
可选值 ["allow","block"]
sha256object[] 本主控 sha256 黑名单(WAF 增强)。
sigboolean 木马 / Webshell 特征(WAF 增强)。
timeout_sinteger 每个请求的扫描超时(秒,缺省 2)。
updated_atstring 响应里的版本(node.global 配置键的 updated_at,没改过为空);修改时忽略。
只读
virusstring 病毒库(ClamAV,WAF 增强):off 关、mem4g 内存 ≥4GB 的节点、all 所有节点。
可选值 ["off","mem4g","all"]

返回与错误

成功直接回资源 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"
}
开始使用

体验在线演示

访问在线演示,或联系我们获取报价与安装命令