增值防护方案 protect-schemes

防重放、防泄露、防篡改各一份方案(租户各自一份,管理员编辑平台方案);保存时一并改「按方案」的站点,单独设置的不动;属 WAF 增强。

点击任一接口,右侧显示对应的调用示例。

防护鉴权: 用户(部分参数仅管理员)10 个接口

鉴权

请求头带 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/protect-schemes/leak获取防泄露方案

鉴权: 用户(部分参数仅管理员)

PUT/api/v2/protect-schemes/leak保存防泄露方案

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
auto_joinobject 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。
custom必填SiteLeakGuardCustom[] 自定义正则,最多 16 条。
detect必填SiteLeakGuardDetect 内置识别各类的处置;不写 = 不查这一类。
enabledboolean 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。
exclude必填string[] 不检测的路径前缀(末尾 * 可省),最多 32 条。
expected_updated_atstring 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。
observe_days必填integer 站点按方案新开启时观察多少天(只记录不处置);0 = 不观察直接处置。
override_customboolean 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。
selectionobject 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。
GET/api/v2/protect-schemes/replay获取防重放方案

鉴权: 用户(部分参数仅管理员)

PUT/api/v2/protect-schemes/replay保存防重放方案

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
actionReplayGuardAction 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。
可选值 ["block","challenge"]
app_saltstring 签名盐(应用密钥,32 字节 hex);app_sign 开而没有它 = 签名头一律不认。
app_signboolean App 签名校验:请求带签名头即按签名校验,不需要令牌。
auto_joinobject 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。
bind_ipboolean 令牌再绑客户端 IP(换 IP 即失效)。
enabledboolean 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。
expected_updated_atstring 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。
methodsReplayGuardMethod[] 受保护方法;不写 = POST/PUT/PATCH/DELETE。
override_customboolean 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。
pathsReplayGuardPath[] 保护接口路径表,最多 64 条;空 = 不保护。
selectionobject 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。
ttl_sinteger 令牌有效期(秒),签名头的时间戳也按它判;不写 = 120。
GET/api/v2/protect-schemes/tamper获取防篡改方案

鉴权: 用户(部分参数仅管理员)

PUT/api/v2/protect-schemes/tamper保存防篡改方案

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
action必填ReplayGuardAction 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。
可选值 ["block","challenge"]
auto_joinobject 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。
enabledboolean 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。
expected_updated_atstring 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。
mode必填string 检查范围:structure 仅结构变化;full 整页任意变化。
可选值 ["structure","full"]
observe_days必填integer 站点按方案新开启时观察多少天(只记录不处置);0 = 不观察直接处置。
override_customboolean 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。
scopes必填SiteTamperScope[] 保护范围,最多 50 条。
selectionobject 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。
POST/api/v2/protect-schemes/{kind}/apply把方案批量应用到网站

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
auto_joinobject 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。
dry_runboolean 为 true 只返回会发生什么的计数,不写任何东西。
默认 false
modestring 检查范围:structure 仅结构变化;full 整页任意变化。
可选值 ["structure","full"]
override_customboolean 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。
selectionobject 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。
GET/api/v2/protect-schemes/{kind}/sites列出已设置这项防护的网站

鉴权: 用户(部分参数仅管理员)

查询参数

字段类型说明
pageinteger 页码,从 1 开始。
默认 1
page_sizeinteger 每页条数。
默认 20
tenant_idinteger 仅管理员可用:按租户过滤(格式错 422)。租户凭据调用时忽略,只返回本租户数据。
qstring 按网站域名或站点名模糊搜索(不区分大小写)。
statusProtectSchemeSiteStatus 按状态过滤。
可选值 ["enabled","disabled","pending","capture_failed"]
sourceProtectSiteSource 按来源过滤:scheme 按方案;custom 单独设置(含单独关闭)。
只读可选值 ["scheme","custom"]
POST/api/v2/protect-schemes/{kind}/sites/bulk批量重设或关闭网站的这项防护

鉴权: 用户(部分参数仅管理员)

请求体 application/json

字段类型说明
action必填ReplayGuardAction 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。
可选值 ["block","challenge"]
filterProtectSchemeSiteFilter 与列表同样的过滤条件,服务端展开成网站集合。
idsinteger[] 网站 id 列表。

增值防护方案对象

字段类型说明
actionReplayGuardAction 没有令牌或重放时:block 回 403;challenge 出 JS 挑战。不写 = block。
可选值 ["block","challenge"]
app_saltstring 签名盐(应用密钥,32 字节 hex);app_sign 开而没有它 = 签名头一律不认。
app_signboolean App 签名校验:请求带签名头即按签名校验,不需要令牌。
appliedinteger 写入(dry_run 时为将写入)的网站数。
applyobject 本次保存应用到网站的结果(只在保存的回包里有)。
auto_joinobject 「以后新加入范围的网站自动加入方案」的规则;没开时不返回。
只读
bind_ipboolean 令牌再绑客户端 IP(换 IP 即失效)。
countsProtectSchemeCounts 站点计数:调用方看得到的站点里,开着的、按方案的、单独设置的、套餐不含的各几个。
只读
customSiteLeakGuardCustom[] 自定义正则,最多 16 条。
demoted_sitesinteger 本次保存因属主没开通 WAF 增强、改为单独设置并保留原值的站点数(只在保存的回包里有)。
只读
detectSiteLeakGuardDetect 内置识别各类的处置;不写 = 不查这一类。
domainstring 网站主域名(没有域名时为站点名)。
dry_runboolean 为 true 只返回会发生什么的计数,不写任何东西。
默认 false
enabledboolean 方案总开关:开着时「按方案」的站跟这份方案生效;关着时这些站关闭(各自的值保留),自动加入规则暂停。没保存过为 false。
只读
excludestring[] 不检测的路径前缀(末尾 * 可省),最多 32 条。
expected_updated_atstring 乐观锁:调用方读到的 updated_at(读到为空 = 还没保存过,用 1970-01-01T00:00:00Z)。与库里当前值不等则回 409 stale_version、不保存;不带则不检查。
failedProtectSchemeFailure[] 没能处理的网站及原因,最多 100 条。
failed_totalinteger 没能处理的网站总数(failed 被截断时大于其长度)。
filterProtectSchemeSiteFilter 与列表同样的过滤条件,服务端展开成网站集合。
gateProtectSchemeGate 方案属主(租户本人或平台)的 WAF 增强判定档:full 可改;readonly、basic 只许减不许增。
只读可选值 ["full","readonly","basic"]
idsinteger[] 网站 id 列表。
is_defaultboolean 没保存过方案时为 true,其余设置是缺省值(不落库);保存过不返回。
只读
itemsReplaySchemeSuggestion[] 按 POST 次数从多到少,最多 3 条;没有数据或没接 ClickHouse 为空。
matchedinteger 范围内调用方看得到的网站数。
methodsReplayGuardMethod[] 受保护方法;不写 = POST/PUT/PATCH/DELETE。
modestring 检查范围:structure 仅结构变化;full 整页任意变化。
可选值 ["structure","full"]
observe_daysinteger 站点按方案新开启时观察多少天(只记录不处置);0 = 不观察直接处置。
observe_untilinteger 观察期截止(Unix 毫秒时间戳);只有防泄露开着且仍在观察期内才有值,已过期、没有观察期、关着或其余方案为空。
override_customboolean 不带即 false,也只能为 false:单独设置的站不跟着改(计入 apply.skipped_custom),要覆盖用按方案重设。
ownerstring 属主用户名。
pathsReplayGuardPath[] 保护接口路径表,最多 64 条;空 = 不保护。
scopesSiteTamperScope[] 保护范围,最多 50 条。
selectionobject 本次要加入方案的网站范围;只在保存后总开关为开、且这次改了范围时带。不带 = 不加新站。
site_idinteger 网站 id。
skipped_custominteger 因单独设置而没覆盖的网站数(override_custom 为 false)。
skipped_gateinteger 因属主 WAF 增强不是 full 而没写的网站数。
sourceProtectSiteSource 站点这一项的来源:scheme 按方案(保存方案时跟着变);custom 单独设置(含关闭、存量迁移来的行)。
只读可选值 ["scheme","custom"]
statusProtectSchemeSiteStatus 站点这一项的状态:enabled 开着;disabled 关着;pending 开着但防篡改基准还在排队采集;capture_failed 开着但基准采集多次失败、已停止重试(只有防篡改有后两种)。
可选值 ["enabled","disabled","pending","capture_failed"]
tenant_idinteger 属主用户 id。
today_blockedinteger 今日(UTC)拦截与换错误页次数,不含观察期内的命中(只有防泄露有,与方案回包 counts.today_blocked 同口径);其余方案、没接 ClickHouse 或查询失败为空。
today_hitsinteger 今日命中数(防泄露为今日 UTC 非观察期的打码与拦截次数之和,即 today_masked + today_blocked,防篡改为今日检出篡改的页数);防重放为空。
today_maskedinteger 今日(UTC)打码次数,不含观察期内的命中(只有防泄露有,与方案回包 counts.today_masked 同口径);其余方案、没接 ClickHouse 或查询失败为空。
ttl_sinteger 令牌有效期(秒),签名头的时间戳也按它判;不写 = 120。
updated_atstring 版本(没保存过为空);修改时用 expected_updated_at。
只读
updated_sitesinteger 本次保存一并改到的按方案站点数(只在保存的回包里有)。
只读
will_changeinteger 只在 dry_run 回包:按 mode 保存后会变的网站数(enable 会开启或加入的、update 会一起更新的、disable 会关掉的)。

返回与错误

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

体验在线演示

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