Detect-Forge/detect-forge

# Detect-Forge AI 原生检测工程工具包。一次安装，一份配置，一个 CI 步骤。 ## 概述 Detect-Forge 是一个面向检测工程师的可组合 CLI。每一项功能都是一个子命令；它们共享配置、输出格式、缓存和单一的 CI 门控。无需平台，无需注册。 首个发布的功能是 `stale` —— 它会根据三个维度为您的 Sigma (YAML) 和 Elastic Detection Rules (TOML — 涵盖 EQL、KQL 和 ESQL) 评估 ATT&CK 技术的过时程度： 1. **时间戳漂移** — 将 ATT&CK STIX 的 `modified` 时间戳与规则修改日期进行比较（确定性）。 2. **语义对齐** ✅ — 基于嵌入的余弦相似度，在规则文本（标题 + 描述）和当前 ATT&CK 技术描述之间进行计算。标记对齐度低于可配置阈值（`--semantic-threshold`，默认为 0.65）的规则。真正的历史漂移（与过去的 MITRE 定义进行比较）属于阶段 3.b。 3. **LLM 差异提案** ✅ — 选择性启用，通过 OpenAI 结构化输出实现 BYOLLM；为 `semantic_drift` 发现提供重写规则的建议。绝不自动应用 —— 每个提案都需人工审查。Anthropic Claude 的支持已推迟至 v0.2。 旨在作为 CI 门控在 GitHub Actions 中运行。不会有任何数据离开您的环境。 ## 状态 🚀 2026 年 5 月 23 日发布 — `stale` 携带所有三个评分维度一同发布：时间戳漂移、语义漂移（阶段 3.a）和 LLM 差异提案（阶段 4）。真正的历史漂移（阶段 3.b）已推迟至 v0.2。其他子命令（`backtest`、`coverage`、`cti ingest`、`audit`）已作为存根注册，将在后续版本中发布。 ## 要求 - Python **3.12** 或更新版本 ## 安装 ``` python3.12 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` ## 用法 ``` detect-forge --help detect-forge --version detect-forge stale path/to/rules ``` ### 子命令 | 命令 | 状态 | 描述 | |---|---|---| | `stale` | ✅ 可用 | 为检测规则的 ATT&CK 技术过时程度评分。 | | `backtest` | 📅 2026 年 6 月 28 日 | 对抗性重放（类型 3 + 4）。 | | `coverage` | 📝 2026 年第三季度 | 覆盖率缺口映射（类型 6a 扩展）。 | | `cti ingest` | 📝 2026 年第三至第四季度 | CTI 到检测的生成。 | | `audit` | 📝 已保留 | 一旦发布 2 个或更多子命令，即运行所有检查。 | ### `stale` 选项 | 选项 | 默认值 | 描述 | |---|---|---| | `RULE_DIR` (位置参数) | — | 要扫描的检测规则目录。递归选取 `.yml`/`.yaml` (Sigma) 和 `.toml` (Elastic Detection Rules: EQL/KQL/ESQL)。必须存在。 | | `--format {terminal,json,html}` | `terminal` | 输出格式。 | | `-o, --output PATH` | _stdout_ | 将输出写入文件而不是标准输出。 | | `--min-severity {low,medium,high,critical}` | `low` | 仅显示达到或超过此严重级别的规则。 | | `--no-cache` | 关闭 | 绕过磁盘缓存并获取最新的 ATT&CK 捆绑包。 | | `--domain {enterprise-attack,ics-attack,mobile-attack}` | `enterprise-attack` | 要获取的 ATT&CK 领域。 | | `--semantic-threshold FLOAT` | `0.65` | 余弦相似度阈值；低于此值的配对将发出 `semantic_drift` 发现。 | 支持的规则格式通过扩展名自动检测。`.yml`/`.yaml` 文件被解析为 Sigma 规则；`.toml` 文件被解析为 Elastic Detection Rules。Elastic 模式涵盖 EQL、KQL (kuery) 和 ESQL —— 它们共享相同的 TOML 结构，仅在 `language` 字段上有所不同。 ### 对齐度如何评分 每条规则作为 `title + description`（自然语言部分 —— 检测查询主体不进行嵌入，因为查询语言与通用文本嵌入的对齐度不高）进行嵌入。每个 ATT&CK 技术作为来自 STIX 捆绑包的 `name + description` 进行嵌入。对于规则标记的每个技术，我们计算两个向量之间的余弦相似度；得分严格低于 `--semantic-threshold`（默认为 `0.65`）的配对将在报告中以 `medium` 严重级别发出 `semantic_drift` 发现，并在报告的 `Similarity` 列中显示得分。 嵌入使用 [`fastembed`](https://github.com/qdrant/fastembed)（模型 `BAAI/bge-small-en-v1.5`，约 30MB，首次运行时自动下载）计算一次，并缓存在 `$CACHE_DIR/embeddings/` 下。后续运行会从缓存中读取。没有 `--no-semantic` 标志：热缓存的成本几乎为零，而冷缓存的工作无论如何都至少必须进行一次。 #### 相似度得分参考 | 相似度 | 含义 | |---|---| | < 0.50 | 重大概念分歧 —— 规则和技术描述的是不同的事物 | | 0.50–0.70 | 显著漂移 —— 技术已发生实质性演进 | | 0.70–0.85 | 中度漂移 —— 措辞改变，部分行为发生偏移 | | > 0.85 | 轻微或无漂移 | 默认触发值（`semantic_threshold = 0.65`）会捕获具有显著或重大漂移的规则 —— 这种有意义的分歧才值得引起关注，而不仅仅是一个标记。 进度指示器输出到 **stderr**；报告输出到 **stdout**，以便 JSON 输出可以安全地通过管道传输： ``` detect-forge stale path/to/rules --format json | jq '.scores' detect-forge stale path/to/rules --format json -o report.json ``` ### 退出代码 | 代码 | 含义 | |---|---| | `0` | 扫描完成；无门控发现（CI 通过）。 | | `1` | 工具错误、存根命令或未实现的功能。 | | `2` | 满足 CI 门控条件（例如，`stale` 发现了严重级别发现）。 | 使用退出代码 `2` 来使您的 CI 流水线失败： ``` detect-forge stale path/to/rules code=$? if [ "$code" -eq 2 ]; then exit 2; fi ``` ### 环境变量 所有设置都可以通过带有 `DETECT_FORGE_` 前缀的环境变量（或工作目录中的 `.env` 文件）进行覆盖。将仓库根目录下的 `.env.sample` 复制为 `.env` 即可开始使用。 | 变量 | 默认值 | 用途 | |---|---|---| | `DETECT_FORGE_CACHE_DIR` | `$XDG_CACHE_HOME/detect-forge`（或 `~/.cache/detect-forge`） | ATT&CK 捆绑包的缓存位置。 | | `DETECT_FORGE_CACHE_TTL_HOURS` | `24` | 缓存生命周期（以小时为单位）。 | | `DETECT_FORGE_ATTACK_DOMAIN` | `enterprise-attack` | 默认的 `--domain` 值。 | | `DETECT_FORGE_NO_CACHE` | `false` | 如果为真值，则始终绕过缓存。 | | `DETECT_FORGE_SEMANTIC_THRESHOLD` | 未设置 | 覆盖 `.detect-forge.toml` 和 CLI 标志中的 `semantic_threshold`（最高优先级）。 | | `OPENAI_API_KEY` | 未设置 | 启用 LLM 差异提案所需。未设置时，扫描会正常完成并打印跳过横幅。 | ### LLM 差异提案 (阶段 4) 当规则发出 `semantic_drift` 发现时，`stale` 可以选择性地调用 OpenAI 的结构化输出 API，以提出与当前 ATT&CK 技术对齐的重写规则建议。提案采用 **BYOLLM** 模式且**绝不自动应用** —— 从业人员需审查每条建议并手动决定保留哪些内容。 #### 启用 在您的环境中设置 `OPENAI_API_KEY`。若未设置，扫描会正常完成并在报告末尾打印 `💡 LLM diff proposals skipped`。 ``` export OPENAI_API_KEY=sk-... detect-forge stale ./rules ``` #### 通过 `.detect-forge.toml` 配置 LLM 提案设置位于 `.detect-forge.toml` 中（从您的当前工作目录向上查找，直至 git 根目录止）。这些设置没有对应的 CLI 标志。仓库根目录附带了一个包含默认值的入门版 `.detect-forge.toml` —— 您可以直接在原处编辑或将其复制到您自己的项目中。 ``` [stale] semantic_threshold = 0.65 # Cosine similarity floor; pairs below trigger a proposal llm_model = "gpt-4o-mini" # Any OpenAI chat-completion model that supports structured outputs max_proposals = 5 # Hard ceiling on LLM calls per scan run (cost guard) ``` `max_proposals` 是您的主要成本控制手段 —— 每次提案尝试（成功、拒绝或验证未通过）都会计入此配额。 #### 成本 在默认设置下（`gpt-4o-mini`，5 份提案）：每次扫描远低于 $0.01。每份提案大约 $0.0005。`max_proposals` 设置是您的硬性成本上限。 #### 提案效果 对于每条候选规则，您将获得一个包含规则文件名、模型置信度 (0–1)、更改字段列表、简要说明以及带有语法高亮的 YAML (Sigma) 或 TOML (Elastic) 形式重写规则主体的终端面板。HTML 报告会在底部添加一个“LLM Proposals”部分，并带有颜色编码的置信度徽章。 #### 提案不会做什么 - 它们绝不会修改磁盘上的规则。审查后请手动应用更改。 - 如果未设置 `OPENAI_API_KEY`，它们不会运行。 - 它们仅使用规则的自然语言字段和您当前的 ATT&CK 技术描述 —— 除了 OpenAI API 调用之外，不会有任何遥测数据离开您的环境。 - 它们不能替代人工审查。模型的 `confidence` 字段是自我报告的且不可靠 —— 请将每份提案视为草稿。 ## Python API 每个子命令都为高级用户提供编程 API： ``` from pathlib import Path from detect_forge.stale import scan report = scan(Path("./rules"), domain="enterprise-attack") for score in report.scores: if score.worst_severity == "critical": print(f"{score.title}: {score.worst_days_stale} days stale") ``` ## 开发 ``` pytest -q # run the test suite ruff check src/ tests/ # lint mypy src/ # type-check (strict) ``` 包布局： ``` src/detect_forge/ ├── cli.py # click root group; registers all subcommands ├── settings.py # DETECT_FORGE_* pydantic-settings config ├── console.py # rich stdout + stderr consoles ├── cache.py # XDG-aware cache (default_cache_dir() factory) ├── common.py # @common_output_options decorator ├── exit_codes.py # CLEAN=0, RESERVED=1, GATED=2 ├── _stubs.py # stub_command() helper ├── stale/ # the staleness pipeline (real subcommand) ├── backtest/ # stub ├── coverage/ # stub ├── cti/ # group + ingest stub └── audit/ # stub ``` ## 许可证 MIT

标签：AI原生, AMSI绕过, ATT&CK评估, Elastic Detection Rules, GitHub Actions, IP 地址批量处理, LLM辅助, OpenAI, PB级数据处理, Petitpotam, Python, SecOps, Sigma规则, TOML, YAML, 云安全架构, 余弦相似度, 内存规避, 向量嵌入, 威胁检测, 子域名变形, 安全工程, 安全库, 安全规则引擎, 安全运维, 无后门, 目标导入, 网络安全审计, 自动笔记, 规则生命周期管理, 规则管理, 规则老化检测, 语义对齐