R1zoro/ChainsawRecon
GitHub: R1zoro/ChainsawRecon
一款具备范围感知和知识图谱记忆的自主 AI 渗透测试智能体，通过隔离沙箱和证据驱动的工作流实现可审计的 Web 应用安全评估。
Stars: 0 | Forks: 0
# ChainsawRecon
**ChainsawRecon** 是一个自主的、具备范围感知能力的 AI 渗透测试与安全评估智能体。它在隔离的 Docker 沙箱中编排安全工具，构建 Web 应用和 API 的有状态世界模型，并通过具体的证据验证来执行假设驱动的实验。
ChainsawRecon 专为授权的渗透测试、安全审计和防御性攻击面评估而设计，将高级 AI 推理与确定性、可审计的执行过程桥接在一起。
## 🌟 核心功能
* **有状态世界模型与交战记忆：** 在多次测试运行中维护持久的关系状态（组织、应用、服务、路由、端点、认证上下文、技术），而不是孤立地处理每个目标。
* **假设生命周期与目标驱动的工作流：** 超越以工具为中心的输出。用结构化的假设跟踪（`observed` $\rightarrow$ `suspected` $\rightarrow$ `evidence_required` $\rightarrow$ `experiment_planned` $\rightarrow$ `reproduced` $\rightarrow$ `validated`/`rejected`）取代原始的扫描器输出。
* **隔离沙箱执行：** 所有命令执行均发生在受严格限制的 Docker 容器内。LLM 绝不会拥有宿主机 shell 访问权限或直接的系统访问权限。
* **范围守卫与速率控制：** 对每一个出站工具请求执行严格的执行前范围验证，并提供可配置的速率限制和请求间隔。
* **多模态证据捕获：** 将 HTTP 请求/响应、HAR 浏览器捕获、技术手册和静态源代码分析导入并标准化为规范的、可重放的证据项。
* **独立验证引擎：** 发现结果遵循证据阶梯，在分类之前必须通过独立的重放和差分对照测试。
* **人类可读目录与机器可读状态：** 生成用于 AI 推理的 SQLite/JSON 知识图谱，以及用于手动测试和报告的整洁 Markdown/TSV 目录。
## 🛠️ 架构与工作原理
ChainsawRecon 跨越四个结构化层运行：
1. **AI 编排与推理层：** Coordinator 模型接收目标范围、当前世界模型状态、覆盖缺口和活动的安全目标。它选择结构化的 JSON 操作，而不是执行未经验证的 shell 命令。
2. **Worker 与策略层：** 有界执行流处理专门的任务（目标映射、技术分析、API/GraphQL 表面探测、认证上下文评估和结果验证）。
3. **工具与沙箱执行层：** 在由严格的 `ScopeGuard` 管理的沙箱环境中执行已批准的工具（`httpx`、`katana`、`nuclei`、`ffuf`、`dalfox`、`sqlmap`、`inql`、`clairvoyance` 等）。
4. **数据与知识记忆层：** 采用双数据库设计，具有用于存储瞬时试验数据的一次性 **Run Store** (`recon.db`)，以及用于存储已验证的跨运行情报和目标拓扑的持久化 **Engagement Store** (`knowledge.db`)。
## 📋 前置条件
* **操作系统：** Linux、macOS 或 Windows (PowerShell/WSL2)
* **Python：** 3.10 或更高版本
* **Docker：** 在本地运行的 Docker Desktop 或 Docker Engine
* **本地 LLM 服务器（可选 / 推荐）：** Ollama、vLLM、LM Studio 或任何兼容 OpenAI 的 API endpoint。
* **Git**
## 🚀 快速入门与设置指南
### 1. 克隆代码库并设置 Python 环境
```
git clone https://github.com/your-org/ChainsawRecon.git
cd ChainsawRecon
# 创建并激活虚拟环境
python -m venv .venv
# 在 Linux/macOS 上：
source .venv/bin/activate
# 在 Windows (PowerShell) 上：
# .venv\Scripts\Activate.ps1
# 以可编辑模式安装依赖项
pip install -e .
```
### 2. 构建 Docker 执行沙箱
安全工具在一个专用的 Docker 容器（`testing-sandbox`）内运行。在本地构建镜像：
```
docker build --pull --no-cache -f sandbox/Dockerfile.sandbox -t testing-sandbox:latest .
```
验证沙箱工具安装：
```
docker run --rm bounty-sandbox:latest bash -lc "command -v httpx nuclei katana inql feroxbuster dalfox"
```
### 3. 启动本地 LLM 提供程序（例如 Ollama）
确保您的 LLM 提供程序正在本地运行，并提供兼容 OpenAI 的 API endpoint：
```
# 使用 Ollama 的示例：
ollama serve
# 拉取您首选的模型（例如，Qwen2.5-Coder、Mistral、Llama-3 等）
ollama pull qwen2.5-coder:14b
```
## 📁 设置交战工作区
ChainsawRecon 将评估数据组织到交战目录中。
### 1. 初始化交战目录
```
# 复制 template 目录
Copy-Item -Recurse engagements\_template engagements\corporate-audit
```
### 2. 配置范围与规则
填充 `engagements/corporate-audit/program/` 内的项目定义文件：
* `scope.json`：机器可读的目标域名、CIDR 和速率限制。
* `in-scope.txt`：授权的目标 URL 和主机名列表。
* `out-of-scope.txt`：排除的 IP 地址或域名。
* `rules.md`：评估规则、测试窗口和操作限制。
* `prompt.md`：为智能体提供的高级安全目标或应用上下文。
* `secrets.env`：*（可选）* 认证 token 或测试凭据。保持 git 忽略状态。
* `priority-targets.txt`：*（可选）* 优先评估的高价值路由/API。
## 💻 用法与 CLI 参考
针对已初始化的交战任务运行 ChainsawRecon：
```
python -m bounty_agent.cli \
--engagement engagements/corporate-audit \
--mode attack \
--provider ollama \
--model ollama/qwen3.5:4b \
--llm-base-url http://localhost:11434/v1 \
--llm-api-key ollama \
--runner docker \
--docker-image testing-sandbox \
--execute \
--max-steps 1000 \
--max-commands-per-minute 40
```
### 操作模式
| 模式 | 描述 | 主要关注点 |
|---|---|---|
| `mapping` | 资产发现与目标映射。 | 发现主机、路由、技术、JS bundles 和端点。无侵入性测试。 |
| `recon` | 主动指纹识别与表面分析。 | 低速率表面探测、标头检查和框架分类。 |
| `attack` | 假设生成与证据主导的测试。 | 基于发现的表面执行安全、结构化的安全实验。 |
| `auto` | 自主阶段转换。 | 根据状态覆盖率自动从 mapping $\rightarrow$ recon $\rightarrow$ attack 推进。 |
| `assistant` | 操作员辅助的交互模式。 | 允许显式的外部搜索查询和操作员指导。 |
### 关键 CLI 标志
* `--engagement `：*（必需）* 目标交战文件夹的路径。
* `--mode `：执行模式（默认：`auto`）。
* `--execute`：在沙箱容器内启用实时工具执行。
* `--dry-run`：以模拟模式运行规划器，而不执行外部命令。
* `--provider `：LLM 提供程序后端类型。
* `--model `：在您的提供程序后端中指定的模型标识符。
* `--llm-base-url `：API endpoint URL（例如，`http://localhost:11434/v1`）。
* `--max-steps `：会话的全局步骤/操作预算。
* `--max-commands-per-minute `：对出站命令强制执行速率限制。
* `--har-file `：*（可选）* 将网络流量捕获导入交战证据模型。
* `--source-dir `：*（可选）* 导入静态源代码目录以进行路由和接收点分析。
## 🔒 安全控制与执行边界
1. **Docker 隔离：** 工具在具有丢弃功能、非 root 执行和 CPU/RAM 限制的容器内运行。
2. **ScopeGuard 强制执行：** 在执行任何操作之前，每个域或 IP 目标都会根据 `scope.json` 进行验证。
3. **无未清理的 Shell 访问权限：** LLM 发出严格的 JSON 格式操作（`run_tool`、`write_file`、`http_request`、`finish`），这些操作在执行前会被确定性地解析和验证。
4. **证据阶梯：** 原始工具命中永远不会直接产生发现结果。它会生成一个 `observation`，进而创建一个 `hypothesis`，这需要一个 `experiment`、原始 `evidence` 以及独立的 `reproduction`。
5. **WAF 与故障感知：** Cloudflare 或速率限制响应会触发自动退避、证据保留和任务延迟，而不是嘈杂的暴力破解尝试。
## 📊 产物与输出
执行后，所有会话记录都会保存在 `engagements//agent/` 下：
```
engagements//agent/
├── knowledge.db # Curated cross-run persistent relational database
├── engagement-report.md # Comprehensive executive & technical report
├── catalogs/ # Operational human-readable catalogs
│ ├── architecture.md # Target topology, services, and tech stack map
│ ├── routes.json # Discovered application endpoints and HTTP methods
│ ├── technologies.json # Detected software stacks & component playbooks
│ └── world-model.json # Exported machine-readable knowledge graph
└── runs// # Execution artifacts per session
├── trace.jsonl # Complete audit log of every LLM decision & command
├── report.md # Per-run technical summary
├── session.state.json # Run status, metrics, and step accounting
└── workspace/ # Raw tool outputs, evidence items, and HTTP logs
```
## 📜 许可证与合规性
ChainsawRecon 专为授权的安全测试、防御态势评估和教育研究而设计。用户有责任在发起任何安全评估之前获得资产所有者的明确授权。
标签：AI风险缓解, CISA项目, Docker沙箱, LLM编排, Web安全, 人工智能, 密码管理, 用户模式Hook绕过, 自动化渗透测试, 蓝队分析, 请求拦截, 运行时操纵, 逆向工具