maxias13/snort_2_validator
GitHub: maxias13/snort_2_validator
基于官方手册的 Snort 2 规则静态验证与优化工具，零依赖纯 Python 实现，提供 20 项语法检查、6 项性能优化建议及量化的规则成本评分。
Stars: 0 | Forks: 0
# snort_2_validator
一个深入、带有主观色彩的 **Snort 2 规则验证器 + 优化器** —— 支持内置 (Talos VRT) 和本地规则。基于纯 Python 的静态分析，以及可选的 `snort -T` 动态检查。以官方 [Snort 手册第 3 章](http://manual-snort-org.s3-website-us-east-1.amazonaws.com/node27.html) 为依据。
设计为 [Claude Code / OpenCode 技能](https://docs.anthropic.com/)，但其 CLI 可以在任何安装了 Python 3.8+ 的环境中运行。
## 功能
- **宽容的规则解析器** —— 处理行连续符 (`\`)、十六进制 `content:"|AA BB|"`、转义引号、所有 8 种动作 (`alert/log/pass/activate/dynamic/drop/reject/sdrop`)、所有 4 种协议 (`tcp/udp/icmp/ip`)。
- **20 项静态检查** (`S001`–`S020`) 覆盖语法、必需选项、SID 策略、已弃用选项、fast_pattern 规范、classtype 存在性、pcre 可编译性、content/pcre 顺序、depth/offset/within/distance 正确性。
- **6 项优化检查** (`O001`–`O006`) 及其量化的**成本分数** (≥15 = 高成本)。
- **动态验证** 通过带有**优雅降级机制** 的 `snort -T` 包装器实现 (即使未安装 snort，该技能仍然可以正常运行)。
- **3 种输出格式**: 彩色文本 (支持 NO_COLOR)、JSON、独立 HTML (支持暗黑模式)。
- 对每项发现提供**手册交叉引用** (例如 `§3.5.7 fast_pattern`)。
- 零运行时依赖 —— 仅使用 Python stdlib。
## 安装
```
git clone https://github.com/maxias13/snort_2_validator.git
cd snort_2_validator
python3 scripts/snort2val.py --help
```
作为 Claude/OpenCode 技能，只需将目录放置在 `~/.claude/skills/snort_2_validator/` (或你项目的 `.claude/skills/`) 下，代理将通过 `SKILL.md` 前置元数据自动发现它。
## CLI 使用方法
```
# Static validation（无需 snort binary）
python3 scripts/snort2val.py validate path/to/local.rules
# Optimization 建议
python3 scripts/snort2val.py optimize path/to/local.rules
# Dynamic check（需要在 PATH 中包含 snort 2 或指定 --snort-bin=）
python3 scripts/snort2val.py dynamic path/to/snort.conf
# Everything（static + optimize + dynamic）
python3 scripts/snort2val.py all path/to/rules_or_conf
# Output 格式
python3 scripts/snort2val.py validate file.rules --format json
python3 scripts/snort2val.py validate file.rules --format html > report.html
```
**退出码:** `0` 干净通过 · `1` 至少有一个 ERROR 级别的发现 · `2` 调用错误。
## 静态检查矩阵 (S001–S020)
| ID | 严重度 | 捕获内容 | 手册 § |
|-------|----------|----------------------------------------------------------------|-----------------|
| S001 | error | 头部解析失败 (action/proto/src/sport/dir/dst/dport) | §3.2 |
| S002 | error | 缺少必需的 `sid:` | §3.4.4 |
| S003 | warn | 缺少 `rev:` | §3.4.5 |
| S004 | warn | 缺少 `msg:` | §3.4.1 |
| S005 | warn | 缺少 `classtype:` | §3.4.6 |
| S006 | error | `sid` < 100 (保留) 或超出 int 范围 | §3.4.4 |
| S007 | error | 规则集中存在重复的 `sid` | §3.4.4 |
| S008 | warn | 无 `content/uricontent/pcre` —— 规则将匹配每个数据包 | §3.9.1 |
| S009 | warn | `content` 长度为 0 | §3.5.1 |
| S010 | error | 十六进制 `content:"|...|"` 的半字节计数为奇数 | §3.5.1 |
| S011 | warn | `fast_pattern` content 短于 4 个字节 | §3.5.7 |
| S012 | warn | `depth` < `content` 长度 (不可能匹配) | §3.5.3 |
| S013 | warn | `within` < `content` 长度 | §3.5.5 |
| S014 | warn | `nocase` 放置在任何 `content` 之前 | §3.5.2 |
| S015 | warn | 已弃用的 `threshold:` 规则选项 | §3.8 |
| S016 | error | 未知的 `classtype` (不在 classification.config 默认值中) | §3.4.6 |
| S017 | warn | `flowbits:set` 没有在任何地方匹配到 `flowbits:isset` | §3.6.10 |
| S018 | info | `pcre` 位于所有 `content` 之前 (慢速路径) | §3.9.4 |
| S019 | info | any/any 头部 + 弱 content | §3.9.4 |
| S020 | error | `pcre:` 正则表达式编译失败 | §3.5.13 |
## 优化矩阵 (O001–O006)
| ID | 建议内容 | 手册 § |
|-------|---------------------------------------------------------------------------|----------|
| O001 | 将最长的唯一 content 提升为 `fast_pattern` | §3.5.7 |
| O002 | 重新排序，使所有 `content` 检查优先于 `pcre` | §3.9.4 |
| O003 | 在方向明确的地方添加 `flow:established,to_server` (或 `to_client`)| §3.6.10 |
| O004 | 使用 `$HOME_NET` / 特定端口替换 `any/any` 头部 | §3.9.4 |
| O005 | 将已弃用的 `threshold:` 迁移为 → `detection_filter:` | §3.8 |
| O006 | 规则成本分数 ≥ 15 —— 结合了 O001..O004 | §3.9.4 |
**成本分数公式** (越高 = 越差):
```
10 * has_pcre
+ 5 * no_fast_pattern
+ 5 * any_any_header
+ 4 * no_flow
+ 3 * fast_pattern_shorter_than_4_bytes
+ 2 * content_after_pcre
+ 1 * no_classtype
```
## 示例
`examples/good.rules` —— 干净的参考规则。`examples/bad.rules` —— 触发所有 S 检查。`examples/expected_output.txt` —— 针对 `bad.rules` 执行 `all` 子命令的基准输出。
```
$ python3 scripts/snort2val.py validate examples/good.rules
snort_2_validator errors=0 warnings=0 info=0
$ python3 scripts/snort2val.py validate examples/bad.rules
snort_2_validator errors=3 warnings=7 info=1
[ERROR] sid:? examples/bad.rules:5 S002 rule missing required `sid` (§3.4.4)
[WARN] sid:? examples/bad.rules:5 S003 rule missing `rev` (§3.4.5)
...
[ERROR] sid:1000010 examples/bad.rules:27 S020 pcre fails to compile (§3.5.13)
```
## 项目布局
```
snort_2_validator/
├── SKILL.md # Skill entrypoint (frontmatter + workflow)
├── README.md # This file
├── references/
│ ├── rule_grammar.md # Header + body grammar (Ch. 3.2, 3.3)
│ ├── rule_options_spec.md # Every option with arity / type / manual §
│ ├── best_practices.md # Derived from §3.9 Writing Good Rules
│ └── deprecations.md # threshold → detection_filter migration
├── scripts/
│ ├── parser.py # Tolerant rule AST (Rule/Header/Option)
│ ├── validator.py # S001..S020 + DEFAULT_CLASSTYPES
│ ├── optimizer.py # O001..O006 + cost_score()
│ ├── dynamic.py # `snort -T` wrapper, graceful absence
│ ├── report.py # text / json / html renderers
│ └── snort2val.py # CLI entrypoint
└── examples/
├── good.rules
├── bad.rules
└── expected_output.txt
```
## 设计说明
- **不逐字复制手册。** 所有引用均源自结构化规范，并会引用 Snort 手册的相应章节，以便操作人员直接进行验证。
- **SID 策略:** `< 100` 为保留，`100–999,999` 属于 Talos VRT，`≥ 1,000,000` 为本地/用户 (如果本地规则使用 < 1M 则会发出警告)。
- **Classtype 范围:** 源自 `classification.config` 的内置默认值；用户可以通过 `--classtypes-file=` 进行扩展。
- **动态检查是可选的。** 如果 `snort` 不在 PATH 中，静态 + 优化检查仍会运行，而动态步骤仅打印一行信息。
- **建议是非破坏性的。** `optimize` 仅进行打印输出；目前有意 **未** 实现 `--apply` 重写模式，以避免静默修改生产环境的规则集。
## 手册交叉引用
每项发现的 `manual_ref` 字段均指向 [Snort 手册第 3 章](http://manual-snort-org.s3-website-us-east-1.amazonaws.com/node27.html) 的特定小节：
- §3.2 规则头部 (Rule Headers)
- §3.4 通用规则选项 (`msg`, `sid`, `rev`, `classtype`, `priority`, `metadata`, `reference`)
- §3.5 负载检测 (`content`, `nocase`, `depth`, `offset`, `within`, `distance`, `fast_pattern`, `pcre`, `byte_test`, `byte_jump`, ...)
- §3.6 非负载检测 (`flow`, `flowbits`, `dsize`, `flags`, `ttl`, `ip_proto`, ...)
- §3.7 后检测 (`detection_filter`, `tag`, `replace`, ...)
- §3.8 规则阈值 (已弃用)
- §3.9 编写良好规则 (`§3.9.1`–`§3.9.5`)
## 贡献
欢迎提交 PR。请：
1. 运行 `python3 -m compileall scripts/` (必须干净通过)。
2. 为任何新检查向 `examples/bad.rules` 中添加触发规则。
3. 重新生成 `examples/expected_output.txt`:
python3 scripts/snort2val.py all examples/bad.rules > examples/expected_output.txt
4. 在检查的 `manual_ref` 中引用相关的 Snort 手册章节。
## 许可证
MIT
标签：AMSI绕过, Claude, CVE检测, fast_pattern, Linux安全, PB级数据处理, PCRE, Python, SecOps, Snort 2, Snort Manual, Talos, VRT, 云安全架构, 云安全监控, 代码分析, 入侵检测系统, 凭证管理, 威胁检测, 安全数据湖, 安全策略, 安全脚本, 安全运维, 提示词设计, 无后门, 深度包检测, 网络安全, 网络安全分析, 网络流量分析, 规则优化, 规则验证, 语法检查, 隐私保护, 静态分析