自分の API をテストする¶

Mayhem がどのように API テストに役立つのかを確認しました。今度は、自分の API をテストしましょう。

API のテストを開始するには、次の 2 つを指定するだけです。

API を記述する仕様
API に到達可能な URL

たとえば、次のようなコマンドを実行します。

mapi run my-api 30 <specification> --url <url>

API 仕様¶

Info

仕様はローカルファイルまたは URL として mapi に渡すことができます。

Mayhem は OpenAPI 3 仕様を中心として構築されています。API を記述した OpenAPI 仕様がすでに存在する場合、準備は完了です。URL またはファイルシステムパスを <specification> 引数として直接 mapi に渡します。

OpenAPI 仕様がない場合、下記のとおり、いくつかの選択肢があります。

OpenAPI 2.x ("Swagger" と呼ばれることもあります)¶

mapi run は自動的に古い OpenAPI/Swagger 仕様を検出し、処理します。

別の方法として、mapi convert swagger2 コマンドを使用して古い仕様を実行することで、OpenAPI 3 への 1 回限りの変換を行うこともできます (詳細については mapi help convert swagger2 を参照してください)。

Postman¶

Mayhem は Postman Collection をサポートしています。詳細についてはこちらの「Postman Collection のサポート」を参照してください。

HAR¶

上記のどれも存在しない場合、Mayhem が使用できる仕様を生成するため、多少の作業を行う必要があります。手順についてはこちらの詳細ドキュメントを参照してください。

API URL¶

Mayhem は API サーバーの URL を認識している必要があります。リクエストはローカルで実行されている mapi CLI ツールから直接送信されるため、以下の API をテストできます。

企業のファイアウォールの背後にある API
ローカルホスト上の API
プライベートなネットワーク内の API
パブリックなインターネット上の API

CLI を実行している CLI が API にアクセスできれば、ファジングが可能です。

近接性と遅延時間¶

Mayhem は任意の構成で動作しますが、(ネットワーク用語で) API サーバーに「近い」ほど良好に動作します。最善の結果を得るには、ローカルで実行されているサーバーインスタンスをファザーに指定します。

絶対に運用環境では実行しない¶

Mayhem の仕事はただ 1 つ、API を壊す方法を発見することです。絶対に、運用環境のサービスの URL をテスト対象として Mayhem に指定してはいけません。

ローカルに結果を保存する¶

Enterprise プランを利用している場合、mapi run の呼び出しで --local フラグを指定することで、「ローカル」モードで mapi CLI を実行できます。通常どおりにターゲット API がファジングされますが、いくつか注意点があります。

ローカルモードで Mayhem API テストを実行する場合の必要事項¶

mapi CLI を実行する組織メンバーのアクティブな Enterprise プラン

ローカルなランで Mayhem サーバーにアップロードされるもの¶

匿名化されたコントリビューターシート数
API ターゲットのプレースホルダー (一致するターゲットが存在しない場合)

ローカルなランで Mayhem サーバーにアップロードされないもの¶

ジョブの詳細 (遅延時間、カバーされたエンドポイント)
問題 (送信リクエスト、受信レスポンス)
変換対象の仕様 (つまり、HAR ファイルは自動的にアップロードされず、仕様に変換されません)
OWASP ZAP API Scan ルールなど、サードパーティとの統合によるカスタム問題ルール

ローカルなランの結果を取得する方法¶

mapi CLI によってサポートされるレポートフォーマットは、Web UI レポート以外は問題のレポートに関する章で説明されているとおりに動作します。結果が Mayhem API テストサービスにアップロードされないため、Web UI レポートは動作しません。

ローカルなランの結果を永続的に保存するのは呼び出し側の責任です。

変換用ファイル (swagger2 → openapi なし)¶

ご自分の API をテストするよう Mayhem を構成できたでしょうか?