VedantBist/suricata-validation-engine

# suricata-validation-engine 用于 Suricata IDS/IPS 规则的生产级验证引擎，基于传统的 Flex（词法分析）和 Bison（语法分析）构建，支持基于 CFG 的语法分析、分层语义验证器、panic 模式错误恢复，以及编译器级的结构化诊断信息。 该引擎能够通过单次流式处理验证大型规则文件（10,000+ 条规则），在遇到格式错误的规则时会进行恢复而不是终止运行，并报告能够感知解析器状态的诊断信息： ``` Rule #3 | Line 3, Col 11 | SYNTAX ERROR Expected: SrcIP Found: -> Source IP missing after protocol Acceptable tokens here: any, !, [, IP address, CIDR block, variable Rule #7 | Line 7 | SEMANTIC ERROR Field: DstPort Value: 70000 Destination port exceeds the valid range (1-65535) TCP/UDP ports are 16-bit values from 1 to 65535 ``` ## 支持的规则语言 ``` alert tcp !$HOME_NET [1:1024,!80] -> [10.0.0.1,192.168.1.0/24] [80,443,8080] (msg:"..."; sid:1001; rev:2;) ``` - 动作 `alert|drop|pass`，协议 `tcp|udp|icmp`，方向 `->|<>` - 地址：IP、CIDR、`$VARIABLES`、`any`、取反 (`!X`, `![...]`，针对元素的 `[a,!b]`)、括号列表 - 端口：单个端口、范围 (`1:1024`, `1024:`, `:65535`)、取反、列表 - 选项：`msg`, `sid`, `rev`, `content` (`key:value;` 块) 语义检查：IPv4 八位组范围、CIDR 前缀、端口边界与范围排序、重复/被包含的列表条目、sid 规范（存在、唯一、数值型、正数、全文件唯一）、rev 类型、空字符串、未知选项键、协议/端口一致性。警告（例如 icmp 上的端口）会在不影响规则有效性的情况下显示。 ## 构建 要求 flex 和 bison ≥ 3.6（macOS：`brew install bison`；Makefile 会自动优先使用 Homebrew 安装的版本，而不是古老的系统自带 bison 2.3）。 ``` make # debug build (UBSan) -> build/bin/suricata-validate make release # optimized build make test # golden-file suite STRESS=1 make test # + 10k-rule stress tiers (invariants, JSON, leaks, # corruption-heavy recovery, determinism) ``` ## 用法 ``` suricata-validate rules.txt # full validation (default) suricata-validate rules.txt --json # machine-readable report suricata-validate rules.txt --summary # one summary line suricata-validate rules.txt --quiet # diagnostics + summary, no verdicts suricata-validate rules.txt --max-errors 50 # fail-fast after 50 errors suricata-validate rules.txt --syntax-only # structural lint, semantics off suricata-validate rules.txt --timing # timing/throughput on stderr suricata-validate --dump-tokens rules.txt # lexer inspection ``` 退出代码：`0` 正常 · `1` 发现违规 · `2` 引擎/用法错误。 使用 `-` 从 stdin 读取。Debug 构建版本接受 `SV_PARSER_TRACE=1` 以输出完整的移进/归约/恢复追踪。 ### JSON schema (v1) ``` { "tool": "suricata-validate", "schema_version": 1, "mode": "validate", "stopped_early": false, "summary": { "total_rules": 10000, "valid_rules": 9581, "syntax_invalid": 189, "semantic_invalid": 230, "errors": 419, "warnings": 0, "lexical_errors": 0, "lines": 11164 }, "diagnostics": [ { "rule": 34, "line": 34, "category": "SEMANTIC", "severity": "ERROR", "field": "DstPort", "value": "70000", "message": "Destination port exceeds the valid range (1-65535)", "explanation": "TCP/UDP ports are 16-bit values from 1 to 65535" } ] } ``` 可选字段（`column`, `expected`, `found`, `field`, `value`, `explanation`）会在适用时出现。输出是确定性的：相同的输入会产生字节完全相同的报告。 ## 工程不变性 以下属性由测试套件强制执行，而不仅仅是文档说明： - **零语法冲突** — bison 在运行时添加 `-Werror`；出现冲突会导致构建失败。 - **基于行尾的恢复** — 格式错误的规则会被直接丢弃至其行尾，记录确切的一条语法诊断信息，并且下一条规则的解析不受影响。恢复过程不会跨越行边界。 - **流式处理** — 一次只保留一条规则；唯一的跨规则状态是 sid 注册表（sid → 首次出现位置）。内存占用受诊断信息限制，绝不受文件大小影响。 - **单向所有权** — 词素 → 元素 → 容器 → Rule；解析器析构函数每次只释放一层，因此 panic 恢复和提前终止都不会造成内存泄漏（已通过在大量损坏数据压力下的堆检查验证）。 - **语法/语义分离** — 解析器根据自身的表判断结构（`parse.error custom` + LAC）；验证器根据 Rule 对象判断语义；两者互不干涉。 - **统计核算** — `valid + syntax-invalid + semantic-invalid == total`（引擎每次运行都会进行自检；违规时以退出代码 2 终止）。 ## 目录结构 | 路径 | 职责 | |------|----------------| | `src/core/` | CLI、运行编排、调度接缝、退出代码 | | `src/lexer/` | Flex 词法分析 + 位置追踪（负责分类，不负责判断） | | `src/parser/` | Bison 语法、错误恢复、Expected/Found 捕获 | | `src/models/` | Rule、Endpoint/PortSpec 容器、Option、Diagnostic、上下文 | | `src/semantic/` | 验证器遍历 + sid 注册表（负责语义，不负责结构） | | `src/diagnostics/` | 诊断信息收集、故障表、所有说明文本 | | `src/reporting/` | 文本 + JSON 渲染器、摘要引擎 | | `src/utils/` | 通用辅助工具，零项目耦合 | | `tests/` | Golden 测试套件：lexer / parser / semantic / cli + 压力测试层级 | | `docs/` | [架构](docs/ARCHITECTURE.md) · [路线图](docs/ROADMAP.md) · [语法日志](docs/GRAMMAR.md) | 完整的设计原理：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

标签：Flex/Bison, IDS/IPS, 云安全监控, 客户端加密, 编译器, 规则验证, 静态分析