HTTP Breakout Proxy

一个用 Go 编写的轻量级 HTTP/HTTPS 拦截代理和流量分析工具，带有基于 Web 的 UI，可实时检查、过滤、着色和注释捕获的流量。

概述

HTTP Breakout Proxy 既可作为 HTTP 和 HTTPS MITM 代理，也可作为实时可视化工具。
它捕获两个软件组件之间的请求和响应，让开发者能够：

• 检查每个请求和响应的标头、正文及时间详情。
• 组织、过滤和持久化捕获的数据。
• 根据用户定义的颜色规则高亮请求。
• 动态暂停或恢复捕获。
• 将请求时序以甘特图形式查看，以可视化性能阶段。

该代理嵌入了一个功能完整的 UI，可通过任何现代 Web 浏览器访问，无需外部工具即可进行实时分析。

功能

🔍 捕获与检查

• 拦截 HTTP 和 HTTPS 流量（支持 MITM CA）。
• 显示所有请求和响应的元数据、标头和正文。
• 支持对大型正文进行截断。

💾 持久化

• 捕获数据和颜色规则存储在 captures.json（或指定文件）中。
• 启动时自动重新加载状态，并定期保存到磁盘。
• 首次运行时，若不存在颜色规则，则生成默认规则。

🖥️ Web UI

• 响应式嵌入 Web 界面（由代理自身提供）。
• 以可滚动列表形式显示捕获，带有颜色编码标识。
• 详情面板显示：
  • 请求和响应标头/正文
  • 时序分解
  • 可编辑注释
  • 连接阶段的甘特图风格性能图

🎨 颜色规则

• 使用灵活的筛选语法定义捕获的条件颜色高亮：
  • 示例：status:4 status:5 → 高亮 HTTP 错误
  • 示例：url:/api/ → 高亮 API 请求
  • 示例：/\.css$/ → 对 URL 进行正则匹配
• 每条规则包含：
  • 名称、颜色、匹配表达式、优先级和注释
• 最高优先级匹配获胜。
• 通过模态 UI 交互式管理，带有实时预览。
• 跨会话持久化。

⏸️ 捕获控制

• 暂停/恢复按钮可停止收集新捕获，而无需停止代理。
• 在专注于固定数据集或隔离特定行为时非常有用。

📈 性能可视化

• 每次捕获包含详细的连接时序：
  • DNS 查找
  • TCP 连接
  • TLS 握手
  • 服务器处理
  • 响应读取
• 以甘特图形式显示在详情面板中。
• 标度自动四舍五入到最接近的秒数，便于阅读。

🧭 筛选与搜索

• 实时筛选框支持：
  • 基于字段的筛选（method:GET、status:404、header:Content-Type=application/json）
  • 正则表达式（/login/）
  • 组合条件，支持 AND/OR 语义
• 支持不区分大小写的部分匹配。
• 筛选同时应用于捕获列表和颜色高亮。
• 搜索历史存储在浏览器本地。

🧹 管理

• 通过 UI 删除单个捕获或清空所有捕获。
• 规则和注释与捕获一起持久化。

🧩 导出工具

• 将捕获复制为：
  • curl 命令（格式化为终端使用）
  • python requests 代码片段（干净的 JSON 表示）
• 直接从 UI 下载响应正文。

命令行使用

httpbreakout -l 127.0.0.1:8080

快速开始

编译（从源码）

git clone https://github.com/jbsouthe/http-breakout-proxy.git
cd http-breakout-proxy
go build -o http-breakout-proxy

这将生成一个包含已编译代理和嵌入 UI 资源的单一可执行文件。

运行（默认）

# 以默认配置运行（代理 + UI）
./http-breakout-proxy

默认情况下，二进制文件绑定到 127.0.0.1:8080 用于代理（以及可选的 UI —— 参见 CLI 标志）。在浏览器中打开 UI 以检查捕获。

示例：使用 curl 测试代理

# 通过代理发送 HTTPS 请求（代理监听 127.0.0.1:8080）
curl -x http://127.0.0.1:8080 https://example.com

捕获的流量将出现在 Web UI 中。

命令行参数

使用 ./http-breakout-proxy -h 列出所有可用标志和用法描述。

Web UI 概述

UI 针对调查工作流进行了优化。

• 顶部工具栏：全局筛选输入（支持正则和键前缀）、暂停/恢复捕获、清空和筛选帮助（在新标签页中打开）。
• 左侧面板：按时间顺序排列的捕获列表（最新的在前）。每个项目显示捕获名称；默认情况下为 METHOD URL [STATUS]，但可以分配自定义名称。
• 右侧面板：所选捕获的详情：
  • 概览：元数据、标头和正文（适用时以格式化的 JSON 显示）。
  • 请求/响应选项卡：原始格式的正文。
  • 原始选项卡：完整的捕获 JSON。
• 行操作：复制为 curl、复制为 Python requests、下载响应正文、重命名、删除。

筛选语言（快速参考）

• 纯文本标记：在任何位置匹配（方法、URL、状态、主机、标头、正文）。
• 前缀：method:、status:、host:、url:、body:、req.body:、resp.body:、header:、req.header:、resp.header:。
• 正则语法：/pattern/flags（例如 /bearer\\s+\\S+/i）。
• 标头规范：header:name=value，其中 name 或 value 可以是正则表达式。

示例：

• method:POST status:2 host:api.example.com
• /token\\s*[:=]\\s*\\S+/i
• req.header:authorization=/bearer/i
• body:/\\"success\\"\\s*:\\s*true/i

HTTPS 拦截 (MITM)

启用中间人模式时：

1. 代理生成一个 RSA CA 密钥对和根证书，并存储在 -ca（默认 ./ca）目录中。
2. 要检查 HTTPS 流量，必须将生成的 CA 证书（ca.pem 或类似文件）添加到发送请求的客户端（或系统）的信任存储中。在许多平台上，这需要管理员权限。
3. 代理通过为客户端请求的每个主机名颁发由本地 CA 签名的叶子证书来执行 TLS 拦截。

安全注意事项： 仅在受控环境中安装 CA。不要在与敏感无关流量的系统中信任此 CA。

持久化

如果启用了持久化（通过 -f 或配置的路径）：

• 捕获定期写入磁盘（例如 captures.json）。
• 启动时，应用程序会尝试从持久化文件将之前的捕获加载到内存缓冲区（保持顺序）。
• 重命名和删除操作将在保存操作时同步到持久化存储；对于关键操作，可以考虑调用立即刷新。

存储格式

捕获项序列化为 JSON，包含以下字段（非详尽）：

• id — 唯一序列标识符
• time — 时间戳（ISO 8601）
• method、url
• request_headers、response_headers
• request_body、response_body — 必要时截断至 -max-body
• response_status、duration_ms
• name — 可选用户标签
• notes、deleted — 用于 SSE 事件和 UI 状态的控制元数据

导出与重放辅助工具

• 复制为 cURL：构建一个 shell 安全的 curl 命令，包括标头和正文（跳过逐跳标头）。
• 复制为 Python：生成一个包含 url、headers 和可选 data 的小型 requests 代码片段。
• 下载：将响应正文保存到文件；扩展名尽量从 Content-Type 推断。

设计考虑：

• 逐跳标头（如 Host、Content-Length、Connection）在生成的 replay 命令中被省略。
• 二进制响应正文（图像、PDF）可使用二进制 blob 下载。如果响应以 Base64 编码存储，则客户端会在下载前解码。

API：REST 端点（用于自动化）

• GET /api/captures — 列出捕获（JSON 数组）。
• DELETE /api/captures — 清空所有捕获。
• GET /api/captures/{id} — 检索单个捕获。
• DELETE /api/captures/{id} — 删除特定捕获。
• PATCH /api/captures/{id} — 更新捕获元数据；body 示例：{ "name": "My label" }。
• GET /api/pause — 返回 { "paused": true|false }。
• POST /api/pause — 设置暂停状态；body 示例：{ "paused": true }。
• GET /events — 用于实时捕获通知和控制事件的服务器推送事件（SSE）流。

实现注记（供开发者参考）

• 嵌入 UI：使用 //go:embed ui/* 和 fs.Sub 来提供静态文件服务。这会产生一个单一的可部署产物。
• 解压缩：捕获代码检查 Content-Encoding 并尝试在显示前解压 gzip 和 deflate 正文。原始字节保留以确保代理透明性。
• 并发：捕获存储使用内部锁提供线程安全的追加/列表/获取/更新操作。在可能的情况下，使用原子布尔变量作为切换标志（例如暂停/恢复）。
• SSE：一个轻量级的代理广播捕获的添加、删除、重命名和控制事件给已连接的 UI 客户端。
• 缓冲：捕获正文使用 io.LimitReader 读取，以检测截断并保护内存使用。

打包与分发

推荐的分发模型：

1. 为目标平台构建静态、精简的二进制文件（CGO_ENABLED=0、-trimpath、-ldflags "-s -w"）。
2. 生成归档文件（Unix 使用 .tar.gz，Windows 使用 .zip），并包含 README.md 和 LICENSE。
3. 提供 SHA-256 校验和，并将产物附加到 GitHub Releases。
4. 可选使用 goreleaser 自动化跨平台构建和发布产物。

示例构建命令：

# Linux x86_64
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-linux-amd64 .

# macOS (arm64)
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-darwin-arm64 .

作为服务运行

systemd 单元文件（Linux 示例）

[Unit]
Description=HTTP Breakout Proxy
After=network.target

[Service]
ExecStart=/opt/http-breakout-proxy/http-breakout-proxy -l 0.0.0.0:8080
Restart=on-failure
User=proxy
Group=proxy

[Install]
WantedBy=multi-user.target

launchd（macOS 用户代理）

在 ~/Library/LaunchAgents 中创建一个 plist 文件，并使用 launchctl 加载。

故障排除

• 捕获的正文显示为二进制乱码
  正文被压缩（例如 gzip）。确保你运行的是包含自动解压缩功能的构建版本；UI 会在可用时显示解压后的 JSON/文本。

• HTTPS 流量不显示 / 连接错误
  客户端不信任生成的 CA。将 ca/ca.pem 安装到客户端/系统信任存储中，并标记为可信以进行 TLS 拦截。

• 清空捕获后 UI 显示过时的选择
  升级到在 cleared SSE 事件上清除 selectedId 的客户端，或调用 GET /api/captures 端点刷新状态。

• DELETE /api/captures 返回 405
  确保服务器处理器接受对 /api/captures 的 DELETE 方法，并且没有因尾部斜杠不匹配而导致问题。

安全与隐私

当启用 MITM 时，此工具执行 TLS 拦截。仅在你有权检查流量的受控环境中使用。生成的 CA 具有强大权限：请像对待任何其他根 CA 私钥一样，对其私钥保密。不要将 CA 安装到共享或生产信任存储中。

贡献

欢迎贡献。请为错误或功能请求提交 issue。对于代码贡献：

1. Fork 此仓库。
2. 创建功能分支。
3. 运行单元测试和 linter（如适用）。
4. 提交描述更改、理由以及任何向后兼容性问题的拉取请求。

许可证

本项目根据 MIT 许可证 分发。详情请参阅 LICENSE。

归属与联系

作者：John Southerland (GitHub: jbsouthe)
项目：http-breakout-proxy — 旨在用于调试、开发以及学习 HTTP 行为。