# Custom AI Agent
**Burp Suite 与现代 AI 之间的桥梁。**
> **关于名称的说明:** 本扩展以 **Custom AI Agent** 发布(原名 *Burp AI Agent*)。更名是为了符合 PortSwigger BApp Store 的命名要求,并避免与 Burp Suite 内置的 **Burp AI** 提供程序混淆。GitHub 仓库(`github.com/six2dez/burp-ai-agent`)、文档站点(`burp-ai-agent.six2dez.com`)以及配置目录(`~/.burp-ai-agent/`)为保持连续性仍保留 `burp-ai-agent` 标识符。
<!-- screenshot: main extension tab with chat and settings visible -->

Custom AI Agent 是一款 Burp Suite 扩展,可将 AI 集成到你的安全工作流中。可使用本地模型或云服务提供商,通过 MCP 连接外部 AI 代理,并让被动/主动扫描器发现漏洞,而你则专注于手动测试。
> [!IMPORTANT]
> **如果你正在运行 1.0.0 或更早版本,请阅读[安全公告](https://github.com/six2dez/burp-ai-agent/blob/main/SECURITY.md#security-advisories)并升级到最新版本 1.1.0。**
> 在开启审计日志记录时写入的审计文件可能包含 MCP 令牌和完整提示词,并且右键
> “发送到 AI”上下文可能绕过隐私模式;两项公告均说明了需要轮换哪些凭据。
> 其中任何一项均未分配 CVE 或 GHSA 标识符。
## v1.1.0 中的新功能
同一仓库构建出两个版本,专为 BApp Store 重新提交而构建。完整详情见
[CHANGELOG.md](https://github.com/six2dez/burp-ai-agent/blob/main/CHANGELOG.md)。
- **两个构建版本。** BApp Store 构建(`./gradlew bappJar`)包含 8 个扩展原生 MCP 工具、
Burp AI 和六个 HTTP 后端。GitHub 完整构建(`./gradlew fullJar`)包含全部 59 个 MCP
工具、五个 CLI 后端、外部 MCP 客户端和可选的自动排队功能。两者均发布在
[Releases](https://github.com/six2dez/burp-ai-agent/releases) 上,各带一个 `.sha256`。一次仅加载
一个;[选择哪个构建?](https://burp-ai-agent.six2dez.com/getting-started/which-build)
对它们进行了比较。
- **BApp Store 构建的 AI 门控。** BApp Store 构建可在 Burp Community 和 Burp Professional 上运行;仅当 Burp 为扩展启用了“Use AI”设置时,它才会发送 AI 请求,若该设置关闭,它会加载并拒绝所有 AI 请求。
- **被动扫描不会向目标发送任何内容。** AI 主动扫描器可测试的被动发现结果
会在其队列对话框中列为建议目标(两个构建均如此),由你手动排队:
在你确认之前,不会向目标发送任何内容。
- **干净卸载。** 卸载后不会留下扩展的任何线程、定时器或 MCP 监听器在运行,也不会
向 AI 提供程序发起新请求。
- **问题详情经过 HTML 编码。** 载荷、取自目标的值以及 AI 文本在 Burp 的问题视图和报告中
以字面文本显示。
- **AI 扫描器在每次加载时均处于关闭状态**,两个构建均如此;开启后持续有效,直到 Burp
卸载该扩展。
## v1.0.1 中的新功能
针对 1.0.0 的正确性与隐私热修复。完整详情见 [CHANGELOG.md](https://github.com/six2dez/burp-ai-agent/blob/main/CHANGELOG.md) 和
[SECURITY.md](https://github.com/six2dez/burp-ai-agent/blob/main/SECURITY.md#fixed-in-101)。
- **非 ASCII 提示词在所有 HTTP 后端上均可正常工作**(#84、#85、#86、#88)。请求体以
UTF-8 字节发送;此前,非 ASCII 字符会被损坏,且目标文本可能改变请求的 JSON
结构。
- **隐私:** 右键上下文、扫描器设置、审计日志记录和聊天链接现在遵循
隐私模式和仅哈希审计默认设置;聊天链接仅在确认后打开。
- **扫描器安全性:** 状态变更请求仅在 DANGEROUS 级别下重放;Burp Scanner AI
检查遵循扫描的资源池和 AI 被动开关。
- **可靠性:** NVIDIA NIM 和 Perplexity 恢复正常工作,后续聊天消息保留其上下文,
且在缓慢或繁忙的机器上脱敏不再丢弃内容。
- **捆绑库:** Netty 4.1.138、Jackson 2.22.3。
## v1.0.0 中的新功能
首个稳定版本,也是安全正确性的里程碑。2026-08-05 对 `0.9.2` 的外部审查通过**实际运行**已发布的代码确认了两个可利用缺陷;本次发布修复了这两个缺陷,以及同一审查暴露出的更广泛的一类问题。完整细节见 [CHANGELOG.md](https://github.com/six2dez/burp-ai-agent/blob/main/CHANGELOG.md)。
**已修复并披露:**
- **SEC-04(严重)** — MCP 访问控制检查未在解析后的路由上运行。启用外部访问时,监听器接受了**未经身份验证**的工具调用;在本地模式下,Origin/Host/User-Agent 检查和安全响应头在匹配的路由上形同虚设。现在决策在路由之前执行。→ [轮换你的 MCP 令牌](https://github.com/six2dez/burp-ai-agent/blob/main/SECURITY.md#security-advisories)
- **PRIV-05(高)** — 会话 Cookie 在 STRICT 和 BALANCED 模式下**未经脱敏**就到达 AI 后端。被动扫描器将 Cookie 输出为裸 `name=value`,丢弃了作为脱敏依据的前缀,且只有字面名为 `session` 的 Cookie 会被捕获。→ [轮换受影响的 Cookie](https://github.com/six2dez/burp-ai-agent/blob/main/SECURITY.md#security-advisories)
**已加固:**
- **模型发出的工具调用现在需要你的批准**(SEC-06)— 从*模型输出*中解析出的工具调用在你做出决定之前不会到达 Burp。各层级均采用失败关闭策略:无法识别的工具名称每次都会要求确认,绝不会静默运行。参见[隐私与安全说明](#privacy-and-security-notes)。
- **端口接管期间不再泄露 MCP 令牌**(SEC-07)— 此前,一个占用 MCP 端口并回显身份头的本地进程可以获取授予完整 MCP 工具访问权限的令牌。接管客户端现在改为出示 HMAC 持有证明,并且在 TLS 下将服务器证书固定到自己的密钥库。
- **`SsrfGuard` 可识别替代 IP 表示法**(SEC-07)— `http://2852039166/`(`169.254.169.254` 的十进制形式)不再仅凭表示法绕过私有/链路本地警告,且分类过程现在完全不进行名称解析。
- **Shell 参数按允许列表进行引用**(QUAL-06)— 封堵了从设置导入到命令执行的路径,该路径涉及携带元字符但不含空白字符的值(`foo;id`、`$(cmd)`)。
- **EDT 隔离与调度器健壮性** — 工具执行、后端 HTTP 和 MCP `stop()` 已移出 Swing 事件调度线程;周期性任务增加了防护,避免因异常而终止。
**已验证:** 测试套件从 660 个增长到 **158 个类中的 1131 个测试**,项目行覆盖率从 34% 提升至 **58%**,detekt 基线从 1096 缩减至 1040,而非增长。
## 亮点
- **12 个 AI 后端** — Burp AI(内置)、Anthropic、Ollama、LM Studio、NVIDIA NIM、Perplexity、通用 OpenAI 兼容、Gemini CLI、Claude CLI、Codex CLI、OpenCode CLI、Copilot CLI。BApp Store 构建包含 7 个(Burp AI 和六个 HTTP 后端);五个 CLI 后端仅在完整构建中提供。
- **59 个 MCP 工具** — 让 Claude Desktop(或任何 MCP 客户端)自主驱动 Burp(商店构建中有 8 个扩展原生 AI 工具,完整构建中全部 59 个)。
- **限定范围的 MCP 访问** — 可选择将每个 MCP 工具限制在范围内的主机上,使外部 AI 客户端无法通过 Burp 访问范围外的目标。
- **62 个漏洞类别** — 覆盖注入、认证、加密等领域的被动和主动 AI 扫描器。被动扫描器作为 Burp `PassiveScanCheck` 运行(Burp Pro)。
- **从 Releases 安装** — 从 [Releases](https://github.com/six2dez/burp-ai-agent/releases) 下载任一构建;[Which Build?](https://burp-ai-agent.six2dez.com/getting-started/which-build) 说明了它们的区别。Custom AI Agent 尚未在 BApp Store 中列出:BApp Store 构建正在通过 PortSwigger 的审核,见 [extension-portal#231](https://github.com/PortSwigger/extension-portal/issues/231)。
- **主题感知 UI** — 内部设计系统为设置面板设置样式,并随 Burp 的浅色/深色切换自动重新应用主题。
- **Burp 扫描技能** — 通过 MCP 将你偏好的 AI 编码助手(Claude Code、Gemini CLI、Codex 等)用作扫描器。
- **工具调用确认** — AI 发出的工具调用受到门控:只读的有界工具静默运行,其他所有工具都会先在聊天中通过审批卡片询问。未知工具默认拒绝。
- **3 种隐私模式** — STRICT / BALANCED / OFF。在敏感数据离开 Burp 之前对其进行脱敏。
- **自定义提示词库** — 按上下文(HTTP 请求或扫描器问题)保存自由格式的提示词;从右键菜单启动它们,或通过 `Custom…` 输入临时提示词。
- **审计日志** — 可选的 JSONL 日志,每条记录带有 SHA-256;除非开启详细审计,否则提示词、上下文和响应以 SHA-256 加长度记录,且凭据永远不会被写入;每次启动都标记 `promptSource` / `contextKind` 以便复现。
## 快速开始
### 1. 安装
从 [Releases](https://github.com/six2dez/burp-ai-agent/releases) 下载最新的 JAR:每个版本都包含 `Custom-AI-Agent-full-<version>.jar`(GitHub 完整构建)和 `Custom-AI-Agent-bapp-<version>.jar`(BApp Store 构建),各自附带一个 `.sha256`。[Which Build?](https://burp-ai-agent.six2dez.com/getting-started/which-build) 说明了该选哪一个。或者从源码构建(Java 21):
```bash
git clone https://github.com/six2dez/burp-ai-agent.git
cd burp-ai-agent
# Full build (GitHub releases) — all 59 MCP tools
JAVA_HOME=/path/to/jdk-21 ./gradlew clean fullJar
# Output: build/libs/Custom-AI-Agent-full-<version>.jar
# Store build (BApp Store submission) — 8 extension-native AI MCP tools only
JAVA_HOME=/path/to/jdk-21 ./gradlew clean bappJar
# Output: build/libs/custom-ai-agent-bapp.jar
```
### 2. 加载到 Burp
1. 打开 Burp Suite(社区版或专业版)。
2. 转到 **Extensions > Installed > Add**。
3. 选择 **Java** 作为扩展类型,并选择 `.jar` 文件。
该扩展在 Burp 中注册为 **Custom AI Agent**(即 Extensions 列表和 Suite 标签页中显示的名称),以区别于 Burp 内置的 **Burp AI** 提供程序。
**只加载一个构建版本。** 完整构建和 BApp Store 构建都会注册为 **Custom AI Agent**,因此它们在 Burp 的 Extensions 列表中看起来完全相同。同时加载两者会导致出现两个 Custom AI Agent 标签页、两个 MCP 服务器争用同一端口,以及两份副本写入共享的 `~/.burp-ai-agent` 目录。在加载另一个之前,请先卸载其中一个。
**Burp 版本与“Use AI”。** BApp Store 构建可在 Burp 社区版和 Burp 专业版上运行;它仅在 Burp 为该扩展启用“Use AI”设置时发送 AI 请求,关闭该设置时它会加载但拒绝所有 AI 请求。PortSwigger 将“Use AI”记录为每个扩展的复选框,默认关闭:**Extensions > Installed > Custom AI Agent > Use AI**。
<!-- screenshot: Burp Extensions > Add dialog with the JAR loaded -->

### 3. 代理配置文件
该扩展在首次运行时会将捆绑的配置文件自动安装到 `~/.burp-ai-agent/AGENTS/`。
将额外的 `*.md` 文件放入该目录即可添加自定义配置文件。
### 4. 配置后端
打开 **AI Agent** 标签页并转到 **Settings**。选择一个后端:
| 后端 | 类型 | 设置 |
| :--- | :--- | :--- |
| **Burp AI(内置)** | 进程内 | 使用 Burp 内置的 AI,需要为该扩展启用 Burp 的“Use AI”设置(参见[要求](#requirements));无需额外配置。 |
| **Ollama** | 本地 HTTP | 安装 [Ollama](https://ollama.com),运行 `ollama serve`,拉取模型(`ollama pull llama3.1`)。 |
| **LM Studio** | 本地 HTTP | 安装 [LM Studio](https://lmstudio.ai),加载模型,启动服务器。 |
| **NVIDIA NIM** | HTTP | 使用默认的 `https://integrate.api.nvidia.com` 端点,设置你的 NVIDIA API 密钥,并选择一个模型,例如 `moonshotai/kimi-k2.5`。 |
| **Perplexity** | HTTP | 使用默认的 `https://api.perplexity.ai` 端点,设置你的 `pplx-...` API 密钥,并选择一个模型,例如 `sonar`、`sonar-pro` 或 `sonar-reasoning`。 |
| **通用 OpenAI 兼容** | HTTP | 为任何 OpenAI 兼容的提供程序提供基础 URL 和模型。 |
| **Gemini CLI** | 云 CLI(仅完整构建) | 安装 `gemini`,运行 `gemini auth login`。 |
| **Claude CLI** | 云 CLI(仅完整构建) | 安装 `claude`,设置 `ANTHROPIC_API_KEY` 或运行 `claude login`。 |
| **Codex CLI** | 云 CLI(仅完整构建) | 安装 `codex`,设置 `OPENAI_API_KEY`。 |
| **OpenCode CLI** | 云 CLI(仅完整构建) | 安装 `opencode`,配置提供程序凭据。 |
| **Copilot CLI** | 云 CLI(仅完整构建) | 安装 `copilot` 并使用你的 GitHub 账户登录。 |
| **Anthropic** | 云 API | 在 Settings 中输入你的 Anthropic API 密钥。API 流量通过 Burp 的代理路由。参见 [docs/anthropic-backend.md](https://github.com/six2dez/burp-ai-agent/blob/main/docs/anthropic-backend.md)。 |
对于 **NVIDIA NIM**,该后端期望与 NVIDIA 托管端点相同的聊天补全风格流程。一个可用的配置是:
```text
Backend: NVIDIA NIM
Base URL: https://integrate.api.nvidia.com
Model: moonshotai/kimi-k2.5
API Key: <your nvapi token>
```
除非你的网关要求,否则额外的请求头留空。该扩展会向 `/v1/chat/completions` 发送请求,并自动使用已配置的 bearer token。
### 5. 运行你的第一次分析
1. 通过 Burp Proxy 浏览目标。
2. 在 **Proxy > HTTP History** 中右键单击任意请求。
3. 选择 **Extensions > Custom AI Agent > Analyze this request**。
4. 将打开一个聊天会话,其中包含 AI 分析。
<!-- screenshot: right-click context menu showing Custom AI Agent actions -->

### 6. 通过 MCP 连接 Claude Desktop(可选)
在 **Settings > MCP Server** 中启用 MCP 服务器,并将以下内容添加到你的 Claude Desktop 配置中:
**macOS**:`~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**:`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"burp-ai-agent": {
"command": "npx",
"args": [
"-y",
"supergateway",
"--sse",
"http://127.0.0.1:9876/sse"
]
}
}
}
```
> 需要 Node.js 18+。如果启用 **External Access**,MCP 客户端必须在每个请求中发送 `Authorization: Bearer <token>`。
**仅限完整构建。** 你也可以在 **Settings > MCP Server > External MCP Servers** 中注册外部或自定义 MCP 服务器(SSE 或 stdio 传输)。外部服务器认证令牌在静态存储时加密,但存在 [隐私与安全说明](#privacy-and-security-notes) 中描述的注意事项。有关设置详情和安全说明,请参阅 [docs/external-mcp-servers.md](https://github.com/six2dez/burp-ai-agent/blob/main/docs/external-mcp-servers.md)。
## Burp Scan Skill(终端 AI 扫描)
`burp-scan` 技能让你可以从终端将任何 AI 编码助手(Claude Code、Gemini CLI、Codex 等)用作 Burp 扫描器。**你的终端 AI 成为推理引擎**,而 Burp 通过 MCP 提供工具,取代插件内置的 AI。
### 包含内容
- 按扫描操作组织的 MCP 工具参考(完整构建中最多包含全部 59 个工具)
- 被动分析协议(不发送请求的流量分析)
- 主动测试载荷库(200+ 载荷,覆盖 62 个漏洞类别,含检测模式)
- 端到端扫描工作流(范围 -> 被动 -> 主动 -> OOB -> 报告)
- 问题创建协议,含严重性/置信度映射
### 为 Claude Code 安装
将技能复制到你的 Claude Code 技能目录:
```bash
# Global (available in all projects)
cp -r skills/burp-scan ~/.claude/skills/burp-scan
# Or project-specific
cp -r skills/burp-scan .claude/skills/burp-scan
```
然后在 Claude Code 中使用 `/burp-scan`,或者在你提到 Burp 扫描时让它自动触发。
### 为其他 AI 助手安装
该技能是一个独立的 Markdown 文件,位于 [`skills/burp-scan/SKILL.md`](https://github.com/six2dez/burp-ai-agent/blob/main/skills/burp-scan/SKILL.md)。你可以将其与任何支持系统提示或上下文文件的 AI 助手配合使用:
- **Gemini CLI / Codex / OpenCode**:作为上下文文件添加,或粘贴到你的系统提示中
- **自定义 MCP 客户端**:将技能内容作为系统上下文,与你的 MCP 连接一起使用
- **任何 LLM**:该文件是自包含的——将其作为上下文与你的 MCP 工具定义一起提供
### 使用示例
```
You: Connect to Burp MCP at localhost:9876 and scan the proxy history for IDOR vulnerabilities
AI: [Uses proxy_http_history to pull traffic]
[Identifies endpoints with numeric IDs]
[Sends http1_request with ID+1, ID-1 payloads]
[Compares responses for different user data]
[Creates issue_create for confirmed IDOR]
```
> 该技能与插件内置扫描器互为补充:插件运行自动化后台扫描,而该技能支持从终端进行交互式、由分析师引导的扫描。
## 文档
完整文档可在 **[burp-ai-agent.six2dez.com](https://burp-ai-agent.six2dez.com)** 获取。
- [安装](https://burp-ai-agent.six2dez.com/getting-started/installation)
- [选择哪个构建版本?](https://burp-ai-agent.six2dez.com/getting-started/which-build)
- [快速开始](https://burp-ai-agent.six2dez.com/getting-started/quick-start)
- [界面导览](https://burp-ai-agent.six2dez.com/user-guide/ui-tour)
- [Agent 配置档案](https://burp-ai-agent.six2dez.com/user-guide/agent-profiles)
- [被动扫描器](https://burp-ai-agent.six2dez.com/scanners/passive)
- [主动扫描器](https://burp-ai-agent.six2dez.com/scanners/active)
- [MCP 概览](https://burp-ai-agent.six2dez.com/mcp/overview)
- [隐私模式](https://burp-ai-agent.six2dez.com/privacy/privacy-modes)
- [设置参考](https://burp-ai-agent.six2dez.com/reference/settings-reference)
- [安全公告](https://burp-ai-agent.six2dez.com/security/advisories)
- [故障排查](https://burp-ai-agent.six2dez.com/reference/troubleshooting)
- [Burp 扫描技能](https://burp-ai-agent.six2dez.com/examples/burp-scan-skill)
## 操作员手册
- [MCP 加固](https://github.com/six2dez/burp-ai-agent/blob/main/docs/mcp-hardening.md)
- [UI 安全指南](https://github.com/six2dez/burp-ai-agent/blob/main/docs/ui-safety-guide.md)
- [后端故障排查](https://github.com/six2dez/burp-ai-agent/blob/main/docs/backend-troubleshooting.md)
- [Anthropic 后端设置](https://github.com/six2dez/burp-ai-agent/blob/main/docs/anthropic-backend.md)
- [外部 MCP 服务器](https://github.com/six2dez/burp-ai-agent/blob/main/docs/external-mcp-servers.md)
### 隐私与安全说明
- **静态存储的机密——加密能做什么、不能做什么。** 所有存储的 API 密钥和令牌(Anthropic、MCP bearer token、TLS keystore 密码等)均使用 AES-256-GCM 加密,密钥为每次安装随机生成的主密钥(`SecretCipher`)。**该主密钥本身以 Base64 编码形式存储在 Burp Preferences 中,与其所保护的密文放在一起**(首选项 `secret.master.key.v1`)。因此,任何能读取你的 Burp Preferences 的人也能读取该密钥并解密这些机密。它**不能**防御本地攻击者或以你的用户身份运行的恶意进程;应将其视为针对随意查看首选项文件或导出项目的混淆手段。如果某项凭据必须在该威胁模型下存活,请将其保存在专用的机密存储中,并在每次会话时粘贴。
- **模型发出的工具调用需要你的批准。** 扩展从*模型输出*中解析出的工具调用,在你做出决定之前不会对 Burp 执行。每个工具都带有一个必需的安全层级:自动运行(只读且输出有界)、通过 **Approve for session** 选项确认,或每次调用都确认。目录无法识别的工具名称会解析为每次确认,绝不会自动执行;外部 `ext:` 命名空间的工具始终每次调用都确认。该决定以卡片形式内联显示在聊天记录中,而不是模态对话框,并且每个决定都会被记录——一个审计事件加上 Burp 的 Output 选项卡中的一行,因为审计日志默认关闭。拒绝会向模型返回中性的“未授权,请勿重试”结果,而不是错误。该层级独立于 **Unsafe Mode** 开关:Unsafe Mode 决定工具是否*可以*运行,层级决定模型是否可以*不经询问*运行它。设计理由:[`DECISIONS.md`](https://github.com/six2dez/burp-ai-agent/blob/main/DECISIONS.md) ADR-15。操作员运行手册:[docs/ui-safety-guide.md](https://github.com/six2dez/burp-ai-agent/blob/main/docs/ui-safety-guide.md)。
- STRICT 隐私模式使用真实的 HKDF(HMAC-SHA256 extract/expand)对主机进行匿名化。BALANCED 模式会遮蔽 cookies、tokens 和 auth headers。OFF 模式按原样发送流量。
- 外部 MCP 服务器的输出在进入 AI 提示之前会被包裹在信任边界标记中,防止来自不受信任服务器响应的提示注入(仅完整构建版本)。
设置内部带有 schema 版本(`settings.schema.version`),并在加载时以增量方式迁移,以实现安全升级。
## 要求
- **Burp Suite** 社区版或专业版,2026.2 或更新版本
- **BApp Store 构建版本中的 AI 功能** — BApp Store 构建版本可在 Burp 社区版和 Burp 专业版上运行;它仅在 Burp 针对该扩展启用“Use AI”设置时发送 AI 请求,关闭该设置后它会加载并拒绝所有 AI 请求。GitHub 完整构建版本的 HTTP 和 CLI 后端不依赖 Burp 的“Use AI”(Burp AI 以及 MCP 工具 `ai_analyze` 和 `ai_passive_scan` 仍然依赖);参见[选择哪个构建版本?](https://burp-ai-agent.six2dez.com/getting-started/which-build)。
- **Java 21**(现代 Burp 运行时已内置;从源码构建时需单独安装)
- 至少配置一个 AI 后端(参见上表)
## 许可证
本项目采用 [MIT 许可证](https://github.com/six2dez/burp-ai-agent/blob/main/LICENSE) 授权。
## 免责声明
未经事先同意使用 Custom AI Agent 攻击目标是违法的。用户有责任遵守所有适用法律。开发者对因误用或本工具造成的损害不承担任何责任。请负责任地使用。
## 贡献
欢迎提交 issue 和 pull request。开发环境搭建与指南请参见 [CONTRIBUTING.md](https://github.com/six2dez/burp-ai-agent/blob/main/CONTRIBUTING.md),架构详情请参见[开发者文档](https://burp-ai-agent.six2dez.com/developer/architecture)。