安全防护策略

• 1: AST 语义分析引擎
• 2: 自定义正则规则
• 3: IP、地理位置与客户端指纹
• 4: Bot 挑战与人机验证码
• 5: 流量限流
• 6: 访问控制列表（ACL）
• 7: 拦截响应页与 HTML 安全清洗

1 - AST 语义分析引擎

CheeseWAF 的核心检测器采用抽象语法树（AST）语法分析架构，而非传统的静态正则表达式堆叠。入站请求首先经过 URL 编码、Unicode、十六进制及嵌套 Base64 等多层递归解码，随后构建特定语言的语法树，精准识别载荷的语义意图。

经过基于 多套权威工业级实网语料库与独立标注保真度分类器（Corpus Fidelity Classifier）的大规模评测与缺口修复，语义引擎的标注可信检出率（TPR）已提升至 97.08%。

语义引擎开关配置

在站点配置项 sites[].waf.semantic_engines 中，可按业务技术栈独立启用或关闭专项分析引擎：

性能保障与低时延设计

为了在具备深层语法分析能力的同时保持微秒级的极低延迟，引擎实现了以下优化机制：

• 廉价子串门限前置（Substring Pre-Filters）：在执行复杂的语法树解析或高成本正则前，先通过常数时间（O(1) 或 O(n)）的廉价特征子串门限进行初筛，无潜在风险的正常业务参数在微秒级直接跳过。
• 并发 Worker 池与请求上下文隔离：多个语义分析器在 Phase 2 阶段通过并发 Worker 协程池执行，检测上下文互不干扰，并在结束时按照优先级确定性合并结果。
• 100ms 硬超时防线：若遭遇超大畸形请求体导致计算耗尽，流水线将根据 budget_exhausted_policy 触发安全兜底，绝不拖垮宿主机。

分析预算与白名单控制

通过 sites[].waf.semantic_policy 可对分析耗时与特殊业务路径进行细粒度调控：

• budget_exhausted_policy：单次请求语法解析预算耗尽时的兜底策略。可选 auto（默认，遵循 web_attack 策略等级）、open（放行可用优先）、observe（仅记录观察）或 closed（挑战/严格拦截）。
• path_allowlist：路径白名单列表，匹配到的 URI 路径将直接跳过语义检测。
• param_allowlist：参数白名单列表，匹配到的特定参数名不执行语法分析。

迁移说明： 规范配置路径为 sites[].waf.semantic_policy.budget_exhausted_policy。旧版本若将该字段放在其他非规范路径，当前版本不会读取，请手动移动到每个站点的 waf.semantic_policy 下。迁移旧枚举时，将 pass 映射为 open，将 block 或 challenge 映射为 closed（当前 closed 在分析无法完成时优先挑战）。留空或设置为 auto 时，实际策略会根据站点 web_attack 等级推导。

在 sites[].waf.performance 中可进一步限制 max_body_bytes（请求体最大分析字节数，默认 8MB）、max_header_bytes 及 proxy_timeout。

出站响应检测（敏感数据防泄露）

sites[].waf.response 支持对后端源站返回的响应体进行出站扫描，防止敏感凭据泄漏：

• 检测范围：支持识别 AWS Access Key、常见账号密码泄露模式及站点自定义敏感模式（注意：站点自定义 sensitive_patterns 将覆盖系统默认规则，默认配置下 PEM 私钥扫描未激活，可在 sensitive_patterns 中按需配置启用）。
• 性能建议：对于大文件下载或视频流业务，建议结合路径规则将响应检测限制在 JSON/HTML 接口范围，并合理设置 max_body_bytes。

关于独立攻击与嵌入长文本攻击的判定逻辑，请参考 独立特征与夹杂特征。

2 - 自定义正则规则

自定义规则引擎（Custom Rule Engine）在检测流水线中作为 Phase 1 预筛选器 运行（引擎优先级为 250）。它先于 AST 语义分析引擎（优先级 290+）执行，主要用于拦截已知的敏感管理路径探测、扫描器指纹特征以及针对特定业务接口的定制化阻断。自定义规则代表管理员显式强意图规则，不受全局 web_attack: smart 策略置信度门限抑制。一旦命中带有 block 动作的规则，请求将立即短路 403 阻断，避免产生高昂的语法树解析开销。

在 Web 管理控制台中可进入 规则管理 模块进行可视化配置与导入导出，底层对应配置项为 sites[].waf.custom_rules，亦可通过 CLI 命令 cheesewaf rules 或 REST API 进行运维管理。

规则配置示例

custom_rules:
  - id: "block-admin-probe"
    name: "Admin path probe"
    pattern: "(?i)/(wp-admin|phpmyadmin|\\.git)"
    location: "uri"
    action: "block"
    severity: "medium"
    enabled: true
    priority: 180
  - id: "challenge-bot-header"
    name: "Challenge suspicious scraper header"
    pattern: "(?i)(headlesschrome|phantomjs)"
    location: "header"
    action: "challenge"
    severity: "high"
    enabled: true
    priority: 200

字段属性与合法枚举

确定性意图与免策略过滤（Deterministic Enforcement）

自定义规则代表管理员的确定性处置意志，而非引擎的概率性弱信号。在数据平面两阶段流水线中：

• 动作直接兑现：当请求命中自定义规则时，系统无条件立即执行所配置的处置动作（block 阻断、challenge 挑战、log 仅记录）。
• 免除门槛过滤：该动作直接生效，不受 protection_policy.web_attack 策略（如最低严重度门槛、模型置信度要求或聚合风险分阈值）的拦截过滤约束，确保管理员配置的规则所见即所行。

安全校验与约束规范

为防止恶意或低效规则对数据平面造成性能衰竭，CheeseWAF 引擎在加载自定义规则时实施以下严格校验：

• 容量配额限制：单站点最多配置 256 条自定义规则；单次导入文档总大小不得超过 1MB；单站点所有规则正则字符串总长度不得超过 256KB。导入 YAML 文档必须显式包含 custom_rules 根节点，严禁空缺文档。
• 复杂度与抗 ReDoS 保证：底层依赖 Go 标准库 regexp（RE2 保证线性时间复杂度，根除灾难性回溯 ReDoS 隐患）。编译后程序指令数超过 4096 的复杂正则将被拒绝。
• 重复性校验：系统强制要求单站点内不得存在重复的规则 ID；同时严格禁止存在相同匹配位置与相同正则的规则（即重复的 location + pattern）。
• 导出文件名安全净化：在导出规则包（API GET /api/rules/export）时，系统对目标文件名强制执行字符白名单清洗（仅允许 [A-Za-z0-9._-]），彻底杜绝 Content-Disposition 响应头注入与路径穿越风险。

批量导入、导出与模板生成

从最新版本开始，CheeseWAF 原生支持通过命令行和 Web 控制台以 YAML 或 JSON 格式全量导入或导出站点规则：

1. 命令行管理（CLI）

# 生成标准自定义规则 YAML 模板
cheesewaf rules example --format yaml --file template.yaml

# 验证并全量替换指定站点的自定义规则（自动触发平滑热载）
cheesewaf rules import --site site-prod-01 --file new-rules.yaml

# 导出指定站点的自定义规则为 JSON
cheesewaf rules export --site site-prod-01 --format json --file rules-backup.json

2. Web 控制台交互

在 Web 管理控制台的 规则管理 页面中，点击右上角「导入/导出」按钮：

• 支持拖拽或选择本地 .yaml / .json 文件上传。
• 支持实时校验规则语法并在提交前预览变更差异。
• 支持一键导出当前站点的全量规则备份。

编写与运维最佳实践

• 特征精准收敛：自定义规则适用于高频已知的路径探测（如后台管理路径、漏洞探测扫描器特征 Header）。复杂的跨站脚本（XSS）与 SQL 注入注入语义，建议直接交给后置的 AST 语义分析引擎处理。
• 合理利用短路阻断：将确定的恶意特征以较小的 priority 数值排在靠前位置，利用短路机制直接丢弃攻击请求，从而降低整体 CPU 计算开销。

3 - IP、地理位置与客户端指纹

CheeseWAF 在请求接入的最外层提供了网络层与客户端维度的快速访问控制能力。在 Web 控制台中进入 IP 管理 模块，或通过配置文件中的 protection.ip 进行设置。

静态名单与基础配置

protection:
  ip:
    whitelist: ["127.0.0.1", "::1"]
    blacklist: []
    access_rules: []
    reputation_overrides: {}
    tags: {}
    threat_intel: []
    geoip:
      enabled: false
      database: "./data/GeoLite2-Country.mmdb"
      blocked_countries: []

• IP 白名单（whitelist）：命中白名单的客户端将跳过 IP 拦截、GeoIP 限制、威胁情报、Bot 挑战与全局速率限制（注：WAF 语义检测流水线仍会执行，以保障业务内容安全）。
• IP 黑名单（blacklist）：命中黑名单的请求将被当场拒绝并返回拦截页，不会进一步消耗语义引擎分析算力。

GeoIP 地理位置封禁

支持基于 MaxMind MMDB 格式的离线 IP 地理数据库实现国家与地区级流量阻断：

1. 将 geoip.enabled 设置为 true。
2. 将 geoip.database 指向有效的 Country MMDB 文件路径（如 ./data/GeoLite2-Country.mmdb）。
3. 在 blocked_countries 列表中填入需要封禁的 ISO 3166-1 alpha-2 两位国家代码（如 ["US", "RU"]）。

威胁情报源集成

支持导入第三方威胁情报 IP 库，并在控制台中支持情报源的自动化定时同步、手动更新与连通性测试。通过 REST API 端点 POST /api/ip/threat-intel/lookup 可查询特定 IP 的情报命中详情与置信度评分。

客户端软指纹与前置代理穿透

• 客户端软指纹：数据平面基于客户端 User-Agent 与 Accept-Language 特征计算轻量级软指纹（sha256 前 8 字节摘要）。ALAP 异步分析在识别高危威胁后，支持将恶意指纹沉淀为封禁规则，作为辅助防御维度。
• 前置代理真实 IP 获取：若 CheeseWAF 部署于 CDN、云负载均衡器或 Nginx 之后，必须在站点配置中声明 sites[].waf.access_control.trusted_cidrs 或 trusted_proxy_providers，以便正确从 X-Forwarded-For 等头部提取真实的客户端源 IP。

4 - Bot 挑战与人机验证码

现代网络中的复杂请求中，往往可能伴随着AI爬虫、撞库攻击及自动化扫描工具等恶意流量，CheeseWAF 提供了多层次的人机识别与流量挑战机制。可通过 Web 控制台的 Bot 挑战 与 验证码实验室 进行可视化调试，或通过 protection.bot 与 console.login.captcha 进行配置。

业务流量挑战配置

protection:
  bot:
    enabled: false
    js_challenge: true
    captcha: true
    captcha_type: "slider"
    cookie_name: "cheesewaf_js_clearance"
    path_prefixes: ["/login", "/register", "/api/order"]
    exempt_path_prefixes: ["/health", "/static"]
    suspicious_user_agents: ["curl", "sqlmap", "nuclei"]

验证码类型与交互形式

• 工作量证明（PoW / Altcha）：客户端后台在浏览器中执行哈希碰撞计算并通过请求头 X-CheeseWAF-Altcha 提交结果，对合法用户完全无感且大幅增加攻击者并发成本。
• 滑动拼图（Slider）：包含几何轨迹分析与最短拖动时间校验（由 slider_captcha_* 参数定义），有效防御机械脚本。
• 图形验证码（Image）：支持自定义字符长度、图片尺寸及语音辅助验证次数限制。
• 实验性行为验证：包括轨迹绘制、刮刮卡与图标点选等实验室题型，建议在控制台 验证码实验室 中验证业务适配性后再推向生产。

通过 /api/captcha/assets 端点支持上传企业定制背景图与图标素材。

管理端登录防护

配置项 console.login.captcha 专用于保护 Web 管理控制台登录入口（与数据平面业务隔离），支持滑块验证码与二次 PoW 校验。

源码模板默认开启管理端登录滑块验证码（console.login.captcha.enabled: true）。因此初始化完成后首次登录时，除用户名和密码外还必须完成浏览器中的人机验证。测试环境如需关闭，可在运行时配置副本中设置 console.login.captcha.enabled: false 并重启；生产环境不建议为了绕过验收而关闭该保护。

此外，可启用 console.login.security_entry 为管理登录配置隐藏的混淆路径与前置 Cookie 密钥，防止管理端被公网自动化探测。

排队室机制（Waiting Room）

通过配置 waiting_room: true 并设定 waiting_room_max_active 活跃用户上限，可在突发秒杀或流量激增时将超出承载能力的客户端优雅调度至排队等待页面。排队室只有在全局 protection.policy.bot_cc 未设为 off 且其 action 为 challenge 时才会生效；仅打开站点级排队室开关并不足够。详见 流量限流。

5 - 流量限流

CheeseWAF 在数据平面内置了高性能的分片滑动窗口计数器限流算法（Sharded Sliding Window Counter），用于平抑瞬时流量高峰并防范 CC 攻击。配置位于 protection.ratelimit，支持通过 REST API PUT /api/protection/ratelimit 进行热更新。

基础配置示例

protection:
  ratelimit:
    enabled: true
    default:
      requests: 100
      window: 60s
      burst: 20

超额处置策略

当客户端的请求速率超出设定配额时，系统支持以下处置动作：

1. 直接返回 429 拦截页：向客户端响应 HTTP 429 Too Many Requests 状态码及定制的拦截提示。
2. 调度至排队室：若同时启用了 排队室机制 且全局 protection.policy.bot_cc 策略未关闭并映射为 challenge，超出限流配额的客户端将被引导至排队等待页面。

建议在上线初期采用较宽松的配额阈值，在观察 1～2 周的正常业务流量基线后，再逐步收紧 requests 与 burst 参数。

6 - 访问控制列表（ACL）

访问控制列表（ACL）位于流量处理流水线的前端，用于以极低的计算开销快速拦截已知无用的调试路由、探测路径或强制校验指定请求头。配置位于 protection.acl，支持通过 REST API PUT /api/protection/acl 进行热更新。

配置示例

protection:
  acl:
    enabled: true
    rules:
      - id: "deny-debug"
        name: "Deny debug endpoints"
        method: ""
        path_prefix: "/debug"
        header: ""
        header_value: ""
        action: "block"
        severity: "high"
        enabled: true

匹配字段说明

7 - 拦截响应页与 HTML 安全清洗

当客户端请求被 IP 黑名单、ACL 访问控制、Bot 挑战或 AST 语义引擎阻断时，CheeseWAF 将向客户端返回结构化的拦截响应页面。配置位于 block_page，可在 Web 控制台的 拦截页 模块进行可视化预览、模板切换与源码定制。

基础配置示例

block_page:
  template_id: "minimal"
  custom_enabled: false
  custom_html: ""

模板管理与实时预览

• 内置现代模板：通过 API GET /api/block-pages/templates 可查询系统预设的现代拦截模板。
• 沙箱安全预览：在控制台中可调用 POST /api/block-pages/preview 在沙箱窗口中实时渲染拦截效果，确认无误后再执行全局发布。
• 自定义 HTML 替换：支持调用 POST /api/block-pages/upload 上传企业品牌定制的 HTML 源码，或通过 DELETE /api/block-pages/custom 清除并恢复默认模板。

自定义 HTML 安全清洗规范（SanitizeBlockPageHTML）

为了防止管理员误上传或遭受供应链投毒导致自定义拦截页引入存储型 XSS（Stored XSS）与恶意跳转风险，CheeseWAF 在保存与渲染自定义 HTML 时，强制经过内置的 SanitizeBlockPageHTML 净化引擎处理：

1. 标签与结构白名单

仅允许安全的语义排版与布局标签：

• 容器与结构：html、head、body、title、main、section、header、footer、div、span
• 排版与文本：h1~h6、p、strong、em、b、i、small、pre、code、br、hr
• 列表与表格：ul、ol、li、table、thead、tbody、tfoot、tr、th、td
• 媒体与链接：a、img、style、meta

2. 主动脚本与事件剥离

• 杜绝内联脚本：所有 <script> 标签与注释节点会被完全剔除。
• 剥离 DOM 事件处理器：所有以 on 开头的属性（如 onclick、onload、onerror 等）一律强制清除。
• 禁用表单劫持：严格过滤 formaction、action 与 method 属性，防止伪造表单收集受害者凭据。
• 防恶意重定向：<meta> 标签仅允许安全的 charset 属性，严格过滤 http-equiv="refresh" 等强制跳转指令。

3. CSS 样式净化与外部引用拦截

• <style> 标签及内联 style 属性中，严格过滤 @import 外部样式加载。
• 自动屏蔽包含 javascript:、vbscript:、expression(、behavior: 及 -moz-binding 等危险 CSS 表达式。

4. URL 协议安全限制

• 对于 href 与 src 属性，仅允许 http、https、mailto、tel 协议。
• 对于 <img> 标签，额外允许安全的 Base64 图片数据（data:image/*;base64,...），严禁非图片类型的数据 URI。

请求追踪与安全规范

• 全局追踪编号（Trace ID）：拦截页面中会自动嵌入唯一的请求追踪标识符。终端用户遇到误报反馈时，运维人员可直接在 监控与日志 中根据该编号精准定位原始请求上下文与命中规则链。
• 敏感信息保护：在编写自定义 HTML 拦截模板时，请勿泄露真实源站名称、内网 IP 地址或内部技术栈拓扑等敏感信息。