コンテンツにスキップ

API Specification Enforcementのセットアップ

この記事では、アップロード済みのAPI仕様に基づいてAPI保護を有効化および構成する方法を説明します。

手順1: 仕様のアップロード

  1. US CloudまたはEU CloudのAPI Specificationsセクションで、Upload specificationをクリックします。

  2. 仕様のアップロードパラメータを設定し、アップロードを開始します。

    仕様のアップロード

仕様ファイルはAPI仕様の構文に準拠しているかを検証し、無効な場合はアップロードされません。仕様ファイルが正常にアップロードされるまで、API Specification Enforcementの設定は開始できませんのでご注意ください。

アップロード元としてURIを選び、Regularly update the specification（毎時）オプションを選択した場合、定期更新時にエラーが発生することがあります。例えば、URIが利用できない、または更新された仕様ファイルがAPI仕様の構文に準拠していないなどです。これらのエラーの通知を受け取るには、設定済みのIntegrationsでSystem relatedイベントを選択してください。このカテゴリには仕様のアップロードエラーに関する通知が含まれます。

手順2: ポリシー違反時のアクションを設定する

  1. API specification enforcementタブをクリックします。

    ローグAPIの検出

    • セキュリティポリシーの適用に加えて、仕様はAPI DiscoveryモジュールによるローグAPIの検出にも使用できます。API Discoveryが有効化されている場合、このタブが表示されます。
    • セキュリティポリシーの適用に仕様を使用する前に、API Discoveryを使ってローグ（シャドウ、ゾンビ、オーファン）APIの探索に使用することを推奨します。そうすることで、仕様が実際のクライアントからのリクエストとどの程度乖離しているかを把握できます。これらの相違は、セキュリティポリシー適用後に関連リクエストのブロックを引き起こす可能性が高いです。

  2. Use for API specification enforcementを選択します。

  3. ポリシー違反時のアクションを有効化したい対象のホストまたはエンドポイントを指定します。

    • アップロードした仕様の適用先エンドポイントを誤って指定すると、多数の誤検知イベントが発生する点に注意してください。
    • 同一ホストに対し、異なるエンドポイント（例：domain.com/v1/api/users/とdomain.com/v1/api/orders/）に適用される仕様が複数ある場合は、各仕様を適用するエンドポイントを必ず明示してください。
    • ホストに対して仕様を追加し、その後同一ホストの特定エンドポイントに別の仕様を追加した場合、両方の仕様がこれらのエンドポイントに適用されます。
    • この値はURI constructorまたはadvanced edit formから設定できます。

  4. リクエストが仕様に違反した場合のシステムの反応を設定します。

    仕様 - セキュリティポリシー適用への利用

    想定される違反の詳細:

    • Requesting an undefined endpoint - a request targets the endpoint not presented in your specification
    • Requesting endpoint with undefined parameter - a request contains the parameter not presented for this endpoint in your specification
    • Requesting endpoint without required parameter - a request does not contain the parameter or its value that are marked as required in your specification
    • Requesting endpoint with invalid parameter value - a request parameter's value in not in correspondence with its type/format defined by your specification
    • Requesting endpoint without authentication method - a request does not contain the information about the authentication method
    • Requesting endpoint with invalid JSON - a request contains an invalid JSON

    The system can perform the following actions in case of found inconsistency:

    • Block - block a request and put in the Attacks section as blocked

      Filtration mode

      The Wallarm node will block requests only when the blocking filtration mode is enabled for target endpoint - otherwise, Monitor action will be performed.

    • Monitor - mark a request as incorrect, but do not block, put it in the Attacks section as monitored

    • Not tracked - do nothing

    Note that several specifications can be used for setting policies. In case when one request falls on two different specifications (the same policy and different actions in different specifications), the following will happen:

    • Block and Block - the request will be blocked and two events will be added to the Attacks section with status Blocked pointing at the reason of blocking and at the fact that the request violated two different specifications.
    • Monitor and Block - the request will be blocked and one event will be added to the Attacks section with status Blocked explaining the reason of blocking.
    • Monitor and Monitor - the request will not be blocked and two events will be added to the Attacks section with status Monitoring pointing at the fact that specific policy was violated.

    仕様をセキュリティポリシーの設定に初めて使用する際は、必要なエンドポイントに仕様が適用され、実際のエラーを検出できていることを確認するため、反応としてMonitorを設定することを推奨します。

無効化

API Specification Enforcementは、アップロード済みの仕様（または、各仕様でUse for API specification enforcementオプションを選択した複数の仕様）に基づいて動作します。特定の仕様でこのオプションの選択を外す、あるいは当該仕様を削除すると、その仕様に基づく保護は停止される点にご留意ください。

また、場合によってはAPIの一部に対してのみAPI Specification Enforcementの機能を無効化する必要があることがあります。次の方法で実施できます。