lumen-argus/crossfire

# Crossfire [](https://github.com/lumen-argus/crossfire/actions/workflows/test.yml) [](https://pypi.org/project/crossfire-rules/) [](https://pypi.org/project/crossfire-rules/) [](https://codecov.io/gh/lumen-argus/crossfire) [](https://github.com/lumen-argus/crossfire/blob/main/LICENSE) **在重复警报产生之前，发现重复和重叠的正则表达式规则。** 如果您维护用于密钥扫描、DLP、SAST、YARA 或 IDS 的检测规则——您可能有一些规则会对相同的输入触发。Crossfire 能找到它们。 ``` $ crossfire scan my_rules.json ======================================================================== Crossfire Analysis Report Rules: 142 from 1 file(s) | Corpus: 4,260 strings | Time: 3.2s ======================================================================== Duplicates (3 pairs) Rule A Rule B Jaccard Recommendation aws_key_v1 aws_key_v2 1.00 Keep A slack_hook slack_webhook_url 0.94 Keep A npm_token npm_auth_token 1.00 Keep A Subsets (5 pairs) Subset Rule Superset Rule A->B % stripe_sk_live generic_secret 98% github_pat_v2 github_token 100% Quality Insights Broad patterns (2): generic_secret overlaps with 15 rules email overlaps with 27 rules Summary: Drop 7 rules, review 3, 2 broad patterns ``` ## 问题所在 检测规则集会随时间增长。不同的团队成员独立添加规则。您从上游项目合并规则。最终会导致： - 多个规则匹配同一个密钥（重复的发现） - 像 `generic_secret` 这样宽泛的规则，静默地覆盖了特定规则已经捕获的内容 - 没人知道删除哪些规则不会破坏覆盖率 **现有的工具无法解决这个问题。** 对于现实世界的模式（锚点、 lookahead、反向引用），正则表达式等价性是不可判定的。YARA 去重工具只能找到完全匹配项。密钥扫描器在输出层面处理重复项——这太晚了。 ## Crossfire 的工作原理 Crossfire 使用**基于语料库的方法**：从每个规则的正则表达式生成合成字符串，针对每个字符串测试每一条规则，并根据经验测量重叠情况。 ``` Load rules → Validate regexes → Generate test strings → Cross-evaluate → Classify → Report ``` 这能处理 Python 支持的任何正则表达式特性——锚点、lookahead、反向引用、Unicode。没有结构分析的限制。 ## 安装 ``` pip install crossfire-rules ``` 若要在大型规则集上获得**快 10-100 倍的正则匹配速度**，请安装 RE2 支持： ``` # macOS brew install re2 pip install crossfire-rules[re2] # Ubuntu/Debian sudo apt-get install -y libre2-dev pip install crossfire-rules[re2] ``` RE2 是可选的——没有它，Crossfire 使用 Python 标准库 `re` 也能正常工作。RE2 加速了不使用反向引用或 lookahead 的模式（大多数 DLP/密钥扫描规则）。不兼容的模式会自动逐个回退到 `re`。 或者从源码安装： ``` git clone https://github.com/lumen-argus/crossfire.git cd crossfire pip install -e . ``` 需要 Python 3.11+。 ## 命令 ### Scan —— 查找文件内的重复项 ``` crossfire scan rules.json ``` “我有冗余规则吗？” ### Compare —— 查找文件间的重叠 ``` crossfire compare community.json pro.json vendor_rules.json ``` “哪些规则在我的规则集之间重叠？” ### Validate —— 检查正则表达式语法 ``` crossfire validate rules.json ``` “我的所有正则表达式都有效吗？” 快速——不生成语料库，仅进行语法检查。 ### Evaluate —— 针对真实数据测试规则 ``` # 针对 JSONL 语料库进行测试 crossfire evaluate rules.json --corpus chat_logs.jsonl # 针对 git 历史记录进行测试 crossfire evaluate-git rules.json --repo /path/to/repo --max-commits 500 ``` “哪些规则实际上会在真实数据上触发？哪些规则会在同一输入上共同触发？” 如果您的语料库有标签，Crossfire 会计算每个规则的精确率、召回率和 F1： ``` {"text": "AKIAIOSFODNN7EXAMPLE", "label": "aws_key"} {"text": "xoxb-123-456-abc", "label": "slack_token"} ``` ### Diff —— 比较不同环境下的规则行为 ``` crossfire diff rules.json --corpus-a production.jsonl --corpus-b staging.jsonl ``` “我的规则在不同环境下的行为是否不同？” 标记匹配率差异超过 5% 的规则。 ## 支持的格式 Crossfire 根据文件内容自动检测格式——只需传递文件： ``` crossfire compare gitleaks.toml semgrep.yaml yara_rules.yar community.json ``` | 格式 | 扩展名 | 工具 | |--------|-----------|------| | JSON | `.json` | 任意（原生格式，自定义规则） | | YAML | `.yaml`, `.yml` | 任意 | | CSV | `.csv` | 任意（`name` 和 `pattern` 列） | | GitLeaks | `.toml` | [GitLeaks](https://github.com/gitleaks/gitleaks) | | Semgrep | `.yaml` | [Semgrep](https://semgrep.dev)（`pattern-regex` 规则） | | YARA | `.yar`, `.yara` | [YARA](https://virustotal.github.io/yara/)(正则表达式字符串) | | Sigma | `.yaml` | [Sigma](https://sigmahq.io)(`\|re` 修饰符字段) | | Snort/Suricata | `.rules` | [Snort](https://www.snort.org) / [Suricata](https://suricata.io)(`pcre` 模式) | ### 自定义字段名称 如果您的规则使用不同的字段名称： ``` crossfire scan rules.json --field-mapping '{"name": "rule_id", "pattern": "regex"}' ``` 默认映射：`name`/`id`/`rule_name` 和 `pattern`/`regex`/`regexp`。 ## 使用案例 ### 审计规则集的冗余情况 随着时间的推移，检测规则会从不同来源积累——手写、从供应商导入、从开源项目合并。运行扫描以查找冗余内容： ``` crossfire scan all_rules.json --format table ``` 丢弃零唯一覆盖率的规则。审查与许多特定规则重叠的宽泛模式。 ### 比较社区规则与商业规则 如果您同时维护免费和付费的规则集，请在发布前检查重叠情况： ``` crossfire compare community.json pro_rules.json --fail-on-duplicate ``` 使用 JSON 报告在构建流水线中自动化排除——用基于重叠的去重取代基于名称的去重。 ### 在 CI 中防止重复规则 将 Crossfire 添加到您的 CI 流水线，以便重复现有规则的新规则会导致构建失败： ``` crossfire compare rules/*.json --fail-on-duplicate --format summary ``` 或者使用 pre-commit hook 在提交之前捕获重复项。 ### 跨工具规则比较 从 GitLeaks 迁移到 Semgrep？从威胁情报源合并 YARA 规则？跨格式比较： ``` crossfire compare gitleaks.toml semgrep_rules.yaml vendor_yara.yar ``` 找出哪些规则已经被覆盖，哪些是每个工具独有的。 ### 验证来自第三方来源的规则 在从外部来源导入规则之前，检查它们是否有效且没有重复您已有的内容： ``` # 首先进行语法检查 crossfire validate vendor_rules.json # 然后检查与现有规则的冲突 crossfire compare your_rules.json vendor_rules.json ``` ### 针对真实数据测试规则 合成重叠分析告诉您规则*可能*会共同触发。真实语料库测试告诉您它们*确实*会： ``` # 针对真实结果的 JSONL 语料库进行测试 crossfire evaluate rules.json --corpus production_samples.jsonl # 针对仓库的 git 历史记录进行测试 crossfire evaluate-git rules.json --repo /path/to/repo --max-commits 500 ``` 查看哪些规则实际触发，哪些在同一输入上共同触发，哪些从未触发。 ### 使用标记数据衡量规则质量 如果您有标记的测试数据，Crossfire 会计算每个规则的精确率、召回率和 F1： ``` crossfire evaluate rules.json --corpus labeled_test_data.jsonl ``` 语料库格式——每行一个 JSON 对象，包含 `text` 和 `label` 字段： ``` {"text": "AKIAIOSFODNN7EXAMPLE", "label": "aws_key"} {"text": "xoxb-123-456-abcdef", "label": "slack_token"} {"text": "not a secret at all", "label": ""} ``` ### 检测跨环境的覆盖率漂移 在生产环境与预发布环境中行为不同的规则可能表明存在特定于环境的问题： ``` crossfire diff rules.json --corpus-a production.jsonl --corpus-b staging.jsonl ``` ## 输出格式 ``` crossfire scan rules.json --format table # Human-readable (default) crossfire scan rules.json --format json # Machine-readable for CI crossfire scan rules.json --format csv # Spreadsheet-friendly crossfire scan rules.json --format summary # One-line summary ``` JSON 输出包含每次重叠测量的置信区间（95% Wilson 得分 CI）和每规则质量指标。 ## 关系类型 Crossfire 对每对规则进行分类： | 关系 | 含义 | 示例 | |-------------|---------|---------| | **Duplicate** (重复) | 两个规则彼此匹配 >80% 的测试字符串 | `aws_key_v1` 和 `aws_key_v2` | | **Subset** (子集) | 规则 A 匹配规则 B 匹配的所有内容，但反之不然 | `stripe_sk_live` 是 `generic_secret` 的子集 | | **Overlap** (重叠) | 部分共同触发 (20-80%) —— 值得调查 | `github_token` 和 `generic_api_key` | | **Disjoint** (不相交) | 无明显重叠 | `aws_key` 和 `email_address` | ### 建议 - **Duplicate**：丢弃优先级较低的规则（如果优先级相同则进行审查） - **Subset**：超集规则覆盖所有内容——考虑特定规则是否增加价值 - **Overlap**：人工审查——可能是有意的 优先级由文件顺序（第一个文件 = 最高）或显式的 `--priority` 确定： ``` crossfire compare --priority "curated.json=100,community.json=80,generated.json=50" \ curated.json community.json generated.json ``` ## 质量洞察 除了成对重叠之外，Crossfire 还单独评估每条规则： - **Specificity** (特异性)：此规则是否匹配随机字符串？低特异性 = 过于宽泛 - **Unique coverage** (唯一覆盖)：是否有任何测试字符串*仅*匹配此规则？零 = 完全冗余 - **Broad pattern detection** (宽泛模式检测)：标记与 5 个以上其他规则重叠的规则 - **Pattern complexity** (模式复杂性)：正则表达式 AST 节点数（仅供参考） ## 快速失败验证 默认情况下，Crossfire 在遇到第一个无效正则表达式时立即失败： ``` $ crossfire scan rules.json ERROR: Rule 'broken_rule' has invalid regex: unbalanced parenthesis at position 12 Pattern: [a-z(+ File: rules.json, entry 47 Fix the pattern and retry. Use --skip-invalid to analyze remaining rules anyway. ``` 使用 `--skip-invalid` 即使遇到损坏的规则也继续运行（适用于您无法修复的第三方规则集）： ``` crossfire scan vendor_rules.json --skip-invalid ``` ## CI 集成 ### GitHub Action ``` - uses: lumen-argus/crossfire@v1 with: rules: rules/*.json threshold: "0.8" fail-on-duplicate: "true" ``` ### Pre-commit Hook ``` repos: - repo: https://github.com/lumen-argus/crossfire rev: v0.1.0 hooks: - id: crossfire-scan args: ["--format", "summary", "--samples", "30"] - id: crossfire-validate ``` ### 任何 CI 流水线 ``` pip install crossfire-rules crossfire compare rules/*.json --fail-on-duplicate --format summary ``` 退出代码：`0` = 干净，`1` = 发现重复项 (`--fail-on-duplicate`)，`2` = 输入错误，`3` = 运行时错误。 ## 选项参考 | 标志 | 默认值 | 描述 | |------|---------|-------------| | `--threshold` | `0.8` | 分类为重复的重叠百分比 (0.0-1.0) | | `--samples` | `50` | 每个规则生成的测试字符串 | | `--seed` | None | 用于可重复结果的随机种子 | | `--workers` | auto | 并行评估工作线程 (或 `CROSSFIRE_WORKERS` 环境变量) | | `--format` | `table` | 输出：`table`, `json`, `csv`, `summary` | | `--output` | stdout | 将报告写入文件 | | `--skip-invalid` | off | 跳过损坏的正则表达式而不是失败 | | `--fail-on-duplicate` | off | 如果发现重复项则退出代码为 1 | | `--partition-by` | None | 仅比较具有相同字段值的规则 (例如 `detector`) | | `--priority` | 按文件顺序 | `file.json=100` 优先级映射 | | `--log-level` | `warning` | `debug`, `info`, `warning`, `error` | | `--log-file` | None | 将日志写入文件 | | `--log-format` | `text` | `text` 或 `json` (结构化) | ## 配置文件 所有选项都可以在 `crossfire.yaml` 中设置： ``` threshold: 0.8 samples_per_rule: 50 seed: 42 workers: 8 format: json fail_on_duplicate: true log_level: warning ``` ## 性能 在 1,537 条规则上测试（每条规则 50 个样本，Docker）： | 步骤 | 时间 | |------|------| | 加载 + 验证 | <1s | | 生成语料库 (并行) | ~5s | | 交叉评估 (83M 次正则匹配) | ~2s | | 分类 + 质量评估 | <1s | | **总计** | **~8s** | 在 Linux 上，Crossfire 使用基于 `fork` 的 worker，通过写时复制继承预编译的模式——零序列化和重新编译开销。在 macOS/Windows 上，基于 spawn 的 worker 从字符串重新编译模式。 ## 贡献 有关开发设置、编码标准以及如何添加格式适配器，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MIT - 详情见 [LICENSE](LICENSE)。

标签：DevSecOps, DLP, Homebrew安装, Python, Python安全, SAST, YARA, 上游代理, 云安全监控, 云资产可视化, 入侵检测系统, 告警疲劳, 安全数据湖, 安全策略, 提示词设计, 无后门, 盲注攻击, 秘密扫描, 规则优化, 规则重叠, 误报减少, 逆向工具, 静态分析, 静态应用安全测试