diff --git a/docs/superpowers/specs/2026-07-19-waf-security-check-node-design.md b/docs/superpowers/specs/2026-07-19-waf-security-check-node-design.md new file mode 100644 index 00000000..985327d6 --- /dev/null +++ b/docs/superpowers/specs/2026-07-19-waf-security-check-node-design.md @@ -0,0 +1,191 @@ +# WAF 规则节点:安全防护(security_check) + +日期:2026-07-19 +范围:WAF 编排图新节点 `security_check`(控制面校验/编译 + 边缘 Lua 特征检测 + 前端编辑器) +状态:已确认,待实现 + +## 背景 + +现有节点覆盖 IP / 地域 / UA / PoW,缺少请求载荷侧的基础攻击特征检测。产品需要在图中提供可编排的「安全防护」单元:多项基础规则可开关,**命中任意已启用规则返回 false**。 + +检测深度采用 **Lua 内置特征规则**(非 ModSecurity/CRS),能拦截常见扫描与明显 payload,允许有限误报/漏报。 + +## 目标 + +1. 新增 match 型节点 **`security_check`**,句柄 `true` / `false`。 +2. 属性栏分组:**安全防护**说明 + **基础防护** 9 项 Switch。 +3. 语义:**任一已启用规则命中 → false**;全部未命中 → true。 +4. 默认仅开启误报较低的两项:**路径穿越**、**文件包含**;其余默认关闭。 + +## 非目标(v1) + +- ModSecurity / OWASP CRS / libinjection 完整引擎 +- 响应侧 XSS 检测、机器学习 +- 自定义规则上传 / 严重级别评分 / 命中日志字段(可后续加) +- 无限制大 Body 全量扫描 + +## 节点模型 + +### 类型 + +| 字段 | 值 | +|------|-----| +| `type` | `security_check` | +| 句柄 | `true`, `false` | +| 可删除 / 可命名 / 可拖放 | 是 | + +### Config + +```json +{ + "sql_injection": false, + "path_traversal": true, + "command_injection": false, + "xss": false, + "ssrf": false, + "file_inclusion": true, + "malicious_upload": false, + "xxe": false, + "crlf_injection": false +} +``` + +| 字段 | 默认 | UI 文案 | 检测面(v1) | +|------|------|---------|--------------| +| `sql_injection` | false | SQL 注入 | Query、Body、Header、Cookie | +| `path_traversal` | **true** | 路径穿越防护 | Path、Query、Body | +| `command_injection` | false | 命令注入 | Query、Body、Header | +| `xss` | false | XSS | Query、Body、Header | +| `ssrf` | false | SSRF | Query、Body 中 URL 形态参数 | +| `file_inclusion` | **true** | 文件包含(LFI/RFI) | Path、Query、Body | +| `malicious_upload` | false | 恶意文件上传 | Multipart Body | +| `xxe` | false | XXE | Body(Content-Type 含 xml 时) | +| `crlf_injection` | false | CRLF 注入 | Header、Query、Body | + +全部关闭时:节点恒 **true**(空操作),合法。 + +## 求值语义 + +``` +inputs := collect_inspection_strings(request) // 见下 +for each enabled rule: + if rule_matches(rule, inputs) → return false +return true +``` + +- **false** = 命中攻击特征(接阻止) +- **true** = 未命中(接通过或其它节点) + +### 采集与限制 + +| 来源 | 方式 | +|------|------| +| Path | `ngx.var.uri`,URL 解码(含常见双重编码路径变体) | +| Query | `ngx.var.args` / `get_uri_args` 键与值 | +| Header | 请求头名+值(可排除 `Host` 等噪声,实现时固定白名单或全量) | +| Cookie | `Cookie` 头或 cookie 表 | +| Body | 仅当某已启用规则需要 Body,且 `Content-Length` 存在且 ≤ **65536**;否则跳过 Body 相关规则 | + +Body 读取失败:跳过 Body 类检测并限频 warn(可用性优先,不 fail-closed 整图)。 + +### 规则特征方向(v1 模式包) + +实现以可维护的模式表为准,下表为方向约束: + +1. **SQL 注入**:`union select`、`or 1=1`、`sleep(`、`benchmark(`、注释符、十六进制/char 拼接等 +2. **路径穿越**:`../`、`..\\`、`%2e%2e`、`%252e`、绝对路径探测 +3. **命令注入**:`;` `|` `` ` `` `$()` 结合 shell 关键字、换行拼接 +4. **XSS**:`