HTTP Breakout Proxy

Go で書かれた軽量な HTTP/HTTPS インターセプトプロキシ兼トラフィック解析ツールです。キャプチャしたトラフィックをリアルタイムに検査・フィルタリング・色分け・注釈付けできる Web ベースの UI を備えています。

概要

HTTP Breakout Proxy は、HTTP と HTTPS の両方に対応する MITM プロキシとして、またライブ可視化ツールとして機能します。
2 つのソフトウェアコンポーネント間のリクエストとレスポンスをキャプチャし、開発者に以下の機能を提供します:

• 各リクエストとレスポンスのヘッダー、ボディ、タイミング詳細を検査。
• キャプチャデータの整理、フィルタリング、永続化。
• ユーザー定義のカラールールに基づくリクエストのハイライト。
• キャプチャの動的な一時停止・再開。
• リクエストのタイミングをガントチャートで表示し、パフォーマンスの各フェーズを可視化。

このプロキシには、あらゆるモダンな Web ブラウザからアクセスできるフル機能の UI が組み込まれており、外部ツールなしで即座にリアルタイム分析が可能です。

機能

🔍 キャプチャと検査

• 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)。
  • リクエスト / レスポンスタブ: 生の整形済みボディ。
  • Raw タブ: キャプチャ全体の JSON。
• 行アクション: curl としてコピー、Python requests としてコピー、レスポンスボディのダウンロード、名前変更、削除。

フィルター言語(簡単なリファレンス)

• プレーントークン: 任意の場所にマッチ(method、URL、status、host、headers、bodies)。
• プレフィックス: 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 としてコピー: ヘッダーとボディを含むシェルセーフな curl コマンドを生成します(ホップバイホップヘッダーは省略)。
• Python としてコピー: url、headers、任意の data を含む小さな requests スニペットを生成します。
• ダウンロード: レスポンスボディをファイルに保存します。可能な場合は Content-Type から拡張子を推測します。

設計上の考慮事項:

• 生成されたリプレイコマンドからは、ホップバイホップヘッダー(例: Host、Content-Length、Connection)が省略されます。
• バイナリのレスポンスボディ(画像、PDF)はバイナリブロブを使用してダウンロード可能です。レスポンスが Base64 エンコードされて保存されている場合、クライアントはダウンロード前にデコードします。

API: REST エンドポイント(自動化用)

• GET /api/captures — キャプチャの一覧(JSON 配列)。
• DELETE /api/captures — すべてのキャプチャをクリア。
• GET /api/captures/{id} — 単一のキャプチャを取得。
• DELETE /api/captures/{id} — 特定のキャプチャを削除。
• PATCH /api/captures/{id} — キャプチャのメタデータを更新。ボディ例: { "name": "My label" }。
• GET /api/pause — { "paused": true|false } を返します。
• POST /api/pause — 一時停止状態を設定。ボディ例: { "paused": true }。
• GET /events — ライブキャプチャ通知と制御イベント用の Server-Sent Events (SSE) ストリーム。

実装メモ(開発者向け)

• UI の埋め込み: //go:embed ui/* と fs.Sub を使用して静的ファイルを配信します。これにより、単一のデプロイ可能な成果物が生成されます。
• 解凍: キャプチャコードは Content-Encoding を確認し、表示前に gzip と deflate ボディの解凍を試みます。元のバイトはプロキシの透過性のために保持されます。
• 並行性: キャプチャストアは内部ロックを使用して、スレッドセーフな append/list/get/update 操作を提供します。トグルフラグ(例: 一時停止/再開)には可能な限りアトミックブールが使用されます。
• 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. リポジトリをフォークします。
2. フィーチャーブランチを作成します。
3. 該当する場合はユニットテストとリンターを実行します。
4. 変更内容、根拠、後方互換性に関する懸念事項を説明するプルリクエストを提出します。

ライセンス

このプロジェクトは MIT License の下で配布されています。詳細は LICENSE を参照してください。

帰属と連絡先

作者: John Southerland (GitHub: jbsouthe)
プロジェクト: http-breakout-proxy — HTTP の動作のデバッグ、開発、学習を目的としています。