スキーマ検証
The API schema defines which API requests are valid based on several request properties like target endpoint, path or query variable format, and HTTP method.
スキーマ検証を使用すると、受信トラフィックが以前に提供されたAPIスキーマに準拠しているかどうかを確認できます。APIスキーマを提供するか、学習したスキーマのリストから選択すると、API Shieldはスキーマ定義から受信トラフィックのルールを作成します。これらのルールは、どのトラフィックが許可され、どのトラフィックがログに記録されるか、またはブロックされるかを定義します。
Cloudflareは最近、スキーマ検証2.0を発表しました。ダッシュボードを使用して1つ以上のホストの以前のバージョンのスキーマ検証を構成する方法については、Configure Classic Schema Validationを参照してください。Classic Schema Validationの設定を変更することはできますが、新しいスキーマを追加することはできません。
スキーマを新しいシステムにアップロードすることで手動でスキーマ検証2.0に移行することができます。または、将来のリリースを待って、スキーマごとに簡単に移行するオプションを追加します。
エンドポイントは、スキーマ検証を保護するためにEndpoint Managementに追加する必要があります。Cloudflareダッシュボードを介してスキーマをアップロードすると、エンドポイントが自動的に追加されます。または、API Discoveryから手動で追加することもできます。
APIまたはTerraformを介してスキーマをアップロードする場合は、スキーマを解析し、エンドポイントを手動で追加する必要があります。
The API endpoint is the location where API calls or requests are fulfilled. API Shield defines endpoints as a host, method, and path tuple.
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validationに移動し、Add validationを選択します。
- アップロードするスキーマファイルを選択します。
- リストされたエンドポイント、そのホスト、メソッド、パスを確認します。新しいエンドポイントは自動的にEndpoint Managementに追加されます。
- エンドポイントへの非準拠リクエストのアクションを選択します。
- Add schema and endpointsを選択します。
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validationに移動し、利用可能な学習したスキーマでフィルタリングします。
- Apply learned schemaを選択します。
- アクションを選択し、Apply schemaを選択します。
現在、学習したスキーマは顧客がアップロードしたスキーマを上書きすることはありません。エンドポイントが顧客がアップロードしたスキーマでカバーされていて、かつ学習したスキーマにも表示される場合、ChangesフィールドはUnaffectedに設定されます。
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validationに移動し、Add Validationを選択します。
- Apply learned schemaを選択します。
- ホスト名を選択し、学習したスキーマによって保護されるエンドポイントを確認します。
- (オプション) リクエストがスキーマに一致しない場合のアクションを変更します。
- Apply schemaを選択します。
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validationに移動し、スキーマリストからスキーマを選択します。
- 現在のページに表示されているエンドポイントを選択するためにマルチセレクトボックスをチェックします。
- Select all endpointsを選択します。
- Change Actionを選択します。
- ドロップダウンメニューからアクションを選択します。
- Set actionを選択します。
スキーマ検証のデフォルトアクションは、メインのスキーマ検証ページに表示されます。このアクションは、アクションがDefaultに設定されている任意のエンドポイントに適用されます。
Logアクション: Firewall Eventsにイベントをログします。Blockアクション: スキーマに失敗したエンドポイントのリクエストをブロックし、Firewall Eventsにイベントをログします。Noneアクション: 非準拠のリクエストはログにもブロックにもされません。
デフォルトアクションを変更するには：
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldに移動します。
- Schema Validationを選択します。
- デフォルトの
Logアクションの下で、Changeを選択します。 - ドロップダウンメニューから新しいアクションを選択します。
- 現在のアクションを確認し、ポップアップウィンドウでChange default actionを選択して変更を受け入れます。
または、Security > API Shield > Settingsを介してグローバルアクションを変更することもできます。
スキーマ検証のデフォルトアクションとは別に、個々のエンドポイントのアクションを変更できます。
これにより、デフォルトアクションがLogの場合に特定のエンドポイントで非準拠リクエストをブロックする際に厳格にすることができます。また、デフォルトアクションがBlockに設定されている場合に特定のエンドポイントで非準拠リクエストの制約を緩和するためにも使用できます。既知の偽陽性をエンドポイントで無視するために、アクションをNoneに設定することもできます。
個々のエンドポイントのアクションを変更するには：
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validationを選択し、選択したエンドポイントでフィルタリングします。
- エンドポイントの行の省略記号を選択します。
- Change Actionを選択します。
- ドロップダウンメニューから新しいアクションを選択し、Set actionを選択します。
一時的なトラブルシューティングのためにスキーマ検証を完全に無効にすることができます。すべてのアクションを一度にオーバーライドし、トラブルシューティングを完了するまでスキーマ検証が何のアクションも取らないようにします。
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validation設定に移動します。
- Disableを選択します。
エンドポイントごとの設定は変更時に保存されるため、設定を失うことはありません。トラブルシューティング後に設定を再有効化するには、設定に戻り、Enableを選択します。
現在アップロードまたは学習したスキーマを表示するには：
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validation設定に移動します。
- Uploaded SchemasおよびLearned schemasの下でスキーマを表示します。
- いずれかのスキーマのエンドポイントでFilterを選択します。
スキーマを削除すると、現在関連付けられているエンドポイントから検証が削除されますが、エンドポイントはEndpoint Managementから削除されません。
現在アップロードまたは学習したスキーマを削除するには：
- Cloudflareダッシュボード ↗にログインし、アカウントとドメインを選択します。
- Security > API Shieldを選択します。
- Schema Validation設定に移動します。
- Uploaded SchemasおよびLearned schemasの下でスキーマを表示します。
- メニューにアクセスするために省略記号を選択し、リストされたスキーマをダウンロードまたは削除します。
Cloudflareは現在、OpenAPI v3スキーマ ↗のみを受け入れています。受け入れられるファイル形式はYAML（.ymlまたは.yamlファイル拡張子）とJSON（.jsonファイル拡張子）です。
異なるツールによって生成されたOpenAPIスキーマは、スキーマ検証にインポートするには特定すぎない場合があります。スキーマがOpenAPI仕様に準拠していることを確認するために、Swagger Editor ↗などのサードパーティツールの使用をお勧めします。
現在、API ShieldはAPIスキーマのいくつかの機能を検証できません。これには、すべてのレスポンス、外部参照、非基本的なパステンプレート、またはユニークアイテムが含まれます。
有効なスキーマには10,000の操作の制限があります。
API Shieldは、アップロードされたスキーマに含まれるボディ仕様を特定し、受信APIリクエストのデータがそれに準拠しているかどうかを検証する能力があります。
スキーマ検証は現在、application/jsonのコンテンツタイプを持つリクエストの検証をサポートしています。
OpenAPI仕様内では、リクエストボディスキーマはメディアレンジ（application/*、application/xml、またはapplication/jsonなど）に関連付けられています。
Cloudflareが受信リクエストを検証する際、リクエストのcontent-typeがOpenAPIで指定されたメディアレンジと一致するかどうかを確認します。
たとえば、OpenAPIファイルがリクエストボディコンテンツマップの一部としてapplication/*を指定している場合、Cloudflareはapplication/xmlおよびapplication/jsonのコンテンツタイプを持つリクエストを受け入れます。ただし、提供されたスキーマで検証されるのはapplication/jsonボディのみです。
Cloudflareは、メディアレンジをできるだけ厳密に保つことを一般的に推奨しています。個々のメディアタイプに設定することをお勧めします。APIエンドポイントで複数のコンテンツタイプをサポートする必要がある場合は、ワイルドカードメディアレンジを利用できます。
オリジンがMIMEスニッフィング ↗を実行するように構成されている場合は、注意が必要です。たとえば、JSONボディを持つリクエストが意図的にapplication/malicousコンテンツタイプを持っており、Cloudflareがapplication/*メディアレンジを許可するように構成されている場合、リクエストはJSONボディの内容を検証せずにオリジンに渡されます。ただし、コンテンツタイプを無視し、試行的にデシリアライズまたはMIMEタイプをスニフするオリジンは、スキーマボディ検証を通過したという誤った仮定でJSONボディをデシリアライズする可能性があります。
そのため、application/jsonとapplication/xmlを同じエンドポイントでサポートする必要がある場合は、application/*を使用できます。Cloudflareは、コンテンツタイプがapplication/jsonに設定されているリクエストボディに対して提供されたスキーマを検証します。コンテンツタイプがapplication/xml（およびapplication/*に一致する他のもの）のリクエストは通過します。オリジンでのコンテンツタイプスニッフィングを無効にすることを強くお勧めします。
Cloudflareは、OpenAPIリクエストボディコンテンツマップで次のメディアレンジを指定することを許可します：
*/*application/*application/json。
メディアレンジは、charsetパラメータを強制するように構成することもできます。この場合、Cloudflareは、メディアレンジ仕様の一部として静的値utf-8を持つcharsetパラメータのみを受け入れ、構成された場合、リクエストのコンテンツタイプにもこのcharsetを持つことを要求します。
スキーマ検証は、すべてのAPI Shield顧客に利用可能です。
API Shieldを購入していないエンタープライズ顧客は、CloudflareダッシュボードでAPI Shield as a non-contract service ↗をプレビューするか、アカウントチームに連絡することができます。