Aditya07771/network-incident-response-env
GitHub: Aditya07771/network-incident-response-env
这是一个基于 OpenEnv 标准的网络事件响应仿真环境，旨在通过无严重性标签的原始遥测数据，训练和评估 AI 代理在复杂攻击场景下的调查与响应能力。
Stars: 0 | Forks: 0
# 🛡️ Network Incident Response Environment
[](https://www.python.org/)
[](https://github.com/meta-pytorch/OpenEnv)
[](https://fastapi.tiangolo.com/)
[](https://www.docker.com/)
**版本：** 2.0.0 | **状态：** 生产就绪
Network Incident Response Environment 是一个兼容 OpenEnv 的 RL 基准测试，用于训练 AI 代理作为安全运营中心 (SOC) 分析员进行操作。代理使用一套包含 7 个工具的调查工具包来调查网络安全事件，在**没有预标记严重性数据**的情况下对原始网络遥测进行推理，并在五种不同的攻击场景下在时间压力下采取遏制行动。
## 🔗 Live Links & Deployments
* 🐳 **Docker Hub:** `docker pull normie69k/network-incident-response-env`
* 🤗 **Hugging Face Space:** 标记为 `openenv` 并针对基于 Docker 的部署进行了结构化处理
* **Hugging Face Deployment link** - https://normie69k-network-incident-response-env.hf.space/
## 📋 目录
1. [Executive Summary & Vision](#1-executive-summary--vision)
2. [Technical Architecture & RL Loop](#2-technical-architecture--rl-loop)
3. [Installation & Setup (Docker & Manual)](#3-installation--setup-docker--manual)
4. [Component Deep Dive](#4-component-deep-dive)
5. [Detailed Task Workflows](#5-detailed-task-workflows)
6. [Reward System & Scoring](#6-reward-system--scoring)
7. [Multi-Dimensional Grading](#7-multi-dimensional-grading)
8. [License](#8-license)
## 1. Executive Summary & Vision
**愿景：** 提供一个强大的、由调查驱动的 Gym 风格环境，用于准确衡量 AI 代理作为 SOC 分析员操作的能力 — 奖励有条理的调查而非盲目猜测。
### 🛑 The Problems Solved
1. **Pre-Labelled Data Leaks:** 许多安全基准测试通过严重性标签泄露了答案。**解决方案：** 原始网络遥测数据，不包含任何严重性提示 — 代理必须从流量模式、payload 内容和时间中推断威胁。
2. **Trivial Action Spaces:** 简单的阻止/无操作动作不需要调查。**解决方案：** 一套 7 工具 SOC 工具包（流量分析、payload 检查、威胁情报、事件关联、阻止、隔离、报告），在采取遏制行动前奖励彻底的调查。
3. **Flat Grading:** 二元通过/失败评分忽略了细微差别。**解决方案：** 跨越消除威胁、速度、调查质量和附带损害规避的多维度连续评分，并包含特定于任务的权重配置。
4. **Homogeneous Tasks:** 简化为相同模式的场景对 RL 没有用处。**解决方案：** 五种在性质上截然不同的攻击场景，需要真正不同的调查策略 — 从 SSH 暴力破解到勒索软件 C2 信标活动。
## 2. Technical Architecture & RL Loop
该环境依赖类型化的 Pydantic v2 模型来严格构建观测、动作和奖励。代理通过“调查-然后-遏制”循环进行交互。
### 🏗️ The Investigation-Action Loop
代理接收原始网络事件，并必须在采取不可逆转的遏制行动之前主动进行调查。
```
graph TD
subgraph "🌐 Network Telemetry"
NE["Raw Network Events
(no severity labels)"] IDS["IDS Alert
(vague direction only)"] end subgraph "🔬 Investigation Toolkit" AT["analyze_traffic(ip)
Traffic flow statistics"] IP["inspect_payload(ip)
Deep packet inspection"] CR["check_reputation(ip)
Threat intelligence"] CE["correlate_events(filter)
Cross-reference patterns"] end subgraph "🛡️ Containment Actions" BI["block_ip(ip)
Firewall block"] IH["isolate_host(ip)
Network isolation"] SR["submit_report(type)
Incident classification"] end subgraph "🤖 AI Agent" AN["Analysis &
Reasoning"] DEC["Decision
Engine"] end subgraph "📊 Grading Engine" RW["Multi-Dimensional
Reward"] GR["Episode Grade
(0, 1)"] end NE --> AN IDS --> AN AN --> DEC DEC -->|"investigate"| AT DEC -->|"investigate"| IP DEC -->|"investigate"| CR DEC -->|"investigate"| CE AT -->|"results"| AN IP -->|"results"| AN CR -->|"results"| AN CE -->|"results"| AN DEC -->|"contain"| BI DEC -->|"contain"| IH DEC -->|"report"| SR BI --> RW IH --> RW SR --> RW AT -->|"+0.01 to +0.04"| RW IP -->|"+0.01 to +0.05"| RW CR -->|"+0.01 to +0.04"| RW CE -->|"+0.01 to +0.05"| RW RW -->|"feedback"| AN RW --> GR ``` ## 3. Installation & Setup (Docker & Manual) ### 🚀 3.1 Automated Deployment (Docker) 启动本地服务器并运行模拟的最快方式。 **1. Pull and Run the Published Image:** ``` docker pull normie69k/network-incident-response-env docker run --rm -p 7860:7860 --env-file .env normie69k/network-incident-response-env ``` **2. Build from Source:** ``` docker build -t network-incident-response:latest . docker run --rm -p 7860:7860 network-incident-response:latest ``` ### ⚙️ 3.2 Manual Native Setup (Developers) 需要 Python >= 3.11。 ``` # 1. Initialize Virtual Environment python3.11 -m venv venv source venv/bin/activate # 2. Install Dependencies python3.11 -m pip install --upgrade pip python3.11 -m pip install -r requirements.txt # 3. Configure Environment cp .env.example .env ``` 确保在 `.env` 中设置了 `HF_TOKEN`、`API_BASE_URL` 和 `MODEL_NAME`。 ### ✅ 3.3 Run Tests ``` python test_local.py # 58/58 passed — All good — ready to deploy 🚀 ``` ## 4. Component Deep Dive ### 🛡️ 1. The Environment Core (`network_incident_env.py`) 提供标准的 `reset()`、`step()`、`episode_summary()` 和 `state()` 方法。 * **Observation Space:** 提供 `network_events`（最近 50 条原始条目 — 无严重性）、`analysis_result`（来自调查动作）、`blocked_ips`、`isolated_hosts`、`time_elapsed`、`time_remaining` 和一个模糊的 `alert_summary`。 * **Action Space:** 7 种类型化动作，通过 Pydantic 验证强制执行 — `analyze_traffic`、`inspect_payload`、`check_reputation`、`correlate_events`、`block_ip`、`isolate_host`、`submit_report`。 * **Investigation Tracking:** 跟踪已调查的唯一 IP、调查动作计数，并在代理首先调查 ≥2 个不同 IP 时，在正确遏制时给予 +0.10 的奖励加成。 ### 🎯 2. The Scenario Engine (`scenarios.py`) 五种攻击场景生成没有任何严重性提示的原始 `NetworkEvent` 对象。每个场景提供调查辅助工具（`get_traffic_analysis`、`get_payload_inspection`、`get_reputation`、`get_event_correlation`），这些工具返回结构化结果，向主动调查的代理揭示攻击模式。 ### 📊 3. The Multi-Dimensional Graders (`graders.py`) 通过特定于任务的权重配置在四个维度上评估性能，输出严格位于 `(0.0001, 0.9999)` 内的连续分数。详情请参阅 [Section 7](#7-multi-dimensional-grading)。 ### 🔌 4. The FastAPI Server (`app.py`) 符合 OpenEnv 标准的 REST API： | Endpoint | Method | Description | | :--- | :--- | :--- | | `/health` | GET | Health check | | `/tasks` | GET | List all 5 available tasks | | `/reset` | POST | Start a new episode `{task_id, seed}` | | `/step` | POST | Execute an action | | `/state` | GET | Current environment state | | `/summary` | GET | Episode summary with graded score | | `/grade_breakdown` | GET | Detailed 4-dimension score breakdown | ## 5. Detailed Task Workflows 该环境附带五种动态生成的场景，需要真正不同的调查策略： * 🟢 **Easy (`ssh_bruteforce`):** 检测隐藏在合法 SSH 流量中的来自外部 IP 的快速 SSH 登录尝试。代理必须识别高频模式，没有任何严重性提示。 * 🟡 **Medium (`port_scan`):** 发现一个隐蔽的 SYN 端口扫描，探测多个内部主机上的非常见端口 — 仅每 2 步一次探测，埋藏在繁重的 Web 流量中。 * 🟡 **Medium (`data_exfiltration`):** 识别一台受损的内部主机，通过 DNS 隧道使用过大、十六进制编码的 DNS 查询窃取数据。需要隔离受损主机。 * 🔴 **Hard (`lateral_movement`):** 关联多阶段 APT 攻击 (SQLi → web-server compromise → database pivot) 并在数据窃取完成前隔离受损的 pivot 主机。 * 🔴 **Hard (`ransomware_c2`):** 检测受损主机使用周期性的、统一大小的 HTTPS 请求向 C2 服务器发送信标，同时通过 SMB 加密本地文件。需要同时阻止 C2 并隔离主机。 ## 6. Reward System & Scoring 该环境在整个轨迹过程中提供丰富的、增量式反馈。**调查动作给予小的正奖励；遏制动作则是高风险的。** | Action | Outcome | Reward | | :--- | :--- | :--- | | **`analyze_traffic`** | Attacker/compromised IP traffic stats | `+0.04` | | **`analyze_traffic`** | Legitimate IP traffic stats | `+0.01` | | **`inspect_payload`** | Attack signatures found | `+0.05` | | **`check_reputation`** | Threat score > 0.5 returned | `+0.04` | | **`correlate_events`** | Attack pattern matched | `+0.05` | | **`block_ip`** | Correctly blocking the attacker | `+0.90` / `+1.00` ★ | | **`block_ip`** | Blocking a legitimate IP (Collateral) | `-0.40` | | **`isolate_host`** | Isolating compromised host | `+0.90` / `+1.00` ★ | | **`isolate_host`** | Isolating a clean host (Collateral) | `-0.40` | | **`submit_report`** | Correct attack type classification | `+0.15` | | **`submit_report`** | Wrong attack type classification | `-0.10` | | **Re-investigation** | Same IP investigated again | `+0.005` (diminishing) | | **Duplicate block** | IP already blocked/isolated | `-0.03` | ★ **Investigation Bonus:** 当代理在采取遏制行动之前调查了 ≥2 个唯一 IP 时，增加 `+0.10`（总计：`1.00`）。若无调查：`0.90`。 *(注：当威胁被消除或达到 30 步时，episode 结束)* ## 7. Multi-Dimensional Grading 最终任务分数计算为四个维度的加权组合： | Dimension | Default Weight | Measures | | :--- | :--- | :--- | | **Threat Neutralization** | 40% | 代理是否阻止了攻击并正确对其进行了分类？ | | **Speed** | 25% | 威胁被遏制的速度有多快？ | | **Investigation Quality** | 20% | 代理在行动前是否收集了证据？ | | **Collateral Avoidance** | 15% | 是否避免了误报的阻止/隔离？ | ### Task-Specific Weight Profiles | Task | Neutralization | Speed | Investigation | Collateral | | :--- | :--- | :--- | :--- | :--- | | `ssh_bruteforce` | 45% | 30% | 10% | 15% | | `port_scan` | 40% | 20% | 25% | 15% | | `data_exfiltration` | 35% | 25% | 25% | 15% | | `lateral_movement` | 35% | 20% | 30% | 15% | | `ransomware_c2` | 35% | 25% | 25% | 15% | 所有分数都被钳制在开区间 `(0.0001, 0.9999)` 内，以满足 OpenEnv 严格的 `(0, 1)` 要求。 ## 8. License 本项目采用 MIT 许可证。
(no severity labels)"] IDS["IDS Alert
(vague direction only)"] end subgraph "🔬 Investigation Toolkit" AT["analyze_traffic(ip)
Traffic flow statistics"] IP["inspect_payload(ip)
Deep packet inspection"] CR["check_reputation(ip)
Threat intelligence"] CE["correlate_events(filter)
Cross-reference patterns"] end subgraph "🛡️ Containment Actions" BI["block_ip(ip)
Firewall block"] IH["isolate_host(ip)
Network isolation"] SR["submit_report(type)
Incident classification"] end subgraph "🤖 AI Agent" AN["Analysis &
Reasoning"] DEC["Decision
Engine"] end subgraph "📊 Grading Engine" RW["Multi-Dimensional
Reward"] GR["Episode Grade
(0, 1)"] end NE --> AN IDS --> AN AN --> DEC DEC -->|"investigate"| AT DEC -->|"investigate"| IP DEC -->|"investigate"| CR DEC -->|"investigate"| CE AT -->|"results"| AN IP -->|"results"| AN CR -->|"results"| AN CE -->|"results"| AN DEC -->|"contain"| BI DEC -->|"contain"| IH DEC -->|"report"| SR BI --> RW IH --> RW SR --> RW AT -->|"+0.01 to +0.04"| RW IP -->|"+0.01 to +0.05"| RW CR -->|"+0.01 to +0.04"| RW CE -->|"+0.01 to +0.05"| RW RW -->|"feedback"| AN RW --> GR ``` ## 3. Installation & Setup (Docker & Manual) ### 🚀 3.1 Automated Deployment (Docker) 启动本地服务器并运行模拟的最快方式。 **1. Pull and Run the Published Image:** ``` docker pull normie69k/network-incident-response-env docker run --rm -p 7860:7860 --env-file .env normie69k/network-incident-response-env ``` **2. Build from Source:** ``` docker build -t network-incident-response:latest . docker run --rm -p 7860:7860 network-incident-response:latest ``` ### ⚙️ 3.2 Manual Native Setup (Developers) 需要 Python >= 3.11。 ``` # 1. Initialize Virtual Environment python3.11 -m venv venv source venv/bin/activate # 2. Install Dependencies python3.11 -m pip install --upgrade pip python3.11 -m pip install -r requirements.txt # 3. Configure Environment cp .env.example .env ``` 确保在 `.env` 中设置了 `HF_TOKEN`、`API_BASE_URL` 和 `MODEL_NAME`。 ### ✅ 3.3 Run Tests ``` python test_local.py # 58/58 passed — All good — ready to deploy 🚀 ``` ## 4. Component Deep Dive ### 🛡️ 1. The Environment Core (`network_incident_env.py`) 提供标准的 `reset()`、`step()`、`episode_summary()` 和 `state()` 方法。 * **Observation Space:** 提供 `network_events`（最近 50 条原始条目 — 无严重性）、`analysis_result`（来自调查动作）、`blocked_ips`、`isolated_hosts`、`time_elapsed`、`time_remaining` 和一个模糊的 `alert_summary`。 * **Action Space:** 7 种类型化动作，通过 Pydantic 验证强制执行 — `analyze_traffic`、`inspect_payload`、`check_reputation`、`correlate_events`、`block_ip`、`isolate_host`、`submit_report`。 * **Investigation Tracking:** 跟踪已调查的唯一 IP、调查动作计数，并在代理首先调查 ≥2 个不同 IP 时，在正确遏制时给予 +0.10 的奖励加成。 ### 🎯 2. The Scenario Engine (`scenarios.py`) 五种攻击场景生成没有任何严重性提示的原始 `NetworkEvent` 对象。每个场景提供调查辅助工具（`get_traffic_analysis`、`get_payload_inspection`、`get_reputation`、`get_event_correlation`），这些工具返回结构化结果，向主动调查的代理揭示攻击模式。 ### 📊 3. The Multi-Dimensional Graders (`graders.py`) 通过特定于任务的权重配置在四个维度上评估性能，输出严格位于 `(0.0001, 0.9999)` 内的连续分数。详情请参阅 [Section 7](#7-multi-dimensional-grading)。 ### 🔌 4. The FastAPI Server (`app.py`) 符合 OpenEnv 标准的 REST API： | Endpoint | Method | Description | | :--- | :--- | :--- | | `/health` | GET | Health check | | `/tasks` | GET | List all 5 available tasks | | `/reset` | POST | Start a new episode `{task_id, seed}` | | `/step` | POST | Execute an action | | `/state` | GET | Current environment state | | `/summary` | GET | Episode summary with graded score | | `/grade_breakdown` | GET | Detailed 4-dimension score breakdown | ## 5. Detailed Task Workflows 该环境附带五种动态生成的场景，需要真正不同的调查策略： * 🟢 **Easy (`ssh_bruteforce`):** 检测隐藏在合法 SSH 流量中的来自外部 IP 的快速 SSH 登录尝试。代理必须识别高频模式，没有任何严重性提示。 * 🟡 **Medium (`port_scan`):** 发现一个隐蔽的 SYN 端口扫描，探测多个内部主机上的非常见端口 — 仅每 2 步一次探测，埋藏在繁重的 Web 流量中。 * 🟡 **Medium (`data_exfiltration`):** 识别一台受损的内部主机，通过 DNS 隧道使用过大、十六进制编码的 DNS 查询窃取数据。需要隔离受损主机。 * 🔴 **Hard (`lateral_movement`):** 关联多阶段 APT 攻击 (SQLi → web-server compromise → database pivot) 并在数据窃取完成前隔离受损的 pivot 主机。 * 🔴 **Hard (`ransomware_c2`):** 检测受损主机使用周期性的、统一大小的 HTTPS 请求向 C2 服务器发送信标，同时通过 SMB 加密本地文件。需要同时阻止 C2 并隔离主机。 ## 6. Reward System & Scoring 该环境在整个轨迹过程中提供丰富的、增量式反馈。**调查动作给予小的正奖励；遏制动作则是高风险的。** | Action | Outcome | Reward | | :--- | :--- | :--- | | **`analyze_traffic`** | Attacker/compromised IP traffic stats | `+0.04` | | **`analyze_traffic`** | Legitimate IP traffic stats | `+0.01` | | **`inspect_payload`** | Attack signatures found | `+0.05` | | **`check_reputation`** | Threat score > 0.5 returned | `+0.04` | | **`correlate_events`** | Attack pattern matched | `+0.05` | | **`block_ip`** | Correctly blocking the attacker | `+0.90` / `+1.00` ★ | | **`block_ip`** | Blocking a legitimate IP (Collateral) | `-0.40` | | **`isolate_host`** | Isolating compromised host | `+0.90` / `+1.00` ★ | | **`isolate_host`** | Isolating a clean host (Collateral) | `-0.40` | | **`submit_report`** | Correct attack type classification | `+0.15` | | **`submit_report`** | Wrong attack type classification | `-0.10` | | **Re-investigation** | Same IP investigated again | `+0.005` (diminishing) | | **Duplicate block** | IP already blocked/isolated | `-0.03` | ★ **Investigation Bonus:** 当代理在采取遏制行动之前调查了 ≥2 个唯一 IP 时，增加 `+0.10`（总计：`1.00`）。若无调查：`0.90`。 *(注：当威胁被消除或达到 30 步时，episode 结束)* ## 7. Multi-Dimensional Grading 最终任务分数计算为四个维度的加权组合： | Dimension | Default Weight | Measures | | :--- | :--- | :--- | | **Threat Neutralization** | 40% | 代理是否阻止了攻击并正确对其进行了分类？ | | **Speed** | 25% | 威胁被遏制的速度有多快？ | | **Investigation Quality** | 20% | 代理在行动前是否收集了证据？ | | **Collateral Avoidance** | 15% | 是否避免了误报的阻止/隔离？ | ### Task-Specific Weight Profiles | Task | Neutralization | Speed | Investigation | Collateral | | :--- | :--- | :--- | :--- | :--- | | `ssh_bruteforce` | 45% | 30% | 10% | 15% | | `port_scan` | 40% | 20% | 25% | 15% | | `data_exfiltration` | 35% | 25% | 25% | 15% | | `lateral_movement` | 35% | 20% | 30% | 15% | | `ransomware_c2` | 35% | 25% | 25% | 15% | 所有分数都被钳制在开区间 `(0.0001, 0.9999)` 内，以满足 OpenEnv 严格的 `(0, 1)` 要求。 ## 8. License 本项目采用 MIT 许可证。
标签：AI安全, AV绕过, Chat Copilot, Docker, Docker Hub, FastAPI, HuggingFace, OpenEnv, PE 加载器, Pydantic, Python, RL环境, SSH暴力破解, 安全运营中心, 安全防御评估, 容器化部署, 密码管理, 异常检测, 强化学习, 插件系统, 无后门, 横向移动, 渗透测试模拟, 编程规范, 网络事件响应, 网络安全, 网络映射, 网络遥测, 请求拦截, 逆向工具, 防御训练, 隐私保护, 隐蔽扫描