dino65-dev/incident-response-env
GitHub: dino65-dev/incident-response-env
一个基于OpenEnv框架构建的网络安全事件响应分诊仿真环境，用于训练和评估AI智能体执行SOC分析师工作流的能力。
Stars: 0 | Forks: 0
# 事件响应分诊环境
一个基于 [OpenEnv](https://github.com/meta-pytorch/OpenEnv) 框架构建的真实世界网络安全**安全运营中心 (SOC) 分析师模拟**。AI 智能体会像人类 SOC 分析师每天所做的那样，调查安全警报、收集取证证据、关联发现、对威胁进行分类并执行事件响应。
## 为什么选择这个环境？
每个设有 SOC 的组织都面临同样的问题：**警报疲劳**。分析师每天处理数百个警报，每个警报都需要多步骤的调查、上下文判断和果断的行动。训练 AI 智能体来处理这项工作流程具有巨大的现实价值：
- 典型企业每天产生 **4,000+** 个 SOC 警报 ([IBM X-Force](https://www.ibm.com/reports/threat-intelligence))
- 2024 年数据泄露的平均成本为 **$4.88M** ([IBM 数据泄露成本报告](https://www.ibm.com/reports/data-breach))
- 识别和控制泄露的平均时间为 **277 天**
- AI SOC 智能体可以将 MTTR (平均响应时间) 降低几个数量级
该环境提供了首个标准化的 OpenEnv 基准，用于在真实的事件响应工作流程上训练和评估 AI 安全智能体。
## 环境描述
智能体接收到一个网络安全警报后必须：
1. **调查** — 检查日志 (防火墙、EDR、代理、身份验证、DNS、电子邮件)，查询威胁情报，检查端点，核查用户资料，关联事件
2. **分类** — 确定严重程度 (严重/高/中/低/信息) 和威胁类别 (恶意软件、网络钓鱼、横向移动、内部威胁、勒索软件、供应链、APT/零日漏洞等)
3. **响应** — 针对正确的目标执行遏制措施 (隔离主机、封禁 IP、禁用账户、隔离文件)
4. **报告** — 提交一份总结调查结果的综合事件报告
### 创造性所在
- **分层证据发现**：调查行动会逐步揭示取证线索。智能体必须像真实的分析师一样，从多个数据源的碎片化证据中拼凑出完整的攻击脉络。
- **多维奖励塑形**：奖励不是二元的。智能体可以在 11 个评分维度上获得部分分数，包括证据发现、IOC 识别、严重程度/类别准确率、遏制完整性与精确度、报告质量、效率、上报准确率、证据链连贯性以及阶段纪律。
- **渐进式难度**：六个场景涵盖从简单到专家的难度，从线索明确的网络钓鱼，到多阶段勒索软件和供应链攻击，再到具有零日漏洞利用和 DNS 隧道 C2 通信的高级持续性威胁。
- **行为欺骗**：内部威胁场景包含表面上看似合法的活动。智能体必须关联细微的行为异常，以区分恶意意图与日常工作。
- **防循环惩罚**：重复相同的动作会受到递增的惩罚，鼓励采用多样化的调查策略。
- **阶段纪律**：遵循正确的 IR 工作流程 (先调查后分类，先分类后遏制) 的智能体将获得奖励，违反阶段规则将受到惩罚。
### 自我演化环境 (独特功能)
该环境具有**自我演化场景生成引擎**，可创建开放式课程体系的网络安全事件：
- **α-课程奖励**：在智能体的“最近发展区”自动生成场景 (目标成功率约 50%)
- **受 POET 启发的演化**：场景基因组种群通过突变、交叉和适应度比例选择进行演化
- **新颖性搜索**：多样性压力确保环境探索所有可能事件的完整空间
- **Elo 评级系统**：对智能体和场景进行双向评级，提供自然的难度校准
- **程序化生成**：6 种攻击原型 (网络钓鱼、横向移动、内部威胁、勒索软件、供应链、APT) 具有参数化的复杂性
使用 `task_id="evolved"` 激活自我演化模式：
```
# 激活 Self-evolving 模式
obs = env.reset(task_id="evolved")
# ... 运行 agent ...
# 基于性能触发 evolution
requests.post(f"{base_url}/env/evolve")
stats = requests.get(f"{base_url}/env/evolution-stats").json()
```
## 动作 / 观察空间
### 动作空间 (`IncidentAction`)
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `action_type` | `ActionType` (enum) | **必填。** 以下之一：`examine_alert`, `query_logs`, `check_threat_intel`, `correlate_events`, `inspect_endpoint`, `check_user_history`, `classify_severity`, `contain_threat`, `escalate`, `close_as_false_positive`, `submit_report`, `analyze_malware`, `request_forensic_image` |
| `log_source` | `str` | 用于 `query_logs` 的日志来源：`firewall`, `edr`, `proxy`, `auth`, `dns`, `email` |
| `query_filter` | `str` | 用于日志查询、威胁情报查找或恶意软件分析的过滤器/关键词 (例如，IP 地址、域名、文件哈希) |
| `endpoint_id` | `str` | 用于 `inspect_endpoint` 或 `request_forensic_image` 的主机名或 IP |
| `user_id` | `str` | 用于 `check_user_history` 的用户名 |
| `severity` | `Severity` | 用于 `classify_severity`：`critical`, `high`, `medium`, `low`, `informational` |
| `threat_category` | `ThreatCategory` | 用于 `classify_severity`：`malware`, `phishing`, `data_exfiltration`, `brute_force`, `insider_threat`, `lateral_movement`, `privilege_escalation`, `false_positive`, `ransomware`, `supply_chain`, `apt_zero_day` |
| `containment_actions` | `List[ContainmentAction]` | 用于 `contain_threat`：`isolate_host`, `block_ip`, `disable_account`, `quarantine_file`, `revoke_sessions` |
| `target` | `str` | 遏制措施的目标 (主机名、IP、用户名或文件哈希) |
| `report_summary` | `str` | 用于 `submit_report` 的最终报告文本 |
| `escalate_to` | `str` | 上报目标：`tier2`, `tier3`, `management`, `legal` |
### 观察空间 (`IncidentObservation`)
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `alert_id` | `str` | 唯一警报标识符 |
| `alert_summary` | `str` | 人类可读的警报描述 |
| `alert_source` | `str` | 生成警报的系统 |
| `timestamp` | `str` | 警报时间戳 (ISO 8601) |
| `findings` | `str` | 上一步操作的结果 (日志条目、TI 数据、端点详情等) |
| `evidence_collected` | `List[str]` | 目前已收集的证据项 |
| `iocs_discovered` | `List[str]` | 调查期间发现的 IOC |
| `action_result` | `str` | 来自环境的反馈消息 |
| `available_actions` | `List[str]` | 当前可用的动作类型 |
| `steps_remaining` | `int` | 超时前剩余的步骤数 |
| `investigation_progress` | `float` | 已发现的关键证据比例 (0.0–1.0) |
| `done` | `bool` | 回合是否结束 |
| `reward` | `float` | 上一步动作的奖励 |
## 任务
### 任务 1：钓鱼邮件分诊 (简单)
| 属性 | 值 |
|----------|-------|
| **难度** | 简单 |
| **最大步数** | 20 |
| **预期步数** | 8–15 |
| **场景** | 包含恶意宏附件的钓鱼邮件。电子邮件网关标记了带有混淆 PowerShell 负载的可疑 `.xlsm` 文件。智能体必须判断该负载是否已执行并遏制该威胁。 |
| **关键技能** | 电子邮件头分析，IOC 识别，端点分诊 |
| **真实基准** | 严重程度: HIGH，类别: Phishing，遏制: Quarantine file + Isolate host |
### 任务 2：暴力破解与横向移动 (中等)
| 属性 | 值 |
|----------|-------|
| **难度** | 中等 |
| **最大步数** | 25 |
| **预期步数** | 12–20 |
| **场景** | 来自俄罗斯 IP 的 VPN 暴力破解成功攻破了一个免 MFA 的服务账户，随后通过 RDP 横向移动到 3 台内部服务器，包括一台域控制器。攻击者提取了 NTDS.dit 并通过 transfer.sh 进行数据外泄。 |
| **关键技能** | 攻击链重建，横向移动检测，凭证窃取分析 |
| **真实基准** | 严重程度: CRITICAL，类别: Lateral Movement，遏制: Disable account + Block IP + Revoke sessions + Isolate DC，上报: Tier 3 |
### 任务 3：内部威胁调查 (困难)
| 属性 | 值 |
|----------|-------|
| **难度** | 困难 |
| **最大步数** | 30 |
| **预期步数** | 15–25 |
| **场景** | DLP 警报显示一名主管向其个人 Google Drive 上传了 340MB 数据。该用户拥有合法访问权限和已授权的云存储。智能体必须通过关联行为异常来区分恶意外泄和日常工作，这些异常包括：非工作时间访问模式、异常的文件范围、求职历史、猎头通信以及 HR 背景 (未能晋升)。 |
| **关键技能** | 行为分析，意图判定，上下文关联 |
| **真实基准** | 严重程度: CRITICAL，类别: Insider Threat，遏制: Disable account + Revoke sessions，上报: Management |
### 任务 4：勒索软件部署与加密 (中高难度)
| 属性 | 值 |
|----------|-------|
| **难度** | 中高难度 |
| **最大步数** | 25 |
| **预期步数** | 15–22 |
| **场景** | EDR 警报显示多台主机在下班时间同时加密文件。攻击者通过受感染的 RDP 凭证进入管理员工作站。部署了 Cobalt Strike Beacon，通过 PsExec 进行横向移动，然后向 3 台服务器部署了 LockBit 勒索软件变种。每台主机上都发现了勒索信。智能体必须追踪从初始 RDP 暴力破解到 C2 建立、横向移动和加密部署的完整杀伤链。 |
| **关键技能** | 杀伤链重建，勒索软件分诊，C2 识别，多主机遏制 |
| **真实基准** | 严重程度: CRITICAL，类别: Ransomware，遏制: Isolate hosts + Block IPs + Disable account + Revoke sessions，上报: Tier 3 |
### 任务 5：软件供应链攻击 (极难)
| 属性 | 值 |
|----------|-------|
| **难度** | 极难 |
| **最大步数** | 30 |
| **预期步数** | 18–26 |
| **场景** | 受信任的内部构建工具 破坏并推送了一个包含后门的更新，该后门会外泄源代码并部署加密矿机。受损的软件包使用被盗的代码签名证书进行了签名。在分阶段推出中有 8 台开发人员工作站受到影响。智能体必须识别供应链攻击向量，评估影响范围，并控制受损的 CI/CD 凭证。 |
| **关键技能** | 供应链分析，代码签名验证，CI/CD 安全，影响范围评估 |
| **真实基准** | 严重程度: CRITICAL，类别: Supply Chain，遏制: Isolate host + Quarantine file + Disable account + Revoke sessions，上报: Management |
### 任务 6：利用零日漏洞的 APT 攻击 (专家)
| 属性 | 值 |
|----------|-------|
| **难度** | 专家 |
| **最大步数** | 35 |
| **预期步数** | 22–32 |
| **场景** | 高级持续性威胁组织 利用 Confluence Server 中的零日漏洞进行初始访问。他们部署了基于内存的植入物 (无文件恶意软件)，使用“靠山吃山”技术实现持久化，通过 DCSync 收集凭证，伪造黄金票据，并通过 DNS 隧道建立隐蔽的 C2 通信。该攻击在被发现前已持续了 7 天。智能体必须揭开这场跨越 DNS 隧道 C2、凭证窃取、向 Exchange 和 HR 服务器横向移动以及高管邮件外泄的复杂多阶段入侵。 |
| **关键技能** | APT 分析，DNS 隧道检测，DCSync/黄金票据识别，无文件恶意软件调查 |
| **真实基准** | 严重程度: CRITICAL，类别: APT/Zero-Day，遏制: Isolate hosts + Block IP + Disable accounts + Revoke sessions，上报: Tier 3 / Management / Legal |
## 评分与奖励
### 评分器评分 (0.0 – 1.0)
| 组件 | 权重 | 描述 |
|-----------|--------|-------------|
| 调查彻底度 | 20% | 发现的关键证据项比例 |
| IOC 识别 | 10% | 发现的关键 IOC 比例 |
| 严重程度分类 | 10% | 完全匹配 = 满分，相邻 = 部分分数，偏差较大 = 扣分| 威胁分类 | 8% | 正确识别威胁类别 |
| 遏制完整性 | 15% | 在正确目标上执行的所需遏制操作比例 |
| 遏制精确度 | 7% | 对错误目标的遏制操作进行惩罚 |
| 报告质量 | 8% | 关键词覆盖率，IOC 提及度，报告长度 |
| 效率 | 5% | 在预期步骤范围内完成的额外奖励 |
| 上报准确度 | 5% | 选择正确的上报目标 |
| 证据链连贯性 | 7% | 智能体在分类前是否遵循了逻辑调查路径 |
| 阶段纪律 | 5% | 遵循正确的 IR 工作流顺序 (调查 → 分类 → 遏制 → 报告) |
### 步骤级奖励塑形
奖励函数在整个轨迹中提供**有意义的信号**，而不仅仅是二元的成功/失败：
- 每发现一个关键证据项 **+0.03**
- 每识别一个 IOC **+0.02–0.03**
- 每查询一个新日志源 **+0.02** (调查广度的发现奖励)
- 对 3 个以上关键 IOC 进行威胁情报检查的深度奖励 **+0.03**
- 正确的严重程度分类 **+0.10** (相邻级别为 +0.03)
- 正确的威胁分类 **+0.08**
- 对正确目标执行的每个正确遏制操作 **+0.06**
- 正确的上报目标 **+0.05**
- 在提交报告时查询了所有 6 种日志源的广度奖励 **+0.05**
- 在最大步数 60% 内完成的时间压力奖励 **+0.05** (80% 内为 +0.03)
- 在分类之前进行调查的证据链连贯性奖励 **+0.03**
- 报告质量组成部分 **+0.01–0.04**
- 重复相同动作 3 次以上 **−0.05** (防循环)
- 每个错误的遏制目标 **−0.05**
- 阶段违规：在分类之前进行遏制 **−0.03**
- 阶段违规：未分类直接提交报告 **−0.10**
- 严重程度判断严重失误 **−0.05**
- 错误的上报目标 **−0.02**
- 将真实事件当作误报关闭 **−0.20**
- 超时未解决 **−0.10**
## 基准分数
确定性基准 (脚本化最优智能体，seed=42)：
| 任务 | 分数 | 步数 |
|------|-------|-------|
| Easy (Phishing) | 0.9400 | 17 |
| Medium (Lateral Movement) | 0.8600 | 19 |
| Hard (Insider Threat) | 0.9175 | 18 |
| Medium-Hard (Ransomware) | — | — |
| Hard-Plus (Supply Chain) | — | — |
| Expert (APT Zero-Day) | — | — |
确定性基准之所以获得高分，是因为它遵循了最优调查路径。LLM 智能体面临的挑战是仅通过观察和推理来发现这条路径。新任务的基准分数将在初步运行后填补。
## LLM 智能体架构
`baseline_inference.py` 智能体实现了以下技术：
### 状态-目标反思
在每一步中，智能体都会在采取行动前反思其**当前状态相对于调查目标的关系** —— 这防止了困扰标准反应式智能体的目标偏移和幻觉问题。
### 调查规划
智能体预先生成**多步调查计划** (INVESTIGATE → CLASSIFY → CONTAIN → REPORT) 并跟踪其执行进度，从而实现结构化且有条理的事件响应。
### SOC 行动手册结构
分阶段的工作流程反映了真实世界的 SOC 事件响应手册 (NIST SP 800-61，SANS IR 框架)，确保智能体遵循正确的 IR 程序和阶段纪律。
### 防循环检测
显式的**重复检测**和强制进度推进机制可防止智能体陷入动作循环 —— 这是 LLM 智能体在多步骤环境中常见的失败模式。
### 基于证据的反馈
每个步骤都包含一个**结构化的状态摘要**，显示已发现的证据、已识别的 IOC、已查询的日志源以及当前调查阶段 —— 为 LLM 的下一步决策提供了明确的依据。
## 设置与使用
### 前置条件
- Python 3.11+
- Docker Desktop / Docker Engine
- OpenEnv: `pip install openenv-core[core]`
### 本地开发
```
# Clone 该 repository
git clone https://github.com/YOUR_USERNAME/incident-response-env.git
cd incident-response-env
# 安装依赖
pip install openenv-core[core] openai
# 在本地运行 server
uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload
# 在另一个终端中，运行 baseline（参见下方的“Supported LLM Providers”）
OPENAI_API_KEY=sk-... python baseline_inference.py --verbose
```
### 支持的 LLM 提供商
基线推理脚本适用于**任何兼容 OpenAI 的 API**。只需设置 `OPENAI_API_KEY`，并可选择设置 `OPENAI_BASE_URL`：
```
# OpenAI（默认 — 仅需设置 API key）
OPENAI_API_KEY=sk-... python baseline_inference.py --model gpt-4o-mini
# OpenRouter — 访问 200+ 个 models（Gemini, Claude, Llama, Mistral 等）
OPENAI_API_KEY=sk-or-... OPENAI_BASE_URL=https://openrouter.ai/api/v1 python baseline_inference.py --model google/gemini-2.5-flash
# Anthropic（OpenAI-compatible endpoint）
OPENAI_API_KEY=sk-ant-... OPENAI_BASE_URL=https://api.anthropic.com/v1 python baseline_inference.py --model claude-sonnet-4-20250514
# 通过 Ollama 运行 Local models
python baseline_inference.py --api-base http://localhost:11434/v1 --api-key dummy --model llama3
# 任何 OpenAI-compatible provider（显式 flags）
python baseline_inference.py --api-key YOUR_KEY --api-base https://your-provider/v1 --model your-model
```
**环境变量：**
| 变量 | 描述 |
|----------|-------------|
| `OPENAI_API_KEY` | API 密钥 (必填) |
| `OPENAI_BASE_URL` | API 基础 URL (可选，默认为 `https://api.openai.com/v1`) |
### Docker
```
# Build
docker build -f server/Dockerfile -t incident-response-env:latest .
# Run
docker run -p 8000:8000 incident-response-env:latest
# Test
curl http://localhost:8000/health
curl http://localhost:8000/tasks
```
### OpenEnv CLI
```
# Validate
openenv validate --verbose
# Build
openenv build
# 推送到 Hugging Face
openenv push
```
### API 端点
| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| `/health` | GET | 健康检查 |
| `/reset` | POST | 重置环境 (接受 `task_id`：easy/medium/hard/medium_hard/hard_plus/expert) |
| `/step` | POST | 执行操作 |
| `/state` | GET | 获取当前状态 |
| `/schema` | GET | 获取动作/观察的 JSON schema |
| `/tasks` | GET | 列出所有 6 个任务及其描述和动作 schema |
| `/grader` | GET | 回合结束后获取评分器分数 |
| `/baseline` | POST | 对所有 6 个任务运行确定性基准测试 |
| `/env/evolve` | POST | 触发场景种群的演化 |
| `/env/evolution-stats` | GET | 获取演化引擎统计数据 |
### 交互示例
```
import requests
BASE = "http://localhost:8000"
# 重置为 easy task
r = requests.post(f"{BASE}/reset", json={"task_id": "easy", "seed": 42})
obs = r.json()["observation"]
print(obs["alert_summary"])
# 检查 alert
r = requests.post(f"{BASE}/step", json={"action": {"action_type": "examine_alert"}})
obs = r.json()["observation"]
print(obs["findings"])
# Query email logs
r = requests.post(f"{BASE}/step", json={"action": {
"action_type": "query_logs",
"log_source": "email"
}})
obs = r.json()["observation"]
print(obs["findings"])
# 检查 threat intel
r = requests.post(f"{BASE}/step", json={"action": {
"action_type": "check_threat_intel",
"query_filter": "185.220.101.42"
}})
# 分类 severity
r = requests.post(f"{BASE}/step", json={"action": {
"action_type": "classify_severity",
"severity": "high",
"threat_category": "phishing"
}})
# 抑制 threat
r = requests.post(f"{BASE}/step", json={"action": {
"action_type": "contain_threat",
"containment_actions": ["quarantine_file", "isolate_host"],
"target": "WS-JSMITH-PC"
}})
# 提交 report
r = requests.post(f"{BASE}/step", json={"action": {
"action_type": "submit_report",
"report_summary": "Phishing email with macro dropper. C2 to 185.220.101.42. Endpoint isolated."
}})
# 检查 grader score
r = requests.get(f"{BASE}/grader")
print(r.json()) # {"score": 0.85, "breakdown": {...}}
```
## 项目结构
```
incident-response-env/
├── __init__.py # Package exports
├── models.py # Pydantic Action/Observation/State models
├── scenarios.py # Backward-compat re-export (scenarios live in tasks/)
├── tasks/ # All 6 incident scenarios
│ ├── __init__.py # Exports SCENARIOS, TASK_DEFINITIONS
│ ├── base.py # Shared dataclasses (LogEntry, Scenario, etc.)
│ ├── task_easy_phishing.py # Easy: Phishing email triage
│ ├── task_medium_lateral.py # Medium: Brute force & lateral movement
│ ├── task_hard_insider.py # Hard: Insider threat investigation
│ ├── task_medium_ransomware.py # Medium-Hard: Ransomware deployment
│ ├── task_hard_supply_chain.py # Hard-Plus: Supply chain compromise
│ └── task_expert_apt_zeroday.py # Expert: APT with zero-day exploitation
├── self_evolving/ # Self-evolving scenario generation engine
│ ├── __init__.py # Package exports
│ ├── evolution_engine.py # α-Curriculum, POET mutations, Elo ratings
│ └── scenario_generator.py # Procedural scenario generation from genomes
├── client.py # EnvClient implementation
├── openenv.yaml # OpenEnv configuration
├── pyproject.toml # Python project metadata
├── baseline_inference.py # LLM baseline inference script
├── README.md # This file
└── server/
├── __init__.py
├── app.py # FastAPI application with custom endpoints
├── incident_response_env_environment.py # Core environment + graders
├── baseline_runner.py # Deterministic baseline runner
└── Dockerfile # Container definition
```
## 设计决策
### 为什么选择网络安全事件响应？
1. **OpenEnv 的新领域**：OpenEnv 目录中尚无现有的 SOC/安全分诊环境
2. **真正的现实任务**：每个企业 SOC 每天都在执行这个完全相同的工作流
3. **丰富的动作空间**：涵盖调查和响应的 13 种不同动作类型
4. **自然的难度递进**：从线索明确的网络钓鱼 → 多阶段勒索软件 → 供应链攻击 → 复杂的 APT 活动
5. **多维评分**：11 个评分组件防止通过任何单一维度来刷分
### 奖励设计理念
奖励函数体现了**在安全领域部分进展也很重要**的原则：
- 发现了 5 项证据中 3 项的分析师，比一无所获的分析师更优秀
- 当真实情况是“严重”时，将其判断为“高”总比判断为“低”更好
- 遏制了正确的主机但漏封了一个 IP 仍然部分有效
- 提及关键 IOC 的报告比泛泛而谈的摘要更有价值
这种连续的奖励信号使得 RL 训练在整个回合中都能获得有意义的梯度，避免了困扰许多智能体环境的稀疏奖励问题。
## 许可证
BSD 3-Clause 许可证
## 致谢
本项目基于由 Meta PyTorch 和 Hugging Face 开发的 [OpenEnv](https://github.com/meta-pytorch/OpenEnv) 框架构建。
场景灵感来源于以下真实世界事件模式文档：
- [MITRE ATT&CK 框架](https://attack.mitre.org/)
- [IBM X-Force 威胁情报指数](https://www.ibm.com/reports/threat-intelligence)
- [CrowdStrike 全球威胁报告](https://www.crowdstrike.com/global-threat-report/)
标签：AI安全智能体, APT, BurpSuite集成, IP封禁, Meta, MTTR, OpenEnv, Petitpotam, PE 加载器, PyTorch, 主机隔离, 事件调查, 人工智能, 供应链攻击, 内部威胁, 凭据扫描, 勒索软件, 威胁分类, 安全事件响应, 安全基准测试, 安全运营中心, 平均响应时间, 强化学习环境, 恶意软件, 数字取证, 文件隔离, 横向移动, 用户模式Hook绕过, 编程规范, 网络安全, 网络映射, 自动化响应, 自动化脚本, 警报分类, 请求拦截, 逆向工具, 隐私保护, 零日漏洞, 高级持续性威胁, 黑客松