0xPdaff/incident-response-playbook-generator
GitHub: 0xPdaff/incident-response-playbook-generator
基于多供应商大模型编排的AI Agent，根据NIST SP 800-61标准自动生成定制化的事件响应Playbook。
Stars: 0 | Forks: 0
# 事件响应 Playbook 生成器
## 🎯 本项目展示了什么
- **多供应商 LLM 编排** — 跨 8 个以上供应商（OpenAI、Anthropic、Deepseek、Minimax、Kimi、Qwen、GLM、Ollama）的统一接口，支持自动回退
- **规范驱动开发** — 编写代码前完成完整的 SDD/BDD 规范，并包含 Gherkin 测试场景
- **Agent 工具设计** — 结构化的工具 schema 和针对 LLM 优化的描述，以确保可靠的 Agent 行为
- **生产级 API 设计** — 使用 FastAPI，包含类型化模型、Swagger 文档、输入验证和安全防护
- **评估驱动质量** — 用于回归追踪的行为评估用例
- **治理层** — 所有权、熔断机制、模型注册和预算控制
## 🛠 技术栈
| 组件 | 技术 |
|-----------|-----------|
| 语言 | Python 3.13 |
| API 框架 | FastAPI + Uvicorn |
| CLI 框架 | Click |
| LLM 接口 | litellm（统一多供应商） |
| 输出格式 | Markdown, PDF (WeasyPrint) |
| 配置 | YAML + dotenv |
| 测试 | pytest + pytest-asyncio |
| PDF 生成 | WeasyPrint + markdown |
## 🏗 架构
```
flowchart TD
A[User Input] --> B[Input Router]
B --> C[Guardrails: Validate & Sanitize]
C --> D[Load Org Profile]
D --> E[Classify Incident]
E --> F[Select Prompt Template]
F --> G[Build Prompt with Context]
G --> H[Check Cache]
H -->|Cache Hit| K[Render Output]
H -->|Cache Miss| I[Call LLM via litellm]
I -->|Success| J[Parse & Validate Response]
I -->|Failure| I1[Fallback Provider]
I1 -->|Success| J
I1 -->|All Failed| ERR[Error Response]
J --> K
K --> L[Markdown File]
K --> M[PDF File]
K --> N[API Response / CLI Output]
```
**4 种输入模式：**
1. **CLI 参数** — `python src/app.py -d "事件描述"`
2. **交互式 CLI** — `python src/app.py -i`
3. **REST API** — 携带 JSON body 的 `POST /api/v1/playbook`
4. **文件输入** — `python src/app.py -f incident.txt`
## 🚀 安装
### 快速安装（通过 GitHub）
无需克隆即可直接安装 — 可在任何目录下作为 `ir-playbook` 使用：
```
pip install git+https://github.com/0xPdaff/incident-response-playbook-generator.git
# 验证
ir-playbook --version
# 设置 API keys
cp ~/.ir-playbook/config/.env.example ~/.ir-playbook/.env
# 使用你的 API keys 编辑 ~/.ir-playbook/.env
```
首次运行时会在 `~/.ir-playbook/` 中自动创建配置文件。
### 标准安装（克隆 + 开发模式）
```
git clone https://github.com/0xPdaff/incident-response-playbook-generator.git
cd incident-response-playbook-generator
pip install -e . # editable install
cp .env.example .env # Add your API keys
ir-playbook --version
```
### 安装为 CLI 工具（可选）
作为全局 CLI 命令安装，可在任何目录下使用：
```
# 从项目目录
pip install .
# 或以 development/editable mode
pip install -e .
# 现已全局可用
ir-playbook -d "ransomware detected"
ir-playbook -i
ir-playbook --version
ir-playbook --show-stack
ir-playbook --setup-stack
ir-playbook --list-providers
ir-playbook -H
```
作为包安装时，配置文件存储在 `~/.ir-playbook/config/`，并在首次运行时自动初始化。传统的使用方法在项目目录中仍然有效：
```
python src/app.py -d "incident description" # direct execution
python src/app.py --serve # API server
```
## 💻 使用说明
### CLI 参数模式
```
python src/app.py --description "Ransomware detected on finance server encrypting files"
```
### 交互模式
```
python src/app.py --interactive
```
### 文件输入
```
python src/app.py --file incident_description.txt
```
### API 服务器
```
python src/app.py --serve
# Swagger UI 位于 http://localhost:8000/docs
```
### API 请求示例
```
curl -X POST http://localhost:8000/api/v1/playbook \
-H "Content-Type: application/json" \
-d '{
"incident_description": "Ransomware detected on finance server",
"severity": "critical",
"provider": "anthropic"
}'
```
### 供应商选择
```
# 为此运行使用特定 provider
python src/app.py -d "..." --provider anthropic
# 默认 provider 在 config/model_config.yaml 中配置
# 通过环境变量全局覆盖
export DEFAULT_PROVIDER=deepseek
```
### 组织简介
查看您当前的组织简介和技术栈：
```
python src/app.py --show-stack
```
交互式配置您的组织简介：
```
python src/app.py --setup-stack
```
设置向导将引导您配置组织名称、所属行业、技术栈、合规框架、上报联系人以及沟通渠道。数据将保存到 `config/org_profile.yaml` 中，并设置 `demo: false`。
## 📖 CLI 参考
### 参数概览
| 参数 | 简写 | 描述 | 类型 | 默认值 |
|------|-------|-------------|------|---------|
| `--description` | `-d` | 事件描述文本 | string | — |
| `--file` | `-f` | 包含事件描述的文件路径 | path | — |
| `--interactive` | `-i` | 启动引导式交互模式 | flag | off |
| `--serve` | `-s` | 启动 REST API 服务器 | flag | off |
| `--severity` | | 严重程度 | `low` \| `medium` \| `high` \| `critical` | 自动推断 |
| `--provider` | | 要使用的 LLM 供应商 | choice（见表格） | 取自配置 |
| `--format` | | 输出格式 | `markdown` \| `pdf` | `markdown` |
| `--output-dir` | | 生成文件的目录 | path | `data/processed` |
| `--port` | | API 服务器端口 | int | `8000` |
| `--verbose` | `-v` | 启用 DEBUG 日志 | flag | off |
| `--extended-help` | `-H` | 显示扩展使用指南 | flag | off |
| `--list-providers` | | 显示供应商和 API 密钥状态 | flag | off |
| `--help` | | 显示基本帮助 | flag | off |
| `--show-stack` | | 显示组织简介和技术栈 | flag | off |
| `--setup-stack` | | 交互式组织简介设置向导 | flag | off |
| `--version` | | 显示版本并退出 | flag | off |
### 输入模式
生成器支持 4 种输入模式。请根据您的工作流程选择合适的方式：
#### 1. CLI 参数（最快）
直接在命令行中传入事件描述：
```
python src/app.py -d "Ransomware detected on finance server encrypting files"
python src/app.py -d "Phishing campaign targeting executives" --severity high --provider anthropic
```
#### 2. 交互模式
通过引导式提示输入描述、严重程度和供应商。非常适合初次使用的用户：
```
python src/app.py -i
```
#### 3. 文件输入
从文本文件中加载预先写好的事件描述：
```
python src/app.py -f incident_description.txt
python src/app.py -f incidents/ransomware.txt --output-dir ./reports --format pdf
```
#### 4. REST API
启动 FastAPI 服务器并通过 HTTP 交互。自带 Swagger UI：
```
python src/app.py --serve
python src/app.py --serve --port 9000 # custom port
# Swagger UI → http://localhost:8000/docs
# ReDoc → http://localhost:8000/redoc
```
```
curl -X POST http://localhost:8000/api/v1/playbook \
-H "Content-Type: application/json" \
-d '{
"incident_description": "Ransomware detected on finance server",
"severity": "critical",
"provider": "anthropic"
}'
```
### 支持的供应商
| 供应商 | 模型 | API 密钥环境变量 | 本地？ |
|----------|-------|-----------------|--------|
| `openai` | gpt-4o | `OPENAI_API_KEY` | 否 |
| `anthropic` | claude-sonnet-4 | `ANTHROPIC_API_KEY` | 否 |
| `deepseek` | deepseek-chat | `DEEPSEEK_API_KEY` | 否 |
| `minimax` | MiniMax-M2.7 | `MINIMAX_API_KEY` | 否 |
| `kimi` | moonshot-v1-128k | `KIMI_API_KEY` | 否 |
| `qwen` | qwen-max | `QWEN_API_KEY` | 否 |
| `glm` | glm-4-plus | `GLM_API_KEY` | 否 |
| `ollama` | llama3 | _(无 — 本地运行)_ | 是 |
检查已配置的供应商：
```
python src/app.py --list-providers
```
系统使用自动回退链（在 `config/model_config.yaml` 中配置）。如果主供应商失败，它将按顺序尝试下一个供应商。
### 配置
#### `.env` — API 密钥和应用设置
复制 `.env.example` 并填入您的 API 密钥：
```
cp .env.example .env
```
```
# 至少需要一个 provider key（Ollama 除外）
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=...
MINIMAX_API_KEY=...
# 可选覆盖
DEFAULT_PROVIDER=openai
LOG_LEVEL=INFO
API_PORT=8000
```
#### `config/model_config.yaml` — 供应商设置
定义了每个供应商的模型、endpoint、temperature、回退链、重试行为和速率限制。编辑此文件以更改模型或添加新的供应商。
#### `config/org_profile.yaml` — 组织上下文
提供您的技术栈、SIEM/EDR 工具、团队联系人和合规框架，以便 playbook 包含相关的命令和上报路径。填写真实数据后请将 `demo` 设置为 `false`。
```
demo: false
org:
name: "My Company"
industry: "technology"
size: "small"
tech_stack:
os: ["linux"]
cloud_providers: ["aws"]
siem: "splunk"
edr: "crowdstrike"
```
### 扩展帮助
获取包含示例和故障排除的详细使用指南：
```
python src/app.py -H # or --extended-help
```
### 常见问题 / 故障排除
| 问题 | 解决方案 |
|-------|-----|
| "No provider available" | 在 `.env` 中设置至少一个 API 密钥，或使用 `--provider ollama` |
| "Description too short" | 提供至少 10 个字符 |
| 速率限制 / 429 错误 | 降低请求频率或使用 `--provider` 切换供应商 |
| PDF 生成被跳过 | `pip install weasyprint` |
| Ollama 连接被拒绝 | 启动 Ollama：`ollama serve && ollama pull llama3` |
| `ModuleNotFoundError` | `pip install -r requirements.txt` |
## 📸 演示
```
python examples/demo.py
```
演示脚本展示了所有输入模式并检查了供应商的可用性。
## 📁 项目结构
```
01-incident-response-playbook/
├── src/
│ ├── app.py # Entry point: CLI + API server
│ ├── agent/
│ │ ├── tools/
│ │ │ ├── schemas/ # JSON schemas for agent tools
│ │ │ └── descriptions/ # LLM-optimized tool descriptions
│ │ ├── chains/ # Orchestration: classify → generate
│ │ └── memory/ # Session state management
│ ├── inference/ # Multi-provider LLM engine (litellm)
│ ├── guardrails/ # Input validation, PII detection, safety checks
│ ├── api/ # FastAPI routes and models
│ ├── caching/ # File-based prompt/response cache
│ └── utils/ # Config, constants, helpers
├── config/
│ ├── org_profile.yaml # Organization tech stack & contacts
│ ├── prompts.yaml # Prompt templates
│ └── model_config.yaml # Provider settings & fallback chain
├── evals/ # Behavioral evaluation cases
├── tests/ # pytest test suite
├── examples/
│ └── demo.py # Demo script
└── docs/
├── SPECS.md # SDD/BDD specs with Gherkin scenarios
├── DECISIONES.md # Technical decision rationale
├── ARQUITECTURA.md # Architecture diagram
└── GOVERNANCE.md # Ownership & safety controls
```
## 📋 路线图
- [x] 具有回退机制的多供应商 LLM 支持
- [x] 4 种输入模式（CLI 参数、交互式、API、文件）
- [x] NIST SP 800-61 Rev. 3 结构化 playbook
- [x] 感知组织简介的命令生成
- [x] 输入验证和 PII 检测
- [x] Markdown 和 PDF 输出
- [x] Prompt/响应缓存
- [x] 针对破坏性命令的安全防护
- [ ] Web UI (Streamlit dashboard)
- [ ] Playbook 版本控制与历史记录
- [ ] 自定义知识库集成
- [ ] 多语言 Playbook 支持
## 📚 参考资料
- [NIST SP 800-61 Rev. 3](https://csrc.nist.gov/pubs/sp/800/61/r3/final) — 计算机安全事件处理指南（核心 playbook 结构）
- [MITRE ATT&CK Framework](https://attack.mitre.org/) — 分类中引用的对手战术、技术和程序
- [SANS Incident Handler's Handbook](https://www.sans.org/white-papers/33901/) — 实用的事件响应方法论
- [FastAPI](https://fastapi.tiangolo.com/) — 用于 REST API 的现代异步 Python Web 框架
- [Click](https://click.palletsprojects.com/) — 用于构建可组合命令行界面的 Python CLI 框架
- [LiteLLM](https://github.com/BerriAI/litellm) — 适用于 100 多种 LLM 供应商的统一接口
- [Anthropic Python SDK](https://github.com/anthropics/anthropic-sdk-python) — 用于兼容 Anthropic 的供应商 (MiniMax)
- [WeasyPrint](https://weasyprint.org/) — 用于生成专业 playbook 文档的 CSS 转 PDF 渲染器
- [LangChain](https://python.langchain.com/) — 用于构建 LLM 驱动应用程序的框架
- [Pydantic](https://docs.pydantic.dev/) — 使用 Python 类型注解进行数据验证
- [Eval-Driven Development (Anthropic)](https://docs.anthropic.com/en/docs/build-with-claude/evals) — LLM 行为的评估模式
## 📄 许可证
MIT — 请参阅 [LICENSE](LICENSE)
标签：AI代理, API安全护栏, AV绕过, BDD, CLI, FastAPI, Kill Switch, Litellm, LLM大模型, Markdown, NIST SP 800-61, osquery, PDF生成, Python, REST API, SOAR, WiFi技术, 事件分类, 人工智能, 企业安全, 多模型编排, 子域名变形, 安全剧本生成, 安全合规, 安全基线, 安全策略, 安全规则引擎, 库, 应急响应, 提示词设计, 故障转移, 教学环境, 无后门, 智能体工具设计, 测试驱动开发, 灰度开关, 用户模式Hook绕过, 网络代理, 网络安防, 网络资产管理, 自动化运维, 行为驱动开发, 运维安全, 防御加固, 预算控制