proxy/README.md

Local Node MITM Proxy

一个本地 HTTP/HTTPS 调试代理，行为类似 Fiddler 的核心代理能力：

• 代理普通 HTTP 请求并保存请求/响应明文。
• 处理 HTTPS CONNECT。
• 对配置匹配的域名执行 HTTPS MITM 解密，例如 *.sunyard.com。
• 对未匹配域名只做 TCP 隧道透传，不解密。
• 生成并安装自定义根证书。
• 一键启用/关闭 Windows 当前用户系统代理。

仅在你拥有授权的设备、账号、网络和域名上使用。安装根证书后，本机信任此代理签发的站点证书；请妥善保管 certs/rootCA.key.pem，使用完及时关闭代理并移除证书。

环境

• Node.js 18+
• Windows PowerShell

安装依赖

npm install

配置

编辑 config.json：

{
  "listenHost": "127.0.0.1",
  "listenPort": 8888,
  "interceptDomains": ["*.sunyard.com"],
  "captureBodies": true,
  "maxBodyBytes": 1048576,
  "certDir": "certs",
  "capturesDir": "captures"
}

interceptDomains 支持：

• 精确域名：api.sunyard.com
• 通配子域名：*.sunyard.com
• 全部解密：*，不建议日常使用

生成根证书

npm run cert:generate

会生成：

• certs/rootCA.key.pem：根证书私钥，必须保密
• certs/rootCA.cert.pem：PEM 根证书
• certs/rootCA.cert.cer：Windows 可安装证书

如果需要重新生成，先删除 certs/rootCA.* 和 certs/generated/。

安装根证书到 Windows 当前用户

npm run cert:install:windows

这会导入到 Cert:\CurrentUser\Root。安装后请重启浏览器或目标应用。

卸载根证书：

npm run cert:uninstall:windows

启动代理

npm start

默认监听：127.0.0.1:8888。

设置系统代理

启用 Windows 当前用户系统代理：

npm run proxy:enable:windows

关闭系统代理：

npm run proxy:disable:windows

脚本修改的是 Windows Internet Settings，通常 Chrome、Edge、系统组件和很多桌面应用会使用它。某些应用有自己的代理设置或证书信任库，需要单独配置。

手动代理设置

如果不想修改系统代理，可以在浏览器或应用里手动配置：

• HTTP 代理：127.0.0.1:8888
• HTTPS 代理：127.0.0.1:8888

查看捕获数据

请求记录写入 captures/，每个请求一个 JSON 文件，包含：

• URL、方法、请求头
• 请求体，文本为 UTF-8，二进制为 Base64
• 响应状态、响应头
• 响应体，自动尝试解 gzip/br/deflate
• mitm: true 表示 HTTPS 已解密拦截

验证示例

未配置进 interceptDomains 的 HTTPS 域名会透传：

curl.exe --ssl-no-revoke -x http://127.0.0.1:8888 https://example.com/

如果要测试 HTTPS 解密，把测试域名加入 interceptDomains 后，确保系统/客户端信任 rootCA.cert.cer，再通过代理访问该域名。

重要限制

• 不支持 HTTP/2 到客户端侧，MITM 后按 HTTP/1.1 转发。
• 证书固定、公钥固定、私有信任库、移动端 App 等场景可能拒绝 MITM。
• 系统代理不等于所有网络流量，非 HTTP/HTTPS 协议不会被该代理处理。
• 仅支持基础抓包保存，没有 GUI、断点修改、重放等 Fiddler 高级功能。