nayefsiddique-eng/Adaptive-Honeypot
GitHub: nayefsiddique-eng/Adaptive-Honeypot
PRAETOR 是一个基于机器学习和协作式强化学习的自主网络欺骗平台，通过动态调整蜜罐环境来防御复杂的多阶段入侵。
Stars: 2 | Forks: 0
# PRAETOR — 自主网络欺骗情报平台
## 📐 系统架构
### Teleception 决策生命周期
以下序列映射了从日志摄取到分类器预测、CMARL 选择、后台会话关闭回收以及 Bellman Q 矩阵更新的实时处理流程：
```
sequenceDiagram
autonumber
actor Attacker as Attacker Client
participant API as Ingestion API (/api/logs/ingest)
participant ML as ML Ensemble & Feature Extractor
participant DB as SQLite Database
participant CMARL as Cooperative RL Core
participant Reaper as Startup Session Reaper
Attacker->>API: Send attack traffic (IP, port, payload)
API->>ML: Extract features & predict class (RF / XGBoost)
ML-->>API: Return attack type & confidence
API->>API: Calculate Combined Risk Score (0-100)
API->>CMARL: Query coordinated strategy (choose_rl_action)
CMARL->>CMARL: Network Agent selects latency, Service Agent selects decoy file
CMARL-->>API: Return coordinated deception action & configuration
API->>DB: Log attack details & update session state
API-->>Attacker: Return deceptive response (mock banner / delay)
Note over Reaper, DB: Autonomous Background Thread (every 5s)
Reaper->>DB: Scan for active sessions inactive for >15s
DB-->>Reaper: Return expired sessions
Reaper->>CMARL: Trigger Bellman updates (update_q_table_for_session)
CMARL->>CMARL: Calculate cooperative reward (deception + duration + depth)
CMARL->>DB: Update Q-value matrices in DB for all agents
Reaper->>DB: Mark session as inactive
```
## 🧪 方法论
### 数据获取与处理管道
1. **摄取层：** 通过 `/api/logs/ingest` 摄取原始流量数据。
2. **特征提取：** 原始 payload 传递给 `FeatureExtractor`，以计算 SQL/命令注入计数、payload 熵和连接标志。
3. **ML 管道：** 提取的特征由集成分类器进行评估：
* **Random Forest & XGBoost：** 识别基于特征的攻击向量。
* **Isolation Forest：** 评估异常分数，以标记潜在的零日漏洞利用。
4. **地理与情报富化：** 获取外部 IP 信誉元数据的馈送。
5. **图关联：** 将摄取的向量添加到流式攻击路径图中，以估计对手的意图路径。
### 协作式强化学习
决策核心使用协作式多智能体 Q-learning (CMAQL) 框架：
* **状态表示：** 由预估攻击类型、会话交互深度和连接信誉分数的复合键定义。
* **智能体划分：**
* **网络智能体 (NA)：** 混洗监听端口并安排延迟。
* **服务智能体 (SA)：** 更改活动的模拟配置（接受的凭证、显示的文件系统路径）。
* **情报智能体 (IA)：** 优化取证日志记录、会话持续时间和 MITRE Engage 对齐。
* **奖励计算：**
$$R_{joint} = \omega_1 \cdot \text{Duration} + \omega_2 \cdot \text{InteractionDepth} + \omega_3 \cdot \text{DeceptionScore}$$
其中 $\omega_1, \omega_2, \omega_3$ 是平衡捕获持久性与威胁情报收集深度的权重。
## 🚀 安装与运行
### 1. 克隆并初始化环境
```
git clone https://github.com/nayefsiddique-eng/Adaptive-Honeypot.git
cd Adaptive-Honeypot
python -m venv venv
# 在 Windows 上
.\venv\Scripts\activate
# 在 Linux/macOS 上
source venv/bin/activate
```
### 2. 安装依赖包
```
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```
### 3. 生成 ML 管道模型
生成训练好的模型并评估性能指标：
```
python ml/train_classifier.py
python ml/evaluate_models.py
```
### 4. 启动 FastAPI 服务器
```
python -m uvicorn backend.main:app --port 8000
```
FastAPI Swagger 文档可通过 `http://localhost:8000/docs` 访问。
### 5. 启动流量攻击模拟器
在单独的终端中，启动闭环多步攻击者模拟脚本：
```
python scripts/simulate_attacks.py --count 15 --delay 0.5 --session-delay 1.0
```
### 6. 启动 Cyber-HUD 前端
在任何 Web 浏览器中直接打开 `frontend/index.html`。它运行在 `file://` 协议上，并在 `http://localhost:8000` 查询后端。
## 📡 API 端点参考
| 方法 | 路径 | 描述 |
| :--- | :--- | :--- |
| `GET` | `/` | API 健康检查和蜜罐活动状态检查。 |
| `POST` | `/api/logs/ingest` | 摄取流量日志，处理预测，进行地理定位，并更新 CMARL。 |
| `GET` | `/api/logs` | 获取所有日志（支持过滤：`?ip={ip_address}`）。 |
| `GET` | `/api/logs/recent` | 检索最近的日志。 |
| `GET` | `/api/logs/{log_id}` | 检索特定日志的详细信息。 |
| `POST` | `/api/decisions/evaluate` | 启发式欺骗配置评估。 |
| `POST` | `/api/decisions/evaluate_rl` | 使用 Q-learning 矩阵进行动态强化学习评估。 |
| `GET` | `/api/decisions/profile/{attack_type}` | 检索特定攻击类型的静态欺骗规则。 |
| `GET` | `/api/sessions` | 获取所有攻击者会话。 |
| `GET` | `/api/sessions/clusters` | K-Means 聚类配置。 |
| `GET` | `/api/sessions/{session_id}` | 检索单个会话的状态详情。 |
| `GET` | `/api/sessions/{session_id}/recording` | 击键时间线记录。 |
| `GET` | `/api/sessions/{session_id}/summary` | 检索 LLM 分析师摘要简报。 |
| `GET` | `/api/sessions/{session_id}/behavior_timeline` | 重建攻击者行为时间线。 |
| `GET` | `/api/sessions/{session_id}/explain` | 暴露特定会话的可解释性指标（反事实、策略）。 |
| `GET` | `/api/sessions/{session_id}/report` | 返回可复制粘贴的总结事件的 Markdown 简报。 |
| `GET` | `/api/sessions/{session_id}/graph` | 计算行为序列图和下一个 TTP 预测。 |
| `GET` | `/api/digital-twin/personas` | 检索已配置的攻击者画像和描述配置。 |
| `POST` | `/api/digital-twin/simulate` | 触发模拟选定对抗性画像的实时孪生会话。 |
| `POST` | `/api/digital-twin/train-offline` | 触发批量仿真以离线训练协作智能体 Q 策略。 |
| `GET` | `/api/research/metrics` | 获取 IEEE 评估数据（包含缓存命中率、误报、延迟）。 |
| `GET` | `/api/research/learning-curve` | 获取追踪 Q 收敛的会话序列运行平均奖励。 |
| `POST` | `/api/admin/reset-demo` | 重置 SQLite 数据库表 (`honeypot.db`)。 |
| `POST` | `/api/admin/close-sessions` | 立即关闭活动会话以触发即时学习更新。 |
## 📊 ML 评估指标
从 `ml/models/evaluation_results.json` 提取的已验证 ML 模型性能指标：
| 模型分类器 | 准确率 | 精确率 | 召回率 | F1-Score |
| :--- | :---: | :---: | :---: | :---: |
| **Random Forest** | 100.00% | 100.00% | 100.00% | 100.00% |
| **XGBoost** | 100.00% | 100.00% | 100.00% | 100.00% |
| **Isolation Forest** | 97.08% | 88.30% | 88.30% | 88.30% |
## ⚖️ 评估策略
我们通过三个指标对平台进行评估：
1. **移动目标防御 (MTD) 验证：** 针对 MTD 控制器运行攻击仿真（`nmap` 端口扫描和活动 payload）。验证攻击者的映射错误率（超过 95%），同时验证在混洗期间活动的 TCP 会话保持 100% 的存活率。
2. **协作式 RL 收敛速度：** 在随机化、多向量入侵输入下，运行 500 次闭环迭代的攻击模拟器。测量 CMARL 智能体达到最佳配置所需的回合数，目标是在 50 个训练 epoch 内实现收敛。
3. **决策延迟：** 在高流量负载下分析 `/api/sessions/{session_id}/explain` 端点的性能。测量处理开销（目标 <2.0ms）以确保其满足实时执行约束。
## 📂 项目结构
```
adaptive-honeypot/
├── .github/
│ └── workflows/
│ └── ci.yml # Automated GitHub Actions Pytest Suite
├── backend/
│ ├── api/ # FastAPI REST API Route definitions
│ │ ├── admin.py # Demo controls & session closures
│ │ ├── digital_twin.py # Sandbox simulations & offline CMARL training
│ │ ├── research.py # IEEE research evaluation & learning curves
│ │ ├── decisions.py # Rule-based and CMARL engine evaluation
│ │ └── logs.py # Primary log ingestion, classification, & session lifecycles
│ ├── core/ # Engine cores
│ │ ├── __init__.py
│ │ ├── adaptive_engine.py # Rule-based heuristics
│ │ ├── behavior_intelligence.py # Sequence graphs & TTP predictions
│ │ ├── cooperative_rl_engine.py # Cooperative CMARL loops & rewards
│ │ ├── decision_engine.py # Autonomous Decision Intelligence Engine brain
│ │ ├── digital_twin.py # Adversary persona sandbox simulation
│ │ ├── explanation_engine.py # Explanations & counterfactuals
│ │ ├── feature_extractor.py # Log payload parsing
│ │ ├── threat_intel_fusion.py # Campaign similarity & actor profiles
│ │ └── traffic_logger.py
│ ├── models/ # SQLAlchemy database schema models
│ ├── services/ # Integrations (GeoIP, LLMs, external feeds)
│ ├── database.py # Database setups and migrations
│ └── main.py # FastAPI bootstrapper & session reaper task
├── frontend/ # Responsive Cyber-HUD static client files
│ ├── css/style.css # Design system stylesheet
│ ├── js/api.js # Fetch layer and status indicators
│ ├── index.html # Command Center & 3D Three.js globe
│ ├── dashboard.html # Live SOC feeds and Chart.js gauges
│ ├── sessions.html # Intruder forensic timeline cards
│ └── intel.html # Threat Map and research statistics
├── ml/ # ML Pipeline code
│ ├── models/ # Saved classifier models (.pkl)
│ ├── train_classifier.py # Training runner
│ └── evaluate_models.py # Evaluation runner
├── scripts/ # Simulation tools
│ ├── simulate_attacks.py # Closed-loop multi-step attack simulation
│ └── run_demo.bat/.sh # Demo startup launch scripts
├── tests/ # Verification tests
│ └── test_rl_learning.py # Policy model convergence unit tests
├── requirements.txt # Pinned python packages
└── README.md # System manual
```
## 📚 引用
如果您将此系统用于学术工作，请参考正在起草的 IEEE Transactions 论文：
```
@ARTICLE{PRAETOR2026,
author={Siddique, Mohammed Nayef},
journal={IEEE Transactions on Information Forensics and Security},
title={PRAETOR: Autonomous Cyber Deception Intelligence Platform Using Digital Twin Simulation, Cooperative Multi-Agent Reinforcement Learning, and Explainable Adaptive Decision Intelligence},
year={2026},
note={Under Review}
}
```
*纯文本引用：*
Mohammed Nayef Siddique, "PRAETOR: Autonomous Cyber Deception Intelligence Platform Using Digital Twin Simulation, Cooperative Multi-Agent Reinforcement Learning, and Explainable Adaptive Decision Intelligence," *IEEE Transactions on Information Forensics and Security*, 2026 (under review).
│
│
###### 核心小组评分
* **发表潜力：** `9.5 / 10`
* **行业影响：** `9.0 / 10`
* **创业潜力：** `8.5 / 10`
* **创新性：** `9.5 / 10`
* **技术深度： `9.0 / 10`
* **总体评分：** `9.1 / 10`
PRAETOR：使用数字孪生仿真、协作式多智能体强化学习和可解释自适应决策智能的自主网络欺骗情报平台
🧪 3 个 ML 模型分类器 • 🛡️ 8 个有状态欺骗配置 • 👯 3 个协作式 CMARL 智能体 • 🤖 5 种攻击者画像 • 📡 31 条 REST API 路由
### 核心研究贡献 ## 🔬 摘要与新颖性 ### 摘要 现代企业网络需要主动安全机制来防御复杂的多阶段入侵。传统的静态蜜罐因为很容易被高级攻击者识别和绕过而失效。本文介绍了 PRAETOR，这是一个动态演进蜜罐环境的自主网络欺骗平台。PRAETOR 将硬件无关的、保留状态的移动目标防御 (MTD) 系统与协作式多智能体强化学习 (CMARL) 引擎集成在一起。通过将动作空间划分为网络层面的混洗和服务层面的配置适配，该平台避免了状态空间爆炸，并加速了 Q 策略的收敛。此外，我们实现了一个低延迟的可解释自适应决策 (X-AD) 模块，该模块提供基于规则的实时决策推理，向安全分析师解释系统的适应性调整。实证评估表明，PRAETOR 实现了快速的策略收敛，在端口突变期间以 100% 的存活率维持已建立的攻击者连接，并在 2 毫秒内生成了可操作的、易于理解的欺骗决策解释。 ### 新颖性声明 与现有的静态蜜罐或依赖硬件的基于 SDN 的移动目标防御架构不同，PRAETOR 在软件层提供保留状态的套接字重定向，并结合了协调的多智能体强化学习循环。集成基于规则的解释模型解决了机器学习在网络安全中典型的“黑盒”局限性，使得自主网络欺骗变得可审查，并适用于企业部署。 ## 🛡️ 核心功能
🎭 自主决策智能融合 ML 分类、GeoIP 地理位置、威胁情报源、击键历史和协作式 RL 结果，以生成上下文感知的欺骗策略。 |
👯 协作式多智能体 RL (CMARL)将决策参数划分为网络（开放端口、延迟、Banner）、服务（模拟配置、凭证、文件）和情报（取证和元数据捕获）智能体，它们共享统一的奖励矩阵。 |
♊ 网络欺骗数字孪生一个模拟对抗性画像（脚本小子、僵尸网络、内部威胁、红队、APT）并执行扫描/利用链的仿真沙盒，用于离线训练 RL 模型和验证策略。 |
🔐 取证击键追踪记录交互式 shell 负载，隔离二进制文件投放以进行 SHA-256 完整性验证，并编制按时间顺序排列的攻击者行为时间线。 |
🧠 行为图智能构建按时间顺序映射入侵者进展的 TTP 转换图，预测可能的下一个 MITRE 技巧，并计算攻击活动的余弦相似度。 |
⚖️ 决策可解释性引擎生成决策推理，触发策略追踪规则，计算反事实场景，并导出可供 SOC 使用的 Markdown 事件报告。 |
标签：Apex, AV绕过, FastAPI, Python, 实时处理, 密码管理, 强化学习, 无后门, 机器学习, 蜜罐技术, 逆向工具