内容
<div align="center">
<h1>BurpSuiteMcp</h1>
<p><strong>English</strong> | <a href="README_CN.md">简体中文</a></p>
<p>
<a href="https://github.com/AJings3c/BurpSuiteMcp/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/AJings3c/BurpSuiteMcp"></a>
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
<a href="pom.xml"><img alt="Java 17+" src="https://img.shields.io/badge/Java-17%2B-orange.svg"></a>
</p>
</div>
一款本地优先的Burp Suite MCP扩展，通过身份验证的流式HTTP向AI客户端暴露HTTP、WebSocket、扫描器和协作/外部攻击测试（OAST）功能，同时在Burp中显示AI实际调用、发送和接收的内容。
## 为什么选择BurpSuiteMcp
许多Burp MCP集成仅关注让AI调用工具，但不为操作员提供清晰的视图来了解AI实际执行了什么。BurpSuiteMcp将可观察性和操作员控制视为首要功能：
- **原生流式HTTP**：基于官方MCP Java SDK 2.0.0，无需遗留的HTTP+SSE或进程内stdio。
- **完整的Burp审计**：记录每次工具/资源调用的输入、实际输出、状态、持续时间、相关工件、主动请求和异步事件。
- **操作员控制的功能**：主动HTTP、主动WebSocket、协作/OAST和主动扫描器默认禁用，只能在本地Burp UI中启用。
- **按需证据访问**：通过有界的工件/资源块公开原始消息，而不是用完整的历史记录淹没AI上下文。
- **安全的默认设置**：仅监听`127.0.0.1`，每个请求都使用Bearer Token进行身份验证，限制对Burp套件范围的访问，并默认删除敏感数据。
## 快速安装
### 选项1：下载发布版本
1. 从 [GitHub Releases](https://github.com/AJings3c/BurpSuiteMcp/releases) 下载 `burp-suite-mcp.jar`。
2. 在Burp Suite中，打开 `扩展` → `已安装` → `添加`。
3. 选择 `Java` 作为扩展类型并加载下载的JAR。
4. 打开Burp的 `MCP` 选项卡并确认服务器状态正在运行。
5. 复制显示的 `MCP地址` 和 `Bearer令牌`。
### 选项2：从源代码构建
需要JDK 17或更高版本。存储库包含Maven包装器，因此不需要系统Maven安装。
Windows PowerShell:
```powershell
.\mvnw.cmd clean verify
```
Linux/macOS:
```bash
chmod +x mvnw
./mvnw clean verify
```
可加载的扩展程序生成在：
```text
target/burp-suite-mcp.jar
```
## 配置MCP客户端
使用以下连接设置：
| 字段 | 值 |
|---|---|
| 传输 | `流式HTTP` |
| URL | `http://127.0.0.1:9876/mcp` |
| 头部 | `Authorization: Bearer <来自Burp的MCP选项卡的令牌>` |
支持远程/HTTP MCP服务器的客户端通常接受等效配置：
```json
{
"mcpServers": {
"burp-suite-mcp": {
"url": "http://127.0.0.1:9876/mcp",
"headers": {
"Authorization": "Bearer 用Burp的MCP选项卡中的令牌替换"
}
}
}
}
```
顶级字段可能被命名为 `servers`、`mcpServers` 或由GUI表单表示，具体取决于客户端。 URL、流式HTTP传输和授权头必须保持不变。 不要选择 `SSE` 或 `stdio`。
连接后，调用：
```text
server_status
```
成功的响应包括 `RUNNING`、端点、版本和当前并发状态。
> 永远不要将真正的Bearer令牌提交到Git或在公共问题、截图或共享配置中公开。 扩展程序随机生成它并将其存储在Burp用户级首选项中。
### 常见连接问题
- `401 Unauthorized`：验证头部是否存在，是否包含 `Bearer` 前缀，并且不包含旧令牌。
- `403 Forbidden`：请求包含浏览器Origin或主机地址超出本地允许列表。 不要直接从普通的网页JavaScript连接。
- 连接被拒绝：确保Burp正在运行，扩展程序已加载，服务器没有被手动停止，并且本地端口 `9876` 可用。
- 主动工具缺失：启用Burp的 `MCP` 选项卡中的相应操作员开关，并确认当前Burp版本支持该功能。
- 仅返回删除的数据：切换数据配置文件为 `FULL_FIDELITY`，并确认目标在当前套件范围内。
## 默认权限模型
扩展程序启动时具有以下安全默认值：
| 设置 | 默认值 | 效果 |
|---|---|---|
| 数据配置文件 | `REDACTED` | 返回可用的证据，同时屏蔽常见的密码、令牌、cookie和其他机密 |
| 数据范围 | `SUITE_SCOPE_ONLY` | 仅允许访问当前Burp套件范围内的目标 |
| 主动HTTP | 禁用 | 防止AI发送主动HTTP请求 |
| 主动WebSocket | 禁用 | 防止AI创建或发送WebSocket会话 |
| 协作/OAST | 禁用 | 防止AI创建或轮询协作客户端 |
| 主动扫描器 | 禁用 | 防止AI启动Burp扫描器审计 |
| 跨重启审计持久性 | 禁用 | 仅在当前Burp进程中保留审计数据 |
要读取确切的原始字节，当地操作员可以将数据配置文件切换到 `FULL_FIDELITY`。 在启用主动功能之前，将目标添加到Burp的套件范围并仅启用所需的开关。 AI提供的字段（如 `force` 或 `unsafe`）无法绕过这些本地策略。
## 功能概述
### HTTP和证据
- `proxy_history_list`：搜索和分页浏览代理历史记录。
- `site_map_list` / `site_map_get`：搜索站点地图并获取完整的HTTP证据。
- `operator_selection_list` / `operator_selection_get`：读取通过Burp的上下文菜单明确公开的HTTP消息。
- `http_exchange_get` / `http_exchange_search`：读取或搜索请求、响应、头部、主体和时间信息。
- `artifact_read`：为不支持MCP资源的客户端读取工件或原始字节块。
- `http_send`：发送原始HTTP请求，同时保留完整的活动请求审计跟踪。
- `http_timing_compare`：交织基准/探测样本并比较TTFB或完整的响应时间。
### WebSocket
- `websocket_history_list` / `websocket_message_get`：读取代理WebSocket历史记录。
- `websocket_connect` / `websocket_send`：创建活动会话并发送文本或二进制帧。
- `websocket_receive` / `websocket_session_status` / `websocket_close`：接收、检查和关闭会话。
### 扫描器
- `scanner_issue_list` / `scanner_issue_get`：读取扫描器问题、标记、HTTP证据和链接的OAST交互。
- `scanner_audit_list` / `scanner_audit_start` / `scanner_audit_status` / `scanner_audit_cancel`：管理专业主动审计任务。
### 协作/OAST
- `collaborator_create` / `collaborator_generate_payload`：在不暴露密钥的情况下创建临时客户端句柄和相关有效载荷。
- `collaborator_poll` / `collaborator_wait`：逐步获取DNS、HTTP和SMTP交互。
### MCP资源
结构化证据和原始字节使用一组统一的 `burp://` 资源：
```text
burp://artifact/{artifactId}
burp://artifact/{artifactId}/{side}/raw/{offset}/{length}
burp://artifact/{artifactId}/body/{side}/{offset}/{length}
```
证据存储默认使用30分钟的TTL、最多500个工件和256 MiB的总预算。 工件ID是绑定到当前Bearer主体的非枚举随机值。
## AI活动审计
Burp的 `MCP` 选项卡包含三个工作区：
- **服务器概览**：服务器状态、端点、令牌、数据配置文件、范围和主动功能开关。
- **MCP调用日志**：每个调用从运行到成功/失败，包含完整的输入、实际输出、相关活动和异步事件。
- **AI请求日志**：单独显示主动HTTP请求、响应、状态、时间以及源调用，包含发送到Repeater或添加到站点地图的操作。
敏感值默认仅在显示层被屏蔽；本地操作员可以明确显示完整内容。 可选的跨重启审计源自当前Bearer令牌的AES-256-GCM密钥，并将加密日志存储在：
```text
~/.burpsuitemcp/audit-v1.enc
```
服务器只能审计客户端通过MCP实际发送的工具/资源调用。 它无法看到AI客户端内部保留的对话、推理或计划。
## Burp版本支持
| 功能 | 社区版 | 专业版 |
|---|:---:|:---:|
| 代理/站点地图HTTP证据 | ✅ | ✅ |
| 操作员选择 | ✅ | ✅ |
| 主动HTTP和时间比较 | ✅ | ✅ |
| WebSocket历史记录/主动WebSocket | ✅ | ✅ |
| 扫描器问题/主动扫描器 | — | ✅ |
| 协作/OAST | — | ✅ |
在当前版本中不可用的工具不会注册，而是在每次调用时返回模糊错误。
## 安全边界
- 监听器固定为 `127.0.0.1`；不支持 `0.0.0.0`、远程绑定和内置TLS。
- 每个GET、POST和DELETE请求必须包含相同的Bearer令牌。
- 主机地址限制为本地地址，普通浏览器源地址被拒绝；绝不启用通配符CORS。
- 主动HTTP、WebSocket和扫描器操作在执行时重新检查套件范围，并阻止扩展程序自己的MCP监听器作为目标。
- 完整的输入、输出和原始流量可能包含敏感数据。 谨慎启用 `FULL_FIDELITY` 和持久审计。
不要为未修补的安全漏洞公开问题。 而是使用GitHub私有漏洞报告。
## 当前限制
- 不提供遗留的HTTP+SSE和内置stdio传输。
- Montoya Repeater API无法读取当前选项卡。 在Repeater、代理、站点地图或HTTP消息编辑器中，使用 `将选定的HTTP消息暴露给MCP` 的上下文菜单操作。
- 扫描器状态事件在任务创建、查询、取消、过期或逐出时记录。 扩展程序不会仅为了审计而连续轮询Burp扫描器。
- 每次调用的批准、审计文件导入/导出和完整的MCP进度/取消集成尚未实现。
## 技术和开发验证
- Java 17+
- Burp Montoya API `2025.10` 具有 `provided` 范围
- MCP Java SDK `2.0.0`
- 嵌入式Tomcat `11.0.24`
- Maven包装器 `3.9.11`
- JUnit + ArchUnit
在提交代码之前运行完整的验证套件：
```powershell
.\mvnw.cmd clean verify
```
测试套件涵盖MCP初始化、工具/资源、Bearer/主机/源安全检查、证据存储、主动HTTP/WebSocket、扫描器、OAST、完整调用审计和架构依赖边界。
## 许可证
BurpSuiteMcp在 [MIT License](LICENSE) 下可用。
