Edgeweir
使用指南

挑战与 CC 防护

要求访客先通过挑战才能访问网站:按规则挑战、全站挑战(Under Attack),或由节点在请求过多时自动逐级升级(分级 CC)。通过挑战的访客拿到通行凭证,在有效期内不再被挑战。

概念

术语定义
挑战节点代替源站返回的验证页面;通过后回到原 URL。
级别挑战的强度,从低到高:Cookie 跳转(1)、JS 计算(2)、工作量证明(3)、图片验证码(4)。级别 L 的凭证满足不高于 L 的要求。
通行凭证通过挑战后下发的签名 cookie,绑定网站、级别、客户端网段与 User-Agent。
Under Attack没有有效凭证的 GET/HEAD 请求一律先挑战。可以按网站开启,也可以为所有网站开启(全局 Under Attack)。
CC 防护按网站配置的自动升级策略:条件持续一段时间后升一级,解除后冷却一段时间降一级。
JA4TLS 客户端指纹,可用于规则与限速,也可记入访问日志。

挑战类型

类型级别通过方式
Cookie 跳转(cookie302)1302 回到原 URL 并设置凭证;能保存 cookie 的客户端即可通过
JS 计算(js)2页面脚本计算一次 SHA-256 并提交
工作量证明(pow)3浏览器在后台线程中找到满足难度(前导零位数)的答案;默认 16 位,可调 8–24
图片验证码(captcha)4输入图片中的 5 个字符;无脚本也能提交。页面提供「改用计算验证」:高难度工作量证明(默认 20 位,可调 8–26,不低于普通难度),通过后同样得到级别 4 的凭证

挑战页不引用任何外部地址,带严格的 Content-Security-Policy,按 Accept-Language 显示中文或英文,系统开启「减少动态效果」时不播放动画。挑战页的状态码为 403,响应头 X-Edgeweir-Challenge 为挑战类型,Cache-Control: no-store, private。

请求需要挑战但没有有效凭证时
GET、HEAD返回挑战页;HEAD 只返回响应头
其他方法(POST、PUT…)返回 403 与 X-Edgeweir-Challenge: required,不返回挑战页
节点尚未取得凭证密钥返回 503 与 X-Edgeweir-Error: challenge-unavailable

保留路径

节点在确定网站之后直接处理以 /.edgeweir/ 开头的路径,永不转发到源站:

路径用途
POST /.edgeweir/challenge/verify提交挑战答案,通过后 303 回到挑战前的 URL(只接受本站路径)
GET /.edgeweir/challenge/worker.js工作量证明的后台脚本
其他404,X-Edgeweir-Error: not-found

源站不能在该前缀下提供内容。

通行凭证

项目行为
Cookie__ew_pass,Path=/; HttpOnly; SameSite=Lax,HTTPS 请求另加 Secure
绑定网站、通过的级别、客户端网段(IPv4 /24、IPv6 /64)、User-Agent 的哈希;换网段或换浏览器需要重新挑战
有效期默认 30 分钟,网站可设 5 分钟–24 小时(300–86400 秒)
集群内通用签名密钥按集群分发,集群内任一节点都能验证;伪造或篡改的凭证被拒绝
密钥轮换控制台每天轮换一次密钥;轮换前签发的凭证在到期前继续有效
防重放每个挑战只能兑换一次,挑战参数 5 分钟后失效

开启 Under Attack

  1. 打开 网站 →(网站)→ 安全。

  2. 在「挑战类型」中选择类型(默认 JS 计算)。

  3. 打开「Under Attack」开关并确认。节点在配置发布后生效。

  4. 验证:

    curl -sI -H 'Host: www.example.com' http://<节点 IP>/

    返回 403,响应头含 X-Edgeweir-Challenge: js。用浏览器打开网站,通过挑战后正常访问。

关闭:再点一次开关并确认。

为所有网站开启:在 防护设置 → 防护 选择「挑战类型」,打开「全局 Under Attack」并确认,所有集群都会发布新配置。网站的「安全」页签随后显示「已为所有网站开启全局 Under Attack」。见防护。

不离开当前页面:按 ⌘K / Ctrl+K,输入网站名或域名,选择「Under Attack:(网站)」并确认,开关切换到相反状态;「全局 Under Attack」同样切换全局开关。

以下请求不受 Under Attack 与 CC 挑战:

请求说明
ACME HTTP-01 验证在确定网站之前已处理
「放行」类 IP 名单中的地址对所有网站生效,见 IP 名单
命中 allow(放行)规则的请求在放行之前命中的 challenge 规则仍然生效

需要的级别取以下各项的最大值:全局 Under Attack、网站 Under Attack、命中的 challenge 规则、网站当前的 CC 级别、该路径的 CC 级别。配置阶段的规则可按请求开关网站 Under Attack、关闭「CC 防护」或设置「CC 最高级别」,全局 Under Attack 不受影响,见覆盖设置。

挑战设置

安全 → 挑战设置:「预设」选择宽松、标准(默认)或严格,填入下表前三项;选择「自定义」后逐项填写。保存的取值与任何预设都不同时显示为「自定义」。

字段取值默认值
通行凭证有效期(秒)300–864001800
计算验证难度8–2416
高难度计算验证8–26,不低于计算验证难度20
访问日志记录 JA4开 / 关关
预设通行凭证有效期计算验证难度高难度计算验证
宽松36001418
标准18001620
严格9001822

难度每增加 1,浏览器平均要做的计算翻倍。

挑战规则

在 规则 → 自定义 WAF 中选择动作「挑战」与挑战类型,例如只挑战登录页,或挑战指定的 JA4 指纹:

http.request.uri.path eq "/login"
tls.ja4 in {"t13d1516h2_8daaf6152771_02713d6af862"}

请求带有级别足够的凭证时继续执行后续规则,否则按上文挑战。字段与语法见规则。

CC 防护

CC 防护按网站配置,默认关闭。安全 → CC 防护:

  1. 打开「启用」。
  2. 保持「跟随默认模板」使用默认阈值(防护设置 → CC 模板);关闭它后在「预设」中选择宽松、标准或严格,或选择「自定义」逐项填写。保存的阈值与任何预设都不同时显示为「自定义」。
  3. 点击「保存」。
字段取值模板默认值
最高级别Cookie 跳转 / JS 计算 / 工作量证明 / 图片验证码图片验证码
验证码级别改用高难度计算验证开 / 关关
窗口(秒)5–6010
站点 QPS0–10000001000
单 URL QPS0–1000000200
单 IP QPS0–100000050
IP 封禁时长(秒)60–86400600
源站错误率(%)0–10050
最小回源请求数0–1000000100
持续多久升级(秒)1–360010
冷却多久降级(秒)1–8640060

阈值为 0 表示关闭该条件。跟随模板的网站在模板修改后自动使用新阈值。

预设最高级别站点 / 单 URL / 单 IP QPSIP 封禁时长源站错误率 / 最小回源请求数持续多久升级 / 冷却多久降级
宽松工作量证明3000 / 600 / 15030070 / 20020 / 60
标准(模板默认值)图片验证码1000 / 200 / 5060050 / 10010 / 60
严格图片验证码300 / 60 / 20360030 / 505 / 300

三个预设的窗口都是 10 秒,验证码级别都不改用高难度计算验证。

条件行为
站点 QPS网站的请求速率超过阈值:整个网站升级
单 URL QPS某个路径的速率超过阈值:只有该路径升级(按精确路径匹配),其他路径不受影响
单 IP QPS某个客户端的速率超过阈值(IPv4 按地址,IPv6 按 /64 计):它被自动封禁「IP 封禁时长」,见自动封禁
源站错误率窗口内回源请求数达到「最小回源请求数」且错误(5xx 与连接失败)比例超过阈值:整个网站升级
升级条件持续「持续多久升级」后升一级,不超过「最高级别」
降级条件解除(低于阈值的 80%)并持续「冷却多久降级」后降一级

计数与升级由每个节点在本地独立完成,阈值按单个节点计算。攻击分散到多个节点时,单个节点可能达不到阈值;按节点数折算阈值。

项目行为
计数滑动窗口(相邻两个窗口加权);路径以有界 Top-K 统计,每个网站跟踪 64 个候选,最多 64 条升级路径
最高级别为图片验证码开启「验证码级别改用高难度计算验证」时,该级别改用高难度工作量证明
上报级别变化、路径升降级与自动封禁每 5 秒上报一次,附当时请求最多的 IP 与路径(各最多 10 个,近似值)

查看状态与事件

安全 页签顶部一行显示当前生效的防护:Under Attack(本网站或全局)、CC(预设名、「自定义」「跟随模板」或「关闭」)、CRS 的模式与预设、挑战设置的预设,在线节点的级别高于正常时还显示「节点:(最高级别)」。点击其中一项跳到对应卡片。

安全 页签下方:

区块内容
节点当前级别集群中每个活动节点上该网站的级别、在线状态与已升级的路径数(每 15 秒刷新)
近期 Top IP 与路径近 1 小时、24 小时或 7 天事件中请求最多的地址与路径(近似值);行右侧的「⋯」可「封禁 IP」(对话框预填本网站与该地址)或「刷新 URL」(路径展开到网站的每个非泛域名,确认后提交)
事件级别变化、路径升降级与自动封禁的时间线:节点、触发条件(观测值 / 阈值),可按类型筛选;自动封禁的「⋯」可「在所有网站封禁」(全局范围的封禁对话框)或「解封」(解除本网站对该地址的封禁,覆盖它的网段封禁保留)

事件默认保留 30 天,可在 防护设置 → 防护 的「安全事件保留天数」调为 7–365 天。网站从正常升级时触发告警「CC 防护升级」(cc_mitigation),同一网站 15 分钟内最多一次(被压下的升级在 15 分钟后仍未恢复时补发),见告警。

JA4

JA4 是 TLS 客户端指纹(格式 a_b_c,例如 t13d1516h2_8daaf6152771_02713d6af862),在 TLS 握手时计算,同一连接上的请求共用。

部分内容
a协议(t 为 TCP,HTTP/3 为 q)、TLS 版本、是否带 SNI(d / i)、密码套件数、扩展数、ALPN 首个值的首尾字符
b排序后的密码套件的 SHA-256 前 12 位
c排序后的扩展与签名算法的 SHA-256 前 12 位
用途说明
规则字段tls.ja4(字符串,明文 HTTP 为空字符串),可用于自定义 WAF、挑战与限速规则
限速键限速规则的「限速键」可选 tls.ja4,同一指纹共享计数
访问日志打开「访问日志记录 JA4」后采样日志带 JA4 列,见访问日志

TLS 版本取客户端 supported_versions 扩展中最高的版本;客户端没有发送该扩展时取握手协商出的版本。对这类旧客户端,指纹的版本位是近似值。

只实现 JA4(TLS 客户端指纹),不实现 JA4S、JA4H 等其他方法。

权限

修改需要控制台会话或读写 AccessKey;只读 AccessKey 只能读取;服务账号不能调用这些接口(SERVICE_ACCOUNT_FORBIDDEN)。所有修改写审计:site.protection_update、system.protection_update、system.cc_template_update。

节点能力

功能需要的能力
Under Attack、CC 防护、挑战规则challenge-v1
tls.ja4 字段、JA4 限速键、JA4 日志ja4-v1

集群内有活动节点缺少所需能力时,修改照常保存并发布;缺少能力的节点保留原配置,在 集群与节点 中显示「需要升级」,见节点升级。服务账号与后台任务发布这类配置时返回 409 NODE_CAPABILITY_REQUIRED(「节点尚不支持:…(<节点>)」),原设置不变。不使用这些功能的集群配置不变。

API

过程端点
protection.getGET /sites/{id}/protection
protection.updatePATCH /sites/{id}/protection
security.stateGET /sites/{id}/security?hours=24
security.eventsGET /sites/{id}/security/events
settings.protection、settings.setProtectionGET、PUT /settings/protection(全局 Under Attack、事件保留天数)
settings.ccTemplate、settings.setCcTemplateGET、PUT /settings/cc-template

字段与示例见 API 与端点。

故障排查

现象原因处理
「高难度计算验证的难度不能低于 N」高难度计算验证低于计算验证难度调高高难度计算验证,或调低计算验证难度
节点显示「需要升级」节点版本过旧,缺少 challenge-v1 或 ja4-v1升级节点
「节点尚不支持:人机验证(<节点>)」服务账号或后台任务发布的配置需要集群节点缺少的能力升级节点
503,X-Edgeweir-Error: challenge-unavailable节点还没有取得凭证密钥检查节点与控制台的连接
表单提交或 API 调用返回 403 与 X-Edgeweir-Challenge: required非 GET/HEAD 请求没有有效凭证先用浏览器通过挑战;机器调用的接口用 allow 规则放行
通过挑战后又被挑战凭证到期;客户端换了网段或 User-Agent;需要的级别高于凭证级别调长有效期;检查代理出口是否在变化
CC 防护迟迟不升级流量分散到多个节点,单节点未达阈值按节点数调低阈值
在 GitHub 上编辑

本页目录