# arts.
面向 CTF 实验室和授权安全测试的自主 AI 代理
Reynard 是一个结构化的多代理黑客助手，针对 **授权的 CTF、实验室和渗透测试目标** 运行。它将 LLM 推理与 Kali Docker 运行时、实时仪表板、持久化内存、payload去重、网络研究、Caido 本地/云集成、可选的 Burp MCP 后备钩子以及精选的工具选择目录相结合。
## ✨ 亮点
- 🧠 **多代理工作流**：协调器、有界引导子代理、侦察、分析、利用、验证、报告。
- 🛠️ **Kali 工具运行时**：`sqlmap`、`nmap`、`ffuf`、`nuclei`、`gobuster`、`nikto`、`john`、`hashcat`、`radare2`、`binwalk`、`frida`、`objection` 等。
- 🧰 **Z4nzu HackingTool 感知**：`/opt/hackingtool/hackingtool.py` 在容器内可用，自动化任务首选直接工具。
- 👀 **实时仪表板**：在代理运行时查看决策、工具调用、发现、内存和验证状态。
- 🔎 **网络研究**：通过 `web_search` / `web_fetch` 获取 CTF 题解、公开 CVE、公告和官方文档。
- 🧾 **内存与去重**：记录 payload、失败尝试、事实、知识图谱实体和经验教训。
- 🔁 **PoC 验证**：验证器重放成功的 payload 并降级弱发现。
- 🧪 **专家级实验室剧本**：针对 PortSwigger 从业者/专家级别课程的确定性先验，包括 JWT、请求走私、缓存中毒、SSTI、原型污染、GraphQL、竞态条件和业务逻辑实验室。
- 📏 **离线实验室就绪性评估**：`reynard-lab-eval` 在实际运行前检查目标解析、配置文件检测、前置条件和证据计划。
- 🧵 **有界子代理**：安全的配置文件/就绪性/分析通道并行运行；除非竞态条件剧本明确允许，否则利用操作保持串行。
- ☁️ **Caido 支持**：用于测试的本地重放/历史记录桥接，以及用于用户/团队/工作区/订阅/PAT 操作的云 API。
- 🧩 **Burp MCP 后备**：当 Burp MCP 扩展在线时，提供流量/重放器/入侵器/协作者工具。
## ⚠️ 范围与安全
Reynard 专为以下场景设计：
- ✅ PortSwigger Web 安全学院实验室
- ✅ 你被允许攻击的 Hack The Box / TryHackMe / CTF 靶机
- ✅ 本地漏洞应用程序，如 DVWA、Juice Shop、WebGoat、故意存在漏洞的 Docker 实验室
- ✅ 有明确范围的授权渗透测试环境
请勿将 Reynard 用于：
- ❌ 未经许可的目标
- ❌ 在授权实验室之外的 DDoS、钓鱼、RAT、撞库或社会工程学攻击
- ❌ 除非明确在范围内，否则进行无线去认证或破坏性测试
- ❌ 在无速率限制、测试窗口和书面批准的情况下对生产环境进行测试
## 🧭 架构
```
flowchart LR
User["User Objective"] --> Orchestrator["Multi-Agent Orchestrator"]
Orchestrator --> Coordinator["Coordinator"]
Coordinator --> Recon["Recon"]
Coordinator --> Analyst["Analyst"]
Coordinator --> Exploit["Exploitation"]
Coordinator --> Validator["Validator"]
Coordinator --> Reporter["Reporter"]
Recon --> Memory["Knowledge Graph + Memory"]
Analyst --> Memory
Exploit --> Evidence["PoC Evidence Store"]
Validator --> Evidence
Exploit --> Tools["Kali Docker Tools"]
Recon --> Tools
Tools --> Docker["reynard-kali"]
Orchestrator --> UI["Live Dashboard"]
```
## 📁 项目结构
```
reynard/
|-- agent.py # Single-agent compatibility launcher
|-- orchestrator.py # Multi-agent launcher
|-- Dockerfile # Kali image with tools, Lightpanda, Z4nzu HackingTool
|-- docker-compose.yml # Starts container named reynard-kali
|-- requirements.txt # Python dependencies
|-- pyproject.toml # Package metadata
|-- .env.example # Safe environment template
|-- methodologies/ # Bug-class playbooks mounted to /data/methodologies
|-- logs/ # Run logs, ignored by git
|-- tests/ # Tests and fixtures
`-- src/hacking_agent/
|-- agents/ # coordinator, recon, analyst, exploitation, validator, reporter
|-- cli/ # CLI entry points
|-- core/ # memory, schemas, tools, state machine, providers
|-- integrations/ # Burp and Caido clients
`-- ui/ # Live dashboard
```
## 🚀 在 Windows PowerShell 上快速开始
### 1. 配置环境
```
Copy-Item .env.example .env
notepad .env
```
至少设置一个 LLM 提供商密钥。示例（兼容 DeepSeek/OpenAI）：
```
LLM_DEFAULT_PROVIDER=openai-compatible
LLM_DEFAULT_MODEL=deepseek-v4-pro
LLM_DEFAULT_BASE_URL=https://api.deepseek.com/v1
LLM_DEFAULT_API_KEY=sk-your-key
```
### 2. 安装 Python 依赖
```
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
### 3. 构建并启动 Kali 运行时
```
docker compose build
docker compose up -d
docker ps --filter "name=reynard-kali"
```
容器命名为：
```
reynard-kali
```
镜像可能很大，首次构建耗时较长，因为它需要安装 Kali 软件包、Go 工具、Lightpanda 和 Z4nzu HackingTool 仓库。
### 4. 运行多代理协调器
```
python orchestrator.py --ui --no-oob --max-iterations 25 "Solve this authorized CTF/lab target: https://TARGET"
```
默认启用有界引导子代理：
```
python orchestrator.py --max-subagents 4 "Authorized lab: https://TARGET"
python orchestrator.py --no-subagents "Authorized lab: https://TARGET"
```
仪表板打开于：
```
http://127.0.0.1:8765
```
## 🏁 针对 CTF 或实验室运行
### PortSwigger 实验室示例
首先运行一个快速的离线就绪性检查：
```
reynard-lab-eval --case "JWT authentication bypass lab. Target: https://YOUR-LAB.web-security-academy.net/" --pretty
reynard-lab-eval --pretty
```
默认的评估套件涵盖了
`docs/portswigger-coverage-matrix.md` 中映射的所有 PortSwigger 主题。
```
python orchestrator.py --ui --no-oob --max-iterations 25 "Solve this authorized PortSwigger Web Security Academy lab: SQL injection vulnerability in WHERE clause allowing retrieval of hidden data. Target: https://YOUR-LAB.web-security-academy.net/"
```
### CTF Web 挑战示例
```
python orchestrator.py --ui --max-iterations 40 "Authorized CTF target: http://10.10.10.10/. Scope: this single host only. Goal: enumerate the web app, identify the intended vulnerability, and capture the flag."
```
### 包含多个服务的 CTF 靶机
```
python orchestrator.py --ui --max-iterations 60 "Authorized CTF box: 10.10.10.10. Scope: single host only. Perform service recon, web enumeration, vulnerability analysis, exploitation proof, and report the flag path."
```
推荐的 CTF 标志：
- 使用 `--ui` 以便观察推理和工具调用。
- 对于不需要盲回调的简单实验室，使用 `--no-oob`。
- 在提示中明确范围：主机、域名、实验室 URL、允许的端口和目标。
- 对于简单的 Web 实验室，将 `--max-iterations` 设置较低；对于完整的靶机，设置较高。
## 🛡️ 在授权渗透测试环境中运行
在提示中使用清晰的范围和交战规则：
```
python orchestrator.py --ui --max-iterations 60 "Authorized pentest assessment for https://app.example.com. Scope: app.example.com only. Test OWASP Top 10 classes. Avoid destructive actions, brute force, phishing, DDoS, persistence, and data modification. Produce reproducible PoCs and a final report."
```
使用经过认证的会话：
```
python orchestrator.py --ui --auth-file .\auth-sessions.json --max-iterations 60 "Authorized pentest assessment for https://app.example.com. Scope: app.example.com only. Test access control using the configured user sessions."
```
示例 `auth-sessions.json`：
```
{
"sessions": {
"user1": {
"headers": {
"Cookie": "session=USER1_COOKIE"
}
},
"user2": {
"headers": {
"Cookie": "session=USER2_COOKIE"
}
}
}
}
```
渗透测试指南：
- 明确定义范围：域名、IP、角色、测试账户、时间窗口。
- 说明禁止行为：暴力破解、破坏性 payload、持久化、钓鱼、DDoS。
- 对 IDOR 和授权测试使用 `--auth-file`。
- 保持仪表板打开，如果运行偏离范围，请停止。
## 👀 实时仪表板
使用 `--ui` 启动：
```
python orchestrator.py --ui "Authorized lab: https://TARGET"
```
仪表板显示：
- 实时的模型计划/决策跟踪
- 协调器路由
- 专家调度
- 工具调用和被阻止的重复 payload
- 网络研究事件
- 内存事实和知识图谱更新
- PoC 证据和验证结果
- 提供商和模式错误
除非模型提供商明确返回推理流，否则提供商隐藏的推理不会暴露。UI 显示代理的可见推理、决策和工具活动。
## 🧰 工具运行时
Reynard 使用一个名为 `reynard-kali` 的 Docker 容器。工具通过 `run_shell` 执行，代理可以调用 `tool_inventory` 来决定使用什么工具。
手动检查工具清单：
```
$env:PYTHONPATH="src"
python -c "from hacking_agent.core.tools import execute_tool; print(execute_tool('tool_inventory', {'role':'general','check_container':True}))"
```
### 推荐的直接工具
| 目标 | 推荐工具 |
|---|---|
| HTTP 证明 payload | `http_request`、`curl` |
| SQL 注入 | 简单证明用 `curl`，盲注/复杂提取用 `sqlmap` |
| Web 内容发现 | `ffuf`、`gobuster`、`dirb`、`wfuzz` |
| 已知 CVE 和配置错误 | `nuclei`、`nikto`、`whatweb` |
| 端口/服务侦察 | `nmap`、`masscan` 或如果可用则用 `rustscan` |
| JS/API 端点发现 | `extract_js_endpoints`、`katana`、`gospider`、如果可用则用 `SecretFinder` |
| XSS 测试 | `browser_execute_js`、`dalfox`、如果可用则用 `XSStrike` |
| 仓库/文件中的密钥 | `trufflehog`、`gitleaks`、如果可用则用 `SecretFinder` |
| 密码/哈希处理 | `john`、`hashcat`、如果可用则用 `haiti` |
| AD 实验室 | `impacket`、`nxc`、`BloodHound`、`Certipy`、如果可用则用 `Kerbrute` |
| 云/容器实验室 | `prowler`、`pacu`、`ScoutSuite`、如果可用则用 `trivy` |
| 逆向工程/移动端 | `radare2`、`ghidra`、`jadx`、`apktool`、`frida`、`objection` |
| 取证/隐写 | `binwalk`、`foremost`、`steghide`、如果可用则用 `volatility3` |
## For example:
Dockerfile 克隆了：
```
https://github.com/Z4nzu/hackingtool.git
```
在容器内部：
```
/opt/hackingtool/hackingtool.py
```
手动运行：
```
docker exec -it reynard-kali bash
python3 /opt/hackingtool/hackingtool.py
```
Reynard 感知此封装器及其主要类别：
- 🛡️ 匿名/代理辅助工具
- 🔍 信息收集
- 📚 字典和哈希工具
- 🌐 Web 攻击工具
- 🧩 SQL 注入工具
- 💥 XSS 工具
- 🕵️ 取证和隐写工具
- 🔁 逆向工程工具
- 📱 移动安全工具
- 🏢 Active Directory 工具
- ☁️ 云安全工具
- 🔧 用于授权实验室的后渗透工具
重要的自动化规则：
除非实验室明确授权该特定行为，否则钓鱼、DDoS、RAT、社会暴力破解和无线去认证等受风险控制的类别不适合常规自主运行。
## - "🦊 Reynard": If "Reynard" is a proper noun, I keep it, so the translation might be the same, but since it's to Simplified Chinese, perhaps I need to add context or translate the emoji description? But emojis are not text, so I should keep them.
Reynard 将 **Caido Cloud** 与 **Caido Local Bridge** 分开：
- `caido_local_api` 是 API 测试、Replay、HTTP 历史记录、请求集合和手动审查工件的首选路径，当本地桥接插件运行时。
- `caido_cloud_api` 仅用于 Caido 账户/团队/工作区/PAT 操作。
配置 Cloud API：
```
CAIDO_PAT=caido_YOUR_PERSONAL_ACCESS_TOKEN
CAIDO_API_BASE_URL=https://api.caido.io
```
配置本地桥接：
```
CAIDO_LOCAL_BRIDGE_URL=http://127.0.0.1:17650
CAIDO_LOCAL_BRIDGE_TOKEN=optional-shared-secret
```
- Caido Cloud 状态
- 用户/团队信息
- 邀请
- 工作区
- 订阅
- 优惠券
- PAT 生命周期管理器
- 原始 Cloud API 后备路径
- 桥接状态
- 通过 Caido Replay 发送原始请求
- 创建/发送 Replay 会话
- 搜索 HTTP 历史记录
- 获取历史记录项
- 从代理证据创建 Caido 发现
预期的桥接契约请参见 `docs/caido-local-bridge.md`。
## The user said "output exactly 4 line(s) of translation", so I need to provide Chinese translations.
Burp MCP 现在是 Burp 特定工作流的后备方案。如果你的 Burp MCP 扩展正在运行，Reynard 可以使用：
- 发送原始 HTTP/1.1 请求
- 读取扫描器问题
- 生成协作者 payload
- 轮询协作者交互
- 创建重放器选项卡
- 将请求发送到入侵器
如果 Burp MCP 离线，代理会回退到 Caido 本地桥接、`http_request`、`curl`、OOB 回调和差异分析。
## 🔎 网络研究
可选的搜索提供商：
```
BRAVE_SEARCH_API_KEY=YOUR_BRAVE_KEY
SERPAPI_API_KEY=YOUR_SERPAPI_KEY
```
代理在以下情况使用 `web_search` 和 `web_fetch`：
- 已知挑战/靶机名称
- 发现了服务/版本横幅
- 可能存在 CVE 或公开漏洞利用
- 命令缺失或安装语法不明确
- 工具返回未知标志/用法错误
- 在尝试后陷入困境
- 官方文档或题解可以减少猜测
为了获得最佳搜索质量，请配置 Brave 或 SerpAPI。如果未设置任何密钥，Reynard 将回退到 DuckDuckGo HTML 搜索。
对于盲注 XXE/SSRF/CMDi 实验室，请 **不要** 使用 `--no-oob`；代理需要通过 `interactsh-client`、Burp Collaborator 或其他批准的回调服务进行 OOB 回调。
## 🤖 LLM 提供商
| 提供商 | 所需密钥环境变量 | 备注 |
|---|---|---|
| `deepseek` | `DEEPSEEK_API_KEY` | 兼容 OpenAI 的 DeepSeek API |
| `openai` / `gpt` | `OPENAI_API_KEY` | OpenAI 模型 |
| `anthropic` / `claude` | `ANTHROPIC_API_KEY` | Claude Messages API |
| `qwen` / `dashscope` | `QWEN_API_KEY` 或 `DASHSCOPE_API_KEY` | Qwen/DashScope |
| `local` | 可选 | 运行在 `http://localhost:8000/v1` 的兼容 OpenAI 的本地服务器 |
| `ollama` | 可选 | 运行在 `http://localhost:11434/v1` 的兼容 OpenAI 的 Ollama |
| `openai-compatible` | `LLM_DEFAULT_API_KEY` | 自定义的兼容 OpenAI 的网关 |
推理控制：
```
LLM_DEFAULT_REASONING_EFFORT=high
LLM_ANALYST_REASONING_EFFORT=high
LLM_EXPLOITATION_REASONING_EFFORT=high
LLM_COORDINATOR_THINKING=true
LLM_COORDINATOR_THINKING_BUDGET=8000
LLM_DEFAULT_ENABLE_THINKING_PARAM=false
```
运行时自动降级不支持的提供商特定推理参数。
## 🧪 常用命令
启动运行时：
```
docker compose up -d
```
检查运行时：
```
docker ps --filter "name=reynard-kali"
```
在 Kali 中打开一个 shell：
```
docker exec -it reynard-kali bash
```
运行多代理模式：
```
python orchestrator.py --ui --max-iterations 40 "Authorized target: https://TARGET"
```
运行单代理模式：
```
python agent.py --ui "Authorized target: https://TARGET"
```
停止运行时：
```
docker compose down
```
## 🧾 日志与输出
运行时日志写入目录：
```
logs/
```
代理记录：
- 工具调用
- payload 历史
- 失败尝试
- 知识图谱实体
- 事实与关系
- PoC 证据
- 验证结果
- 最终报告摘要
## ✅ 推荐工作流
1. 启动 Docker：`docker compose up -d`
2. 使用 `--ui` 运行
3. 提供明确的授权范围
4. 观察仪表板
5. 让验证器重放任何成功的 PoC
6. 审查最终报告
7. 如果代理遇到困难，将有用的经验教训保存到方法论中
## 法律声明
Reynard 仅用于教育、CTF、研究实验室和授权的安全评估。你有责任确保每个目标、技术和工具调用都符合适用的交战规则和法律。