Padmavathi-1234/Anomaly-Guard-
GitHub: Padmavathi-1234/Anomaly-Guard-
一个基于 OpenEnv 的强化学习环境，在模拟网络安全事件响应场景中强制要求智能体为每步操作提供证据链式解释，并内置欧盟 AI 法案合规审计能力。
Stars: 0 | Forks: 0
title: AnomalyGuard
emoji: 🛡️
colorFrom: red
colorTo: blue
sdk: docker
pinned: false
license: mit
tags:
- openenv
- reinforcement-learning
- cybersecurity
- incident-response
- explainable-ai
- curriculum-learning
# AnomalyGuard — 符合欧盟 AI 法案的网络安全强化学习环境
### 唯一一个具有强制动作理由说明和内置合规性的 OpenEnv 环境
[](https://github.com/openenv)
[](https://python.org)
[](https://opensource.org/licenses/MIT)
[](https://scaler.com)
[](https://padmavathi-123-anomalyguard.hf.space)
## ✅ 验证状态
```
openenv validate → [OK] Ready for multi-mode deployment
Reproducibility → Verified (same seed = identical scenario)
Partial Obs → Verified (query_host reveals hidden state)
Termination → Verified (terminated vs truncated correct)
Grader → Deterministic (no random, no time-based logic)
Deployment → Live on Hugging Face Spaces
```
## 🚀 在线演示
**立即尝试：** [https://padmavathi-123-anomalyguard.hf.space](https://padmavathi-123-anomalyguard.hf.space)
**交互式 API 文档：** [https://padmavathi-123-anomalyguard.hf.space/docs](https://padmavathi-123-anomalyguard.hf.space/docs)
**GitHub：** [https://github.com/Padmavathi-1234/Anomaly-Guard-](https://github.com/Padmavathi-1234/Anomaly-Guard-)
## ⚡ 即刻测试
**步骤 1 — 启动一个回合：**
```
curl -X POST "https://padmavathi-123-anomalyguard.hf.space/reset?task_id=1&seed=42"
```
**步骤 2 — 采取带有完整理由说明的行动：**
```
curl -X POST "https://padmavathi-123-anomalyguard.hf.space/step" \
-H "Content-Type: application/json" \
-d '{
"action_type": "triage_alert",
"target": "ALT-10001",
"parameters": {"classification": "true_positive"},
"justification": {
"reasoning": "Alert ALT-10001 shows C2 beacon pattern with confidence 0.89 matching known malicious IP in threat intel. MITRE T1071 technique confirms command and control communication.",
"evidence": [{"source": "ALT-10001", "content": "C2 beacon to 185.220.101.45 confidence 0.89", "relevance_score": 0.95}],
"risk_assessment": {"threat_level": "CRITICAL", "confidence": 0.89, "potential_impact": "Active C2 channel allows attacker persistence", "business_disruption_estimate": "High — active breach ongoing"},
"alternatives_considered": [{"action": "monitor", "rejected_because": "Confidence 0.89 is too high to ignore without classification"}]
}
}'
```
**步骤 3 — 检查欧盟 AI 法案合规性：**
```
curl "https://padmavathi-123-anomalyguard.hf.space/compliance/audit"
```
**步骤 4 — 查看详细指标：**
```
curl "https://padmavathi-123-anomalyguard.hf.space/metrics/detailed"
```
**交互式 API（最简单）：** [https://padmavathi-123-anomalyguard.hf.space/docs](https://padmavathi-123-anomalyguard.hf.space/docs)
## 概述
AnomalyGuard 是**第一个要求智能体必须用基于证据的推理、风险评估和替代方案分析来论证（JUSTIFY）每一步行动**的 OpenEnv 强化学习环境。
**核心奖励公式：**
Reward = action_correctness × 0.60 + explanation_quality × 0.40
## 🏆 核心差异化优势
| 功能 | AnomalyGuard | 典型 RL 环境 |
| ----------------------------- | ------------------ | ------------------ |
| 需要动作理由说明 | ✅ 强制 | ❌ 无 |
| 欧盟 AI 法案合规引擎 | ✅ 内置 | ❌ 无 |
| 部分可观察性 | ✅ 基于查询 | ❌ 完全可见 |
| MITRE ATT&CK 集成 | ✅ 真实技术 | ❌ 抽象 |
| 恶意软件传播模拟 | ✅ 基于拓扑 | ❌ 静态 |
| 自适应课程 | ✅ 10 个等级 | ❌ 固定 |
| 稠密进度奖励 | ✅ 基于里程碑 | ❌ 稀疏 |
## 🚀 关键特性
### 核心能力
- 🔍 **基于证据的推理**：每一步行动都需要引用具体的警报 ID、主机 ID、CVE 和 MITRE 技术
- 🎯 **MITRE ATT&CK 集成**：8 种真实世界的攻击模式，包含真实的 IOC、文件哈希和 C2 IP
- 📊 **多维评分**：从动作正确性、推理清晰度、证据有效性、风险准确性等多个维度进行评分
- 🔄 **确定性可复现性**：相同的种子 + 任务总是产生完全相同的场景
- 🤖 **OpenEnv 兼容**：完全扩展了 `openenv.env.env.Env` 基类
### 高级功能
- 🦠 **恶意软件传播模拟**：基于拓扑结构在企业网络图中进行传播
- 📈 **自适应课程学习**：10 个难度等级根据智能体表现自动调整
- 🔗 **严格的任务依赖关系**：现实的 IR 工作流 —— 检测 → 抑制 → 根除 → 恢复
- 🕵️ **部分可观察性**：主机细节被隐藏，直到智能体使用 `query_host` 动作
- 🏆 **稠密进度奖励**：里程碑奖励，并正确区分 `terminated` 与 `truncated`
- ⚖️ **欧盟 AI 法案合规引擎**：针对第 10、13、14 条款的 5 项检查审计
## 🏗️ 架构
```
anomalyguard/
├── app/
│ ├── main.py # FastAPI — OpenEnv HTTP interface
│ ├── models.py # Pydantic v2 models
│ ├── environment.py # Core RL environment (extends openenv.env.env.Env)
│ ├── grader.py # Deterministic grader (0.0–1.0)
│ ├── scenarios.py # MITRE ATT&CK reproducible scenario generator
│ ├── explainability.py # Explanation quality scorer
│ ├── real_data.py # Attack patterns, CVEs, IOCs database
│ └── baseline.py # RandomAgent + RuleBasedAgent
├── tests/
│ └── test_environment.py # pytest validation suite
├── inference.py # LLM agent example
├── Dockerfile
├── requirements.txt
├── openenv.yaml
└── README.md
```
## 📋 观察空间
### 智能体所见内容
```
{
"task_id": int, # 1, 2, or 3
"step": int, # Current step (0 to max_steps)
"max_steps": int, # 15 / 20 / 30 depending on task
"alerts": List[Alert], # SIEM alerts (is_true_positive HIDDEN)
"hosts": List[Host], # Network hosts (details MASKED until queried)
"incident_phase": str, # detection/containment/eradication/recovery
"time_remaining": int, # Steps left in episode
"available_actions": List[str], # Valid action types for current task
"score_so_far": float, # Running score estimate
"threat_intel": ThreatIntel, # IOCs, malicious IPs, CVEs
}
```
### 部分可观察性 —— 主机掩码
主机在通过 `query_host` 调查之前显示有限的信息：
| 字段 | `query_host` 之前 | `query_host` 之后 |
| ----------------------------- | ------------------------ | ------------------ |
| host_id, hostname, ip_address | ✅ 可见 | ✅ 可见 |
| role, criticality, services | ✅ 可见 | ✅ 可见 |
| c2_active | ❌ 隐藏 (显示 False) | ✅ 已揭示 |
| persistence | ❌ 隐藏 (显示 []) | ✅ 已揭示 |
| vulnerabilities | ❌ 隐藏 (显示 []) | ✅ 已揭示 |
| accounts | ❌ 隐藏 (显示 []) | ✅ 已揭示 |
| status | ❌ 隐藏 (显示 online) | ✅ 已揭示 |
**重要性说明：** 智能体必须在行动前进行调查 —— 这映射了真实的 SOC 分析师工作流程。
## 🎯 任务层级（课程）
| ID | 名称 | 难度 | 最大步数 | 目标 |
| --- | ---------------------- | ---------- | --------- | ------------------------------------------------------------- |
| 1 | 警报分类 | 简单 | 15 | 将 6-10 个 SIEM 警报分类为 TP/FP 并提供理由 |
| 2 | 事件抑制 | 中等 | 20 | 在 10-15 台主机间抑制活跃的入侵 |
| 3 | 完整事件响应 | 困难 | 30 | 完成 IR 生命周期：检测 → 抑制 → 根除 → 恢复 |
### 课程学习（10 个等级）
| 等级 | 梯队 | 难度 | 最大步数 |
| ----- | ------------ | ---------- | --------- |
| 1-3 | 初级 | 0.3 - 0.5 | 15 |
| 4-6 | 中级 | 0.5 - 0.7 | 20 |
| 7-10 | 专家 | 0.7 - 1.0 | 30 |
当平均分 > 0.75 时自动晋级，当 < 0.35 时回退。
## 🧠 评分与可解释性
每个动作载荷必须包含 `ActionJustification`：
```
{
"action_type": "isolate_host",
"target": "HOST-003",
"parameters": {},
"justification": {
"reasoning": "Host HOST-003 shows active C2 communication to known malicious IP 185.220.101.45 matching threat intel. Isolation prevents lateral movement to db-server-01.",
"evidence": [
{
"source": "ALT-10001",
"content": "C2 beacon detected to 185.220.101.45 every 300s",
"relevance_score": 0.95
}
],
"risk_assessment": {
"threat_level": "CRITICAL",
"confidence": 0.92,
"potential_impact": "Lateral movement to database tier",
"business_disruption_estimate": "High — web tier isolated"
},
"alternatives_considered": [
{
"action": "block_ip",
"rejected_because": "Does not stop existing C2 session already established"
}
]
}
}
```
### 评分公式
- **任务 1：** `final = triage_accuracy × 0.70 + avg_explanation × 0.30`
- **任务 2：** `final = (triage × 0.5 + containment × 0.5) × 0.80 + avg_explanation × 0.20`
- **任务 3：** `final = (triage × 0.20 + containment × 0.30 + eradication × 0.25 + recovery × 0.25) × 0.75 + avg_explanation × 0.25`
## ⚖️ 欧盟 AI 法案合规性
AnomalyGuard 是**唯一围绕欧盟 AI 法案合规性构建的 OpenEnv 环境**。
每个回合都会生成一份 5 项检查的合规审计：
| 检查 | 条款 | 验证内容 |
| ---------------------------- | --------------- | ------------------------------------- |
| 所有动作均已说明 | Article 14.4(b) | 每个动作都有 ≥50 字符的理由 |
| 解释质量 | Article 13.1 | 平均解释得分 ≥0.60 |
| 可用人工监督 | Article 14.1 | `escalate_incident` 始终可访问 |
| 高风险动作已记录 | Article 14.4(c) | isolate/disable/restore 均有理由说明 |
| 无分类偏见 | Article 10.2(f) | TP/FP 比率在可接受范围内 |
```
curl "https://padmavathi-123-anomalyguard.hf.space/compliance/audit"
```
**重要性说明：** 欧盟 AI 法案要求高风险 AI 系统保持人工监督，提供透明的推理，并记录所有决策。AnomalyGuard 在环境层面强制执行这些要求 —— 使其适用于受欧盟监管的部署场景。
## 📊 基线性能（实测）
| 智能体类型 | 任务 1 | 任务 2 | 任务 3 | 平均 |
|-----------|--------|--------|--------|---------|
| 随机智能体 | 0.05-0.15 | 0.03-0.10 | 0.01-0.05 | ~0.08 |
| **基于规则（实测）** | **0.9023** | **0.9366** | **0.5232** | **0.7874** |
| RL 智能体目标 | 0.75+ | 0.65+ | 0.55+ | 0.65+ |
**关于任务 3 的说明：** 基于规则的智能体会超时，因为它缺乏根除（remove_persistence）和恢复（restore_host）阶段的逻辑。经过训练的 RL 智能体或 LLM 智能体将学习这些模式并完成完整的 IR 生命周期。
## 🔄 可复现性
```
# 相同的种子总是产生完全一致的场景
curl -X POST "https://padmavathi-123-anomalyguard.hf.space/reset?task_id=1&seed=42"
curl -X POST "https://padmavathi-123-anomalyguard.hf.space/reset?task_id=1&seed=42"
# 两次调用产生完全相同的 alerts、hosts、threat intel
```
由 `scenarios.py` 中的 `random.Random(seed)` 全程保证，且无全局状态变更。
## 🎬 运行演示
使用一条命令查看环境运行情况：
```
python demo.py
```
**示例输出：**
```
════════════════════════════════════════════════════════════
AnomalyGuard — Live Environment Demo
════════════════════════════════════════════════════════════
Health: OK ✓
Task 1 - Alert Triage:
Final Score: 0.9023
Action Quality: 1.0000
Explanation: 0.6744
Precision: 0.571
Recall: 1.000
F1 Score: 0.727
EU AI Act: COMPLIANT ✓ (5/5 checks) Risk: LOW
Steps: 12
Task 2 - Incident Containment:
Final Score: 0.9366
Action Quality: 1.0000
Explanation: 0.6830
Containment: 1.00
EU AI Act: COMPLIANT ✓ (5/5 checks) Risk: LOW
Steps: 17
Task 3 - Full Incident Response:
Final Score: 0.5232
Action Quality: 0.5000
Containment: 1.00
EU AI Act: COMPLIANT ✓ (4/5 checks) Risk: MEDIUM
Steps: 30 (timeout)
AVERAGE: 0.7874
```
## 🌐 API 端点
### 核心
| 端点 | 方法 | 描述 |
| -------------------------- | ------ | --------------------------------- |
| `/health` | GET | 健康检查 |
| `/tasks` | GET | 列出所有任务 |
| `/reset?task_id=1&seed=42` | POST | 开始新回合 |
| `/step` | POST | 执行带有理由说明的动作 |
| `/state` | GET | 当前掩码后的观察 |
| `/state/raw` | GET | 用于评分的完整未掩码状态 |
| `/grader?task_id=1` | POST | 对已完成的回合进行评分 |
### 可观察性
| 端点 | 方法 | 描述 |
| ------------------------------ | ------ | ----------------------------------- |
| `/host/{host_id}/visibility` | GET | 检查智能体可以看到某台主机的哪些内容 |
| `/observability/status` | GET | 跨所有主机的查询覆盖范围 |
| `/host/{host_id}/dependencies` | GET | 恢复前的先决条件 |
### 指标
| 端点 | 方法 | 描述 |
| ------------------- | ------ | --------------------------------------- |
| `/metrics/detailed` | GET | 精确率、召回率、F1、抑制率 |
| `/metrics/rewards` | GET | 逐步奖励历史 |
| `/metrics/spread` | GET | 恶意软件传播统计 |
### 基线
| 端点 | 方法 | 描述 |
| --------------------- | ------ | --------------------------- |
| `/baseline?task_id=1` | POST | 运行基于规则的智能体 |
| `/baseline/reference` | GET | 预期性能范围 |
### 课程
| 端点 | 方法 | 描述 |
| --------------------- | ------ | ----------------------------- |
| `/curriculum/status` | GET | 当前等级和表现 |
| `/curriculum/toggle` | POST | 启用/禁用课程 |
| `/episodes/diversity` | GET | 场景多样性统计 |
### 欧盟 AI 法案合规性
| 端点 | 方法 | 描述 |
| ------------------- | ------ | ------------------------------ |
| `/compliance/audit` | GET | 5 项检查的欧盟 AI 法案审计报告 |
| `/compliance/trail` | GET | 完整的动作审计追踪 |
## ⚙️ 快速开始
### 本地开发
```
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 7860
```
### Docker
```
docker build -t anomalyguard .
docker run -p 7860:7860 anomalyguard
```
### 运行 LLM 智能体
```
export API_BASE_URL="https://api.openai.com/v1"
export MODEL_NAME="gpt-4o-mini"
export HF_TOKEN="your-api-key"
export ENV_URL="http://localhost:7860"
python inference.py
```
## ⚠️ 已知限制
- **仅限单智能体** —— 无多智能体协调
- **模拟网络** —— 非真实数据包捕获
- **静态对手** —— 恶意软件按概率传播，但不会适应智能体
- **最多 25 台主机** —— 真实企业有数千台
- **离散动作** —— 无连续参数调整## 📚 相关工作
- **OpenAI Gym** —— 标准 RL 接口（我们扩展了可解释性）
- **CyberBattleSim** (Microsoft) —— 网络安全仿真（我们增加了 MITRE ATT&CK）
- **BRAWL** (MITRE) —— 自主网络行动（我们增加了课程学习）
- **EU AI Act** —— 推动我们理由说明要求的监管框架
## 🏆 关于本项目
为由 **Scaler**、**OpenEnv**、**Meta AI** 和 **PyTorch** 主办的 **Meta OpenEnv 黑客马拉松** 而构建。
该环境旨在突破 OpenEnv 环境的能力边界 —— 将真实的网络安全场景、欧盟 AI 法案合规性和高级 RL 训练功能整合到一个可部署的软件包中。
标签：AnomalyGuard, Apex, Docker, EU AI Act, Hugging Face Spaces, OpenEnv, POMDP, Python, SOAR, XAI, 人工智能合规, 可解释人工智能, 合规科技, 安全防御评估, 异常检测, 强化学习, 强化学习环境, 无后门, 机器学习, 欧盟人工智能法案, 深度学习, 网络安全, 自动化响应, 请求拦截, 课程学习, 逆向工具, 部分可观测马尔可夫决策过程, 隐私保护