surinort-ast

用于 Suricata/Snort 规则的生产级 AST 解析与分析工具包

## 概述 **surinort-ast** 是一个 Python 工具包，用于解析、验证、序列化和分析来自 Suricata、Snort2 和 Snort3 的 IDS/IPS 规则。它提供了类型化 AST、CLI 工作流以及包括 JSON 和 SARIF 2.1.0 在内的机器可读输出。 ### 主要特性 | 特性 | 描述 | |---------|-------------| | **Typed AST** | 基于 Pydantic 的完整 AST，支持头部、选项和元数据 | | **Multi-dialect** | 支持 Suricata、Snort2 和 Snort3 | | **Validation** | 带有严重性级别的语法/语义诊断 | | **Serialization** | 支持 JSON 和 protobuf | | **SARIF 2.1.0** | 用于 Code Scanning 的解析/验证/分析结果导出 | | **CLI + Library** | 可作为命令行工具或 Python 包使用 | | **Coverage/Optimization Analysis** | 用于覆盖率和优化洞察的内置分析器 | | **Streaming Mode** | 针对大型规则集的高效内存解析 | ### 支持的输出 ``` AST Data JSON, protobuf Diagnostics Human-readable tables, SARIF 2.1.0 Analysis Text reports, SARIF 2.1.0 findings CI Integration SARIF artifact + GitHub Code Scanning upload ``` ## 安装 ### 从 PyPI 安装（推荐） ``` pip install surinort-ast ``` ### 从源码安装 ``` git clone https://github.com/seifreed/surinort-ast.git cd surinort-ast python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -e . ``` ### 可选扩展 ``` pip install "surinort-ast[all]" pip install "surinort-ast[serialization]" pip install "surinort-ast[analysis]" pip install "surinort-ast[cli-enhanced]" ``` ## 快速开始 ``` # 解析 rule 文件 surinort parse rules/local.rules # 使用 strict 模式验证 surinort validate rules/local.rules --strict # 导出解析结果到 SARIF surinort parse rules/local.rules --format sarif -o parse-results.sarif ``` ## 使用 ### 命令行界面 ``` # 解析为 JSON surinort parse rules/local.rules --json -o rules.json # 验证并导出 SARIF surinort validate rules/local.rules --format sarif -o validate-results.sarif # SARIF 中的统计和覆盖率结果 surinort stats rules/local.rules --format sarif -o stats-results.sarif ``` ### 可用选项（主要命令） | 命令 | 描述 | |--------|-------------| | `surinort parse` | 解析规则（`text`、`json`、`sarif`） | | `surinort validate` | 验证规则，支持可选严格模式和 SARIF 输出 | | `surinort stats` | 规则统计信息和可选 SARIF 覆盖率发现 | | `surinort fmt` | 规则文件的规范格式化 | | `surinort to-json` | 将规则转换为 JSON | | `surinort from-json` | 将 JSON 转换回规则文本 | | `surinort schema` | 打印 AST JSON schema | ### SARIF Flags | 选项 | 描述 | |--------|-------------| | `--format sarif` | 将 SARIF 内容作为命令输出打印 | | `--sarif-out ` | 写入 SARIF 报告，同时保持默认输出模式 | | `-o, --output ` | 将主要输出写入文件 | ## Python 库 ### 基本用法 ``` from surinort_ast import parse_rule, validate_rule, to_json rule = parse_rule('alert tcp any any -> any 80 (msg:"HTTP"; sid:1;)') diags = validate_rule(rule) print(to_json(rule)) for diag in diags: print(diag.level, diag.code, diag.message) ``` ### SARIF API 用法 ``` from surinort_ast import ( diagnostics_to_sarif, parse_file, validate_rule, ) rules = parse_file("rules/local.rules") diagnostics = [] for rule in rules: diagnostics.extend(validate_rule(rule)) sarif = diagnostics_to_sarif(diagnostics, default_file_path="rules/local.rules") with open("results.sarif", "w", encoding="utf-8") as f: f.write(sarif) ``` ### 其他 SARIF 辅助工具 ``` from surinort_ast import ( coverage_report_to_sarif, optimization_results_to_sarif, to_sarif, ) ``` ## CI 和 GitHub Code Scanning (SARIF) 项目 CI 现已支持 SARIF 生成和上传： 1. 从实际验证诊断生成 `results.sarif`。 2. 将 SARIF 作为 workflow artifact 上传。 3. 将 SARIF 上传至 GitHub Code Scanning。 最小化 workflow 示例： ``` - name: Generate SARIF report run: | python - <<'PY' from pathlib import Path from surinort_ast import diagnostics_to_sarif, parse_file, validate_rule fixture_path = Path("tests/fixtures/simple_rules.txt") rules = parse_file(fixture_path) diagnostics = [] for rule in rules: diagnostics.extend(validate_rule(rule)) Path("results.sarif").write_text( diagnostics_to_sarif(diagnostics, default_file_path=str(fixture_path)), encoding="utf-8", ) PY - name: Upload SARIF to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` ## 环境要求 - Python 3.11+ - 参见 [pyproject.toml](pyproject.toml) 以了解依赖和扩展 ## 许可证 本项目采用 GPL-3.0-or-later 许可证授权。详见 [LICENSE](LICENSE)。 **署名** - 作者：**Marc Rivero López** | [@seifreed](https://github.com/seifreed) - 仓库：[github.com/seifreed/surinort-ast](https://github.com/seifreed/surinort-ast)

_{专为实用的 IDS/IPS 规则工程和安全自动化而构建}

标签：AMSI绕过, DevSecOps, Homebrew安装, IPS, odt, Python, Siem集成, Suricata, 上游代理, 云安全监控, 云计算, 入侵检测系统, 威胁检测, 威胁检测与响应, 安全数据湖, 序列化, 抽象语法树, 文档结构分析, 无后门, 现代安全运营, 网络安全, 规则引擎, 规则解析, 规则验证, 逆向工具, 隐私保护, 静态分析