SanMuzZzZz/LuaN1aoAgent
GitHub: SanMuzZzZz/LuaN1aoAgent
基于 LLM 与 P-E-R 认知框架的自主渗透测试 Agent，通过因果图推理与动态任务规划实现智能化的攻击链编排与漏洞利用。
Stars: 404 | Forks: 67
LuaN1aoAgent
**认知驱动型 AI 黑客**
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](CONTRIBUTING.md)
[](#system-architecture)
[](#)
![[TCH]Top-RankedIntelligent Pentest Project](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/25e5dde122021615.png)
**🧠 像人类专家一样思考** • **📊 动态图规划** • **🔄 从失败中学习** • **🎯 证据驱动决策**
[🚀 快速开始](#quick-start) • [✨ 核心创新](#core-innovations) • [🏗️ 系统架构](#system-architecture) • [🗓️ 路线图](#roadmap)
[🌐 中文版](README_zh.md) • [English Version](README.md)
## 📖 简介
**LuaN1ao (鸾鸟)** 是由大语言模型 (LLM) 驱动的新一代**自主渗透测试 Agent**。
传统的自动化扫描工具依赖于预定义的规则，在复杂的现实场景中往往力不从心。LuaN1ao 通过创新性地融合 **P-E-R (Planner-Executor-Reflector) Agent 协作框架**与**因果图推理**技术，突破了这些限制。
LuaN1ao 模拟人类安全专家的思维模式：
- 🎯 **战略规划**：基于全局态势感知动态规划攻击路径
- 🔍 **证据驱动**：构建严密的“证据-假设-验证”逻辑链
- 🔄 **持续进化**：从失败中学习，自主调整战术策略
- 🧠 **认知闭环**：形成规划-执行-反思的完整认知循环
从信息收集到漏洞利用，LuaN1ao 将渗透测试从“自动化工具”提升为“自主 Agent”。
## 🖼️ 项目展示
## 🚀 核心创新
### 1️⃣ **P-E-R Agent 协作框架** ⭐⭐⭐
LuaN1ao 将渗透测试思维解耦为三个独立但协作的认知角色，形成完整的决策闭环：
- **🧠 Planner**
- **战略大脑**：基于全局图感知进行动态规划
- **自适应能力**：识别死胡同并自动生成替代路径
- **图操作驱动**：输出结构化的图编辑指令而非自然语言
- **并行调度**：基于拓扑依赖自动识别可并行化任务
- **⚙️ Executor**
- **战术执行**：专注于单一子任务工具调用与结果分析
- **工具编排**：通过 MCP (Model Context Protocol) 统一调度安全工具
- **上下文压缩**：智能消息历史管理，避免 token 溢出
- **容错机制**：自动处理网络瞬态错误和工具调用失败
- **⚖️ Reflector**
- **审计分析**：审查任务执行情况，验证 Artifact 有效性
- **失败归因**：L1-L4 级别失败模式分析，防止错误重演
- **情报生成**：提取攻击情报，构建知识积累
- **终止控制**：判断目标达成或任务陷入困境
**核心优势**：角色分离避免了单 Agent 的“精神分裂”问题。各组件专注于核心职责，通过事件总线协作。
### 2️⃣ **因果图推理** ⭐⭐⭐
LuaN1ao 拒绝盲目猜测和 LLM 幻觉，构建显式的因果图来驱动测试决策：
```
graph LR
E[🔍 Evidence
Evidence Node] -->|Support| H[💭 Hypothesis
Hypothesis Node]
H -->|Validation| V[⚠️ Vulnerability
Vulnerability Node]
V -->|Exploitation| X[💥 Exploit
Exploit Node]
```
**核心原则**：
- **证据优先**：任何假设都需要明确的前置证据支持
- **置信度量化**：每条因果边都有置信度分数，避免盲目推进
- **可追溯性**：完整记录推理链，用于失败追溯和经验复用
- **防止幻觉**：强制性证据验证，拒绝无依据的攻击
**示例场景**：
```
Evidence: Port scan discovers 3306/tcp open
↓ (Confidence 0.8)
Hypothesis: Target runs MySQL service
↓ (Validation successful)
Vulnerability: MySQL weak password/unauthorized access
↓ (Attempt exploitation)
Exploit: mysql -h target -u root -p [brute-force/empty password]
```
### 3️⃣ **Plan-on-Graph (PoG) 动态任务规划** ⭐⭐⭐
告别静态任务列表。LuaN1ao 将渗透测试计划建模为动态演化的**有向无环图 (DAG)**：
**核心特性**：
- **图操作语言**：Planner 输出标准化的图编辑操作 (`ADD_NODE`, `UPDATE_NODE`, `DEPRECATE_NODE`)
- **实时适应**：任务图随测试进度实时变形
- 发现新端口 → 自动挂载服务扫描子图
- 遇到 WAF → 插入绕过策略节点
- 路径阻塞 → 自动剪枝或分支规划
- **拓扑依赖管理**：基于 DAG 拓扑自动识别并**并行化**独立任务
- **状态跟踪**：每个节点包含状态机 (`pending`, `in_progress`, `completed`, `failed`, `deprecated`)
**与传统规划对比**：
| 特性 | 传统任务列表 | Plan-on-Graph |
|---------|----------------------|---------------|
| 结构 | 线性列表 | 有向图 |
| 依赖管理 | 手动排序 | 拓扑自动排序 |
| 并行能力 | 无 | 自动识别并行路径 |
| 动态调整 | 重新生成 | 局部图编辑 |
| 可视化 | 困难 | 原生支持 (Web UI) |
**可视化示例**：启动 Web Server 即可在浏览器中实时查看任务图演化。
## 核心能力
### 工具集成 (MCP 协议)
LuaN1ao 通过 **Model Context Protocol (MCP)** 实现工具的统一集成与调度：
- **HTTP/HTTPS 请求**：支持自定义 Headers、代理、超时控制
- **Shell 命令执行**：安全封装的系统命令调用（建议容器化执行）
- **Python 代码执行**：动态执行 Python 脚本处理复杂逻辑
- **元认知工具**：`think` (深度思考)、`hypothesize` (假设生成)、`reflect` (经验总结)
- **任务控制**：`halt_task` (提前终止任务)
### 知识增强 (RAG)
- **向量检索**：基于 FAISS 的高效知识库检索
- **领域知识**：集成 PayloadsAllTheThings 等开源安全知识库
- **动态学习**：持续添加自定义知识文档
### Web 可视化 (新架构)
Web UI 现已作为独立服务运行，由数据库驱动，实现持久的任务监控与管理。
- **实时监控**：浏览器查看动态任务图演化与实时日志。
- **节点详情**：点击节点查看执行日志、Artifact、状态转换。
- **任务管理**：创建、中止以及**删除**历史任务。
- **数据持久化**：所有任务数据存储于 SQLite (`luan1ao.db`)，重启后保留历史。
### 人机协同 (HITL) 模式
LuaN1ao Agent 支持 Human-in-the-Loop (HITL) 模式，允许专家监督并干预决策过程。
- **启用**：在 `.env` 中设置 `HUMAN_IN_THE_LOOP=true`。
- **审批**：Agent 在生成计划（初始或动态）后暂停，等待通过 Web UI 或 CLI 进行人工资质审批。
- **修改**：专家可在执行前拒绝或直接修改计划 (JSON 编辑)。
- **注入**：支持通过 Web UI 实时注入新的子任务（“主动干预”）。
**交互方式**：
- **Web UI**：自动弹出审批模态框。使用“Modify”编辑计划或点击“Add Task”按钮注入任务。
- **CLI**：提示符为 `HITL >`。输入 `y` 批准，`n` 拒绝，或 `m` 修改（打开系统编辑器）。
## 🗓️ 路线图
- [ ] **经验自我进化**
- 跨任务长期记忆
- 自动提取成功攻击模式入库向量库
- 基于历史经验的智能推荐
- [x] **人机协同模式**
- 高风险操作前确认机制
- 运行时任务图编辑接口 (Graph Injection)
- 专家干预与策略注入
- [ ] **工具生态扩展**
- 集成 Metasploit RPC 接口
- 支持 Nuclei, Xray, AWVS 扫描器
- Docker 沙箱工具执行环境
- [ ] **多模态能力**
- 图像识别（验证码、截图分析）
- 流量分析（PCAP 文件解析）
### 长期愿景
- [ ] **协作 Agent 网络**：多 Agent 分布式协作
- [ ] **强化学习集成**：通过环境交互自主优化攻击策略，实现 Agent 在复杂场景下的自我进化与策略收敛
- [ ] **合规报告生成**：自动生成符合规范的渗透测试报告
## 📋 系统需求
| 组件 | 需求 | 备注 |
|-----------|--------------|-------|
| **操作系统** | Linux (推荐) / macOS / Windows (WSL2) | 建议在隔离环境中运行 |
| **Python** | 3.10+ | 需支持 asyncio 和类型提示 |
| **LLM API** | OpenAI 兼容格式 | 支持 GPT-4o, DeepSeek, Claude-3.5 等 |
| **内存** | 最低 4GB，推荐 8GB+ | RAG 服务和 LLM 推理需要内存 |
| **网络** | 互联网连接 | 访问 LLM API 及知识库更新 |
## 🚀 快速开始
### 步骤 1：安装
```
# Clone repository
git clone https://github.com/SanMuzZzZz/LuaN1aoAgent.git
cd LuaN1aoAgent
# 创建 virtual environment (推荐)
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# Windows: venv\Scripts\activate
# 安装 dependencies
pip install -r requirements.txt
```
### 步骤 2：配置
#### 2.1 环境变量配置
```
# 复制 configuration template
cp .env.example .env
# 编辑 .env file
nano .env # or use your preferred editor
```
**核心配置项**：
```
# LLM API Configuration (必填)
LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
LLM_API_BASE_URL=https://api.openai.com/v1
# 建议使用强大的模型以获得更好的结果
LLM_DEFAULT_MODEL=gpt-4o
LLM_PLANNER_MODEL=gpt-4o # Planner requires strong reasoning capability
LLM_EXECUTOR_MODEL=gpt-4o
LLM_REFLECTOR_MODEL=gpt-4o
OUTPUT_MODE=default # simple/default/debug
```
#### 2.2 知识库初始化（首次运行必选）
LuaN1ao 依赖 **RAG (检索增强生成)** 系统获取最新安全知识。首次运行前需初始化知识库：
```
# 1. Clone PayloadsAllTheThings 知识库
mkdir -p knowledge_base
git clone https://github.com/swisskyrepo/PayloadsAllTheThings \
knowledge_base/PayloadsAllTheThings
# 2. Build vector index (需要几分钟)
cd rag
python -m rag_kdprepare
```
### 步骤 3：运行（新架构）
系统现在作为两个独立进程运行：**Web Server** (仪表盘) 和 **Agent** (工作进程)。它们通过本地 SQLite 数据库 (`luan1ao.db`) 通信。
#### 1. 启动 Web Server (仪表盘)
首先启动持久化 Web 界面。该进程应保持运行。
```
python -m web.server
```
#### 2. 运行 Agent 任务
打开一个**新终端窗口**并运行 Agent。Agent 将执行任务，将日志写入数据库，完成后退出。Web UI 将实时更新。
```
# 基本用法
python agent.py \
--goal "Perform comprehensive web security testing on http://testphp.vulnweb.com" \
--task-name "demo_test"
# 启用 --web flag 以打印 task URL
python agent.py \
--goal "Scan localhost" \
--task-name "local_scan" \
--web
```
### 查看结果
- **实时**：使用 Web UI () 监控进度。
- **归档**：任务历史持久化于数据库中。日志和指标也保存在 `logs/TASK-NAME/TIMESTAMP/`：
```
logs/demo_test/20250204_120000/
├── run_log.json # Complete execution log (includes all P-E-R interactions)
├── metrics.json # Performance metrics and statistics
└── console_output.log # Formatted console output
```
## 🏗️ 系统架构
### 整体架构图
```
┌─────────────────────────────────────────────────────────┐
│ User Goal │
│ "Perform comprehensive penetration testing" │
└────────────────────────┬────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ P-E-R Cognitive Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Planner │ ───> │ Executor │ ───> │Reflector │ │
│ │ │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ ▲ │
│ │ LLM API Calls │
└─────────────────────────┼────────────────────────────────┘
│
┌─────────────────────────┴────────────────────────────────┐
│ Core Engine │
│ ┌────────────────────────────────────────────────┐ │
│ │ GraphManager │ │
│ │ • Task Graph Management (DAG) │ │
│ │ • State Tracking and Updates │ │
│ │ • Topological Sorting and Dependency Resolution│ │
│ │ • Parallel Task Scheduling │ │
│ └────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Database Layer (SQLite) │ │
│ │ • Persistence for Tasks, Graphs, Logs │ │
│ │ • Decoupled State Management │ │
│ └────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ EventBroker (Global) │ │
│ │ • Inter-component Communication │ │
│ │ • Event Publishing/Subscription │ │
│ └────────────────────────────────────────────────┘ │
└─────────────────────────┬────────────────────────────────┘
│
┌─────────────────────────┴────────────────────────────────┐
│ Capability Layer │
│ ┌────────────────────┐ ┌──────────────────────────┐ │
│ │ RAG Knowledge │ │ MCP Tool Server │ │
│ │ Service │ │ │ │
│ │ • FAISS Vector Retrieval│ • http_request │ │
│ │ • Knowledge Document Parsing│ • shell_exec │ │
│ │ • Similarity Search │ • python_exec │ │
│ │ │ • think/hypothesize │ │
│ └────────────────────┘ │ • halt_task │ │
│ └──────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
### P-E-R 协作流程
```
sequenceDiagram
participant U as User
participant P as Planner
participant G as GraphManager
participant E as Executor
participant R as Reflector
participant DB as SQLite DB
participant W as Web UI
U->>P: Input Goal
P->>G: Initialize Task Graph
G->>DB: Persist Initial State
W->>DB: Poll for Updates (SSE)
loop P-E-R Cycle
P->>G: Analyze graph, generate graph edit operations
G->>G: Update graph structure
G->>DB: Sync Updates
G->>E: Assign pending sub-tasks
E->>E: Execute Tools
E->>DB: Log Events
E->>R: Request reflection
R->>R: Analyze success/failure
R->>G: Update node status
G->>DB: Sync Updates
end
```
### 目录结构
```
LuaN1aoAgent/
├── agent.py # Main entry point, P-E-R cycle control
├── requirements.txt # Project dependencies
├── pyproject.toml # Project configuration and code quality tool settings
├── mcp.json # MCP tool service configuration
├── .env # Environment variables configuration (manual creation required)
│
├── conf/ # Configuration module
│ ├── config.py # Core configuration items (LLM, scenarios, parameters)
│ └── __init__.py
│
├── core/ # Core engine
│ ├── planner.py # Planner implementation
│ ├── executor.py # Executor implementation
│ ├── reflector.py # Reflector implementation
│ ├── graph_manager.py # Graph manager
│ ├── events.py # Event bus
│ ├── console.py # Console output management
│ ├── data_contracts.py # Data contract definitions
│ ├── tool_manager.py # Tool manager
│ ├── intervention.py # Human-in-the-Loop manager
│ ├── database/ # Database persistence layer
│ │ ├── models.py # SQLAlchemy models
│ │ └── utils.py # DB utilities
│ └── prompts/ # Prompt template system
│
├── llm/ # LLM abstraction layer
│ ├── llm_client.py # LLM client (unified interface)
│ └── __init__.py
│
├── rag/ # RAG knowledge enhancement
│ ├── knowledge_service.py # FastAPI knowledge service
│ ├── rag_client.py # RAG client
│ ├── rag_kdprepare.py # Knowledge base index construction
│ ├── markdown_chunker.py # Document chunking
│ └── model_manager.py # Embedding model management
│
├── tools/ # Tool integration layer
│ ├── mcp_service.py # MCP service implementation
│ ├── mcp_client.py # MCP client
│ └── __init__.py
│
├── web/ # Web UI
│ ├── server.py # Web dashboard server
│ ├── static/ # Frontend assets
│ └── templates/ # HTML templates
│
├── knowledge_base/ # Knowledge base directory (manual creation required)
│ └── PayloadsAllTheThings/ # Security knowledge base (clone required)
│
└── logs/ # Runtime logs and metrics
└── TASK-NAME/
└── TIMESTAMP/
├── run_log.json
├── metrics.json
└── console_output.log
```
## 🔐 安全免责声明
**⚠️ 重要提示：本软件仅用于授权的安全测试和教育目的。请仔细阅读以下内容。**
### 使用限制
使用 LuaN1ao 即表示您确认并同意以下条款：
#### 1. 授权要求
- **须明确授权**：在测试任何系统、网络或应用程序之前，您**必须**获得系统所有者的**明确书面授权**。
- **范围限制**：测试活动必须严格限制在授权范围内，不得越界。
- **教育与研究用途**：本工具适用于网络安全教育、学术研究和授权的安全评估。
#### 2. 法律合规
- **遵守法律**：您需自行确保使用本工具符合所有适用的地方、国家及国际法律法规。
- **法律后果**：未经授权的渗透测试是**违法的**，可能导致刑事起诉、民事诉讼及巨额罚款。
- **个人责任**：用户需承担因不当使用本工具而产生的一切法律后果。
#### 3. 道德使用
- **负责任披露**：发现的安全漏洞应遵循负责任披露原则。
- **专业标准**：使用本工具须符合专业安全研究标准和行业最佳实践。
- **保密义务**：尊重测试过程中发现的所有漏洞的隐私性和保密性；未经授权不得披露或利用。
#### 4. 禁止行为
**本软件严禁用于：**
- ❌ 未经授权访问计算机系统、网络或数据
- ❌ 恶意攻击、破坏或服务中断
- ❌ 窃取、篡改或破坏数据
- ❌ 任何非法或犯罪活动
- ❌ 侵犯隐私或违反保密协议
- ❌ 商业间谍或不正当竞争
### 技术风险警告
#### 5. 代码执行风险
- **高特权工具**：LuaN1ao 包含 `_exec` 和 `python_exec` 等高特权工具，具备执行任意系统命令和代码的能力。
- **潜在破坏性**：不当使用可能对目标系统造成**不可逆的损害**，包括但不限于：
- 系统崩溃或服务中断
- 数据丢失或损坏
- 配置文件修改
- 安全机制受损
#### 6. 隔离环境要求
- **强制隔离**：**强烈建议在以下隔离环境中运行：**
- Docker 容器（推荐）
- 专用虚拟机 (VMware, VirtualBox, KVM 等)
- 完全隔离的沙箱环境
- **网络隔离**：测试环境应与生产网络物理或逻辑隔离。
- **数据隔离**：请勿在包含真实用户数据或敏感信息的系统上运行。
#### 7. 禁止生产环境使用
- **禁止生产使用**：切勿在生产环境、关键业务系统或包含敏感数据的系统上运行 LuaN1ao。
- **仅限测试环境**：仅在专用测试、开发或沙箱环境中使用。
### 免责声明与责任限制
#### 8. 软件保证声明
- **按“原样”提供**：本软件按“原样”提供，不提供任何形式的明示或暗示保证。
- **无适销性保证**：不保证适销性、特定用途适用性或不侵权。
- **无结果保证**：不保证软件能发现所有漏洞或达到预期结果。
#### 9. 责任限制
**作者和贡献者明确声明不对本软件的滥用承担任何责任。**
在任何情况下，开发者、贡献者或版权持有人均不对以下情况承担责任：
- ✗ 因使用或无法使用本软件而产生的任何直接、间接、偶然、特殊、惩罚性或后果性损害
- ✗ 未经授权的系统访问或数据泄露
- ✗ 系统损坏、数据丢失或业务中断
- ✗ 法律诉讼、罚款或其他法律后果
- ✗ 商誉损失、利润损失或其他经济损失
- ✗ 即使已被告知可能发生此类损害
#### 10. 用户完全责任声明
- **独立判断**：用户对使用本工具的决定拥有完全自主权和判断力。
- **风险承担**：使用本软件的所有风险由用户承担。
- **完全责任**：用户对本工具的所有使用行为及其后果承担全部责任。
### 知情同意
**通过下载、安装、配置或使用 LuaN1ao，您明确声明：**
1. ✅ 您已完整阅读并充分理解本免责声明的所有条款
2. ✅ 您同意受本免责声明约束
3. ✅ 您承诺仅在授权范围内使用本工具
4. ✅ 您理解并接受使用本工具的所有风险
5. ✅ 您承认开发者不对您的任何使用行为负责
**如果您不同意上述任何条款，请立即停止使用本软件并删除所有相关文件。**
## 🤝 贡献
我们欢迎各种形式的贡献！无论是报告 Bug、提出新功能建议、改进文档还是提交代码。
### 如何贡献
1. **报告问题**：在 [Issues](https://github.com/SanMuzZzZz/LuaN1aoAgent/issues) 页面提交 Bug 报告或功能请求
2. **提交代码**：Fork 本仓库，创建分支并提交 Pull Request
3. **改进文档**：勘误纠错、补充说明、增加示例
4. **分享经验**：在 Discussions 分享使用经验和最佳实践
### 贡献指南
详细的贡献流程和代码规范请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 📝 许可证
本项目基于 [Apache License 2.0](LICENSE) 许可。
```
Copyright 2025 LuaN1ao (鸾鸟) Project Contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```
## 📞 联系我们
- **GitHub Issues**: [提交 Issue](https://github.com/SanMuzZzZz/LuaN1aoAgent/issues)
- **GitHub Discussions**: [参与讨论](https://github.com/SanMuzZzZz/LuaN1aoAgent/discussions)
- **Email**: <1614858685x@gmail.com>
- **WeChat**: SanMuzZzZzZz
## ⭐ Star 历史
如果 LuaN1ao 对您有所帮助，请给我们一个 Star ⭐！
## 🌐 语言版本
- [English](README.md) (默认)
- [简体中文](README_zh.md)标签：CISA项目, DeepSeek, DLL 劫持, Go语言工具, P-E-R框架, PE 加载器, Python, TGT, Web报告查看器, XBOW Benchmark, XXE攻击, 人工智能, 决策引擎, 动态规划, 反取证, 因果图推理, 图神经网络, 大语言模型, 安全评估, 密码管理, 攻防演练, 无后门, 灰盒测试, 熵值分析, 用户模式Hook绕过, 网络安全, 自主代理, 自动化利用, 自动化攻防, 逆向工具, 隐私保护, 黑客模拟