InfoSecJay/sigma-llm-doc
GitHub: InfoSecJay/sigma-llm-doc
基于LLM自动为Sigma检测规则生成结构化调查指南的命令行工具，支持多LLM提供商和CI/CD流水线集成。
Stars: 0 | Forks: 0
# sigma-llm-doc
自动为 Sigma 检测规则生成由 LLM 驱动的调查指南，并将其作为 `note` 字段附加到 YAML 输出中。
## 流程上下文
此工具是 detection-as-code CI/CD 流水线中的**第 1 步**：
```
Mirrored external Sigma repo (SigmaHQ, LOLRMM, custom)
|
v
sigma-llm-doc --> Enriched Sigma rules (with `note` field)
|
v
Sigma-to-TOML converter --> Elastic SIEM-compatible rules
```
## 环境要求
- Python 3.10+
- 至少一个支持的提供商的 API key：
- **OpenAI** (`OPENAI_API_KEY`) -- 默认提供商
- **Anthropic Claude** (`ANTHROPIC_API_KEY`)
- **Google Gemini** (`GEMINI_API_KEY`)
## 安装
```
pip install -e .
```
用于开发（包含 pytest）：
```
pip install -e ".[dev]"
```
复制 `.env.example` 到 `.env` 并添加您的 API key(s)：
```
cp .env.example .env
# 编辑 .env 并设置你的 provider 的 API key：
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=your-gemini-key-here
```
（可选）复制 `config.example.yaml` 到 `sigma-llm-doc.yaml` 以自定义默认设置：
```
cp config.example.yaml sigma-llm-doc.yaml
```
## 使用方法
安装后，即可使用 `sigma-llm-doc` 命令。您也可以将其作为 Python 模块运行：
```
sigma-llm-doc ./rules/
# 或
python -m sigma_llm_doc ./rules/
```
```
usage: sigma-llm-doc [-h] [--config CONFIG] [--prompt PROMPT]
[--output OUTPUT] [--provider {openai,claude,gemini}]
[--model MODEL] [--concurrency N] [--force] [--check]
[--verbose | --quiet]
input
Generate LLM-powered investigation guides for Sigma detection rules.
positional arguments:
input Path to a Sigma rule file (.yml/.yaml) or directory
optional arguments:
-h, --help show this help message and exit
--config CONFIG Path to config file (default: sigma-llm-doc.yaml)
--prompt PROMPT Path to prompt file (default: built-in prompt)
--output OUTPUT Output directory (default: ./output)
--provider {openai,claude,gemini}
LLM provider (default: openai)
--model MODEL LLM model to use (default depends on provider)
--concurrency N Max concurrent API calls (default: 5)
--force Regenerate all guides, ignoring cache
--check Validate existing guides without generating new ones
--verbose Increase log verbosity (debug level)
--quiet Suppress all output except errors and summary
```
### 示例
处理单个规则：
```
sigma-llm-doc rules/windows/process_creation/suspicious_cmd.yml
```
处理整个目录：
```
sigma-llm-doc ./sigma-rules/ --output ./enriched-rules/
```
强制重新生成所有指南：
```
sigma-llm-doc ./sigma-rules/ --force
```
验证现有指南（CI 关卡）：
```
sigma-llm-doc ./enriched-rules/ --check
```
使用自定义 prompt 和 model：
```
sigma-llm-doc ./sigma-rules/ --prompt my_prompt.txt --model gpt-4o
```
使用 Claude 作为 LLM provider：
```
sigma-llm-doc ./sigma-rules/ --provider claude
```
使用特定的 Claude model：
```
sigma-llm-doc ./sigma-rules/ --provider claude --model claude-opus-4-6-20250929
```
使用 Google Gemini：
```
sigma-llm-doc ./sigma-rules/ --provider gemini
```
使用特定的 Gemini model：
```
sigma-llm-doc ./sigma-rules/ --provider gemini --model gemini-2.5-pro
```
## 配置
配置解析优先级为：**CLI 参数 > 配置文件 > 默认值**。
### 配置文件
创建 `sigma-llm-doc.yaml`（或使用 `--config` 指定路径）：
```
llm:
provider: openai # openai, claude, or gemini
model: gpt-4o-mini # model name (default depends on provider)
api_key_env: OPENAI_API_KEY
processing:
concurrency: 5
max_retries: 3
api_max_retries: 3
output:
directory: ./output
```
### 支持的提供商
| Provider | `--provider` | Default Model | API Key Env Var |
|----------|-------------|---------------|-----------------|
| OpenAI | `openai` | `gpt-4o-mini` | `OPENAI_API_KEY` |
| Anthropic Claude | `claude` | `claude-sonnet-4-5-20250929` | `ANTHROPIC_API_KEY` |
| Google Gemini | `gemini` | `gemini-2.0-flash` | `GEMINI_API_KEY` |
当您使用 `--provider` 切换提供商时，默认 model 和 API key 环境变量会自动解析。您可以通过 `--model` 覆盖 model，或在配置文件中使用 `api_key_env` 覆盖环境变量。
### 环境变量
API key 从所选提供商的环境变量中读取（OpenAI 对应 `OPENAI_API_KEY`，Claude 对应 `ANTHROPIC_API_KEY`，Gemini 对应 `GEMINI_API_KEY`）。您可以通过以下方式设置：
- 项目根目录下的 `.env` 文件（通过 `python-dotenv` 自动加载）
- 系统环境变量
- CI/CD 密钥（例如 GitLab CI 变量）
## 退出代码
| Code | 含义 |
|------|---------|
| 0 | 成功 —— 所有规则已成功处理或跳过 |
| 1 | 错误 —— 不可恢复的错误（配置错误、缺少输入等） |
| 2 | 部分失败 —— 部分规则在重试后失败（参见摘要） |
## 工作原理
1. 从输入路径**加载规则**（文件或目录遍历）
2. **计算每个规则内容的哈希值**（排除 `note` 字段）并与 JSON 缓存进行比对
3. **跳过未更改的规则**，即内容哈希和 prompt 哈希与缓存匹配的规则
4. **将更改的规则发送到 LLM**，使用信号量控制的并发进行批处理
5. 根据必需的节标题、格式规则和最小长度**验证响应**
6. **后处理**响应（去除分隔线、规范空白、附加免责声明）
7. 验证失败时**重试**，最多 `max_retries` 次
8. 将丰富的规则**写入**输出目录，镜像源目录结构
9. **更新缓存**并打印包含 token 使用情况的摘要报告
### 输出验证
每个 LLM 响应在写入前都会经过验证。验证器检查：
- 所有四个必需的 `###` 标题是否存在（Technical Context、Investigation Steps、Prioritization、Blind Spots and Assumptions）
- 无水平分隔线（`---`）
- 无编号列表（必须使用破折号 `-` 项目符号）
- 无 `*` 项目符号，无三重反引号代码块
- 仅允许 `###` 级别的标题（禁止 `#` 或 `##`）
- Investigation Steps 中至少有 3 个项目符号点
- 响应长度至少 200 个字符
- 每个部分内容非空
### YAML 保真度
该工具在所有 YAML 操作中使用 `ruamel.yaml`，以保留键顺序、流式风格、引号和块标量格式。仅添加或修改 `note` 字段 —— 所有其他内容完全保留。`note` 值使用 `LiteralScalarString` 以 YAML 块标量（`|` 风格）写入。
### 变更检测
JSON 缓存文件（`.sigma-llm-doc-cache.json`）存储在输出目录中。仅当以下情况时才跳过规则：
1. prompt 哈希匹配（prompt 未更改）
2. 规则的内容哈希匹配（规则未更改）
3. 输出文件存在且具有非空的 `note` 字段
使用 `--force` 可绕过所有缓存并重新生成每个指南。
### 安全性
- **路径遍历防护**：验证输出文件必须位于输出目录内
- **符号链接保护**：在收集过程中排除解析路径位于输入目录之外的文件
- **响应长度限制**：拒绝超过 50,000 个字符的 LLM 响应
- **配置验证**：在启动时验证 Provider、model、并发和重试值
## CI/CD 集成
请参阅 [docs/gitlab-cicd-guide.md](docs/gitlab-cicd-guide.md) 获取完整的 GitLab CI/CD 集成指南，涵盖：
- 流水线配置（`.gitlab-ci.yml` 模板）
- 使用 CI/CD 变量管理 API key
- Merge request 和夜间富化工作流
- Provider 选择和成本管理
- 故障排除和最佳实践
## 测试
```
pytest
```
测试套件覆盖所有模块：validator、cache、providers、config、processor 和 CLI（67 个测试）。
## 项目结构
```
sigma-llm-doc/
pyproject.toml # PEP 621 project metadata, deps, entry point
.gitignore
.env.example # Example environment file
config.example.yaml # Example config file
README.md
docs/
gitlab-cicd-guide.md # GitLab CI/CD integration guide
src/
sigma_llm_doc/
__init__.py
__main__.py # python -m sigma_llm_doc support
cli.py # CLI entry point (argparse, logging, summary)
llm_provider.py # LLM providers (OpenAI, Claude, Gemini)
processor.py # Core logic: load rules, detect changes, orchestrate
validator.py # Validate generated markdown against required format
cache.py # Content + prompt hashing, cache read/write
config.py # Config file loading, defaults, CLI arg merging
default_prompt.txt # Default investigation guide prompt
tests/
test_validator.py # Validator unit tests
test_cache.py # Cache and hashing unit tests
test_providers.py # Provider registration, mocked API calls, retry logic
test_config.py # Config resolution, validation, provider defaults
test_processor.py # Processing pipeline, clean_markdown, check mode
test_cli.py # Argument parsing tests
prompt_tests/ # Model comparison outputs and cost analysis
cost_analysis.md
model_ranking.md
sample_outputs/ # Per-model investigation guide samples
```
标签：AMSI绕过, Anthropic Claude, Detection-as-Code, DLL 劫持, LLM, OpenAI, Petitpotam, Python, Sigma规则, Unmanaged PE, YAML处理, 人工智能, 内存规避, 大语言模型, 威胁检测, 安全运营, 库, 应急响应, 扫描框架, 无后门, 用户模式Hook绕过, 目标导入, 网络安全, 自动化文档生成, 调查指南, 隐私保护