cognis-digital/injectguard

# injectguard **一个防御性检测规则调优实验室。** `injectguard` 是一个小巧的 CLI，它针对标记为良性和恶意的测试字符串**语料库**来评估你的**检测签名** （正则表达式规则），然后报告混淆矩阵指标 —— TP / FP / FN， precision、recall 和 F1 —— **提供总体和每个类别的数据**。它会告诉你哪些 恶意输入*逃避*了你的规则（假阴性），以及哪些良性输入 被*错误标记*（假阳性），这样你就可以**通过可测量的反馈来调优你的 WAF/IDS 检测规则**，而不是靠猜测。 ## 安装 / 构建 要求 Go 1.22+。 ``` git clone https://github.com/cognis-digital/injectguard cd injectguard go build -o injectguard . ``` 或者不安装直接运行： ``` go run . eval ``` ## 用法 ``` injectguard eval [flags] evaluate rules against a labeled corpus injectguard rules list the built-in starter rules injectguard corpus list the built-in labeled corpus injectguard help show help ``` ### `eval` 标志 | 标志 | 含义 | |------|---------| | `--rules PATH` | JSON 规则集（默认使用内置的入门规则） | | `--corpus PATH` | JSON 标记语料库（默认使用内置语料库） | | `--json` | 以 JSON 格式输出报告 | | `--show-fn` | 列出假阴性（逃避了所有规则的恶意输入） | | `--show-fp` | 列出假阳性（被错误标记的良性输入） | | `--fail-under-recall X` | 如果总体 recall < X (0..1) 则以非零状态退出 —— 用于 CI 门禁 | 如果你省略 `--rules`/`--corpus`，将使用内置的入门数据，因此你可以 立即试用： ``` injectguard eval injectguard eval --show-fn --show-fp injectguard eval --json ``` ### 输出示例 ``` injectguard evaluation rules: injectguard-starter-rules (10 rules) corpus: injectguard-starter-corpus (23 samples) overall: TP=12 FP=0 FN=1 TN=10 precision=1.000 recall=0.923 f1=0.960 category TP FP FN TN precision recall f1 ---------------------------------------------------------------- auth-bypass 4 0 0 3 1.000 1.000 1.000 sqli 4 0 1 4 1.000 0.800 0.889 xss 4 0 0 3 1.000 1.000 1.000 ``` 入门级的 `sqli` 类别有意包含**一次逃避** —— 带引号的重言式 `") or ("1"="1` 绕过了 `sqli-tautology`。运行 `injectguard eval --show-fn` 即可暴露它；弥补这个漏洞（将 规则扩展以允许带引号的操作数）是经典的首次调优练习。 ## 文件格式 **规则集** —— 每条规则对应一个正则表达式 `pattern`，按 `category` 分组。模式匹配 不区分大小写。 ``` { "name": "my-rules", "rules": [ { "id": "sqli-union-select", "category": "sqli", "severity": "high", "pattern": "\\bunion\\b[\\s\\S]{0,40}?\\bselect\\b" } ] } ``` **语料库** —— 带标记的输入。`malicious: true` 表示该输入*应该* 被至少一条规则检测到；`false` 表示应将其忽略。 ``` { "name": "my-corpus", "samples": [ { "id": "m1", "category": "sqli", "malicious": true, "text": "1' UNION SELECT pw FROM users" }, { "id": "b1", "category": "sqli", "malicious": false, "text": "union representatives met today" } ] } ``` 可直接编辑的示例位于[`examples/`](examples/)。 ## 指标的定义方式 *阳性*预测意味着规则集标记了某个样本（≥1 条规则匹配）。 | | 预测为阳性 | 预测为阴性 | |---|---|---| | **实际为恶意** | TP | FN (逃避) | | **实际为良性** | FP (噪声) | TN | - `precision = TP / (TP + FP)` — 当没有预测出阳性结果时，precision 报告为 `1.0`。 - `recall = TP / (TP + FN)` — 当不存在实际的阳性结果时，recall 报告为 `1.0`。 - `f1 = 2·precision·recall / (precision + recall)` — 当两者均为 `0` 时为 `0`。 ## 调优工作流 1. 从你当前的规则和包含真实良性及恶意形态的语料库开始。 2. 运行 `injectguard eval --show-fn --show-fp`。 3. **假阴性**显示了逃避情况 → 为该类别添加或拓宽规则。 4. **假阳性**显示了存在噪声的规则（通过 `matched-by` 标识）→ 收紧这些规则。 5. 重新运行；观察每个类别的 recall 上升且 precision 保持稳定。 6. 将 `--fail-under-recall 0.8` 接入 CI，这样覆盖率的回归就会导致构建失败。 ## CI 当总体 recall 降至 `X` 以下时，`injectguard eval --fail-under-recall X` 将以非零状态（代码 `3`）退出，因此你可以对规则更改进行门禁控制： ``` - run: go run . eval --rules rules.json --corpus corpus.json --fail-under-recall 0.8 ``` 请参阅[`.github/workflows/ci.yml`](.github/workflows/ci.yml) 了解本项目自身的 构建 + 测试 + 自检门禁。 ## 退出代码 | 代码 | 含义 | |------|---------| | `0` | 成功 | | `1` | 运行时错误（文件错误/缺失、无效的规则集或语料库） | | `2` | 用法错误（未知命令 / 错误标志） | | `3` | 触发 recall 门禁 (`--fail-under-recall`) | ## 开发 ``` go build ./... go test ./... go vet ./... ``` 仅使用标准库（使用 `regexp`、`encoding/json`、`flag`）。 ## 许可证 许可证：COCL 1.0 ## 维护者 Cognis Digital

标签：EVTX分析, Go, Homebrew安装, Ruby工具, WAF/IDS, 性能评估, 文档结构分析, 日志审计, 规则调优