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 标识。

Custom AI Agent 是 Burp Suite 的一个扩展，将 AI 集成到你的安全工作流程中。你可以使用本地模型或云提供商，通过 MCP 连接外部 AI Agent，并让被动/主动扫描器发现漏洞，而你则可以专注于手动测试。

v0.9.0 的新特性

• 原生 Anthropic 后端 (CAP-01) — 通过 Burp 的 HTTP 传输直接使用 Anthropic Messages API；所有流量都会出现在 Proxy 历史记录中。
• AES-256-GCM 静态密钥加密 (SEC-01) — 所有存储的 API 密钥和令牌都使用 javax.crypto 以每个安装实例唯一的密钥进行加密。主密钥与密文一起存放在 Burp 偏好设置中，因此这只能防御对偏好设置文件的随意查看，无法防御本地攻击者 — 请参阅隐私与安全说明。
• 真正的 HKDF 主机匿名化 (PRIV-01) — STRICT 模式现在使用真正的 HMAC-SHA256 extract/expand（而非加盐的 SHA-256）进行主机匿名化。
• 请求/响应正文脱敏 + 自定义模式 (PRIV-02) — 脱敏流程覆盖正文字段以及经过 ReDoS 校验的用户可配置正则模式。
• 发送前密钥绊线 (PRIV-03) — 在高熵值离开 Burp 之前发出警告；白名单操作会被记录到审计日志。
• 外部 MCP 服务器 (CAP-02) — 连接外部/自定义 MCP 服务器（SSE 或 stdio），使 AI Agent 可以调用这些服务器的工具以及 Burp 的内置工具。
• 按会话令牌预算护栏 (CAP-04) — BudgetGuard 通过 WARN/CAP/OFF 状态限制被动扫描器的令牌消耗；达到硬上限时被动扫描器会自动暂停。

主要特性

• 12 个 AI 后端 — Burp AI（内置）、Anthropic、Ollama、LM Studio、NVIDIA NIM、Perplexity、通用 OpenAI 兼容、Gemini CLI、Claude CLI、Codex CLI、OpenCode CLI、Copilot CLI。
• 59 个 MCP 工具 — 让 Claude Desktop（或任何 MCP 客户端）自主驱动 Burp（商店版包含 8 个扩展原生 AI 工具，完整版包含全部 59 个）。
• 范围限定的 MCP 访问 — 可选择将所有 MCP 工具限制在你的范围内主机上，使外部 AI 客户端无法通过 Burp 访问范围外的目标。
• 62 类漏洞 — 覆盖注入、认证、密码学等领域的被动和主动 AI 扫描器。被动扫描器以 Burp PassiveScanCheck（Burp Pro）的形式运行。
• 从 Releases 安装 — 从 Releases 下载 JAR。不在 BApp Store 上：提交自 2026 年 1 月起一直处于开放状态。
• 自适应主题 UI — 内部设计系统为设置面板提供样式，并随 Burp 的浅色/深色切换自动更换主题。
• Burp 扫描技能 — 通过 MCP 将你喜欢的 AI 编程助手（Claude Code、Gemini CLI、Codex 等）用作扫描器。
• 3 种隐私模式 — STRICT / BALANCED / OFF。在敏感数据离开 Burp 之前进行脱敏。
• 自定义提示词库 — 按上下文（HTTP 请求或扫描器问题）保存自由格式的提示词；可通过右键菜单启动，或通过 Custom… 输入临时提示词。
• 审计日志 — 使用带 SHA-256 完整性哈希的 JSONL 以满足合规要求；每次启动都会打上 promptSource / contextKind 标记以确保可复现性。

快速开始

1. 安装

从 Releases 下载最新的 JAR，或从源码构建（Java 21）：

git clone https://github.com/six2dez/burp-ai-agent.git
cd burp-ai-agent

# Full build (default, GitHub releases) — all 59 MCP tools
JAVA_HOME=/path/to/jdk-21 ./gradlew clean shadowJar
# 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 shadowJar -PstoreBuild=true
# Output: build/libs/Custom-AI-Agent-<version>.jar

2. 加载到 Burp

1. 打开 Burp Suite（Community 或 Professional）。
2. 转到 Extensions > Installed > Add。
3. 选择 Java 作为扩展类型，然后选择 .jar 文件。

该扩展在 Burp 中注册为 Custom AI Agent（即 Extensions 列表和 Suite 选项卡中显示的名称），以区别于 Burp 内置的 Burp AI 提供方。

3. Agent 配置文件

该扩展在首次运行时会自动将捆绑的配置文件安装到 ~/.burp-ai-agent/AGENTS/。 将额外的 *.md 文件放入该目录即可添加自定义配置文件。

4. 配置后端

打开 AI Agent 选项卡，进入 Settings。选择一个后端：

对于 NVIDIA NIM，该后端期望与 NVIDIA 托管端点相同的 chat-completions 风格流程。一个可用的配置示例如下：

Backend: NVIDIA NIM
Base URL: https://integrate.api.nvidia.com
Model: moonshotai/kimi-k2.5
API Key: <your nvapi token>

除非你的网关有要求，否则请将额外的请求头留空。扩展会向 /v1/chat/completions 发送请求，并自动使用已配置的 bearer 令牌。

5. 运行你的第一次分析

1. 通过 Burp Proxy 浏览目标。
2. 在 Proxy > HTTP History 中右键单击任意请求。
3. 选择 Extensions > Custom AI Agent > Analyze this request。
4. 将打开一个包含 AI 分析的聊天会话。

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

{
  "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 > External Servers（SSE 或 stdio 传输）中注册外部或自定义 MCP 服务器。外部服务器的认证令牌以加密形式静态存储，但存在隐私与安全说明中所述的注意事项。有关设置细节和安全说明，请参阅 docs/external-mcp-servers.md。

Burp 扫描技能（终端 AI 扫描）

burp-scan 技能让你可以从终端使用任何 AI 编程助手（Claude Code、Gemini CLI、Codex 等）作为 Burp 扫描器。与插件的内置 AI 不同，你终端中的 AI 将成为推理引擎，而 Burp 则通过 MCP 提供工具。

包含内容

• 按扫描操作组织的 MCP 工具参考（完整版中最多包含全部 59 个工具）
• 被动分析协议（不发送请求即可分析流量）
• 主动测试载荷库（覆盖 62 类漏洞的 200+ 载荷及检测模式）
• 端到端扫描工作流程（范围 -> 被动 -> 主动 -> OOB -> 报告）
• 问题创建协议，带有严重性/置信度映射

为 Claude Code 安装

将技能复制到你的 Claude Code 技能目录：

# 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 助手安装

该技能是位于 skills/burp-scan/SKILL.md 的独立 Markdown 文件。你可以将其用于任何支持系统提示词或上下文文件的 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。

• 安装
• 快速开始
• UI 导览
• Agent 配置文件
• 被动扫描器
• 主动扫描器
• MCP 概述
• 隐私模式
• 设置参考
• 故障排查
• Burp 扫描技能

运维手册

• MCP 加固
• UI 安全指南
• 后端故障排查
• Anthropic 后端设置
• 外部 MCP 服务器

隐私与安全说明

• 静态密钥的 AES-256-GCM 加密 — 加密能做什么、不能做什么。 所有存储的 API 密钥和令牌（Anthropic、MCP bearer 令牌、TLS 密钥库密码等）都使用 AES-256-GCM 加密，密钥为每个安装实例随机生成的主密钥（SecretCipher）。该主密钥本身以 Base64 编码存储在 Burp 偏好设置中，与其所保护的密文相邻（偏好项 secret.master.key.v1）。因此，任何能读取你的 Burp 偏好设置的人，也同样能读取该密钥并解密这些机密。它无法防御本地攻击者或以你的用户身份运行的恶意进程；请将其视为一种针对随意查看偏好设置文件或导出项目的混淆手段。如果某个凭据必须在这种威胁模型下保持安全，请将其保存在专用的密钥存储中，并在每次会话时重新粘贴。

• 模型发出的工具调用需要你的批准。 扩展从模型输出中解析出的工具调用，在你做出决定之前不会对 Burp 执行。每个工具都带有一个必需的安全级别：自动运行（只读且输出有界）、通过 Approve for session 选项确认，或每次调用都需确认。工具目录无法识别的工具名称会被解析为每次确认，绝不会自动运行，外部 ext: 命名空间的工具则始终需要每次确认。该决定以内嵌卡片的形式显示在聊天记录中，而不是模态对话框，并且每个决定都会被记录 — 一条审计事件，加上 Burp 的 Output 选项卡中的一行记录（因为审计日志默认是关闭的）。拒绝时，会向模型返回中性的"not authorised, do not retry"结果，而不是错误。该级别与 Unsafe Mode 开关相互独立：Unsafe Mode 决定工具是否可以运行，而级别决定模型是否无需询问即可运行它。设计理由参见 DECISIONS.md ADR-15。操作员手册参见 docs/ui-safety-guide.md。

• STRICT 隐私模式使用真正的 HKDF（HMAC-SHA256 extract/expand）对主机进行匿名化。BALANCED 模式会脱敏 Cookie、令牌和认证请求头。OFF 模式按原样发送流量。

• 外部 MCP 服务器的输出在进入 AI 提示词之前会被包裹在信任边界标记中，以防止来自不受信任服务器响应的提示注入。

设置内部带有 schema 版本（settings.schema.version），并在加载时进行增量迁移，以确保安全升级。

系统要求

• Burp Suite Community 或 Professional（2023.12+）
• Java 21（现代版 Burp 已捆绑 Java 21 用于运行时；从源码构建则需要单独安装）
• 至少配置一个 AI 后端（参见上表）

许可证

本项目基于 MIT License 许可发布。

免责声明

未经事先同意，使用 Custom AI Agent 攻击目标是违法行为。遵守所有适用法律是用户的责任。开发者不对因本工具造成的误用或损害承担任何责任。请负责任地使用。

贡献

欢迎提交 Issue 和 Pull Request。有关开发环境搭建和贡献指南，请参阅 CONTRIBUTING.md，或参阅开发者文档了解架构细节。