Burp Montoya API 自研扩展最小骨架:BurpExtension 初始化、Suite Tab 注册与 ContextMenuItemsProvider 右键菜单
tools/burp · verified
一句话结论
从零写一个自研 Burp 扩展的最小闭环是:Java 工程引入 net.portswigger.burp.extensions:montoya-api,写一个 public、无参构造、实现 BurpExtension 的类并在 initialize(MontoyaApi api) 里配置名称与日志;要 UI 交互时再用 api.userInterface().registerSuiteTab(name, JPanel) 挂顶层 tab、用 createHttpRequestEditor(READ_ONLY) 嵌入 HTTP 报文编辑器、实现 ContextMenuItemsProvider.provideMenuItems 往右键菜单加动作,即可把测试中的重复操作固化成一个可加载的 jar 插件。
原理
- 加载机制:Burp 加载扩展 jar 时会自动检测并实例化所有实现了
burp.api.montoya.BurpExtension的类,并调用其initialize(MontoyaApi api)。插件类必须是public且提供 public 无参构造,不需要额外的注册文件或清单,这也是入口代码能极短的原因。initialize返回后,已注册的 handler 才会生效。 - MontoyaApi 是总入口:Burp 通过
initialize把MontoyaApi传给插件,它按模块暴露 Burp 的能力,原文列出的主要模块包括: burp.api.montoya.burpsuite:命令行参数、导出项目级/用户级配置为 JSON、编程式关闭、任务执行引擎;burp.api.montoya.collaborator:Collaborator payload 生成与反连结果获取;burp.api.montoya.comparer:Comparer 比较功能;burp.api.montoya.extension:插件自身属性(如setName);burp.api.montoya.http/.http.handler/.http.message:HTTP 请求响应访问、HttpHandler注册、HttpRequest/HttpResponse/HttpParameter;burp.api.montoya.ui:Suite Tab、HTTP 编辑器、主题、选择内容等 UI 能力;burp.api.montoya.logging:扩展 Output/Error 输出。- 叶模块结构决定了扩展能做什么:
http.handler.HttpHandler让插件在请求/响应经过 Burp 时自动改写(适合自动加解密、签名、加头);ui模块让插件把自己的面板放进 Burp 主界面,从而把“复制到外部脚本处理再粘回”的流程收敛到 Burp 内部。 - UI 组合方式:
createHttpRequestEditor(...)返回一个HttpRequestEditor,其uiComponent()是标准 Swing 组件,可加入任意JPanel;registerSuiteTab把这个JPanel注册成 Burp 顶部的独立标签页。READ_ONLY选项让编辑器只展示不可改,不传参数则为可读写。 - 右键菜单:实现
ContextMenuItemsProvider的provideMenuItems(ContextMenuEvent event),返回List<Component>(实际为JMenuItem),Burp 会把这些项挂到右键菜单的扩展分组下。点击后的actionPerformed运行在 Swing 事件线程,修改界面组件需用SwingUtilities.invokeLater回到事件线程,避免线程问题。 - 与旧 Extender API 的关系:Montoya 是 PortSwigger 新推的插件 API,旧 Extender API 将被逐步放弃;Montoya 的接口按模块拆分、类型更全,因此新插件应直接按 Montoya 写。
触发条件
- 需要在 Burp 中固化一个重复动作:如一键把当前请求/响应写入自定义面板、对选中报文做自定义解析、给右键菜单加“发送到我的工具”等。
- 本机有 JDK(原文用 JDK 11)与 Maven 或 Gradle;Burp 版本支持 Montoya API(原文用 Burp Suite Professional v2024.3.1.2,依赖 montoya-api 2023.12.1)。
- 已获得在测试机上加载自研扩展的权限;只对授权目标使用。
利用步骤
- 建工程:IDEA 新建 Java 项目(Maven 或 Gradle 均可),语言 Java。
- 加依赖:Maven 在
pom.xml加入net.portswigger.burp.extensions:montoya-api:2023.12.1;Gradle 在dependencies加implementation 'net.portswigger.burp.extensions:montoya-api:2023.12.1'。依赖也可从 Burp 的扩展 API 界面导出/保存获得。 - 写入入口类:
public class MyExtension implements BurpExtension,实现initialize(MontoyaApi api);在方法内保存api引用,调用api.extension().setName("MyExtension1.0"),用api.logging().logToOutput(...)输出加载日志。 - 加 Suite Tab:new 一个
JPanel(如BorderLayout),把api.userInterface().createHttpRequestEditor(READ_ONLY).uiComponent()放到 CENTER,再加一个JTextArea+JScrollPane到 NORTH 作为结果区,最后api.userInterface().registerSuiteTab("test", Mytab)。 - 加右键菜单:实现
ContextMenuItemsProvider,在provideMenuItems中创建JMenuItem,用addActionListener绑定动作;动作内用SwingUtilities.invokeLater更新结果区。把 provider 注册到UserInterface(注册调用原文未展示,按 Montoya API 为api.userInterface().registerContextMenuItemsProvider(provider))。 - 构建与安装:构建 jar/工件,Burp
Extensions → Add → Java选择该 jar;在扩展的 Output 页看到this is a test、by ccc说明initialize已执行;顶部出现自定义 tab,右键菜单的“扩展”子菜单出现MyExtension1.0 → Test。 - 查 API:需要具体类/方法时,在 Burp 的 Extender/扩展页面打开内置 API javadoc 检索,或读
PortSwigger/burp-extensions-montoya-api源码与示例;不要只依赖类名列表。
PoC
Maven 依赖:
<dependency>
<groupId>net.portswigger.burp.extensions</groupId>
<artifactId>montoya-api</artifactId>
<version>2023.12.1</version>
</dependency>
扩展入口(按原文整理,import 由 IDE 补全):
package org.example;
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.logging.Logging;
public class MyExtension implements BurpExtension {
public MontoyaApi api;
@Override
public void initialize(MontoyaApi api) {
this.api = api;
// 插件名称,显示在扩展列表中
api.extension().setName("MyExtension1.0");
// 加载后输出到扩展 Output 页
Logging log = api.logging();
log.logToOutput("this is a test");
log.logToOutput("by ccc");
}
}
Suite Tab + 内嵌请求编辑器(原文片段):
JPanel Mytab = new JPanel(new BorderLayout());
HttpRequestEditor myRequestEditor = api.userInterface().createHttpRequestEditor(READ_ONLY); // READ_ONLY 只读;不传则可读写
Mytab.add(myRequestEditor.uiComponent(), BorderLayout.CENTER);
api.userInterface().registerSuiteTab("test", Mytab);
JTextArea resultArea = new JTextArea(10, 30);
JScrollPane scrollPane = new JScrollPane(resultArea);
Mytab.add(scrollPane, BorderLayout.NORTH);
右键菜单(原文片段,仅 provider 实现):
public List<Component> provideMenuItems(ContextMenuEvent event) {
List<Component> listMenuItems = new ArrayList<>();
JMenuItem TestJmenu = new JMenuItem("Test");
TestJmenu.addActionListener(new ActionListener() {
@Override
public void actionPerformed(ActionEvent e) {
SwingUtilities.invokeLater(() -> {
resultArea.append("baidu test\n");
resultArea.setCaretPosition(resultArea.getDocument().getLength());
});
}
});
listMenuItems.add(TestJmenu);
return listMenuItems;
}
变体与关联
- HttpHandler 路线:若目标是自动改写流量而不是手动点菜单,实现
burp.api.montoya.http.handler.HttpHandler并调用api.http().registerHttpHandler(...),比 UI 路线更适合加解密/加签场景;与 [[tools-burp-galaxy-http-hook-dynamic-key-capture]] 的 Montoya 四段 hook 思路同源,但本卡是自研扩展骨架,那张卡是使用 Galaxy 插件。 - 旧 API 路线:旧 Extender API(
IBurpExtender、IExtensionHelpers等)仍可用但已被宣布逐步放弃,新开发应选 Montoya。 - 开发辅助变体:用 IDE/大模型(原文用通义灵码)基于 Montoya 类和 javadoc 生成样板代码,可加快 UI 部分;核心 hook 逻辑仍需自己按 Burp 生命周期验证。
- 关联卡片:[[tools-burp-galaxy-jsrpc-auto-encrypt-decrypt-sign]]、[[tools-burp-autodecoder-flask-custom-encrypt-decrypt-script]]、[[tools-burp-burpy-pyro-python-auto-encrypt-decrypt]](均为现成加解密插件路线,可与自研扩展对比选型)。
- 边界:扩展运行在 Burp 进程内、拥有与 Burp 相同的权限,能读取全部流量与配置;只加载可信来源的 jar。不同 Burp 版本内置的 Montoya API 版本不同,依赖版本不匹配可能导致运行期
NoSuchMethodError,应以目标 Burp 自带 javadoc/API 导出为准。
检测与防御
- 本卡是自研测试工具的开发骨架,本身不针对特定目标,无远程攻击面;“防御”主要针对插件供应链与使用合规。
- 插件来源审计:Burp 扩展能读取代理中的全部请求响应(含 Cookie/Token),只从官方 BApp Store 或自己构建的源码加载;第三方 jar 加载前审代码或至少核对哈希。
- 最小权限与隔离:自研扩展只做当前项目需要的事,不额外外联;调试日志避免打印敏感头与凭据。
- 版本匹配:升级 Burp 后重新编译扩展并对齐 montoya-api 版本,避免旧 jar 静默失效或抛异常。
- 合规:仅在授权测试与自有环境中安装和使用;扩展产生的自动化请求需限速并控制在授权范围内。