レスポンス分類プラグイン¶

Mayhem はプラグインによるレスポンス分類をサポートしています。プラグインは、 protobuf インターフェイスを実装し、gRPC を通じて公開されるスタンドアロンプログラムです。

インターフェイスの詳細は下記のとおりです。その前に、以下を説明します。

この機能が必要な場合¶

Mayhem はできるだけ多くのユースケースにそのまま利用できるよう設計されており、これからも機能の追加が続けられます。プラグインは、API に現時点の Mayhem がそのままでは対応できない要件がある場合のいわば緊急避難の手段として用意されています。

以下は、機能を開発する際に想定されたケースの例です。

機密データの漏洩¶

入力にかかわらず API 出力に特定のキー、値、パターンが現れないことを検証したい場合、現時点では、Mayhem には直接的な解決策がありません。

レスポンス分類プラグインは、このような検証を行うことができます。

非標準レスポンスコードの検証¶

Mayhem が従うルールは、各エンドポイントのレスポンスコードが標準に基づいた既製のコードであることを前提としています。400 エラーを返してはならないという制約を持つエンドポイントなど、特定のエンドポイントにより厳密な制約を適用したい場合があるでしょう。

レスポンス分類プラグインは、このような制約のチェックに使用できます。

その他¶

分類プラグインのインターフェイスは非常に自由度が高く、レスポンスのどのような側面でもチェックできます。

何らかの理由で分類プラグインの利用を検討している場合、お問い合わせください。この機能はまだ導入されたばかりであり、ユーザーがどのように機能を利用されているか、またどのような改善が可能かを知りたいと考えています。

インターフェイス¶

呼び出し¶

API テストのランにレスポンス分類プラグインを追加するには、mapi run に --classify-plugin <path-to-plugin-executable> 引数を指定します。

実行可能 gRPC サーバー¶

mapi はコマンドライン引数なしで実行ファイルを実行し、実行ファイルが以下の特徴を持つ長期間実行されるプロセスであることを期待します。 * localhost のポートで gRPC トラフィックを待機する * 標準出力の先頭行としてポート番号の後に改行を出力する

この他の処理に制限はありません。プラグインからの追加の標準出力/標準エラー出力は、mapi デバッグログにフォワードされます。

テストランが終了すると、mapi はプラグインプロセスを終了しようとします。

Protobuf¶

レスポンス分類プラグインは、次の protobuf インターフェイスを実装します。

syntax = "proto3";

package mapi.classify;

service ClassifyPlugin {
   rpc Classify(Response) returns (Issues);
}

message Response {
   message Header {
      bytes name = 1;
      bytes value = 2;
   }
   string request_url = 1;
   string final_url = 2;
   uint32 status = 3;
   repeated Header headers = 4;
   bytes body = 5;
}

message Issues {
   message Issue {
      string summary = 1;
   }
   repeated Issue issues = 1;
}

サンプル¶

次に挙げるのは、分類プラグインのサンプルです。このプラグインは、まったく何も処理せず、レスポンスをそのまま承認しているだけです。

まず、.proto からすべての gRPC および protobuf のボイラープレートを生成します。

$ pip install grpcio-tools
$ python -m grpc_tools.protoc --python_out=. --grpc_python_out=. -I. response-classify-plugin.proto

次に、ClassifyPluginServicer を実装する Python プログラムを作成し、 gRPC サーバーを立ち上げ、mapi に待機するポートを指示します。

#!/usr/bin/env python

import sys
from concurrent import futures
import grpc
import response_classify_plugin_pb2
import response_classify_plugin_pb2_grpc

## implement the ClassifyPlugin interface
class ClassifyPluginServicer(response_classify_plugin_pb2_grpc.ClassifyPluginServicer):
    def Classify(self, response, context):
        issues = response_classify_plugin_pb2.Issues()
        if something_went_wrong():
            issue = response_classify_plugin_pb2.Issues.Issue()
            issue.summary = "something went wrong!"
            issues.issues.append(issue)
        return issues

if __name__ == '__main__':
    ## boot up the gRPC server
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    response_classify_plugin_pb2_grpc.add_ClassifyPluginServicer_to_server(
        ClassifyPluginServicer(), server)
    server.add_insecure_port('127.0.0.1:50051')
    server.start()

    ## inform mapi of the port we're listening on
    print("50051")
    sys.stdout.flush()

    server.wait_for_termination()

.py ファイルが実行可能であることを確認したら、--classify-plugin を使用して mapi に渡します。これで完了です。

注意事項¶

文字列ではなくバイト¶

API レスポンスは、常に文字列として表現可能とはかぎりません。注意してください。

変更の可能性¶

この機能は流動的であり、変更される可能性があります。この機能を利用する場合は、改良や変更を検討する際にお知らせできるよう、当社までご連絡ください。