API 仕様の検証
API 仕様により、API (アプリケーションプログラミングインターフェイス) によるシステム間のシームレスなデータ転送が保証されます。これにより、交換されるデータが事前に定義された構造または形式に従うことが保証されるため、システム全体の信頼性とセキュリティが向上します。
API 仕様は、エンドポイント、スキーマ、およびパラメータを定義します。スキーマ検証は、受信トラフィックが API 仕様で指定したスキーマに準拠しているかどうかを確認できるプロセスです。API 仕様を Web App Firewall プロファイルに関連付けることで、どの受信トラフィックを許可するか、どの受信トラフィックをブロックするかログに記録するかを指定できます。インポートされた API 仕様に照らして受信トラフィックを検証することで、ネットワークトラフィックが安全で準拠していることを確認できます。
ソフトウェア開発で一般的に使用されるAPIタイプはいくつかあります。これらのタイプは、異なるソフトウェアシステム間でデータがどのように構造化され、交換されるかを決定します。NetScalerは次のAPIタイプをサポートしています。
- リプレゼンテーションステートトランスファー (REST)
- グーグルリモートプロシージャコール (gRPC)
API 仕様は、エンドポイント、メソッド、パラメータ、データ形式を含む API の設計を定義します。これらの仕様により、API を開発および使用する際の一貫性、相互運用性、使いやすさが保証されます。NetScalerは次の仕様形式をサポートしています:
- オープン API (以前はスワッガーと呼ばれていました)
- プロトバフ (プロトコルバッファ)
注:GUI または CLI を使用して API 仕様ファイルをインポート、追加、更新、削除できます。詳細については、「 インポート」を参照してください。
CLI を使用して API 仕様をプロファイルに割り当てる
API 仕様ファイルを使用して Web App Firewall プロファイルを設定し、トラフィックを検証します。RestAction (REST API の場合) または grPCAction (gRPC API の場合) パラメーターを使用して、検証が失敗したときに使用されるアクションを設定できます。
コマンドプロンプトで入力します:
set appfw profile <Profile Name> -apispec <API spec entity name>
- Profile name - The name of the profile.
- API spec entity name - The name of the entity that is created from the uploaded API specification.
GUI を使用して API 仕様をプロファイルに割り当てる
- [ **セキュリティ] > [NetScaler Web App Firewall] > [プロファイル ] に移動し、[追加]**をクリックします。
- API 仕様スキーマに必要なファイルを選択し、[ OK] をクリックします。
GUI を使用して既存のプロファイルに API 仕様を割り当てる
- [ セキュリティ]> NetScaler Web App Firewall]>[プロファイル]に移動します
- ユーザー定義のプロファイルを選択し、[ 編集] をクリックします。
- NetScaler Web App Firewall プロファイルページで 、 編集アイコンをクリックします 。
- API 仕様スキーマに必要なファイルを選択し、[ OK] をクリックします。
CLI を使用して REST および gRPC API スキーマの検証を設定します
コマンドプロンプトで入力します:
set appfw profile <profile name> -restAction [block log none stats]
set appfw profile <profile name> -grpcAction [block log none stats]
<!--NeedCopy-->
GUI を使用して REST および gRPC API スキーマの検証を設定します
REST および gRPC API スキーマの検証を設定または変更するには:
- [セキュリティの設定]> [NetScaler Web App Firewall] > [プロファイル]** に移動します。
- ユーザー定義のプロファイルを選択し、[ 編集] をクリックします。
- NetScaler Web App Firewall プロファイルページの [ 詳細設定 ] セクションで、[ セキュリティチェック] をクリックします。
- セキュリティチェックセクションで 、 REST API スキーマ検証またはgRPC API スキーマ検証を選択し、アクション設定をクリックします。
- アクションページで 、 アクションパラメータを設定します。オプションは選択または選択解除できます。
- [OK] をクリックします。
注:
API スキーマ検証のセキュリティチェックを設定する前に、「開始 URL」オプションを選択解除してください。
CLI を使用して API スキーマ検証の緩和ルールを設定
Web App Firewall プロファイルにリンクされた API 仕様で指定されたスキーマに対して特定のトラフィックが検証されないようにする緩和ルールを設定します。
REST API スキーマ検証の緩和ルールを構成するには、コマンドプロンプトで次のように入力します:
bind appfw profile <profile name> -restValidation <REST relaxation pattern> -ruleAction <Log|None>
-
REST 緩和パターン-緩和が適用される URL パターン。Google API のプロトカレントリンクで説明されているように、パターンにはワイルドカード定義だけでなく変数も含めることができます。 https://github.com/googleapis/googleapis/blob/master/google/api/http.proto
指定された URL は API 仕様の一部である必要はありません。
注: パターンのプレフィックスには、HTTP メソッド (つまりGET、PUT、投稿、削除、パッチ) の後にコロン (:) が続きます。 例:
- GET: /v1/ {名前=メッセージ/*}-/v1/メッセージで始まる 3 つのセグメント URL を許可します。メソッドは GET です。
- パッチ:/v1/messages/ {message_id=**}-/v1/messages プレフィックスが付いているものなら何でも許可され、メソッドは PATCH です。
- POST: /v1/lists/** -/v1/lists というプレフィックスが付いているものはすべて許可され、メソッドは POST です。
- ://engineering/**-メソッドに関係なく、2 番目のセグメントを持つすべての URL をエンジニアリングとして許可します。
-
[ログ] または [なし]-ルールに一致するバイパストラフィックのログを生成するかどうかを指定します。アクションをログに設定すると、緩和されたURLとそれに対応するルールがシステムログにダンプされます。アクションをログに設定すると、緩和されたURLと対応するルールがシステムログに記録されます。
gRPC API スキーマ検証の緩和ルールを設定するには、コマンドプロンプトで次のように入力します:
bind appfw profile <profile name> -grpcValidation <gRPC pattern> -ruleAction <Log|None>
-
gRPC パターン-緩和が適用される gRPC エンドポイントのパターン。指定された gRPC メソッドは API 仕様の一部である必要はありません。
例:
- citrix.api.doc.AddBook-citrix.api.docパッケージ内のRPC追加ブックを許可します。
- test.api.** -test.api から始まるパッケージ内のすべてのRPCを許可します。
- *.エンジニアリング。** -パッケージ名の 2 番目のセグメントとしてエンジニアリングを含むすべての RPC を許可します。
-
ログ なし-ルールに一致するバイパストラフィックのログを生成するかどうかを指定します。
GUI を使用して API スキーマ検証の緩和ルールを設定
REST API スキーマの検証
- [ **セキュリティ] > [NetScaler Web App Firewall] **[プロファイル] に移動します。
- ユーザー定義のプロファイルを選択し、[ 編集] をクリックします。
- NetScaler Web App Firewall プロファイルページの [ 詳細設定 ] セクションで、[ 緩和ルール] をクリックします。
- REST API スキーマ検証を選択し 、 編集をクリックします。
- REST API スキーマ検証緩和ルールページで 、「 追加」をクリックします。
-
REST API スキーマ検証緩和ルールページで 、次の詳細を指定します:
- 有効-緩和ルールを有効にするオプションを選択します。
- REST URL パターン-緩和を適用する URL パターンを入力します。
- REST URL 緩和アクション-アクションを選択します。
- コメント-式の説明。
- リソース ID-リソースを識別する一意の ID。
- [作成]をクリックします。 新しく追加された REST API スキーマ検証緩和ルールは、REST API スキーマ検証緩和ルールページに一覧表示されます。
gRPC API スキーマの検証
- [ **セキュリティ] > [NetScaler Web App Firewall] **[プロファイル] に移動します。
- [ プロファイル] ページでプロファイルを選択し 、[ 編集] をクリックします。
- NetScaler Web App Firewall プロファイルページの [ 詳細設定 ] セクションで、[ 緩和ルール] をクリックします。
- gRPC API スキーマ検証を選択し 、「 編集」をクリックします。
- gRPC API スキーマ検証緩和ルールページで 、「 追加」をクリックします。
-
gRPC API スキーマ検証緩和ルールページで 、次の詳細を指定します:
- 有効-緩和ルールを有効にするオプションを選択します。
- gRPC メソッドパターン-緩和を適用する gRPC メソッドパターンを入力します
- REST URL 緩和アクション-アクションのいずれかを選択します。
- コメント-式の説明。
- リソース ID-リソースを識別する一意の ID。
- [作成]をクリックします。 新しく追加されたgRPC APIスキーマ検証緩和ルールは、gRPC APIスキーマ検証緩和ルールページにリストされています。