コンテンツにスキップ

API仕様施行設定

本記事では、アップロードしたAPI仕様に基づいてAPI保護を有効化し、構成する方法について解説します。

ステップ1：仕様のアップロード

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

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

    仕様のアップロード

仕様ファイルが正常にアップロードされるまで、API仕様施行の構成を開始できないのでご注意ください。

ステップ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機能を無効化する必要がある場合、以下の方法で実施できます:

  • all-in-one installer展開の場合、serverセクションでNGINXディレクティブwallarm_enable_apifwをoffに設定することにより無効化できます.

  • NGINXベースのDockerイメージの場合、environment variable WALLARM_APIFW_ENABLEをfalseに設定することにより無効化できます.

  • NGINX Ingress Controllerの場合、controller.wallarm.apifirewallの値グループにおいてenableをfalseに設定することにより無効化できます.