内容
# Awesome MCP
Awesome MCP 是一款 Burp Suite 扩展程序，直接在 Burp 中运行 MCP 服务器，并为渗透测试工作流程提供基于代理的工具。
该项目旨在优化 `operator + agent` 使用：
- 来自 Burp UI 的稳定对象寻址
- 具有下划线命名规范的严格模式
- 分页安全的历史查询
- 上下文安全的请求/响应序列化
- 实用主动工具（HTTP 发送、Repeater、Intruder、范围、cookie jar）
## 为什么存在
典型的 Burp MCP 桥梁使得代理执行昂贵的循环并返回嘈杂的负载。Awesome MCP 通过以下方式解决了这个问题：
- 稳定 ID 和直接获取 API（`list_*` + `get_*_by_ids` / `get_*_by_keys`）
- 可预测的信封（`total`、`next`、`results`)
- 明确的正文控制（二进制包含、大小限制、超大文本模式）
- 确定光标分页整个 Burp 列表
## 核心架构
主要模块：
- `ExtensionBase` — 扩展生命周期、选项卡注册、设置连接
- `AgentMcpServerManager` — 进程内 Ktor + MCP 传输服务器
- `McpSettingsStore` — 设置持久性（全局/项目，用户可选）
- `ToolRegistrar` — MCP 工具目录 + 处理程序
- `HistoryQueryService` — 代理/站点地图/WebSocket 查询 + 获取 ID 服务
- `Serialization` — 安全有效载荷塑形，用于 HTTP/WebSocket 内容
- `McpOutputLogger` — 紧凑的 MCP 活动日志记录到 Burp 输出 + 事件日志
## 传输
支持的传输：
- `sse`
- `streamable_http`
默认运行时值：
- 主机：`127.0.0.1`
- 端口：`26001`
- 传输：`streamable_http`
- 已启用：`true`
端点规则：
- SSE：`http://<host>:<port>`
- Streamable HTTP：`http://<host>:<port>/mcp`
如果主机是通配符 (`0.0.0.0`/`::`)，则复制端点使用环回地址以方便客户端。
## 设置 UX 模型
在 Awesome MCP 选项卡中：
- `Enabled` 切换按钮立即启动/停止服务器（独立于应用）
- `Apply` 应用端点设置（`host`、`port`、`transport`、`storage scope` 复选框）
- 端点 URL 仅反映已应用的设置
- 仅当设置与应用的快照不同时，应用按钮才启用
持久性范围：
- 复选框：`在当前项目中存储设置`
- 未勾选：在 Burp 全局首选项中保存
- 勾选：在当前项目扩展数据中保存
- 范围复选框本身在项目数据中持久保存
## 工具目录
### 历史记录和检索
- `list_proxy_http_history`
- `get_proxy_http_history_by_ids`
- `list_proxy_websocket_history`
- `get_proxy_websocket_messages_by_ids`
- `list_site_map`
- `get_site_map_by_keys`
- `summarize_http_history_cookies`
- `summarize_http_history_auth_headers`
### 主动 HTTP
- `send_http1_requests` （批量）
- `send_http2_requests` （批量）
HTTP 传输说明：
- `send_http1_requests` 将原始请求内容转发为提供的内容（无换行符/正文规范化）。
- `send_http2_requests` 强制执行 HTTP/2 模式：
`request_options.http_mode` 必须是 `http_2` 或 `http_2_ignore_alpn` （或省略）。
- 对于重复的 HTTP/2 头部名称，请使用 `items[].headers_list` (`[{name,value}, ...]`).
### Burp 工作流集成
- `create_repeater_tabs` （批量）
- `send_requests_to_intruder` （批量）
- `send_requests_to_intruder_template` （批量）
- `send_requests_to_organizer` （批量）
- `list_organizer_items`
- `get_organizer_items_by_ids`
### 范围控制
- `scope_add_include`
- `scope_add_exclude`
- `scope_remove_include`
- `scope_remove_exclude`
- `scope_is_url_in_scope`
`scope_add_include` / `scope_add_exclude` 支持：
- `include_subdomains` （可选，默认为 false）
- 当为 true 时，Awesome MCP 更新项目范围主机规则 (`target.scope.include/exclude`) 为 `include_subdomains=true`
- `url` 接受绝对 URL、短主机形式 (`host`、`host:port`) 或轻量级前缀 (`a/`、`1`)
- 验证故意宽容；仅拒绝没有字母/数字的明显垃圾
- 输入值按提供的内容保留；仅在需要时使用规范化为绝对 URL 的内部回退
`scope_remove_include` / `scope_remove_exclude` 支持：
- 从 `target.scope.include/exclude` 中删除匹配规则
- 可选 `include_subdomains` 选择器仅删除同一前缀的其中一个变体
### 实用工具
- `url_encode` （批量）
- `url_decode` （批量）
- `base64_encode` （批量）
- `base64_decode` （批量）
- `generate_random_string`
- `list_cookie_jar`
- `set_cookie_jar_cookie`
- `expire_cookie_jar_cookie`
Cookie 删除说明：
- `expire_cookie_jar_cookie` 过期匹配 Cookie （Montoya Cookie Jar 没有硬删除 API）。
- `list_cookie_jar.order` 仅接受 `asc` 或 `desc`。
### Burp 控制和配置
- `set_proxy_intercept_enabled`
- `get_proxy_intercept_enabled`
- `set_task_engine_state`
- `get_task_engine_state`
- `get_project_options_json`
- `get_user_options_json`
- `list_proxy_request_listeners`
- `get_project_scope_rules`
- `set_project_options_json`
- `set_user_options_json`
- `get_active_text_editor_contents`
- `set_active_text_editor_contents`
### 仅限 Burp Pro
- `start_scanner_crawl`
- `start_scanner_audit`
- `get_scanner_task_status`
- `list_scanner_tasks`
- `cancel_scanner_task`
- `generate_scanner_report`
- `list_scanner_issues`
- `generate_collaborator_payload`
- `list_collaborator_interactions`
`list_scanner_issues` 关键输入：
- 分页：`limit`、`offset`
- 过滤器：`severity[]`、`confidence[]`、`name_regex`、`url_regex`
- 可选的丰富上限：`max_request_responses`
- 可选项目投影：`fields`、`exclude_fields`
- 可选的附加请求/响应快照正文塑形：`serialization`
`list_scanner_issues` 输出规范化：
- `severity`、`confidence`、`typical_severity` 以小写线格式返回
(`high`、`medium`、`low`、`information`、`false_positive`; `certain`、`firm`、`tentative`)
`list_scanner_tasks` 限制：
- 仅返回当前 MCP 运行时由 Awesome MCP 跟踪的任务
- 仅包括通过此 MCP 实例启动的任务（`start_scanner_crawl` / `start_scanner_audit`)
- 不会枚举 MCP 跟踪之外可能存在于 Burp 中的所有扫描器任务
协作合同：
- `generate_collaborator_payload` 返回 `payload`、`payload_id`、`server`、`secret_key`
- `custom_data` 必须匹配 `^[A-Za-z0-9]{1,16}$` （Burp Collaborator 运行时限制）
- `list_collaborator_interactions` 接受：
`payload_id` （当前会话中跟踪的有效负载），或
`payload` （+ 可选 `secret_key`）用于重启安全轮询
- 协作客户端秘密 + 跟踪的有效负载映射在扩展程序首选项中持久保存，
因此轮询可以在扩展程序重新加载/重启后继续
## 合同约定
- 输入/输出键：`snake_case`
- 工具名称：`snake_case`
- 拒绝未知字段 (`ignoreUnknownKeys=false`)
- 枚举值严格；解码错误使用允许的值规范化
枚举错误示例：
`invalid value 'qwerty' for 'text_overflow_mode'; allowed: [truncate, omit]`
## 查询模型
光标列表响应形状 (`list_proxy_http_history`、`list_proxy_websocket_history`、`list_site_map`、`list_organizer_items`)：
- `total`
- `next` （完整下一个请求对象，或 `null`）
- `results`
偏移列表响应形状 (`list_scanner_issues`、`list_cookie_jar`)：
- `total`
- `returned`
- `offset`
- `limit`
- `has_more`
- `results`
`get_*` 响应形状：
- `requested`
- `found`
- `results` 具有每个 ID/键的成功或错误
HTTP 历史记录 / 站点地图 / 组织者投影：
- 可选的顶级 `fields` （字符串数组）
- 可选的顶级 `exclude_fields` （字符串数组）
- 仅允许其中一个为非空
- 两个均为 `null` = 优化的默认项目有效载荷
- 投影仅适用于结果项，不适用于信封字段，如 `total`、`next`、`requested`、`found` 或 `results`
- 使用 `fields` 时，标头和请求/响应正文仅为选定分支物化
- 使用 `exclude_fields` 或两个投影字段均为 null 时，物化优化的默认非原始形状
- `request.raw` 和 `response.raw` 仅在显式请求 `fields` 时物化
- 过滤和正则表达式匹配发生在源 Burp 数据在输出之前，因此记录可以匹配，即使匹配分支从输出中省略
- `match_context` 是当启用 `serialization.regex_excerpt` 时的可选结果分支，可以通过 `fields` / `exclude_fields` 投影
- 默认 HTTP 输出省略：
- `listener_port`
- `edited`
- 根 `in_scope`
- `request.path`、`request.query`、`request.in_scope`
- 空 `response.cookies`
- 当它们等于 `response.mime_type` 时，`response.stated_mime_type` 和 `response.inferred_mime_type`
直接发送结果投影：
- `send_http1_requests` / `send_http2_requests` 也支持 `fields` / `exclude_fields`
- 路径相对于每个成功的 `results[].result` 对象
- 公共根：
- `status_code`
- `has_response`
- `request.*`
- `response.*`
扫描器问题投影：
- `list_scanner_issues` 也支持 `fields` / `exclude_fields`
- 公共根：
- `name`、`severity`、`confidence`、`base_url`
- `detail`、`remediation`
- `issue_background`、`remediation_background`、`typical_severity`、`type_index`
- `request_responses.*`
- `request_responses` 故意为复数：扫描器问题可能带有多个附加的请求/响应对
站点地图密钥合同：
- `list_site_map` 返回 `results[].key` （24 个字符的十六进制稳定密钥）
- `get_site_map_by_keys.keys` 必须包含这些密钥值
- 合成字符串（如 `METHOD URL::...`）不支持
默认值：
- 历史记录/站点地图/WebSocket/组织者查询默认为 `filter.in_scope_only=true`
- `start_id` 默认值为 `0` （历史记录/WebSocket/组织者）
- `id_direction` 默认值为 `increasing` （历史记录/WebSocket/组织者）
- `increasing`: 朝向更大的 ID 移动
- `decreasing`: 朝向更小的 ID 移动
- `start_id` 语义（历史记录/WebSocket/组织者）：
- `start_id >= 0` 是包含 Burp ID 锚点
- `start_id < 0` 使用类似 python 的索引从尾部 (`-1` 最后一项，`-2` 上一项）
- `id_direction=decreasing` 时，`start_id=0` 从最后一项开始
- `start_after_key` 默认值为 `null` （站点地图）
支持的结构化 `filter`：
- `list_proxy_http_history`
- `list_proxy_websocket_history`
- `list_site_map`
- `list_organizer_items`
HTTP 历史记录 `filter` 字段：
- `in_scope_only` （布尔型，默认为 `true`）
- `regex` （搜索请求/响应内容和注释的正则表达式）
- `methods` （数组，不区分大小写）
- `host_regex`
- `mime_types` （数组）
- `inferred_mime_types` （数组）
- `status_codes` （数组）
- `listener_ports` （数组）
- `has_response` （布尔型）
- `time_from` / `time_to` （ISO-8601 / RFC3339 时间戳）
站点地图 / 组织者 `filter` 字段：
- `in_scope_only` （布尔型，默认为 `true`）
- `regex` （搜索请求/响应内容和注释的正则表达式）
- `methods` （数组，不区分大小写）
- `host_regex`
- `mime_types` （数组）
- `inferred_mime_types` （数组）
- `status_codes` （数组）
- `has_response` （布尔型）
- `time_from` / `time_to` （ISO-8601 / RFC3339 时间戳）
`mime_types` 匹配说明：
- 首先匹配显式 MIME 信号：`response.mime_type`、`response.stated_mime_type` 和 `Content-Type`
- 对于 `Content-Type`，同时接受完整值（例如 `APPLICATION/JSON`）和子类型别名（例如 `JSON`）
- 仅当显式 MIME 信号不可用时，使用 `response.inferred_mime_type` 作为回退
- `inferred_mime_types` 是 `response.inferred_mime_type` 的专用严格过滤器
正则表达式转义说明：
- 在 JSON 输入中，反斜杠必须转义；对于字面点使用 `ads\\.`
WebSocket `filter` 字段：
- `in_scope_only` （布尔型，默认为 `true`）
- `regex`）
- `regex` （搜索消息内容和注释的正则表达式）
- `direction` (`client_to_server` | `server_to_client`)
- `web_socket_ids` （WebSocket ID 数组）
- `host_regex`
- `listener_ports`
- `has_edited_payload` （布尔型）
- `time_from` / `time_to` （ISO-8601 / RFC3339 时间戳）
分页行为：
- 查询始终按照 `id_direction` 顺序遍历完整的 Burp 列表
- `total` 是应用 `filter` 之前的完整列表大小
- HTTP/WebSocket/组织者使用包含 `start_id` 锚点 + `id_direction`
- 站点地图使用 `start_after_key` 游标（基于关键字的独占）
- `next` 始终存在：完整的后续查询有效载荷或显式 `null`
## 序列化模型
### HTTP 序列化控制
对于 HTTP 历史记录/站点地图/组织者/直接发送结果/扫描器请求-响应快照，`serialization` 控制：
- `serialization.include_binary`
- `serialization.max_text_body_chars` （回退限制）
- `serialization.max_request_body_chars` （可选覆盖）
- `serialization.max_response_body_chars` （可选覆盖）
- `serialization.text_overflow_mode` = `omit` | `truncate`
- `serialization.max_binary_body_bytes`
- `serialization.regex_excerpt`
- `context_chars` （默认为 `10`）
- `regex`
- `serialization.regex_excerpt` 必须是对象，而不是裸正则表达式字符串
重要：
- 这些字段 **不** 过滤匹配项
- 它们控制二进制处理和正文大小/溢出处理
- 标头，请求/响应正文和原始分支根据 `fields` / `exclude_fields` 自动物化
- 如果省略 `serialization`，则使用默认值
- 如果 `serialization` 为 `{}`，则也使用默认值
- 对于 HTTP 历史记录/站点地图/组织者/直接发送/扫描器问题，首选 `fields` / `exclude_fields` 以进行令牌减少，而不是正文格式化
- `serialization.regex_excerpt` 可用于 `list_proxy_http_history`、`get_proxy_http_history_by_ids`、`list_site_map`、`get_site_map_by_keys`、`list_organizer_items`、`send_http1_requests` 和 `send_http2_requests`
- 当启用 `serialization.regex_excerpt` 时：
- `match_context` 每个项目/结果可用
- `request.body`、`response.body`、`request.raw` 和 `response.raw` 不得在 `fields` 中请求
- 如果 `fields` 为 `null`，则自动修剪正文/原始分支以适应优化的默认形状
- `serialization.regex_excerpt.regex` 用于摘录
默认溢出策略：
- `text_overflow_mode = omit`
- `max_text_body_chars = 1024`
- `max_binary_body_bytes = 65536` （64 KB）
扫描器默认值：
- `list_scanner_issues` 默认保持轻量
- `detail`、`remediation`、定义字段和 `request_responses` 仅在通过 `fields` 请求时出现
- 使用 `max_request_responses` 在 `fields` 包括 `request_responses` 时限制附加的请求/响应对
### WebSocket 序列化控制
- `serialization.include_binary`
- `serialization.include_edited_payload`
- `serialization.max_text_payload_chars`
- `serialization.max_binary_payload_bytes`
重要：
- 这些字段 **不** 过滤选定的 WebSocket 消息
- 它们仅控制输出中的有效载荷序列化
### 二进制行为
- 默认情况下（`include_binary=false`），二进制正文被省略并带有原因
- 要强制返回二进制，请设置 `include_binary=true`
示例（历史记录查询）：
```json
{
"limit": 20,
"filter": {
"in_scope_only": true
},
"serialization": {
"include_binary": true,
"max_response_body_chars": 3000,
"text_overflow_mode": "omit"
}
}
```
## 日志记录
Awesome MCP 将紧凑的活动日志记录到：
- Burp 输出 (`logToOutput`)
- Burp 事件日志 (`raiseDebugEvent` 用于正常流程，`raiseErrorEvent` 用于故障）
日志有效载荷包括：
- `type`
- `name`
- `status`
- `ms`
- `req` （清理：重型 blob 字段掩码/采样）
- 可选 `note`、`resp_bytes`
## 构建
```bash
./gradlew buildPlugin
```
主要任务：
```bash
# 构建 + 单元测试
./gradlew buildWithTests
# 构建 + 集成测试
./gradlew buildWithIntegrationTests
# 语法检查 + 格式化
./gradlew lintAndFormat
```
产物：
- `build/libs/burp-awesome-mcp.jar`
调试构建开关：
- 默认构建类似于发布版本，抑制 Burp 事件日志中的 MCP 调试事件
- Burp 输出日志记录在所有构建中保持启用
- 在 `awesome.debug=true` 构建开关的情况下传递 `-Pawesome.debug=true` 以启用 Burp 事件日志中的 MCP 调试事件
```bash
./gradlew buildPlugin -Pawesome.debug=true
```
## CI
GitHub Actions 工作流：
- `.github/workflows/ci.yml`
CI 在推送/PR/工作流调度上运行并执行：
```bash
./gradlew clean test integrationTest ktlintCheck shadowJar
```
## 发布
GitHub 发布工作流：
- `.github/workflows/release.yml`
发布触发器：
- 推送标签匹配 `v*`（例如 `v1.2.3`)
发布工作流验证：
- 标签格式为 `v<major>.<minor>.<patch>`
- `gradle.properties` 版本与标签版本匹配
- 完整的验证构建通过（`test`、`integrationTest`、`ktlintCheck`、`shadowJar`）
发布资产包括：
- 版本化 jar：`burp-awesome-mcp-<version>.jar`
- `SKILL.md`
- `AGENTS.md`
- `burp-awesome-mcp-<version>.jar.sig`
- `SKILL.md.sig`
- `AGENTS.md.sig`
必需的签名私钥：
- `RELEASE_SIGNING_PRIVATE_KEY`（PEM 私钥用于 `openssl pkeyutl -sign`)
版本增量和标签助手：
```bash
# 补丁增量，运行检查，提交+标签，推送
./scripts/release.sh --part patch --push
# 显式版本
./scripts/release.sh --version 1.2.3 --push --create-gh-release
```
## 加载到 Burp
1. `扩展` -> `添加`
2. `扩展类型` = `Java`
3. 选择 `build/libs/burp-awesome-mcp.jar`
4. 打开 `Awesome MCP` 选项卡
5. 切换 `启用`
6. 根据需要调整设置并点击 `应用`
## 测试
运行常规测试：
```bash
./gradlew test --rerun-tasks
```
此命令仅运行常规测试（类名匹配 `*IntegrationTest` 被排除）。
运行非实时集成测试：
```bash
./gradlew integrationTest --rerun-tasks
```
实时 Burp 集成测试（对抗正在运行的 Burp 且 Awesome MCP 已启用）：
```bash
./gradlew liveBurpTest \
--tests "*LiveBurpMcpIntegrationTest" \
-Dawesome.mcp.live.url=http://127.0.0.1:26001/mcp \
-Dawesome.mcp.live.transport=streamable_http
```
可选的自定义前缀用于实时范围断言：
```bash
-Dawesome.mcp.live.scope.include_prefix=my-include-prefix \
-Dawesome.mcp.live.scope.exclude_prefix=my-exclude-prefix
```
如果您想使用 SSE 运行实时测试：
```bash
-Dawesome.mcp.live.url=http://127.0.0.1:26001 \
-Dawesome.mcp.live.transport=sse
```
运行所有集成测试，包括实时测试：
```bash
./gradlew buildWithIntegrationTests \
-Pawesome.live=true \
-Dawesome.mcp.live.url=http://127.0.0.1:26001/mcp \
-Dawesome.mcp.live.transport=streamable_http
```
注意：
- `buildWithIntegrationTests` 现在自动包含 `LiveBurpMcpIntegrationTest`，前提是
`AWESOME_MCP_LIVE_URL` 或 `-Dawesome.mcp.live.url=...` 已提供。
- `-Pawesome.live=true` 仍然受支持，但不再需要在这种情况下使用。
生成的日志：
- `tests_log.txt` — 完整的测试执行 + 每项测试的输出
- `test-artifacts/mcp-integration-trace.log` — MCP 集成请求/响应跟踪日志
如果您需要自定义 Gradle 缓存位置，请在命令行上设置：
```bash
GRADLE_USER_HOME=<custom-cache-dir> ./gradlew <task>
```
## 安全和操作说明
- v1 设计时无审批门控逻辑。
- 扫描器执行编排故意不公开（仅限问题查询）。
- Collaborator 和扫描器工具受 Burp 版本检查保护。
- 请勿将 Awesome MCP 侦听器暴露给不受信任的网络。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器