Xavrir/burp-autopilot
GitHub: Xavrir/burp-autopilot
一个通过 CLI 和 AI agent 按需驱动 Burp Suite 的自动化安全测试工具，支持脚本化 fuzzing、扫描启动和代理历史检索等功能。
Stars: 1 | Forks: 0
# Burp Autopilot Skill
**通过命令行驱动 Burp Suite。** 它发送实时请求、搜索代理历史记录、
运行 Collaborator (OOB) 检查、启动扫描并对 fuzzing 进行脚本化，每一项都是一个普通的 CLI
子命令，您可以将其串联成一个 Web 安全工作流。
它是运行常驻型 Burp MCP server 的一种按需替代方案。您无需注册
持久的 MCP client，只需调用一个小型的 Python client，仅在需要时与 Burp 进行通信。
这使得它可以轻松融入脚本、CI 任务或编码 agent 的工具循环中。
该仓库包含两部分：
- `skills/controlling-burpsuite-autonomously/` 包含 agent skill：其传输 client
`burp_client.py`、一个通过 Burp 驱动浏览器的封装器，以及参考文档。您可以将其加载到
[Claude Code](https://docs.claude.com/en/docs/claude-code) 或兼容 opencode 的
运行器中，或者直接将 client 作为 CLI 调用。
- `extension/` 是一个可选的配套 Burp 扩展（`burp-autopilot-ext`，构建于
[Montoya API](https://portswigger.github.io/burp-extensions-montoya-api/) 之上）。它添加了原生 MCP 扩展无法做到的
两件事：启动扫描，以及一个可脚本化的 fuzzing 引擎。
## 功能说明
| 能力 | 支持来源 |
|---|---|
| 发送实时 HTTP/1.1 & HTTP/2 请求 | 原生 MCP 扩展 (阶段 1) |
| 读取 / 正则搜索代理 & WebSocket 历史记录 | 原生 MCP 扩展 |
| 生成 & 轮询 Burp Collaborator (OOB) payload | 原生 MCP 扩展 |
| 读取 scanner 问题、切换拦截、导出/修改配置 | 原生 MCP 扩展 |
| 编码/解码 (URL, base64) | 原生 MCP 扩展 |
| 启动主动审计 & 爬取，轮询状态 | 配套扩展 (阶段 2) |
| 带有机器可读的逐请求结果的脚本化 fuzzing | 配套扩展 |
| 会话结束后依然存活的原生 REST-API 扫描 | Burp Pro REST API (阶段 3) |
| *通过* Burp 浏览目标 (Playwright) | `burp-browser` + Burp proxy |
## 本 Skill 与原生 Burp MCP server 的对比
此 skill 的阶段 1 与您通常作为独立 MCP server 注册的同一个原生 "MCP Server" 扩展进行通信。
下表说明了当您将此 skill 放在其前面时会有什么变化，而不是对扩展本身的批评；它是这里所有其他内容
构建的基础。
| | 原生 Burp MCP (直接使用) | Burp Autopilot Skill |
|---|---|---|
| 连接模型 | 常驻开启，在您的 agent 配置中注册为持久的 MCP client | 按需：仅在命令运行时生成连接，随后退出 |
| 调用方式 | 原始 JSON-RPC 工具调用；您每次都需要提供完整的 schema | 确定性的 CLI 子命令（`send-request`, `proxy-history-regex` 等），具有合理的默认值 |
| 工具命名 | 固定为 client 在连接时缓存的内容 | 每次运行时从 `list-tools` 实时解析，因此重命名或添加的工具不会破坏它 |
| 输出大小 | 无论扩展返回什么，都没有上限 | 字段截断 + 总输出上限，为 agent 的上下文窗口进行了调整 |
| 启动扫描 | 不支持；该扩展只能读取现有的 scanner 问题 | 通过配套扩展实现 `scan-start` / `scan-status` (Pro) |
| 脚本化 fuzzing | 不支持；没有可编程的攻击引擎 | `fuzz`，提供每个请求的状态/长度/时间结果 (Community + Pro) |
| REST API 扫描 | 未连接；您需要自己编写 Burp REST API 的脚本 | `rest-scan-start` / `rest-scan-status` 子命令 (Pro) |
| 通过 Burp 浏览 | 超出了 MCP server 的范围 | `burp-browser`：一个通过 Burp proxy 路由的 Playwright 会话 |
| 在不支持 MCP 的 client 下工作 | 否，需要一个支持 MCP 的 client | 是，它是一个纯 Python 脚本；可以从 shell、CI 任务或 cron 运行 |
| 设置 | 添加到您的 MCP client 配置中，并保持运行 | `npx skills add Xavrir/burp-autopilot`，然后临时调用 |
**特别说明关于输出大小的这一行：** 原生扩展会返回 Burp 提供给它的任何内容，
没有上限。单个 `proxy-history-regex` 匹配可以包含完整的请求和响应体，
而 Burp 的主体通常每个都有数 KB；如果在没有 client 端限制的情况下拉取哪怕数量适中的条目，单次调用就可能达到六位数的字节数，这相当于针对您的上下文的数万个 token。这个 client 在构造上对其进行了限制：
每个超过 1,000 个字符（大约 250 个 token，按照人们用于英文/JSON 文本的粗略的 4 个字符/token 速率计算）的字符串字段都会被截断，并且完整的 JSON 响应在打印之前会被硬性限制在 50,000 字节（大约 12,500 个 token）以内。因此，对于“它能节省多少”的真正回答是：它将无限制的开销转变为有限的开销，每次调用最多大约值 12,500 个 token，无论 Burp 持有多少流量。可以通过 `--field-cap` / `--total-cap` 为每次调用提高或降低这些上限，或者在您故意想要完整查看某一条记录时使用 `--raw`。
在两者重叠的地方（代理历史、Repeater 暂存、Collaborator、编码器、配置导出/修改），它们的表现是一样的，因为底层使用的是相同的扩展。下面描述的 Community/Pro 门槛对两者同样适用；此 skill 不会解锁原生扩展同样需要 Pro 才能使用的任何内容。
## 架构
分为三层。仅阶段 1 是必需的；其余为可选。
```
your CLI / agent / script
│
▼
burp_client.py ───────────────┬─────────────────────────┐
│ (Phase 1) │ (Phase 2) │ (Phase 3)
│ stdio↔SSE │ loopback HTTP │ REST
▼ ▼ ▼
mcp-proxy.jar burp-autopilot-ext.jar Burp Pro REST API
│ SSE :9876 (Montoya) :9877 :1337
▼ ▲ ▲
Burp "MCP Server" ext ─────────┴──────────────────────────┘
(27 live tools) scan-start / scan-status / fuzz
burp-browser → Playwright Chromium ──(proxy :8080)──▶ Burp (history + passive scan)
```
- 阶段 1 是核心。`burp_client.py` 启动 `mcp-proxy.jar`（一个 stdio↔SSE 桥接器）并通过
JSON-RPC 与 Burp 内置的 MCP Server 扩展通信。工具名称是从扩展中 *实时* 解析的，
而不是硬编码的，因此 client 能够在扩展更新后继续正常工作。
- 阶段 2 添加了配套扩展，用于通过单独的环回 endpoint 进行扫描启动和 fuzzing。
- 阶段 3 将 Burp 的原生 REST API 连接为替代扫描路径。
有关完整设计及其限制，请参阅 [`docs/architecture.md`](docs/architecture.md)。
## 前置条件
- 启用了内置 "MCP Server" 扩展的 Burp Suite（在 Settings 中，然后打开 MCP
server；环回 SSE `127.0.0.1:9876`）。Community 或 Pro 都可以，但请先阅读
[版本矩阵](#burp-edition-community-vs-pro)：Community 涵盖了请求、代理
和编码器功能以及通过 Burp 运行的 Playwright，而 scanning、Collaborator (OOB) 和
REST API 则需要 Pro。
- `mcp-proxy.jar`，用于 MCP endpoint 的 stdio↔SSE 桥接器。您需要自行提供（参见
[获取 mcp-proxy.jar](#obtaining-mcp-proxyjar)) 并使用
`BURP_MCP_PROXY_JAR` 指向它。
- Java 17+。构建配套扩展需要 JDK 21。
- Python 3.8+。该 client 仅使用标准库，因此无需进行任何 `pip install`。
- 可选，仅适用于 `burp-browser`：
[`playwright-cli`](https://github.com/microsoft/playwright) 和
`playwright-cli install-browser chromium`。
## 安装说明
### 使用 `npx skills` (推荐)
使用 [`skills`](https://github.com/vercel-labs/skills) 包管理器进行安装，这也是
[skills.sh](https://www.skills.sh) 目录背后使用的同一
工具。只需一条命令：
```
npx skills add Xavrir/burp-autopilot
```
它会获取此仓库，找到 skill，并将其放在您的 agent 查找的位置（Claude Code、
opencode 等）。相关命令：
```
npx skills use Xavrir/burp-autopilot # try it without installing
npx skills list # show what's installed
```
这仅安装 skill（Python client 和参考资料）。配套扩展需要
Java 构建并手动加载到 Burp 中，下文会有说明。
### 或者将提示词粘贴到您的 agent 中
如果您想让 CLI agent 来进行设置，请将以下内容粘贴进去：
```
Install the Burp Autopilot skill for me by running:
npx skills add Xavrir/burp-autopilot
Then confirm the controlling-burpsuite-autonomously skill shows up (npx skills list). Do not
send any live Burp traffic until I give you an authorized, in-scope target.
```
### 手动安装
```
git clone https://github.com/Xavrir/burp-autopilot.git
cd burp-autopilot
./install.sh # symlinks the skill into ~/.claude/skills/
```
或者跳过安装，直接从克隆的仓库中运行 client：
```
python3 skills/controlling-burpsuite-autonomously/scripts/burp_client.py ping
```
### 配套扩展 (可选，用于扫描 + fuzzing)
```
cd extension
./fetch-deps.sh # one-time: pulls Montoya API + org.json from Maven Central into lib/
./build.sh # -> extension/build/burp-autopilot-ext.jar
```
然后在 Burp 中，转到 **Extensions ▸ Installed ▸ Add ▸ Java** 并选择
`extension/build/burp-autopilot-ext.jar`。请参阅 [`extension/README.md`](extension/README.md)。
## 快速入门
```
cd skills/controlling-burpsuite-autonomously # or your installed skill dir
C="python3 scripts/burp_client.py"
# 1. Preflight：Burp 是否已启动并加载 MCP Server extension？
$C ping
# 2. 发现实时 tool surface（source of truth；切勿硬编码 tool 名称）
$C list-tools
# 3. 通过 Burp 发送实时请求（仅限授权目标）
$C send-request --args '{"content":"GET / HTTP/1.1\r\nHost: example.com\r\n\r\n","targetHostname":"example.com","targetPort":443,"usesHttps":true}'
# 4. Regex 搜索 Burp 已捕获的内容
$C proxy-history-regex --args '{"regex":"api/v1","count":50}'
```
加载配套扩展后：
```
$C autopilot-health
$C scan-start --args '{"type":"audit","urls":["https://in-scope.example/path"],"requireInScope":true}'
$C scan-status --task-id all
```
## 配置 (环境变量)
| 变量 | 默认值 | 用途 |
|---|---|---|
| `BURP_MCP_PROXY_JAR` | `~/mcp-proxy.jar` | stdio↔SSE 桥接器 jar 包的路径 |
| `BURP_MCP_SSE_URL` | `http://127.0.0.1:9876` | Burp MCP Server SSE endpoint |
| `BURP_MCP_JAVA` | `/usr/bin/java` | 用于运行桥接器的 Java 二进制文件 |
| `BURP_AUTOPILOT_URL` / `_PORT` | `http://127.0.0.1:9877` | 配套扩展 endpoint |
| `BURP_AUTOPILOT_TOKEN` | *(未设置)* | 可选的 `X-Autopilot-Token` 共享密钥 |
| `BURP_REST_URL` / `BURP_REST_KEY` | `http://127.0.0.1:1337` | Burp Pro REST API (阶段 3) |
| `BURP_PROXY` | `http://127.0.0.1:8080` | `burp-browser` 使用的代理监听器 |
## Burp 版本：Community 与 Pro
Burp Autopilot 会在您的 Burp 版本暴露的任何接口上运行。大多数传输和
请求级别的功能都可以在 Community 上运行。扫描层需要 Pro，因为这些引擎
根本没有在 Community 中提供。
| 功能 | Community | Pro |
|---|:---:|:---:|
| `send-request` / `send-request-http2`，Repeater 暂存 | 是 | 是 |
| 代理 / WebSocket 历史记录 + 正则搜索 | 是 | 是 |
| 拦截切换、编码器、配置导出/修改 | 是 | 是 |
| `burp-browser` (通过代理的 Playwright) | 是 | 是 |
| 脚本化 `fuzz` (配套扩展，通过 HTTP API 发送) | 是¹ | 是 |
| 主动/被动 scanner (`scan-start`, `scan-status`, `scanner-issues`) | 否 | 是 |
| Burp Collaborator / OOB (`collab-generate`, `collab-poll`) | 否 | 是 |
| REST API 扫描 (`rest-scan-start`, `rest-scan-status`) | 否 | 是 |
| 原生 Intruder 攻击引擎 | 受限 | 是 |
¹ 配套的 `fuzz` 引擎通过 Montoya HTTP API 发送请求，因此 Community 的
Intruder 时间限制不适用于它。无论如何，请保持 payload 集较小并设置 `delayMs`。
## 获取 `mcp-proxy.jar`
`mcp-proxy.jar` 是一个通用的 stdio↔SSE MCP 桥接器，它不包含在此仓库中。请构建或
下载您自己的，放在任何地方，并使用 `BURP_MCP_PROXY_JAR` 指向它。如果您没有配置
桥接器 jar，`burp_client.py` 将回退为直接使用 Python 标准库与 Burp SSE endpoint 进行通信。
## 限制
您可以自动化的范围是 Montoya 和 REST API 暴露的内容。对于任何工具来说，都有一些东西是
无法触及的：DOM Invader、嵌入式 Chromium 浏览器、BApp 和扩展管理
以及仅限 GUI 的对话框。GUI Intruder 攻击引擎也没有完全脚本化，这就是为什么
配套扩展在 HTTP API 之上重建了 fuzzing。因此，这里的“自主”指的是整个 Montoya 加上 REST 接口，而不是字面意义上的 GUI 中的每一次点击。
## 贡献
欢迎提交 Issue 和 PR。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)。配套扩展链接了在
[`extension/THIRD_PARTY_NOTICES.md`](extension/THIRD_PARTY_NOTICES.md) 中列出的第三方库。
标签：Burp Suite, CISA项目, JS文件枚举, MCP, Web安全, 安全测试, 密码管理, 攻击性安全, 特征检测, 蓝队分析, 逆向工具