charles-proxy-extract

Charles Proxy セッション抽出ツール

Charles Proxy のセッションファイル（.chlsj 形式）から、構造化データを解析して抽出します。

前提条件

• Python 3.x（外部依存関係は不要です）
• .chlsj 形式の Charles Proxy セッションファイル

このスキルを使用する場面

ユーザーが次のような場合に、このスキルを使用します。

• 「Charles Proxy」または「Charles session」と言及する
• .chlsj ファイルの「抽出」「分析」「調査」を依頼する
• エンドポイントまたはメソッドで HTTP/HTTPS リクエストを絞り込みたい
• プロキシログから API リクエスト／レスポンスデータを調べたい
• ネットワークトラフィックデータを JSON にエクスポートしたい

このスキルの実行方法

ユーザーから Charles Proxy セッションファイルの抽出、分析、調査を依頼された場合は、Bash ツールを使って Python スクリプトを実行します。

python3 ./extract_responses.py <file.chlsj> <pattern> [options]

必須パラメーター

1. <file.chlsj> - Charles Proxy セッションファイルへのパス（ユーザーが指定した正確なパスを使用します）
2. <pattern> - 一致させる URL パスパターン（例："/today"、"/logs"、すべてに一致させる場合は"/"）

オプションフラグ

• -m, --method METHOD - HTTP メソッド（GET、POST、PUT、PATCH、DELETE）で絞り込みます
• -f, --first-only - 一致する最初のリクエストのみを表示します（簡易調査用）
• -s, --summary-only - レスポンス本文を表示せず、統計情報を表示します
• -o, --output FILE - レスポンスを JSON ファイルに保存します
• --no-pretty - JSON の整形表示を無効にします

実行例

/today の全レスポンスを抽出：

python3 ./extract_responses.py session.chlsj "/today"

POST メソッドで絞り込み（リクエスト本文も自動的に表示）：

python3 ./extract_responses.py session.chlsj "/logs" --method POST

簡易確認（最初の結果のみ）：

python3 ./extract_responses.py session.chlsj "/users" --first-only

本文を含めずに要約：

python3 ./extract_responses.py session.chlsj "/" --summary-only

ファイルにエクスポート：

python3 ./extract_responses.py session.chlsj "/items" --output items_data.json

ユーザーの依頼パターン

ユーザーが次のように依頼した場合：

• 「[file] から [endpoint] を抽出」→ パターンマッチングを使用した基本的な抽出を行います
• 「[endpoint] への POST/PUT/PATCH を表示」→ --method フラグを追加します（リクエスト本文は自動的に表示されます）
• 「[endpoint] の最初のレスポンス」→ --first-only フラグを追加します
• 「[file] を要約」または「[file] には何が含まれていますか」→ --summary-only フラグを追加します
• 「[endpoint] を [output] に保存」→ --output フラグを追加します
• 「[endpoint] をモデルと比較」→ 最初のレスポンスを抽出し、構造を分析します

重要な注意事項

• パターンマッチングでは、大文字と小文字を区別して部分文字列を照合します
• メソッドの絞り込みでは、大文字と小文字を区別しません
• メソッドの絞り込みを適用すると、POST/PUT/PATCH メソッドのリクエスト本文が自動的に表示されます
• すべてのリクエストに一致させるには、パターンとして "/" を使用します

このスキルでできること

Charles Proxy セッションファイルから HTTP/HTTPS リクエストとレスポンスのデータを抽出し、次のことができます。

• URL パターン（部分文字列の照合）でリクエストを絞り込む
• HTTP メソッド（GET、POST、PUT、PATCH、DELETE）でリクエストを絞り込む
• 変更操作（POST/PUT/PATCH）のリクエスト本文を表示する
• 抽出したデータを JSON ファイルにエクスポートする
• 統計情報を含むトラフィックの概要を生成する
• JSON レスポンス本文を整形して表示する

入力要件

必須：

• Charles Proxy セッションファイルへのパス（.chlsj 形式）
• 一致させる URL パターン（すべてのリクエストに一致させるには "/" を使用します）

任意：

• HTTP メソッドの絞り込み（GET、POST、PUT、PATCH、DELETE）
• 出力モード（full、first-only、summary-only）
• JSON エクスポート先のファイルパス
• JSON 整形表示の切り替え

出力形式

要約モード：

• パターン一致の統計情報
• リクエスト数別にグループ化したパス
• メソッドとステータスコードの分布

フルモード：

• リクエストの詳細（メソッド、パス、ステータス、タイムスタンプ）
• リクエスト本文（メソッドの絞り込みを適用した場合の POST/PUT/PATCH）
• レスポンス本文（JSON 解析済みまたはプレーンテキスト）
• デフォルトで JSON を整形して表示

エクスポートモード：

• 次の構造の JSON ファイル：

  {
    "pattern": "/api/endpoint",
    "total_requests": 10,
    "extracted_at": "ISO8601 timestamp",
    "requests": [...]
  }
  

よくある使用シナリオ

「session.chlsj から /today の全レスポンスを抽出」 → /today パターンに一致するすべてのリクエストを表示します

「/logs への POST リクエストを本文付きで表示」 → POST メソッドで絞り込み、リクエスト本文を表示します

「/items の全レスポンスを items.json にエクスポート」 → 絞り込んだレスポンスを JSON ファイルに保存します

「Charles セッション内のリクエストを要約」 → レスポンス本文を表示せずに統計情報を表示します

制限事項

• Charles Proxy の JSON セッション形式（.chlsj）のみをサポートしています
• パターンマッチングでは、大文字と小文字を区別して部分文字列を照合します
• メソッドによるフィルタリングでは、大文字と小文字を区別しません
• 大きなレスポンスボディは表示時に切り詰められる場合があります（エクスポートには影響しません）
• 標準ライブラリのみを使用する Python 3.x が必要です（外部依存関係はありません）

エラー処理

このスキルでは、次のケースに対応します。

• ファイルが見つからない、またはアクセスできない場合（明確なエラーメッセージを表示）
• セッションファイル内の JSON が無効な場合（デコードエラーの詳細を表示）
• 結果が空の場合（状況を伝えるメッセージを表示）
• リクエスト／レスポンスの構造が不正な場合（可能な範囲で処理を継続）

トラブルシューティング

「File not found」エラー：

• .chlsj ファイルのパスが正しいことを確認してください
• 絶対パスを使用するか、ファイルが現在のディレクトリにあることを確認してください

「Invalid JSON」エラー：

• ファイルが有効な Charles Proxy セッションエクスポートであることを確認してください
• Charles Proxy からセッションを再エクスポートしてください

結果が見つからない場合：

• パターンマッチングでは大文字と小文字が区別されます。大文字・小文字の使い方を確認してください
• まず「/」を使用して、すべてのリクエストに一致させてみてください
• --summary-only を使用して、セッションファイルにエンドポイントが存在することを確認してください

Python が見つからない場合：

• Python 3.x がインストールされ、PATH から利用できることを確認してください
• python3 の代わりに python を使用するか、その逆を試してください