cloud-armor-crs-rule-upgrader

Cloud Armor OWASP ルールアップグレーダー（CRS 3.0/3.3 -> 4.22）

このスキルでは、Network Security Agent と Google Cloud の実務担当者向けに、 Google Cloud Armor セキュリティポリシーを監査、評価し、 従来の OWASP Core Rule Set（CRS）3.0 または 3.3 から OWASP CRS 4.22 に アップグレードする手順を説明します。

使用状況の帰属

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 使用状況の帰属の指示を必ず読み、従ってください。

---

前提条件と環境設定

Google Cloud Armor セキュリティポリシーを監査または変更する前に、 以下の前提条件を満たしていることを確認してください。

1. Google Cloud SDK：
   Google Cloud CLI（gcloud）を インストールまたは更新します。

2. プロジェクトの選択と有効な請求先：対象の Google Cloud プロジェクトを選択し、有効な請求先アカウントが関連付けられていることを確認します。

   gcloud config set project PROJECT_ID
   gcloud billing projects describe PROJECT_ID --format="value(billingEnabled)"
   

3. API の有効化：Compute Engine API（Cloud Armor セキュリティポリシー用）と Cloud Logging API（プレビューモードのテレメトリー用）を有効にします。

   gcloud services enable compute.googleapis.com logging.googleapis.com
   

4. 認証：

   • 対話型 CLI：gcloud auth login
   • Application Default Credentials（ADC）：gcloud auth application-default login
   • サービスアカウント：
     GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"を設定します。

5. 必要な IAM ロール：

   • roles/compute.securityAdmin：Cloud Armor セキュリティポリシーとルールの作成、更新、削除、インポートに必要です（読み取り専用のポリシー監査には roles/compute.securityViewerを使用します）。
   • roles/logging.viewer：Cloud Logging で HTTP ロードバランサーのプレビューテレメトリーを確認するために必要です。

6. スコープとリージョンでの利用可否：

   • Cloud Armor セキュリティポリシーはグローバル（グローバル外部 Application Load Balancer のデフォルト）またはリージョン（リージョン外部 Application Load Balancer 用。たとえば、--region=us-central1。gcloud config set compute/region us-central1でデフォルトのリージョンを設定します）にできます。
     リージョンでの利用可否については、Google Cloud のロケーションをご覧ください。

7. 料金とリソースのクリーンアップ：

   • Cloud Armor では、ティア（Standard または Enterprise）に応じて、セキュリティポリシーごと、ルールごと、および 100 万リクエストごとに料金が発生します。現在の料金については、 Google Cloud Armor の料金をご確認ください。
   • 削除／クリーンアップ：ポリシーのクォータを消費したり、ルールの継続的な料金が発生したりしないよう、切り替え後は一時的な--previewルール（gcloud compute security-policies rules delete PREVIEW_PRIORITY --security-policy="POLICY_NAME"）または単独のテストポリシー（gcloud compute security-policies delete TEST_POLICY_NAME）を必ず削除してください。

---

クイックスタートと CLI ヘルパー

自動的で決定論的な解析、シグネチャのマッピング、およびプレビューモードの 優先度割り当てには、同梱のスタンドアロン Python CLI を実行してください。

# In-Place Upgrade (Report Summary)
python3 scripts/upgrade_policy.py /path/to/policy.json --mode=in-place --format=report

# In-Place Upgrade (Output gcloud commands)
python3 scripts/upgrade_policy.py /path/to/policy.json --mode=in-place --format=gcloud

# Preview Mode Upgrade (Generates preview rules at priority - 5)
python3 scripts/upgrade_policy.py /path/to/policy.json --mode=preview --format=gcloud

# Direct stdin piping from gcloud describe
gcloud compute security-policies describe POLICY_NAME --format=json | \
  python3 scripts/upgrade_policy.py - --mode=preview --format=json

コマンドのワークフロー全体については、gcloud_recipes.mdをご覧ください。

ネットワークセキュリティエージェントのコアアップグレードワークフロー

重要

エージェントの必須応答動作：1. 両方のアップグレードモードを説明する：アップグレードについて説明する際は（ユーザーがプレビューモードまたはインプレースについて具体的に尋ねた場合でも）、必ず インプレースアップグレード（ルールをその場で直接置き換え、即時に適用し、追加割り当てを一切消費しない）と プレビューモード（数値の優先度がより低いルールを preview = true でデプロイし、トラフィックをブロックするリスクがなく、切り替え前に Cloud Logging でテレメトリーを確認できる）の両方を説明してください。2. ポリシー監査に関する問い合わせへの対応：ポリシー（'ecommerce-waf' など）の監査や確認を求められた際に、ポリシー JSON が提供されていない場合、または gcloud describe で Google Cloud リソースにアクセスできない場合は、直ちに gcloud compute security-policies describe POLICY_NAME --format=json コマンドを提示し、次の監査項目をユーザーに案内してください。- 古い OWASP 3.0／3.3 ルールセット（sqli-stable、xss-stable、rce-stable、methodenforcement-stable、または evaluatePreconfiguredExpr）がないか確認します。- 対象範囲内の WAF ルールと、通過させるカスタムルール（IP 許可リスト SRC_IPS_V1、レート制限、デフォルトルール priority: 2147483647 など）を報告します。- CRS 4.22 でのシグネチャ数の拡大を示します（例：RCE は 11／15 から 44 シグネチャに、SQLi は 60 シグネチャに拡大）。

Cloud Armor セキュリティポリシーをアップグレードするために顧客とやり取りする際は、次の 5 段階のワークフローを実行してください。

1. 検出と取得：対象のセキュリティポリシーを特定し、その JSON 定義を取得します。
2. 監査とリスク分類：ルール、シグネチャ数の拡大、運用上のリスクレベルを確認します。
3. モードと手法のリスク確認：プレビューモードとインプレースアップグレード、メソッド適用のリスク、割り当てまたは優先度の制約について顧客と合意します。
4. ルールの変換：ルールセット名、CEL 式、シグネチャ ID、preconfiguredWafConfig の除外設定を CRS 4.22 向けに変換します。
5. 実行と検証：gcloud を使用してアップグレードを適用し、Cloud Logging でテレメトリーを検証します。

ステップ 1：ポリシーの検出と取り込み

1. 対象となるセキュリティポリシー名と Google Cloud プロジェクトを特定します。

2. gcloud を使用して現在のポリシー定義を取得します。

   gcloud compute security-policies describe POLICY_NAME --project=PROJECT_ID --format="json"
   

   ポリシー JSON が提供されていない場合、または会話モードで実行している場合は、gcloud describe コマンドを提示し、以下の監査基準を説明してください。

3. rules リストを確認します。

   • 対象範囲内の WAF ルールを特定します。該当するのは、古い 3.0／3.3 ルールセット（sqli-stable、xss-stable、rce-stable、methodenforcement-stable など）を使用する evaluatePreconfiguredWaf または evaluatePreconfiguredExpr の呼び出しです。
   • 対象範囲外のルールを特定します。該当するのは、通過させるカスタムルール（純粋な IP 許可リスト SRC_IPS_V1、レート制限、WAF 呼び出しを含まないヘッダー照合、デフォルトルール priority: 2147483647 など）です。これらは変更せず、そのまま引き継ぎます。
   • シグネチャの対象範囲の拡大を示します（例：CRS 4.22 では、RCE は 11／15 から 44 シグネチャに、SQLi は 60 シグネチャに拡大します）。

ステップ 2：監査とリスク分類

対象範囲内の各ルールを、標準的な運用リスクの分類に照らして評価します。

リスクレベル	影響カテゴリ	基準と推奨アクション
🔴 高リスク	破壊的変更	切り替え時に正規の本番トラフィックを 直ちにブロックするリスクがあります。 例：methodenforcement-v422-stable は GET、HEAD、POST、OPTIONS のみを許可し、PUT、PATCH、DELETE リクエストをブロックします。顧客の確認と API パス／署名の除外設定が必要です。
🟡 中リスク	要注意	適用前にプレビューモードで検証すべき動作の変化です。 • カバレッジの拡大：感度レベル 4 では、より多くのシグネチャが有効になります（例：RCE は 11 件から 44 件に、SQLi は 60 件に拡大）。 • 非推奨の除外設定の喪失：レガシールールで、廃止された CRS 3.0／3.3 の 15 個の ID（981172、981173、980130、949110、SQLi：942110、RCE：932100、932105、932106、932110、932115、932150、スキャナー検出：913101、913102、913110、913120）のいずれかをオプトアウトしていた場合、4.22 ではこれらが含まれなくなります。 • カスタムフィルターの継続性：WAF 呼び出しと組み合わせたカスタムのヘッダー／Cookie／クエリ／IP 条件は維持されます。
🟢 低リスク	問題のないアップグレード	有効なオプトアウト設定が維持され、動作の差異が予想されない、ルールセットの直接的な 1 対 1 の変換です（例：標準的な SQLi または XSS ルール）。
⚪ 対応不要	そのまま引き継ぎ	OWASP 以外のルール（IP のみの許可リスト／拒否リスト、レート制限、デフォルトルール）。変更せずに引き継がれます。

ステップ 3：アップグレードモードの選択とユーザーとの合意

変更を適用する前に、調査結果を顧客に伝えます。

1. 調査結果の報告：アップグレードする WAF ルールの数、シグネチャカバレッジの拡張内容、廃止される非推奨のシグネチャがあれば、その内容を伝えます。
2. メソッド適用に関する警告：methodenforcement が存在する場合は、次のように警告します。> 「注意：CRS 4.22 の Method Enforcement で許可されるのは GET、HEAD、POST、OPTIONS のみです。アプリケーションで REST API の更新（PUT、PATCH、DELETE）を処理する場合、これらのメソッドは HTTP 403 でブロックされます。API パスに対する例外を追加するか、ルール id911100 を適用対象から外しますか？」
3. 各モードの違いの説明：
   • プレビューモード（推奨）：既存のレガシールールによる適用を維持しながら、対応するアップグレード後の CRS 4.22 プレビュールールを、数値の優先度がより低い値（評価優先度が高い値、例：PRIORITY - 5）で preview = true を指定してデプロイします。プレビュールールでトラフィックを最初に評価し、Cloud Logging に記録しますが、ブロックはしないため、切り替え前にダウンタイムや誤検知が発生するリスクはありません。200 ルールの上限内に収まる十分なクォータが必要です。
   • インプレースアップグレード：既存のルールの優先度番号はそのままに、CEL 式と preconfiguredWafConfig を直接変更します。追加のルールを必要とせず、すぐに適用できますが、新しいシグネチャやメソッド適用によって正当なトラフィックがブロックされる切り替えリスクがあります。
4. クォータのガードレール（200 ルール）：
   • ルール数の見込みを計算します：current_total_rules + in_scope_waf_rules。
   • 見込みのルール数が 200 を超える場合は、顧客に次のように警告します。> 「Cloud Armor では、セキュリティポリシーごとに最大 200 ルールまでという上限が適用されます。プレビューモードでデプロイするには、PROJECTED_COUNT 個のルールが必要です。プレビューモードではアップグレードを続行できません。インプレースアップグレードを実行するか、ルールを統合する必要があります。」
5. 優先度間隔のガードレール（プレビューモード）：
   • 対象の WAF ルールが PRIORITY にあり、その直前のルールが PREV_PRIORITY にあって、その間に空きの整数優先度がない場合（例：999 と 1000 の場合、または優先度 0 の WAF ルールの場合）は、顧客に次のように警告します。> 「直前の優先度 PREV_PRIORITY のルールと PRIORITY の間に空きの優先度番号がなく（また、プレビュールールを PREV_PRIORITY より上に配置すると評価順が変わるため）、ルール PRIORITY をプレビューモードでデプロイできません。プレビューモードを使用するには、PRIORITY の前に少なくとも 1 つの空き優先度を確保できるようルールの優先度を調整するか、インプレースアップグレードを選択してください。」
   • 既存の顧客ルールの番号を自動的に振り直してはいけません：Cloud Armor ではルールの優先度が主識別子として機能し、Terraform/IaC リソースや SIEM アラートのフィルターに関連付けられていることも多いため、空きを確保する目的で既存の顧客ルールの優先度を黙って変更してはいけません。顧客がルールの優先度調整を明示的に依頼した場合は、まず Terraform/IaC の状態ドリフトが発生する可能性を警告し、優先度を変更する前に新しい優先度番号を正確に確認してください。

ステップ 4：ルールの変換ロジック

A. ルールセット名の変換

ruleset_mappings.md の対応表に従って、レガシーのルールセット名を変換します。

• 安定版：sqli-stable から sqli-v422-stable、rce-stable から rce-v422-stable
• カナリア版：sqli-canary から sqli-v422-canary
• 3.3 安定版：sqli-v33-stable から sqli-v422-stable、nodejs-v33-stable から generic-v422-stable

B. CEL のオプトアウトとオプトインの変換

• 従来の evaluatePreconfiguredExpr(ruleset, ['id1', 'id2']) は、厳密に **オプトアウト（無効化）**リストです。

• ネイティブの 4.22 構文に変換します。

  evaluatePreconfiguredWaf('sqli-v422-stable', {'opt_out_rule_ids': ['owasp-crs-v042200-id942120-sqli']})
  

• シグネチャ ID を次のように再マッピングします。owasp-crs-v030001-idSIGNATURE_ID-GROUP を owasp-crs-v042200-idSIGNATURE_ID-GROUP に変換します。(例外：cve-canary シグネチャの owasp-crs-v030001-id*-cve や google-mrs-* などの単独の CVE シグネチャは元の ID を維持し、v042200 に再マッピングしたり削除したりしてはいけません。)

• 非推奨の CRS 3.0／3.3 シグネチャ番号をすべて（15 個）削除します（981172、981173、 980130、949110、SQLi：942110、RCE：932100、932105、932106、 932110、932115、932150、スキャナー検出：913101、913102、913110、 913120）。

C. 微調整（preconfiguredWafConfig）

構造化された preconfiguredWafConfig.exclusions[] を含むルールについて：

• targetRuleSet を CRS 4.22 相当のものに更新します。
• targetRuleIds を v042200 に再マッピングし、非推奨の ID を削除します。警告：非推奨 ID の削除後に 除外の targetRuleIds リストが空（[]）になった場合は、targetRuleIds: [] のままにせず、 除外エントリ全体を削除してください（空の targetRuleIds リストはルールセット全体を除外するためです）。
• すべてのフィールド除外（requestHeadersToExclude、 requestCookiesToExclude、requestQueryParamsToExclude、 requestUrisToExclude、requestBodiesToExclude）と一致演算子は 変更せずに引き継ぎます。
• 詳細は fine_tuning_and_cel.md を参照してください。

ステップ 5：実行内容の適用と検証

インプレースアップグレードの適用

gcloud compute security-policies rules update を実行します。

gcloud compute security-policies rules update PRIORITY \
  --security-policy="POLICY_NAME" \
  --project=PROJECT_ID \
  --expression="UPGRADED_EXPRESSION"

プレビューモードアップグレードの適用

rules create を使用して、直前のルールと ENFORCED_PRIORITY の間の数値優先度に （PREV_PRIORITY < PREVIEW_PRIORITY < ENFORCED_PRIORITY）、プレビュールールをデプロイします。

gcloud compute security-policies rules create PREVIEW_PRIORITY \
  --security-policy="POLICY_NAME" \
  --project=PROJECT_ID \
  --expression="UPGRADED_EXPRESSION" \
  --action="ACTION" \
  --preview \
  --description="PREVIEW: Upgraded CRS 4.22 Rule for Priority ENFORCED_PRIORITY"

Cloud Logging でのテレメトリ検証

切り替え前にプレビューログを確認するよう顧客に案内します。

gcloud logging read '
  resource.type="http_load_balancer" AND
  jsonPayload.enforcedSecurityPolicy.name="POLICY_NAME" AND
  jsonPayload.previewSecurityPolicy.matchedRulePriority:*
' --project=PROJECT_ID --limit=20

---

重要な注意点とドメインルール

1. evaluatePreconfiguredExpr はオプトインではありません：従来の evaluatePreconfiguredExpr の配列は、除外（オプトアウト）リストとしてのみ機能していました。 これをオプトインとして扱うと、そのルールセット内の他のすべてのシグネチャが 誤って無効になります。
2. 非推奨のシグネチャを再導入しないでください：廃止された CRS 3.0/3.3 の シグネチャ番号 15 件（981172、981173、980130、949110；SQLi：942110； RCE：932100、932105、932106、932110、932115、932150；スキャナー 検出：913101、913102、913110、913120）は CRS 4.22 で削除されました。 これらを opt_out_rule_ids または targetRuleIds に残すと、Cloud Armor API の スキーマ検証で拒否されます。
3. メソッド強制のデフォルト：CRS 4.22 のメソッド強制では、PUT、 PATCH、DELETE がブロックされます。ユーザーの確認なしに、メソッド強制を その場で黙ってアップグレードしないでください。
4. プレビュールールの優先度と切り替え時の安全性：Cloud Armor はルールを優先度の 昇順（0 から 2147483647）で評価します。プレビュールールは、プレビュー対象の 強制ルールより先に評価される必要がありますが、それより前にあるルールの後に 評価される必要もあります（PREV_PRIORITY < PREVIEW_PRIORITY < ENFORCED_PRIORITY）。 これにより、途中にある allow ルールやカスタムルールをまたぐことがありません。 全面強制へ切り替える際は、元の ENFORCED_PRIORITY ルールをその場で CRS 4.22 に 更新し、PREVIEW_PRIORITY を昇格させるのではなく削除してください。
5. 構造化除外のアトミックなインポート：ポリシーに複雑な preconfiguredWafConfig ブロックが含まれる場合は、ポリシー JSON をエクスポートして 変換し、gcloud compute security-policies import で適用する方法を推奨します。これにより、アトミックな更新を確実に行えます。
6. 単独の CVE シグネチャ（cve-canary）を保持する：cve-canary は、特定の脆弱性 （たとえば、Log4j CVE-2021-44228／CVE-2021-45046、React RCE CVE-2025-55182）を 対象とする帯域外ルールです。そのシグネチャ ID（owasp-crs-v030001-id044228-cve、 id144228-cve、id244228-cve、id344228-cve）は有効であり、v030001 プレフィックスを 保持します。構文を evaluatePreconfiguredWaf('cve-canary', ...) にアップグレードする のみとし、v042200 に書き換えたり、非推奨として削除したりしないでください。

---

参考資料とリソース

• ruleset_mappings.md：CRS 3.0／3.3 から 4.22 へのルールセットの完全なマッピング、感度レベル、シグネチャ数。
• fine_tuning_and_cel.md：CEL 構文の オプション、構造化された preconfiguredWafConfig の除外設定、メソッド強制の 緩和策。
• gcloud_recipes.md：監査、プレビューモード、 Cloud Logging クエリ用のコピーしてすぐ使える gcloud のレシピ。
• upgrade_policy.py：決定論的な CLI ヘルパースクリプト。
• contributing.md：このスキルを保守するためのドメインと コードの不変条件。