核心概念

• 1: 流量处理路径与两阶段流水线
• 2: 防护等级机制
• 3: 独立特征与夹杂特征
• 4: 统一管理入口与权限模型

1 - 流量处理路径与两阶段流水线

CheeseWAF 的流量处理链路分为同步检测链路与异步旁路研判链路两大部分。系统在同步链路中采用了独特的**两阶段流水线（Two-Phase Pipeline）**架构，兼顾极端高并发下的微秒级快速阻断与复杂语法树解析的高吞吐：

flowchart TB
  Client[客户端请求] --> Ingress[网络接入层 HTTP / HTTPS / HTTP3]
  subgraph Phase1 [Phase 1: 预筛选器链 Pre-Filters (顺序执行 / 短路阻断 / 优先级 < 290)]
    IP{IP / 地理位置 / 软指纹} -->|放行| Bot{Bot 挑战 / 限流 / 排队室}
    Bot -->|放行| Rules{自定义规则引擎 Priority 250}
  end
  Ingress --> IP
  IP -->|命中黑名单| Block[返回拦截页]
  Bot -->|触发挑战| Challenge[验证码校验 / 排队等待]
  Challenge -->|挑战通过| Rules
  Rules -->|命中阻断规则| Block

  subgraph Phase2 [Phase 2: 语义分析组 Semantic Group (Worker 线程池并发 / 确定性合并 / 优先级 >= 290)]
    Sem[AST 语义分析引擎: SQL / XSS / RCE / LFI / NoSQL / SSTI 等]
  end
  Rules -->|无阻断| Sem

  Sem --> Shape{特征形态判断}
  Shape -->|独立特征 2~5 级| Block
  Shape -->|夹杂特征 5 级| Block
  Shape -->|夹杂特征 2~4 级| Pass[放行并投递异步队列]
  Shape -->|无异常| Origin[转发至上游源站]
  Pass --> Origin
  Pass -.-> Queue[ALAP 异步审查队列]
  Sem -.->|5 级阻断样本| Queue
  Queue --> LLM[调用配置的大语言模型]
  LLM --> Review{研判判定}
  Review -->|高危 / 严重| Rule[沉淀为长期规则]
  Review -->|低危 / 误报| Dismiss[归档忽略 / 加入白名单]
  Rule -.-> IP

两阶段流水线设计（Phase 1 与 Phase 2）

为了在生产高流量下保障服务时延确定性，CheeseWAF 的请求检测流水线在内存中将所有注册的检测器按 Priority 分离为两个截然不同的执行阶段：

1. Phase 1：Pre-Filters 顺序预筛选器（优先级 < 290）

• 涵盖范围：IP 黑白名单与地理围栏、Bot 挑战与防刷识别、分片滑动窗口限流，以及 自定义正则规则引擎（Priority 250）。
• 执行特性：单线程顺序执行，对执行顺序极度敏感。
• 快速短路机制：任意前置检测器判定为 ActionBlock 时，请求将立即被短路拦截并终止流水线，绝对不进入昂贵的 AST 语法树解析阶段。这使得针对已知敏感路径、特定扫描特征的大规模扫描流量在毫秒级内被拦截丢弃。

2. Phase 2：Semantic Group 并发语义分析组（优先级 >= 290）

• 涵盖范围：SQL 注入、XSS 跨站脚本、RCE 命令注入、LFI 文件遍历、NoSQL 注入、SSTI 模板注入、SSRF 以及 XXE 等深层语法分析器。
• 执行特性：
  • Worker 协程池并发调度：系统维护全局共享的 Worker 协程池（上限为 8 协程），入站请求将各项语义分析任务并发推入任务队列并行分析。
  • 请求上下文隔离（Forked Context）：每个检测器在独立的 Fork 上下文中运行，向元数据和检测结果写入数据时互不干扰，在架构上杜绝并发数据竞争（Data Race）。
  • 确定性优先级合并：所有并发检测器执行完成（或超时）后，系统严格按照既定的优先级序号执行稳定合并，确保威胁评估结果与日志记录在任何并发环境下均保持 100% 幂等。

流水线超时与预算控制（Budget Protection）

• 100ms 硬超时防线：整个流水线设有全局 100ms 硬超时时钟，防止复杂畸形载荷将 WAF 进程长时间卡死。
• 分析预算耗尽策略（budget_exhausted_policy）：当请求体异常巨大或语法树分析在超时窗口内未能完整结束时，系统将触发安全兜底策略：
  • auto：遵循全局 web_attack 防护策略等级映射兜底动作。
  • open：以业务可用性为先予以放行（记录指标）。
  • observe：仅记录观察日志，不执行硬阻断。
  • closed：安全优先，触发人机挑战或严格拦截。
• 过载保护（Guard Overload）：底层内置基于协程管程与信号量的过载防护，当极端并发导致分析队列溢出时主动触发 ErrDetectionOverload，保障主服务进程的高可用与自愈。

异步旁路研判链路（ALAP Loop）

异步链路完全独立于实时转发流程，在客户端完成响应接收后于后台触发：

• 样本投递：在防护等级 2～4 下被放行的夹杂特征样本，以及在等级 5 下被阻断的高危样本，均会被投递至 ALAP 审查队列。
• 模型智能分析：后台 Worker 异步调用大模型提取攻击意图并输出置信度评估。
• 闭环规则沉淀：人工审核可将确认样本转换为所选的载荷、URI、IP 或指纹规则；站点级自动采纳范围更窄，仅写入该站点的自定义载荷规则。

2 - 防护等级机制

CheeseWAF 支持为每个站点独立配置防护等级（sites[].waf.paranoia_level）。取值范围为 0 至 5，系统默认推荐值为 3。

防护等级机制的核心目标是在保证高检出率的同时最大程度降低误报率。语义分析引擎在对单个解码后的参数值进行检测时，会根据特征形态（独立特征 vs 夹杂特征）与当前防护等级执行分级处置。

防护等级对照表

动态临时升档机制

在 防护等级 4 下，当系统检测到业务流量中出现疑似攻击的夹杂特征时，为防止攻击者正处于探测阶段，系统会自动将该站点的防护等级临时上调至 5 级（严格模式），持续时间由 promote_seconds（例如 300 秒）指定。

• 状态持久化：升档截止时间戳保存在本地管理存储中，重启后依然生效；访问日志可异步投递至 PostgreSQL 存储。
• 自动衰减：当升档时间窗口结束且无新的可疑特征触发时，站点将自动恢复至原本的 4 级状态。

严格等级（5 级）审查说明

在防护等级 5 下被阻断的请求样本仍会被投递至 ALAP 审查队列，并附带 blocked 标记：

• 不可追溯放行：由于该请求已被物理拦截，管理员无法在审查控制台中将其变更为“已放行”状态。
• 规则沉淀转换：审查通过后，可将样本一键转化为长期的全局防护规则（包括特征规则、URL 路径规则、IP 黑名单或客户端软指纹封禁）。

3 - 独立特征与夹杂特征

在 Web 业务场景中，用户提交的内容形态各异。例如在论坛发帖、博客评论或技术社区中，正常用户经常会引用代码片段或 SQL 查询语句；若简单使用纯特征匹配，极易导致大面积误报。

为了解决这一问题，CheeseWAF 的 AST 语义分析引擎在完成参数多层解码后，会根据载荷的上下文占比与包裹形态，将判定命中标记为独立特征（Isolated Payload）或夹杂特征（Embedded Payload）。

特征形态定义

1. 独立特征（Isolated Payload）

独立特征指参数值的绝大部分内容直接构成了攻击载荷本身，且缺乏合法的业务文本上下文。

• 典型场景：在登录框或搜索框参数中直接输入 UNION SELECT 1,2,3、' OR 1=1 -- 等。
• 包裹判定：即使攻击者添加了 @、结尾分号、/{${...}} 或简单前后缀等轻微包装，只要有效载荷占据主要结构，引擎依然将其判定为独立特征。
• 处置策略：在防护等级 2～5 下，独立特征命中将触发立即阻断。

2. 夹杂特征（Embedded Payload）

夹杂特征指疑似攻击语法的片段嵌入在较长的正常自然语言、技术文章或商品描述等大段文本中。

• 典型场景：技术论坛帖子中讨论数据库优化并包含了一条示例 SQL，或者文章中讨论 Log4j 漏洞时引用了相关 payload 字符串。
• 处置策略：在标准防护等级（2～4 级）下，系统采取放行请求并异步投递 ALAP 队列的策略，避免中断正常业务交互；在严格模式（5 级）下，则执行严格拦截。

引擎隔离覆盖范围与工程实现事实

为确保策略的严密性与透明度，以下为当前版本语义引擎针对特征隔离的具体实现边界：

• 已覆盖 Gadget：隔离分析器专门覆盖了 PHP/JSP 动态 WebShell、Log4j JNDI 注入 以及 短引号/谓词 SQL 注入（针对长度不超过 96 个字符/rune 的短片段）。
• 形态守卫机制：针对 XSS、系统命令执行（RCE）、服务端模板注入（SSTI）、服务端请求伪造（SSRF） 及 XML 外部实体注入（XXE） 等攻击类型，引擎采用专门的文档形态守卫（Document Shape Guards），独立于短 Gadget 隔离分析器运行。
• 兜底证据链：被标记为 embedded 的命中在低于 5 级时免除阻断；对于未明确归类的边界命中，系统依然严格遵从 blockableHit 证据判定逻辑，不会默认降级为夹杂特征。
• 最佳实践建议：特征隔离机制用于降低已知 Gadget 在富文本业务下的误报率，若业务系统完全面向 API 或固定表单交互，建议在关键接口上开启更高的防护等级或针对性 Schema 校验。

4 - 统一管理入口与权限模型

CheeseWAF 提供了三种各司其职的管理入口，满足可视化运维、无图形终端交互及 CI/CD 自动化集成等多种场景：

三端统一鉴权机制

当配置文件中启用 setup.three_end_unified: true 时，CheeseWAF 实现了三大管理入口的用户体系与权限闭环：

• 用户身份通用：在 Web 控制台创建的管理员或普通用户账号，可直接用于 TUI 命令行登录与 API 鉴权。
• 统一 RBAC 授权：在控制台“系统管理”中生成的 API Token，遵从与用户角色相同的 RBAC 权限矩阵（定义于 apisec.permissions）。
• 细粒度角色划分：系统默认预设 admin（拥有 ["*"] 全量权限）与 readonly（拥有 ["read:*", "read:cluster"] 等只读权限）等角色。
• 身份字段精确校验：用户名遵循 CLI 手册中的 3–32 个 ASCII 字符规范。角色必须精确匹配 apisec.permissions 中的已配置键；首尾或嵌入 Unicode 空白、控制字符（Cc）、格式/不可见字符（Cf）以及 *、: 等权限表达式都会被拒绝。服务端不会自动去空格或改大小写。

操作审计链路

当开启 apisec.audit.enabled: true 时，所有通过 Web 控制台、TUI 终端以及 REST API 执行的配置变更、策略启停及用户管理操作，均会结构化写入 apisec.audit.path 指定的审计日志文件中，确保生产环境运维操作的可追溯性。

相关模块参考

• Web 控制台使用指南
• 命令行与 TUI 交互手册
• REST API 接口与权限对照表