基于Montoya API编写BurpSuite HTTP请求响应中间人插件

如果你平时用 BurpSuite 调试接口、抓 App 流量或者做安全评估，应该经常遇到这种局面：Repeater 可以把单个请求反复折腾，但它本质上还是“手动改”。一旦需求变成“让每个经过代理的请求自动加上某个 Header、替换一段 Body、满足特定条件才篡改”，光靠界面点击就完全玩不转了。这个时候，写一个 HTTP 请求层面的“中间人”插件，是最干净的解法。这篇博文会从零开始，基于 Montoya API 这套新架构创建一个 BurpSuite 插件，在请求进入服务器之前截获它、修改它、再放行，同时在响应回来时也能做同样的处理。内容适合有一定 Java 基础、想把 BurpSuite 从手工工具升级成自动化工具的开发者，也适合刚接触插件开发、想快速搞懂新版 API 用法的朋友。

1. 为什么需要 HTTP 中间人插件

1.1 中间人能力解决什么问题

举一个最常见的场景：某个接口协议要求所有请求必须带一个版本号头，比如X-API-Version，否则服务器直接返回 400。你在 Postman 里加一次容易，但当你用 Burp 的浏览器代理做前端联调时，页面发出的几十个请求全都缺这个头，于是在 Network 面板里一片红。用 Repeater 一个个补头显然不现实，更可靠的做法是让插件在请求流经 Burp 的那一瞬间，自动把版本号头补上。

另一个更典型的场景是移动端抓包。很多 App 的接口会校验时间戳或者签名，你在调试的时候希望固定某个参数、临时替换 token，甚至动态注入一个 trace-id 用于全链路排查。这类需求如果靠人工在代理工具里改，几乎不可能重复操作，只有让代码在请求经过代理时接管逻辑，才能做到“无感修改”。

这就是中间人插件的核心价值：它在 BurpSuite 的 HTTP 处理链路上加了一个可编程的关卡，请求进去时你能看、能改、能放行；响应返回时你同样能看、能改、能放行。它把 BurpSuite 从一个手动测试工具，变成一个具备自动干涉能力的流量处理平台。

1.2 为什么选 Montoya API 而不是旧版 API

BurpSuite 的扩展开发经历过两代接口。旧时代的主力是IBurpExtender，你需要实现一个registerExtenderCallbacks方法，然后在回调对象上挂各种I开头的接口，比如IHttpListener、IHttpRequestResponse、IExtensionHelpers。这套接口用了很多年，能跑，但问题也很明显：所有回调都是全局状态，命名风格不统一，类型设计比较弱，一个新人翻开旧文档学的时候，经常会迷失在十几个I接口里。

Montoya API 是 BurpSuite 为插件开发者准备的新一代扩展接口。它最大的变化是提供了一个统一的门面对象MontoyaApi，插件只需要实现一个BurpExtension接口，在initialize方法里拿到这个门面，然后通过api.http()、api.proxy()、api.scanner()、api.logging()这类模块化入口去调用功能。整个代码组织感强了很多，接口命名也更直白，不再有一堆毫无意义的I前缀。

新版要求自然是更高的：需要 JDK 17 或更高版本，BurpSuite 本身也得是较新的稳定版，否则插件加载时会直接报类版本错误。但对一个新插件项目来说，选择 Montoya API 是明确的决定——你不用再去维护一堆过时的回调写法，而且 Burp 后续的新特性只会更多围绕这套 API 展开，早用早省心。

2. 项目搭建：JDK 17 与 Gradle 环境

2.1 项目结构与 Gradle 依赖配置

写 BurpSuite 插件本质上是写一个 Java 工程，然后用 Gradle 或 Maven 构建成 JAR 包再加载。我习惯用 Gradle，结构简单，打包也顺手。先建一个普通 Java 项目，目录大致长这样：

my-burp-plugin/ ├── build.gradle ├── settings.gradle └── src └── main └── java └── example └── interceptor ├── RequestInterceptor.java └── RequestModifier.java

build.gradle是整个项目最关键的文件之一。注意这里有一个重要选择：Montoya API 的 jar 包只在编译时需要，不应该打包进最终的插件 JAR，因为 BurpSuite 运行时已经自带这些类了。所以依赖声明要用compileOnly，意思就是“编译期可见，运行期由外部提供”。

plugins { id 'java' } group = 'example' version = '1.0.0' repositories { mavenCentral() } dependencies { compileOnly 'net.portswigger.burp.extensions:montoya-api:2024.12' } java { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 }

有两点我需要提醒你。第一，net.portswigger.burp.extensions:montoya-api这个依赖坐标里的版本号更新很快，我这里写的只是一个示例版本，你动手前最好去中央仓库搜索这个坐标，拿最新的稳定版号替换上去，否则可能跟你的 BurpSuite 版本不匹配。第二，如果你在插件里引用了其他第三方库（比如 JSON 解析库），那这些依赖就必须打进最终 JAR，否则运行时会报NoClassDefFoundError。打包方式后面会说到。

2.2 加载编译产物到 BurpSuite

代码写完之后，构建插件。如果没有任何第三方依赖，直接执行：

gradle jar

生成的文件在build/libs目录下，一个名为my-burp-plugin-1.0.0.jar的包。如果插件里带了第三方依赖，就要用 fat JAR 方式，把所有依赖的 class 打到一个包里面。社区里常用的方案是 Shadow 插件，在plugins里加上com.gradleup.shadow，之后执行gradle shadowJar，产物会变成xxx-all.jar。

加载到 BurpSuite 的路径很固定：打开 Burp -> Extensions -> Add，Extension Type 选 Java，然后选中你构建出来的 JAR。加载成功后，Output 面板里如果出现你自己日志输出的启动信息，就说明插件被正常识别了。如果 Burp 的版本偏老，无法识别 Montoya API 的类，这里就会直接报清单很长的一段AbstractMethodError或者NoClassDefFoundError，这大概率不是代码逻辑问题，而是 API 版本和 Burp 版本不匹配，先检查这两个。

3. 核心接口拆解：从入口到处理链

3.1 BurpExtension 生命周期与初始化

Montoya API 的入口类写法非常固定。你需要实现burp.api.montoya.BurpExtension接口，并在initialize(MontoyaApi api)方法中完成所有初始化工作。这个方法会在插件加载时被 Burp 调用一次，类比的话，它就是插件的main方法。

来看最小可运行的入口代码：

package example.interceptor; import burp.api.montoya.BurpExtension; import burp.api.montoya.MontoyaApi; public class RequestInterceptor implements BurpExtension { @Override public void initialize(MontoyaApi api) { api.extension().setName("HTTP Request Interceptor"); api.http().registerHttpHandler(new RequestModifier()); api.logging().logToOutput("HTTP Request Interceptor loaded."); } }

这里几行代码各有所用：api.extension().setName(...)是设置插件在 Burp 扩展列表里的展示名；api.http().registerHttpHandler(...)是把我们自定义的处理器挂到 HTTP 链路上，这一步不做的话，后面所有拦截逻辑都不会生效；api.logging().logToOutput(...)则是往 Burp 的 Output 面板打一行日志，方便确认插件真的加载了。

需要留个心眼的点是，initialize方法不要做任何耗时操作，比如发网络请求、读取大文件、密集计算。虽然它只执行一次，但如果这里慢下来，Burp 会在启动插件时表现出明显的卡顿。把该注册的注册好、该初始化的数据结构建好，就够了，重活留给处理器去干。

3.2 HttpHandler 请求响应处理链

HTTP 处理器是整个中间人能力的核心，对应接口是burp.api.montoya.http.handler.HttpHandler。你要实现它的两个方法：

• handleHttpRequest(HttpRequest request)：每个请求从客户端发出、经过 Burp 处理时会调用。
• handleHttpResponse(HttpResponse response)：每个响应从服务器返回、经过 Burp 处理时会调用。

这两个方法的返回值约定很关键，可以说是写这类插件的第一个理解门槛。返回值如果是null，表示“我不需要修改”，Burp 会把原本的对象原样放行；如果返回一个新的请求或响应对象，则后续链路和发送动作都会使用你替换过的版本。很多新手第一次写的时候，在方法里调用了一个withHeader方法，却没意识到返回值没有赋给任何变量，于是耗时半天发现毫无变化——这正是因为没有理解“修改逻辑的产物是新对象，而不是原地改动”。

HttpHandler的完整雏形长得像这样：

package example.interceptor; import burp.api.montoya.http.handler.HttpHandler; import burp.api.montoya.http.message.requests.HttpRequest; import burp.api.montoya.http.message.responses.HttpResponse; public class RequestModifier implements HttpHandler { @Override public HttpRequest handleHttpRequest(HttpRequest request) { // 返回 null 表示不修改，返回新对象表示替换 return request.withHeader("X-Interceptor", "true"); } @Override public HttpResponse handleHttpResponse(HttpResponse response) { // 这里先不做响应修改 return null; } }

实际执行时机很好理解：开启 Burp 的代理并让浏览器或 App 走 127.0.0.1:8080 之后，所有 HTTP 流量都会经过 Burp 的 HTTP 处理链。你的 handler 就挂在链上，请求到达时先过一遍handleHttpRequest，响应返回时再过一遍handleHttpResponse。你在 Burp 的Proxy->HTTP history里看到的报文，其实已经是处理器链跑完一遍之后的结果。

3.3 不可变请求对象与修改范式

Montoya API 里的HttpRequest和HttpResponse都是不可变对象。这跟 Java 里String的规则一样：你不能在一个已有对象上直接“改动”，每次修改都会产生一个新的对象。因此，所有形如withXxx的方法，返回值才是修改后的对象，原对象保持原封不动。

举几个常用的方法，帮助建立修改直觉：

// 添加或替换请求头 HttpRequest r1 = request.withHeader("X-API-Version", "2"); // 修改请求方法 HttpRequest r2 = request.withMethod("POST"); // 修改请求体（ByteArray 是字节数据封装） HttpRequest r3 = request.withBody(ByteArray.stringToBytes("name=test&count=1"));

这种设计有实际的好处。当多个处理器串联协作时，每个处理器接收到的都是上一个处理器返回的新对象，而不是被某个环节污染过的共享对象；线程安全方面也省心很多，因为没有任何人可以中途改动同一个对象。代价就是你得习惯“每次修改都刷新一下变量引用”的写法，我自己早期写代码就经常犯懒，写完一行request.withHeader(...)直接回车，然后发现逻辑根本没生效。

4. 第一个可运行插件：请求拦截与修改

4.1 注册处理器并完成请求头修改

在环境准备好之后，把上面两个类组合起来，就是一个能用的插件了。启动 BurpSuite、加载 JAR，浏览器配置代理到127.0.0.1:8080，然后随便访问一个 HTTP 网站。此时你在 Burp 的 HTTP history 里打开任意一条请求记录，展开请求头列表，会看到多出来一个X-Interceptor: true。

这个改动虽然微小，但已经证明了整条链路是通的：请求从浏览器出来，经过 Burp，我们的 handler 被调用，修改后的请求再继续往后走。从零到一的第一步，是先看到“我的代码真的被 Burp 执行了”，这比任何复杂功能都重要。我见过不少朋友一上来就写几百行的加密解密逻辑，结果插件加载完都没意识到自己的 handler 根本没被调用，白白排查了很久。

一个更实用的变体是：只给某些域名的请求加 Header。做法很简单，在handleHttpRequest里读取请求的 URL 做判断：

@Override public HttpRequest handleHttpRequest(HttpRequest request) { if (request.url().getHost().toLowerCase().contains("api.example.com")) { return request.withHeader("X-API-Version", "2"); } return null; }

request.url()返回的是 URL 对象，里面有 host、path、port 等信息，这是请求判断的常用入口。只有当目标主机名匹配时，我们才修改；否则返回null让请求保持原样。这个模式会贯穿后续几乎所有实战插件。

4.2 修改请求方法、路径与请求体

请求头修改只是开胃菜。很多时候你需要连方法、路径、请求体一起调整。举个实际场景：在接口联调环境里，你希望把所有 GET 请求转换成 POST，并给请求体加入默认参数，同时把路径中的/v1前缀改写掉。这些操作在HttpRequest上都有对应的withXxx方法可以链式调用。

package example.interceptor; import burp.api.montoya.http.handler.HttpHandler; import burp.api.montoya.http.message.requests.HttpRequest; import burp.api.montoya.http.message.responses.HttpResponse; import burp.api.montoya.http.message.ByteArray; public class RequestModifier implements HttpHandler { @Override public HttpRequest handleHttpRequest(HttpRequest request) { String path = request.url().getPath(); // 只处理 /v1/ 路径 if (!path.startsWith("/v1/")) { return null; } // 1. 方法改成 POST HttpRequest modified = request.withMethod("POST"); // 2. 路径从 /v1/api/list 改成 /v2/api/list String newPath = path.replaceFirst("/v1/", "/v2/"); modified = modified.withPath(newPath); // 3. 写入新的请求体 ByteArray body = ByteArray.stringToBytes("source=interceptor&mode=debug"); modified = modified.withBody(body); // 4. 修正 Content-Length modified = modified.withHeader("Content-Length", String.valueOf(body.length())); return modified; } @Override public HttpResponse handleHttpResponse(HttpResponse response) { return null; } }

关于Content-Length，你千万不要忽略。改动请求体之后长度就变了，如果还用旧的长度值，服务器在读取请求体时会一直等待，最终超时。Burp 的处理器链路不会自动帮你重新计算 HTTP 报文长度，这个问题必须自己在代码里处理。同理，修改响应体之后也要手动维护响应里的Content-Length。这个坑我踩过一次，症状是浏览器转圈很久，最后才发现请求体长度和实际内容对不上。

4.3 修改响应内容

请求能改，响应当然也能改。handleHttpResponse的用法和请求侧完全对称。一个常见的需求是把响应体里的某些字符串替换掉，比如把测试环境返回的版本号统一替换成固定文案，或者把敏感接口返回里的某段字段做脱敏处理。示例：

package example.interceptor; import burp.api.montoya.http.handler.HttpHandler; import burp.api.montoya.http.message.requests.HttpRequest; import burp.api.montoya.http.message.responses.HttpResponse; import burp.api.montoya.http.message.ByteArray; public class ResponseModifier implements HttpHandler { @Override public HttpRequest handleHttpRequest(HttpRequest request) { return null; } @Override public HttpResponse handleHttpResponse(HttpResponse response) { String oldBody = response.body().toString(); if (oldBody.contains("default-version")) { String newBody = oldBody.replace("default-version", "custom-version"); HttpResponse modified = response.withBody(ByteArray.stringToBytes(newBody)); modified = modified.withHeader("Content-Length", String.valueOf(newBody.length())); return modified; } return null; } }

这里有一个很关键的隐患：如果你的目标站点启用了 gzip 或 br 压缩，响应体的实际字节是压缩后的数据，你拿到的body()是压缩字节流，直接做字符串替换就会产生乱码，甚至替换操作根本匹配不到。稳妥的做法是先判断响应头里的Content-Encoding，如果发现是gzip，就先解压、替换、再重新压缩，然后更新Content-Length。别嫌麻烦，生产环境里所有 CDN 和大型站点几乎都在启用压缩，不做这步的插件基本只对本地小服务有效。

4.4 处理多个 Handler 的顺序

BurpSuite 的 HTTP 链路允许注册多个HttpHandler。你可以把一个复杂的拦截逻辑拆成几个模块，比如一个模块管鉴权头，一个模块管请求体标准化，一个模块管响应脱敏。每个模块各自实现HttpHandler，然后在initialize里全部注册。

多个 handler 的执行顺序遵循注册顺序，前面的 handler 返回的新请求，会作为下一个 handler 的输入。这就意味着你要留心修改的层次：如果你在第一个 handler 里面加了X-API-Version，第二个 handler 如果想判断这个头是否存在，它是能看到的。反过来，如果两个 handler 同时给同一个请求添加同名的头，后注册的那个会覆盖之前的值。设计模块时，最好明确每个 handler 的职责边界，比如“A 只负责加认证头，B 只负责改请求体”，这样排错会轻松很多。

另外，registerHttpHandler还有一个带布尔参数的重载，用来控制 handler 在链路中是否作为最终处理器。这个参数的具体语义在不同版本里有细微差别，你在编译时最好看一眼前后的 Javadoc，或者直接在源码里确认。我通常用最普通的单参数版本，已经能覆盖绝大多数场景。

5. 实操中踩过的坑与排查方法

5.1 插件加载失败类问题

先说最常见的插件压根加载不上的情况。症状是 Burp 加载 JAR 后，Extensions 面板里出现红色错误信息。这类问题里，九成是环境不匹配，不是代码逻辑问题。

我建议做一次纯粹的最小验证：拿一个只实现BurpExtension、只写一行日志的 JAR 加载到你的 Burp 里，看能不能跑通。如果最小插件能加载，你就能确认环境没问题，剩下的就是自己代码的问题；如果最小插件都失败，那就是版本链问题，先修环境再继续。

5.2 修改不生效类问题

插件成功加载了，但流量经过时你的改动完全没出现，这也是高频问题。以下几种情况我都遇到过，你对照排查就好。

首先看 handler 方法返回值。handleHttpRequest返回null等价于“不改动”，如果你在方法最后写了：

return null;

那前面做的一堆withHeader操作就全部白费。修改逻辑必须让返回值指向最后一次修改后的对象。

其次看是否更新了对象引用。前面强调过不可变性，有些人会写：

request.withHeader("X-Foo", "bar"); return request;

withHeader返回了一个新的对象，但你没接住，返回的还是原来的request，自然没变化。正确写法是HttpRequest modified = request.withHeader(...); return modified;。

第三，如果你修改了请求体，却没有同步更新Content-Length头，结果是服务器读不到完整的请求体，不会立刻报错，但接口行为会变得很奇怪——超时、返回空响应、甚至直接中断连接。排查这类问题时，可以把问题定位从“我的插件没生效”转成“我的插件改了但改得不完整”。用 Burp 自带的历史记录对比一下原始报文和最终报文，很快就能看出差距。

5.3 性能隐患与递归陷阱

中间人插件是在流量必经之路上执行的，任何耗时操作都会被放大。比如你在handleHttpRequest里做了一个同步的外网 API 调用，那么每一个请求经过时，用户都要停下来等你这个外呼返回。在并发场景下，这相当于把整个代理链路拖慢了几百毫秒，体验非常糟糕。如果确实需要远程数据，建议预加载缓存、异步更新数据，或者只在特定触发条件下做远程调用。

另一个隐蔽的坑是处理逻辑“非幂等”。如果你的修改逻辑是无条件执行的，比如每次请求都往 Header 里追加一个当前时间戳，那么修改后的请求在 Burp 的某些处理阶段中可能又会被 handler 调用一次，从而再追加一个时间戳。一旦链路存在这种循环，你可能看到同一个请求被反复修改，甚至陷入无限循环。最好的习惯是，在修改前先做条件判断：如果目标 Header 已经存在了，就直接返回原对象，不要重复修改。

还有一点，ByteArray与 Java 字符串之间的编码转换要使用正确的字符集。响应体里的二进制内容并不都是 UTF-8 文本，如果你用toString()方法强行转字符串再替换，遇到非文本字节就会损坏内容。稳妥的路线是先判断响应类型，比如只处理Content-Type: text/html、application/json这类的文本响应，对图片、字体这类二进制响应直接放行。

6. 更进一步：把中间人能力变成生产级插件

6.1 与 UI、存储结合

到这一步，你的中间人插件在功能上已经能跑，但还是个“硬编码插件”：改什么、什么时候改，全部写在代码里，每次调整都要重新编译 JAR。生产级插件的下一个明显改进，是给插件加一个配置界面。

Montoya API 也覆盖了 UI 这块。你可以用api.userInterface()注册一个自定义 Tab，里面放一个普通的 Swing 面板。面板上可以放复选框、输入框，用于控制拦截开关、目标域名、要注入的 Header 内容等等。相关的配置值可以用api.persistence().preferences()做持久化存储，这样插件重启之后，配置还能保留下来，不需要每次重新输入。

把硬编码改成配置项，收益是非常直观的：你在公司内部给别人用这个插件时，对方不需要看代码、不需要改代码，只需要在面板上勾一勾、填一填，就能适配自己的场景。插件也因此从“为某个项目定制的脚本”变成“可复用的小工具”。

6.2 结合扫描器与自动化

中间人能力还可以往更深一层走——既然你能在请求到达服务器之前修改它，那你同样可以在扫描器发起主动检测时注入自定义逻辑。Montoya API 提供了扫描扩展能力，你可以通过api.scanner().registerScanCheck(...)注册自定义的扫描检查项，把中间人插件的修改逻辑和扫描策略结合起来。

举个例子：你写了一个自动给请求加时间戳签名的中间人插件，那么在 Intruder 或者主动扫描里跑一个字典时，以前你会遇到“字典跑了一堆，但签名不对，服务器全返回 401”的尴尬；但现在处理器在扫描请求发出前已经把签名加好了，扫描器拿到的就是合法请求。这样做既缩短了测试准备时间，也让扫描结果更接近真实攻击路径。自动化工具之间的边界，在这里其实是可以打通的。

6.3 可扩展方向与维护建议

把一个能运行的最小插件打磨成长期维护的项目，我最后想分享几条个人体会。

一是版本的维护要主动。BurpSuite 和 Montoya API 都在频繁迭代，插件用了哪个版本的 API 编译、在哪个版本的 Burp 上验证过，最好在 README 里写清楚。我自己就经历过一次 Burp 升级后插件接口行为变得不一致，排查了半天才意识到是新版本对registerHttpHandler的调用时机做了调整。版本写清楚，能避免半年以后你自己都忘了当时的运行环境。

二是开发过程中保持修改逻辑的幂等性。无论一个请求会经过多少次处理，你都应该保证“改一次”和“改一百次”的结果是一样的。这个习惯不仅是为了安全，也是为了在复杂的过滤器链中保持行为可预期。

三是善用日志。在 handler 的入口和出口各打一行日志，记录请求路径和是否做了修改，能大幅减少排错时间。生产插件里的日志级别最好做区分，不要每个请求都无脑打全量报文，否则日志面板会瞬间被刷爆。

如果你正准备做一个能长期使用的请求处理插件，我的建议是从今天这个最小版本出发，先把请求头修改跑通，再逐步加上条件判断、请求体处理、响应处理、配置界面。每一步都验证到位，最终你会得到一个非常顺手的“流量改写工具”，它做的是那些 Repeater 手动操作永远做不了的事情。

最后再分享一个我的使用习惯：这类中间人插件，我一定会加一个总开关，默认关闭。只有明确开启时才修改流量，这样在平时抓包、排障时，插件不会干扰正常观察；需要自动化改造时再打开，观察完又可以关上。这个习惯帮我挡掉了不少“验证半天发现是插件改坏了数据”的问题，你也可以试试。