mitmproxy2swagger

https://user-images.githubusercontent.com/5400940/168086818-c48f60ab-3f95-42eb-b435-c8b1a6326b81.mp4

mitmproxy のキャプチャを OpenAPI 3.0 仕様に自動変換するツールです。つまり、アプリを実行してトラフィックをキャプチャするだけで、REST API を自動的にリバースエンジニアリングできます。

🆕 新着！

ブラウザ DevTools からエクスポートされた HAR の処理をサポートしました。詳細は 使用方法 - HAR を参照してください。

インストール

最初に python3 と pip3 が必要です。

$ pip install mitmproxy2swagger
# ... または ...
$ pip3 install mitmproxy2swagger
# ... または ...
$ git clone [email protected]:alufers/mitmproxy2swagger.git
$ cd mitmproxy2swagger
$ docker build -t mitmproxy2swagger .

次にリポジトリをクローンし、以下の例に従って mitmproxy2swagger を実行します。

使用方法

Mitmproxy

HTTP トラフィックを検査して仕様を作成するには、以下を行う必要があります。

1. mitmproxy ツールを使用してトラフィックをキャプチャします。個人的には、mitmproxy に組み込まれている Web インターフェースである mitmweb を使用することをお勧めします。

   root@kitploit:~

   $ mitmweb
   Web server listening at http://127.0.0.1:8081/
   Proxy server listening at http://*:9999
   ...
   

   重要

   クライアントが mitmproxy のプロキシを使用するように設定する方法については、mitmproxy ドキュメント を参照してください。

2. トラフィックをフローファイルに保存します。

   mitmweb では、「File」メニューの「Save」オプションから保存できます。

   

3. mitmproxy2swagger の最初のパスを実行します。

   root@kitploit:~

   $ mitmproxy2swagger -i <mitmproxy_flow_へのパス> -o <出力スキーマへのパス> -p <APIプレフィックス>
   # ... または ...
   $ docker run -it -v $PWD:/app mitmproxy2swagger mitmproxy2swagger -i <mitmproxy_flow_へのパス> -o <出力スキーマへのパス> -p <APIプレフィックス>
   

   既存のスキーマを使用することもできます。その場合、既存のスキーマに新しいデータが追加されます。異なるフローキャプチャで数回実行しても、キャプチャデータは安全にマージされます。

   <APIプレフィックス> は、リバースエンジニアリングしたい API のベース URL です。mitmproxy で送信されるリクエストを観察して取得する必要があります。

   例えば、アプリが次のようなリクエストを行った場合:

   root@kitploit:~

   https://api.example.com/v1/login
   https://api.example.com/v1/users/2
   https://api.example.com/v1/users/2/profile
   

   プレフィックスはおそらく https://api.example.com/v1 になります。

4. 最初のパスを実行すると、スキーマファイルに次のようなセクションが作成されているはずです。

   root@kitploit:~

HAR

1. ブラウザ DevTools からトラフィックをキャプチャしてエクスポートします。

   ブラウザ DevTools の Network タブで、「Export HAR」ボタンをクリックします。

   

2. その後は mitmproxy ダンプの場合と同様に進めます。mitmproxy2swagger は自動的に HAR ファイルを検出して処理します。

出力例

examples を参照してください。生成されたスキーマと、(redoc-cli による) 生成されたドキュメントの HTML ファイルがあります。

生成された HTML ファイル もご覧ください。

開発と貢献

このプロジェクトでは以下を使用しています:

• 依存関係管理: uv
• コードフォーマットとリンティング: prek
• 単体テスト: pytest

依存関係をインストールするには:

uv sync

リンターを実行するには:

uv run prek run --all-files

prek フックをインストールするには:

uv run prek install

テストを実行するには:

uv run pytest

カバレッジ付きでテストを実行するには:

uv run pytest --cov=mitmproxy2swagger

ライセンス

MIT