API Shield

解決する課題

Webアプリケーションと異なり、APIは機械同士の通信が前提のため、想定外のパラメータや型、異常に大量のリクエストが送られても気づきにくいという特性があります。API Shieldは、こうしたAPI特有のリスクをエッジ側でまとめて低減するための機能群です。

• 定義したスキーマに存在しないパラメータや不正な型のリクエストを、アプリ改修なしにエッジで遮断したい
• APIキーやBasic認証よりも強固な相互TLS（mTLS）クライアント証明書でAPI呼び出し元を認証したい
• 開発者が把握していないシャドーAPI（ドキュメント化されていないエンドポイント）を発見し、棚卸ししたい
• 特定のAPIエンドポイントに対する異常な呼び出し頻度やスクレイピングを検知・抑制したい
• JWTのようなトークンベース認証を、アプリ側の実装を待たずにエッジで検証したい

主要概念と用語

• スキーマ検証（Schema Validation）: アップロードしたOpenAPIスキーマに基づき、リクエストのパス・メソッド・パラメータ・型がスキーマに適合するかをエッジで検証する機能
• エンドポイント管理（Endpoint Management）: トラフィックから実際に呼ばれているAPIエンドポイントを自動検出し、ドキュメント化されていない未管理のエンドポイント（シャドーAPI）を洗い出す仕組み
• mTLS（相互TLS）クライアント証明書認証: サーバー証明書だけでなくクライアント側の証明書もエッジで検証し、正当なクライアントのみ接続を許可する認証方式
• JWT検証（JWT Validation）: リクエストに含まれるJSON Web Tokenの署名や有効期限をエッジ側で検証し、不正・期限切れトークンを弾く機能
• 異常検知（Volumetric Abuse Detection）: 個々のエンドポイントへのリクエスト量やパターンを分析し、通常と異なる急増や機械的な呼び出しを検知する仕組み
• セッション識別子（Session Identifiers）: Cookieやヘッダーなどからセッションを識別し、エンドポイントごとの利用状況をセッション単位で分析する仕組み

仕様・制限・クォータ

• 対象はゾーンに属するHTTP/HTTPSのAPIトラフィックで、スキーマ検証はアップロードしたOpenAPI定義（バリデーション対象のフォーマット）に基づいて動作する
• スキーマ検証は**Log（検知のみ）とBlock（遮断）**のモードを持ち、まずログ収集で誤検知の有無を確認してから遮断へ移行する運用が前提
• 提供される機能のうち、エンドポイント自動検出や異常検知など一部は上位プランでのみ利用可能で、プランによって使える範囲が異なる
• 登録できるスキーマの数やスキーマファイルのサイズ、mTLS証明書の発行数などにはサービス上限があり、上限は契約プランに依存する
• mTLSを使う場合、クライアント証明書の発行・失効管理はCloudflareの証明書機能と連携して行う

内部の仕組み

API Shieldは、Cloudflareのエッジネットワーク上でリクエストがオリジンへ転送される前に評価されます。まずエンドポイント管理機能がトラフィックを継続的に観測し、実際に呼ばれているパスとメソッドの組を学習してエンドポイント一覧を構築します。これにより、開発者が想定していなかった未文書化のエンドポイントも可視化されます。

スキーマ検証を有効にすると、アップロードされたOpenAPIスキーマとリクエストのパス・メソッド・パラメータ・ボディの型が突き合わされます。スキーマに定義がないパラメータや、型が一致しないリクエストはルールに一致したものとして扱われ、設定したアクション（ログ記録または遮断）が適用されます。mTLSを有効にした場合は、TLSハンドシェイクの段階でクライアント証明書の有効性がエッジで検証され、正当な証明書を持つクライアントのみが接続を継続できます。JWT検証を有効にした場合も同様に、トークンの署名・有効期限がエッジで検証されてからオリジンへ転送されます。

異常検知機能は、エンドポイントごとのリクエスト量やパターンを継続的に分析し、通常のトラフィックから逸脱した急増や機械的なアクセスパターンをスコアリングして可視化します。これらの評価はすべてログとして記録され、ダッシュボードで検知・遮断の状況を確認できます。

設計パターン / ベストプラクティス

• スキーマは自動生成し継続更新する: エンドポイント管理機能で検出した実トラフィックからスキーマのたたき台を作り、API変更に追随して更新し続ける
• Log運用で慣らしてからBlockへ: 新規スキーマや新ルールは検知モードで様子を見て、誤検知を洗い出してから遮断に切り替える
• 重要なAPIほど強い認証を重ねる: 決済・個人情報系のエンドポイントにはmTLSやJWT検証を組み合わせ、認証を多層化する
• シャドーAPIの棚卸しを定期実施する: エンドポイント自動検出で意図しない公開エンドポイントがないか定期的に確認する
• 異常検知としきい値ベースのレート制限を併用する: 異常検知で傾向を把握しつつ、明確なしきい値超過は別のレート制限ルールで機械的に抑止する
• オリジンへの直接到達を遮断する: API Shieldを経由しない直接アクセス経路が残っていると、エッジでの検証をすべて迂回されてしまう

運用・監視

• スキーマ検証・mTLS・JWT検証の判定結果はダッシュボードのログで確認し、遮断傾向や誤検知の有無を継続的にレビューする
• エンドポイント管理画面で新規出現したエンドポイントを定期的に確認し、意図しない公開がないかチェックする
• 異常検知のアラートを受けたエンドポイントは、正規のトラフィック急増か不正利用かを切り分けて対応する
• スキーマ更新やルール変更は、適用前後でブロック率・エラー率を比較し、リグレッションがないか確認してから本番展開する
• 証明書の失効・更新やJWTの署名鍵ローテーションなど、認証系の運用サイクルもあわせて管理する

コスト

具体的な料金体系やプランごとの機能差は変動するため、最新の料金ページで確認してください。保護対象のAPIエンドポイント数とトラフィック量、利用する機能（スキーマ検証・mTLS・異常検知など）の組み合わせが主なコストドライバになります。

セキュリティ

• 未定義入力の排除: スキーマ検証により、アプリが想定していないパラメータや型のリクエストを入口で遮断し、攻撃面を狭める
• 強固なクライアント認証: mTLSクライアント証明書により、APIキーの漏えいだけでは突破できない認証層を追加できる
• トークンの正当性検証: JWT検証をエッジで行うことで、改ざんされたトークンや期限切れトークンをオリジンに到達する前に弾ける
• 可視性の確保: エンドポイント自動検出により、開発チームが把握していない公開APIを発見し、意図しない情報露出を防げる
• 多層防御の一部として運用: API Shield単体に依存せず、WAFのマネージドルールやレート制限、アクセス制御と組み合わせて全体の防御を構成する

関連サービス・比較

同じCloudflareのWAF機能のうち、汎用的なマネージドルールでOWASP系の攻撃を防ぐWAFと、API仕様に特化して検証するAPI Shieldは役割が異なります。両者は併用して多層防御を構成するのが一般的です。

ハンズオン / CLI例

# wrangler でCloudflareアカウントにログイン（API Shieldの操作はAPI経由が中心）
wrangler login

# OpenAPIスキーマをアップロードしてスキーマ検証用に登録する例
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/api_gateway/user_schemas" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@openapi-schema.json" \
  -F "name=my-api-schema" \
  -F "kind=openapi_v3" \
  -F "validation_enabled=true"

# 登録済みのAPIエンドポイント一覧（自動検出結果を含む）を確認
curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/api_gateway/discovery/operations" \
  -H "Authorization: Bearer API_TOKEN"

# スキーマ検証の動作モードをLog（検知のみ）からBlockへ切り替える例
curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/api_gateway/settings/schema_validation" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"validation_default_mode": "block"}'