Cloud Armor OWASP Rule Upgrader (CRS 3.0/3.3 -> 4.22)
This skill guides Network Security Agents and Google Cloud practitioners through
auditing, assessing, and upgrading Google Cloud Armor security policies from
legacy OWASP Core Rule Set (CRS) 3.0 or 3.3 to OWASP CRS 4.22.
Usage Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read and follow the instructions in
Usage Attribution.
Prerequisites and Environment Setup
Before auditing or modifying Google Cloud Armor security policies, ensure the
following prerequisites are met:
Google Cloud SDK: Install or update the
Google Cloud CLI (gcloud).
Project Selection and Active Billing: Select your target Google Cloud
project and verify that an active billing account is attached:
gcloud config set project PROJECT_ID
gcloud billing projects describe PROJECT_ID --format="value(billingEnabled)"
API Enablement: Enable the Compute Engine API (for Cloud Armor security
policies) and Cloud Logging API (for preview mode telemetry):
gcloud services enable compute.googleapis.com logging.googleapis.com
Authentication:
- Interactive CLI:
gcloud auth login
- Application Default Credentials (ADC):
gcloud auth application-default login
- Service Accounts: Set
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json".
Required IAM Roles:
roles/compute.securityAdmin: Required to create, update, delete, or
import Cloud Armor security policies and rules (use
roles/compute.securityViewer for read-only policy audits).
roles/logging.viewer: Required to inspect HTTP load balancer preview
telemetry in Cloud Logging.
Scope and Regional Availability:
- Cloud Armor security policies can be Global (default for global
external Application Load Balancers) or Regional (for regional
external Application Load Balancers, for example,
--region=us-central1;
set a default region via gcloud config set compute/region us-central1).
See Google Cloud Locations
for regional availability.
Pricing and Resource Cleanup:
- Cloud Armor incurs charges per security policy, per rule, and per
million requests depending on your tier (Standard vs. Enterprise); check
Google Cloud Armor Pricing
for current rates.
- Teardown / Cleanup: Always delete temporary
--preview rules
(gcloud compute security-policies rules delete PREVIEW_PRIORITY --security-policy="POLICY_NAME") or standalone test policies (gcloud compute security-policies delete TEST_POLICY_NAME) after cutover to
avoid leaving orphan rules that consume policy quota or incur recurring
rule charges.
Quick Start and CLI Helper
For automated, deterministic parsing, signature remapping, and preview-mode
priority allocation, invoke the bundled standalone 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
See gcloud_recipes.md for full command
workflows.
Core Upgrade Workflow for Network Security Agent
[!IMPORTANT] Mandatory Agent Response Behaviors: 1. Explain Both Upgrade
Modes: Whenever discussing an upgrade (even if the user asks specifically
about Preview Mode or In-Place), ALWAYS explain BOTH In-Place Upgrade
(direct in-situ rule replacement, immediate enforcement, zero extra quota) and
Preview Mode (preview rules deployed at lower numeric priority numbers
with preview = true, zero risk of blocking traffic, allows telemetry
inspection in Cloud Logging before cutover). 2. Handling Policy Audit
Inquiries: When asked to audit or inspect a policy (such as
'ecommerce-waf'), if policy JSON is not provided or gcloud describe cannot
reach Google Cloud resources, immediately provide the gcloud compute security-policies describe POLICY_NAME --format=json command and guide the
user through the audit checks: - Check for legacy OWASP 3.0 / 3.3 rulesets
(sqli-stable, xss-stable, rce-stable, methodenforcement-stable, or
evaluatePreconfiguredExpr). - Report in-scope WAF rules versus pass-through
custom rules (such as IP allowlists SRC_IPS_V1, rate limiting, or default
rules priority: 2147483647). - Highlight signature count expansions under
CRS 4.22 (for example, RCE expanding from 11/15 to 44 signatures; SQLi
expanding to 60 signatures).
When interacting with a customer to upgrade a Cloud Armor security policy,
execute this 5-step workflow:
- Discover and Fetch: Identify the target security policy and fetch its
JSON definition.
- Audit and Classify Risk: Inspect rules, signature count expansions, and
operational risk levels.
- Confirm Mode and Method Risk: Align with the customer on Preview Mode
versus In-Place Upgrade, method enforcement risk, and quota or priority
constraints.
- Transform Rules: Translate ruleset names, CEL expressions, signature
IDs, and
preconfiguredWafConfig exclusions to CRS 4.22.
- Execute and Verify: Apply the upgrade via
gcloud and verify telemetry
in Cloud Logging.
Step 1: Policy Discovery and Ingestion
Identify the target security policy name and Google Cloud project.
Fetch the current policy definition via gcloud:
gcloud compute security-policies describe POLICY_NAME --project=PROJECT_ID --format="json"
If policy JSON is not provided or executing in conversational mode, provide
the gcloud describe command and outline the audit criteria below.
Inspect the rules list:
- Identify in-scope WAF rules: calls to
evaluatePreconfiguredWaf or
evaluatePreconfiguredExpr using legacy 3.0 / 3.3 rulesets
(sqli-stable, xss-stable, rce-stable, methodenforcement-stable,
etc.).
- Identify out-of-scope rules: pass-through custom rules (such as pure IP
allowlists
SRC_IPS_V1, rate limiting, header matches without WAF
calls, or default rules priority: 2147483647). Pass these through
unchanged.
- Highlight signature coverage expansions (for example, RCE expanding from
11/15 to 44 signatures; SQLi expanding to 60 signatures in CRS 4.22).
Step 2: Audit and Risk Classification
Evaluate each in-scope rule against standard operational risk categories:
| Risk Level |
Impact Category |
Criteria and Recommended Action |
| 🔴 High Risk |
Breaking Change |
Immediate risk of blocking legitimate production traffic upon cutover. Example: methodenforcement-v422-stable only permits GET, HEAD, POST, OPTIONS, and blocks PUT, PATCH, DELETE requests. Requires customer confirmation and API path/signature exemptions. |
| 🟡 Medium Risk |
Attention Required |
Behavioral shifts that should be validated in Preview Mode before enforcement:• Coverage Expansion: Sensitivity level 4 activates significantly more signatures (for example, RCE expands from 11/15 to 44 signatures; SQLi expands to 60 signatures).• Deprecated Exemption Lost: Legacy rule opted out of any of the 15 retired CRS 3.0/3.3 IDs (981172, 981173, 980130, 949110; SQLi: 942110; RCE: 932100, 932105, 932106, 932110, 932115, 932150; Scanner Detection: 913101, 913102, 913110, 913120), which are omitted in 4.22.• Custom Filter Continuity: Preserved custom header/cookie/query/IP conditions combined with WAF calls. |
| 🟢 Low Risk |
Clean Upgrade |
Direct 1:1 ruleset translation with preserved active opt-outs and no expected behavioral divergence (for example, standard SQLi or XSS rules). |
| ⚪ No Action |
Pass-Through |
Non-OWASP rules (pure IP allowlist/denylist, rate limiting, default rule). Carried over unchanged. |
Step 3: Upgrade Mode Selection and User Alignment
Engage the customer with findings before applying changes:
- Report Findings: State how many WAF rules will be upgraded, signature
coverage expansions, and any deprecated signatures being retired.
- Method Enforcement Warning: If
methodenforcement is present, warn: >
"Notice: Method Enforcement in CRS 4.22 permits only GET, HEAD, POST, and
OPTIONS. If your application handles REST API updates (PUT, PATCH, DELETE),
these methods will be blocked with HTTP 403. Would you like to add an
exemption for API paths or opt out of rule id911100?"
- Explain Differences Between Modes:
- Preview Mode (Recommended): Keeps existing legacy rules actively
enforcing while deploying corresponding upgraded CRS 4.22 preview rules
with
preview = true at a lower numeric priority number (higher
evaluation priority, for example, PRIORITY - 5). Traffic is evaluated
first by preview rules and logged to Cloud Logging without blocking,
ensuring zero risk of downtime or false positives prior to cutover.
Requires sufficient quota under the 200-rule limit.
- In-Place Upgrade: Directly modifies the CEL expressions and
preconfiguredWafConfig on existing rule priority numbers in-situ.
Immediate enforcement with zero additional rule overhead, but carries
cutover risk if new signatures or method enforcement block valid
traffic.
- Quota Guardrail (200 Rules):
- Calculate projected rule count:
current_total_rules + in_scope_waf_rules.
- If projected count > 200, alert the customer: > "Cloud Armor enforces a
maximum limit of 200 rules per security policy. Deploying in Preview
Mode would require PROJECTED_COUNT rules. The upgrade cannot proceed
in Preview Mode. We must either perform an In-Place Upgrade or
consolidate rules."
- Priority Spacing Guardrail (Preview Mode):
- If an in-scope WAF rule at
PRIORITY immediately follows another rule
at PREV_PRIORITY with no free integer priority slot between them
(for example, 999 and 1000, or a WAF rule at priority 0), alert
the customer: > "Rule PRIORITY cannot be deployed in Preview Mode
because the preceding rule at priority PREV_PRIORITY leaves no open
priority number between PREV_PRIORITY and PRIORITY (and placing the
preview rule above PREV_PRIORITY would change evaluation order). To use
Preview Mode, please readjust your rule priorities to leave at least one
open priority slot before PRIORITY, or choose an In-Place Upgrade."
- Do NOT automatically re-number existing customer rules: Because rule
priorities act as primary identifiers in Cloud Armor and are often tied
to Terraform/IaC resources and SIEM alerting filters, never silently
shift existing customer rule priorities to make room. If the customer
explicitly asks you to readjust their rule priorities for them, first
warn them about potential Terraform/IaC state drift and confirm the
exact new priority numbers before executing any priority changes.
Step 4: Rule Transformation Logic
A. Ruleset Name Translation
Translate legacy ruleset names according to the mapping table in
ruleset_mappings.md:
- Stable:
sqli-stable to sqli-v422-stable, rce-stable to
rce-v422-stable
- Canary:
sqli-canary to sqli-v422-canary
- 3.3 Stable:
sqli-v33-stable to sqli-v422-stable, nodejs-v33-stable
to generic-v422-stable
B. CEL Opt-Out and Opt-In Translation
Legacy evaluatePreconfiguredExpr(ruleset, ['id1', 'id2']) is strictly an
opt-out (disabled) list.
Convert to native 4.22 syntax:
evaluatePreconfiguredWaf('sqli-v422-stable', {'opt_out_rule_ids': ['owasp-crs-v042200-id942120-sqli']})
Remap signature IDs: owasp-crs-v030001-idSIGNATURE_ID-GROUP to
owasp-crs-v042200-idSIGNATURE_ID-GROUP. (Exception: Standalone CVE
signatures such as cve-canary signatures owasp-crs-v030001-id*-cve and
google-mrs-* retain their original IDs and must not be remapped to
v042200 or dropped).
Drop all 15 deprecated CRS 3.0/3.3 signature numbers (981172, 981173,
980130, 949110; SQLi: 942110; RCE: 932100, 932105, 932106,
932110, 932115, 932150; Scanner Detection: 913101, 913102,
913110, 913120).
C. Fine-Tuning (preconfiguredWafConfig)
For rules with structured preconfiguredWafConfig.exclusions[]:
- Update
targetRuleSet to the CRS 4.22 equivalent.
- Remap
targetRuleIds to v042200 and drop deprecated IDs. Warning: If
an exclusion's targetRuleIds list becomes empty ([]) after dropping
retired IDs, remove the entire exclusion entry rather than leaving
targetRuleIds: [] (otherwise an empty targetRuleIds list exempts the
entire ruleset).
- Carry over all field exclusions (
requestHeadersToExclude,
requestCookiesToExclude, requestQueryParamsToExclude,
requestUrisToExclude, requestBodiesToExclude) and match operators
without modification.
- Details in fine_tuning_and_cel.md.
Step 5: Execution Delivery and Verification
Delivering In-Place Upgrade
Execute gcloud compute security-policies rules update:
gcloud compute security-policies rules update PRIORITY \
--security-policy="POLICY_NAME" \
--project=PROJECT_ID \
--expression="UPGRADED_EXPRESSION"
Delivering Preview Mode Upgrade
Deploy preview rules at a numeric priority strictly between the immediately
preceding rule and ENFORCED_PRIORITY (PREV_PRIORITY < PREVIEW_PRIORITY < ENFORCED_PRIORITY) using rules create:
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"
Telemetry Verification in Cloud Logging
Instruct the customer to inspect preview logs before cutover:
gcloud logging read '
resource.type="http_load_balancer" AND
jsonPayload.enforcedSecurityPolicy.name="POLICY_NAME" AND
jsonPayload.previewSecurityPolicy.matchedRulePriority:*
' --project=PROJECT_ID --limit=20
Critical Gotchas and Domain Rules
evaluatePreconfiguredExpr is NEVER Opt-In: The array in legacy
evaluatePreconfiguredExpr was strictly an exclusion (opt-out) list.
Treating it as opt-in would inadvertently disable all other signatures in
that ruleset!
- Never Re-introduce Deprecated Signatures: All 15 retired CRS 3.0/3.3
signature numbers (
981172, 981173, 980130, 949110; SQLi: 942110;
RCE: 932100, 932105, 932106, 932110, 932115, 932150; Scanner
Detection: 913101, 913102, 913110, 913120) were removed in CRS 4.22.
Keeping them in opt_out_rule_ids or targetRuleIds causes Cloud Armor API
schema rejections.
- Method Enforcement Defaults: CRS 4.22 Method Enforcement blocks
PUT,
PATCH, and DELETE. Never perform a silent in-place upgrade of method
enforcement without user confirmation.
- Preview Rule Priorities and Cutover Safety: Cloud Armor evaluates rules
in ascending priority order (
0 to 2147483647). A preview rule must
evaluate before the enforcing rule it previews, but after any preceding
rule (PREV_PRIORITY < PREVIEW_PRIORITY < ENFORCED_PRIORITY) so it never
crosses intervening allow or custom rules. During cutover to full
enforcement, update the original ENFORCED_PRIORITY rule in-place to CRS
4.22 and delete PREVIEW_PRIORITY rather than promoting PREVIEW_PRIORITY
in place.
- Atomic Import for Structured Exclusions: When a policy contains complex
preconfiguredWafConfig blocks, prefer exporting the policy JSON,
transforming it, and applying it via gcloud compute security-policies import to ensure atomic updates.
- Preserve Standalone CVE Signatures (
cve-canary): cve-canary is an
out-of-band rule for specific vulnerabilities (for example, Log4j
CVE-2021-44228 / CVE-2021-45046, React RCE CVE-2025-55182). Its signature
IDs (owasp-crs-v030001-id044228-cve, id144228-cve, id244228-cve,
id344228-cve) are valid and retain the v030001 prefix. Only upgrade the
syntax to evaluatePreconfiguredWaf('cve-canary', ...); never rewrite them
to v042200 or drop them as deprecated.
References and Resources
- ruleset_mappings.md: Full CRS 3.0 / 3.3 to
4.22 ruleset mapping, sensitivity levels, and signature counts.
- fine_tuning_and_cel.md: CEL syntax
options, structured
preconfiguredWafConfig exclusions, and method
enforcement mitigations.
- gcloud_recipes.md: Copy-pasteable
gcloud
recipes for audit, preview mode, and Cloud Logging queries.
- upgrade_policy.py: Deterministic CLI helper
script.
- contributing.md: Domain and code invariants
for maintaining this skill.
1---2name: cloud-armor-crs-rule-upgrader3metadata:4 source: https://skillmd.com/skills/google/cloud-armor-crs-rule-upgrader5 category: Security6 version: "1.0.1"7description: >-8 Upgrades Google Cloud Armor security policies from OWASP CRS 3.0 and 3.3 to OWASP CRS 4.22. Preserves signature opt-in and opt-out lists, translates evaluatePreconfiguredExpr to native evaluatePreconfiguredWaf dictionary parameters, remaps signature IDs to v042200, drops retired signature IDs, and updates structured preconfiguredWafConfig fine-tuning exclusions. Evaluates operational risk (High Breaking Change, Medium Attention Required, Low Clean Upgrade) including Method Enforcement breaking changes (PUT/PATCH/DELETE blocking) and sensitivity coverage expansions. Supports both in-place rule upgrades and smooth preview mode deployments with priority spacing and a 200-rule quota guardrail. Use when a user or agent needs to audit, upgrade, or transition Cloud Armor WAF rules to CRS 4.22. Don't use for non-WAF Cloud Armor rules (IP rate-limiting, geo-blocking, reCAPTCHA) or AWS/Azure WAF migrations.9---1011# Cloud Armor OWASP Rule Upgrader (CRS 3.0/3.3 -> 4.22)1213<!-- disableFinding(LINE_OVER_80) -->1415This skill guides Network Security Agents and Google Cloud practitioners through16auditing, assessing, and upgrading Google Cloud Armor security policies from17legacy OWASP Core Rule Set (CRS) 3.0 or 3.3 to OWASP CRS 4.22.1819## Usage Attribution2021**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you22MUST read and follow the instructions in23[Usage Attribution](references/attribution.md).2425--------------------------------------------------------------------------------2627## Prerequisites and Environment Setup2829Before auditing or modifying Google Cloud Armor security policies, ensure the30following prerequisites are met:31321. **Google Cloud SDK**: Install or update the33 [Google Cloud CLI (`gcloud`)](https://docs.cloud.google.com/sdk/docs/install-sdk).342. **Project Selection and Active Billing**: Select your target Google Cloud35 project and verify that an active billing account is attached:3637 ```bash38 gcloud config set project PROJECT_ID39 gcloud billing projects describe PROJECT_ID --format="value(billingEnabled)"40 ```41423. **API Enablement**: Enable the Compute Engine API (for Cloud Armor security43 policies) and Cloud Logging API (for preview mode telemetry):4445 ```bash46 gcloud services enable compute.googleapis.com logging.googleapis.com47 ```48494. **Authentication**:50 - **Interactive CLI**: `gcloud auth login`51 - **Application Default Credentials (ADC)**: `gcloud auth52 application-default login`53 - **Service Accounts**: Set54 `GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"`.555. **Required IAM Roles**:56 - `roles/compute.securityAdmin`: Required to create, update, delete, or57 import Cloud Armor security policies and rules (use58 `roles/compute.securityViewer` for read-only policy audits).59 - `roles/logging.viewer`: Required to inspect HTTP load balancer preview60 telemetry in Cloud Logging.616. **Scope and Regional Availability**:62 - Cloud Armor security policies can be **Global** (default for global63 external Application Load Balancers) or **Regional** (for regional64 external Application Load Balancers, for example, `--region=us-central1`;65 set a default region via `gcloud config set compute/region us-central1`).66 See [Google Cloud Locations](https://cloud.google.com/about/locations)67 for regional availability.687. **Pricing and Resource Cleanup**:69 - Cloud Armor incurs charges per security policy, per rule, and per70 million requests depending on your tier (Standard vs. Enterprise); check71 [Google Cloud Armor Pricing](https://cloud.google.com/armor/pricing)72 for current rates.73 - **Teardown / Cleanup**: Always delete temporary `--preview` rules74 (`gcloud compute security-policies rules delete PREVIEW_PRIORITY75 --security-policy="POLICY_NAME"`) or standalone test policies (`gcloud76 compute security-policies delete TEST_POLICY_NAME`) after cutover to77 avoid leaving orphan rules that consume policy quota or incur recurring78 rule charges.7980--------------------------------------------------------------------------------8182## Quick Start and CLI Helper8384For automated, deterministic parsing, signature remapping, and preview-mode85priority allocation, invoke the bundled standalone Python CLI:8687```bash88# In-Place Upgrade (Report Summary)89python3 scripts/upgrade_policy.py /path/to/policy.json --mode=in-place --format=report9091# In-Place Upgrade (Output gcloud commands)92python3 scripts/upgrade_policy.py /path/to/policy.json --mode=in-place --format=gcloud9394# Preview Mode Upgrade (Generates preview rules at priority - 5)95python3 scripts/upgrade_policy.py /path/to/policy.json --mode=preview --format=gcloud9697# Direct stdin piping from gcloud describe98gcloud compute security-policies describe POLICY_NAME --format=json | \99 python3 scripts/upgrade_policy.py - --mode=preview --format=json100```101102See [gcloud_recipes.md](references/gcloud_recipes.md) for full command103workflows.104105## Core Upgrade Workflow for Network Security Agent106107> [!IMPORTANT] **Mandatory Agent Response Behaviors**: 1. **Explain Both Upgrade108> Modes**: Whenever discussing an upgrade (even if the user asks specifically109> about Preview Mode or In-Place), ALWAYS explain BOTH **In-Place Upgrade**110> (direct in-situ rule replacement, immediate enforcement, zero extra quota) and111> **Preview Mode** (preview rules deployed at lower numeric priority numbers112> with `preview = true`, zero risk of blocking traffic, allows telemetry113> inspection in Cloud Logging before cutover). 2. **Handling Policy Audit114> Inquiries**: When asked to audit or inspect a policy (such as115> `'ecommerce-waf'`), if policy JSON is not provided or `gcloud describe` cannot116> reach Google Cloud resources, immediately provide the `gcloud compute117> security-policies describe POLICY_NAME --format=json` command and guide the118> user through the audit checks: - Check for legacy OWASP 3.0 / 3.3 rulesets119> (`sqli-stable`, `xss-stable`, `rce-stable`, `methodenforcement-stable`, or120> `evaluatePreconfiguredExpr`). - Report in-scope WAF rules versus pass-through121> custom rules (such as IP allowlists `SRC_IPS_V1`, rate limiting, or default122> rules `priority: 2147483647`). - Highlight signature count expansions under123> CRS 4.22 (for example, RCE expanding from 11/15 to 44 signatures; SQLi124> expanding to 60 signatures).125126When interacting with a customer to upgrade a Cloud Armor security policy,127execute this 5-step workflow:1281291. **Discover and Fetch**: Identify the target security policy and fetch its130 JSON definition.1312. **Audit and Classify Risk**: Inspect rules, signature count expansions, and132 operational risk levels.1333. **Confirm Mode and Method Risk**: Align with the customer on Preview Mode134 versus In-Place Upgrade, method enforcement risk, and quota or priority135 constraints.1364. **Transform Rules**: Translate ruleset names, CEL expressions, signature137 IDs, and `preconfiguredWafConfig` exclusions to CRS 4.22.1385. **Execute and Verify**: Apply the upgrade via `gcloud` and verify telemetry139 in Cloud Logging.140141### Step 1: Policy Discovery and Ingestion1421431. Identify the target security policy name and Google Cloud project.1442. Fetch the current policy definition via `gcloud`:145146 ```bash147 gcloud compute security-policies describe POLICY_NAME --project=PROJECT_ID --format="json"148 ```149150 *If policy JSON is not provided or executing in conversational mode, provide151 the `gcloud describe` command and outline the audit criteria below.*1521533. Inspect the `rules` list:154155 - Identify in-scope WAF rules: calls to `evaluatePreconfiguredWaf` or156 `evaluatePreconfiguredExpr` using legacy 3.0 / 3.3 rulesets157 (`sqli-stable`, `xss-stable`, `rce-stable`, `methodenforcement-stable`,158 etc.).159 - Identify out-of-scope rules: pass-through custom rules (such as pure IP160 allowlists `SRC_IPS_V1`, rate limiting, header matches without WAF161 calls, or default rules `priority: 2147483647`). Pass these through162 unchanged.163 - Highlight signature coverage expansions (for example, RCE expanding from164 11/15 to 44 signatures; SQLi expanding to 60 signatures in CRS 4.22).165166### Step 2: Audit and Risk Classification167168Evaluate each in-scope rule against standard operational risk categories:169170<!-- mdformat off -->171172| Risk Level | Impact Category | Criteria and Recommended Action |173| :--- | :--- | :--- |174| 🔴 **High Risk** | **Breaking Change** | Immediate risk of blocking legitimate production traffic upon cutover. Example: `methodenforcement-v422-stable` only permits `GET`, `HEAD`, `POST`, `OPTIONS`, and **blocks `PUT`, `PATCH`, `DELETE`** requests. Requires customer confirmation and API path/signature exemptions. |175| 🟡 **Medium Risk** | **Attention Required** | Behavioral shifts that should be validated in Preview Mode before enforcement:<br>• **Coverage Expansion**: Sensitivity level 4 activates significantly more signatures (for example, RCE expands from 11/15 to 44 signatures; SQLi expands to 60 signatures).<br>• **Deprecated Exemption Lost**: Legacy rule opted out of any of the 15 retired CRS 3.0/3.3 IDs (`981172`, `981173`, `980130`, `949110`; SQLi: `942110`; RCE: `932100`, `932105`, `932106`, `932110`, `932115`, `932150`; Scanner Detection: `913101`, `913102`, `913110`, `913120`), which are omitted in 4.22.<br>• **Custom Filter Continuity**: Preserved custom header/cookie/query/IP conditions combined with WAF calls. |176| 🟢 **Low Risk** | **Clean Upgrade** | Direct 1:1 ruleset translation with preserved active opt-outs and no expected behavioral divergence (for example, standard SQLi or XSS rules). |177| ⚪ **No Action** | **Pass-Through** | Non-OWASP rules (pure IP allowlist/denylist, rate limiting, default rule). Carried over unchanged. |178179<!-- mdformat on -->180181### Step 3: Upgrade Mode Selection and User Alignment182183Engage the customer with findings before applying changes:1841851. **Report Findings**: State how many WAF rules will be upgraded, signature186 coverage expansions, and any deprecated signatures being retired.1872. **Method Enforcement Warning**: If `methodenforcement` is present, warn: >188 *"Notice: Method Enforcement in CRS 4.22 permits only GET, HEAD, POST, and189 OPTIONS. If your application handles REST API updates (PUT, PATCH, DELETE),190 these methods will be blocked with HTTP 403. Would you like to add an191 exemption for API paths or opt out of rule id911100?"*1923. **Explain Differences Between Modes**:193 - **Preview Mode (Recommended)**: Keeps existing legacy rules actively194 enforcing while deploying corresponding upgraded CRS 4.22 preview rules195 with `preview = true` at a lower numeric priority number (higher196 evaluation priority, for example, `PRIORITY - 5`). Traffic is evaluated197 first by preview rules and logged to Cloud Logging without blocking,198 ensuring zero risk of downtime or false positives prior to cutover.199 Requires sufficient quota under the 200-rule limit.200 - **In-Place Upgrade**: Directly modifies the CEL expressions and201 `preconfiguredWafConfig` on existing rule priority numbers in-situ.202 Immediate enforcement with zero additional rule overhead, but carries203 cutover risk if new signatures or method enforcement block valid204 traffic.2054. **Quota Guardrail (200 Rules)**:206 - Calculate projected rule count: `current_total_rules +207 in_scope_waf_rules`.208 - If projected count > 200, alert the customer: > *"Cloud Armor enforces a209 maximum limit of 200 rules per security policy. Deploying in Preview210 Mode would require PROJECTED_COUNT rules. The upgrade cannot proceed211 in Preview Mode. We must either perform an In-Place Upgrade or212 consolidate rules."*2135. **Priority Spacing Guardrail (Preview Mode)**:214 - If an in-scope WAF rule at `PRIORITY` immediately follows another rule215 at `PREV_PRIORITY` with no free integer priority slot between them216 (for example, `999` and `1000`, or a WAF rule at priority `0`), alert217 the customer: > *"Rule PRIORITY cannot be deployed in Preview Mode218 because the preceding rule at priority PREV_PRIORITY leaves no open219 priority number between PREV_PRIORITY and PRIORITY (and placing the220 preview rule above PREV_PRIORITY would change evaluation order). To use221 Preview Mode, please readjust your rule priorities to leave at least one222 open priority slot before PRIORITY, or choose an In-Place Upgrade."*223 - **Do NOT automatically re-number existing customer rules**: Because rule224 priorities act as primary identifiers in Cloud Armor and are often tied225 to Terraform/IaC resources and SIEM alerting filters, never silently226 shift existing customer rule priorities to make room. If the customer227 explicitly asks you to readjust their rule priorities for them, first228 warn them about potential Terraform/IaC state drift and confirm the229 exact new priority numbers before executing any priority changes.230231### Step 4: Rule Transformation Logic232233#### A. Ruleset Name Translation234235Translate legacy ruleset names according to the mapping table in236[ruleset_mappings.md](references/ruleset_mappings.md):237238- Stable: `sqli-stable` to `sqli-v422-stable`, `rce-stable` to239 `rce-v422-stable`240- Canary: `sqli-canary` to `sqli-v422-canary`241- 3.3 Stable: `sqli-v33-stable` to `sqli-v422-stable`, `nodejs-v33-stable`242 to `generic-v422-stable`243244#### B. CEL Opt-Out and Opt-In Translation245246- Legacy `evaluatePreconfiguredExpr(ruleset, ['id1', 'id2'])` is strictly an247 **opt-out (disabled)** list.248- Convert to native 4.22 syntax:249250 ```cel251 evaluatePreconfiguredWaf('sqli-v422-stable', {'opt_out_rule_ids': ['owasp-crs-v042200-id942120-sqli']})252 ```253- Remap signature IDs: `owasp-crs-v030001-idSIGNATURE_ID-GROUP` to254 `owasp-crs-v042200-idSIGNATURE_ID-GROUP`. *(Exception: Standalone CVE255 signatures such as `cve-canary` signatures `owasp-crs-v030001-id*-cve` and256 `google-mrs-*` retain their original IDs and must not be remapped to257 `v042200` or dropped).*258- Drop all 15 deprecated CRS 3.0/3.3 signature numbers (`981172`, `981173`,259 `980130`, `949110`; SQLi: `942110`; RCE: `932100`, `932105`, `932106`,260 `932110`, `932115`, `932150`; Scanner Detection: `913101`, `913102`,261 `913110`, `913120`).262263#### C. Fine-Tuning (`preconfiguredWafConfig`)264265For rules with structured `preconfiguredWafConfig.exclusions[]`:266267- Update `targetRuleSet` to the CRS 4.22 equivalent.268- Remap `targetRuleIds` to `v042200` and drop deprecated IDs. **Warning**: If269 an exclusion's `targetRuleIds` list becomes empty (`[]`) after dropping270 retired IDs, remove the entire exclusion entry rather than leaving271 `targetRuleIds: []` (otherwise an empty `targetRuleIds` list exempts the272 entire ruleset).273- Carry over all field exclusions (`requestHeadersToExclude`,274 `requestCookiesToExclude`, `requestQueryParamsToExclude`,275 `requestUrisToExclude`, `requestBodiesToExclude`) and match operators276 without modification.277- Details in [fine_tuning_and_cel.md](references/fine_tuning_and_cel.md).278279### Step 5: Execution Delivery and Verification280281#### Delivering In-Place Upgrade282283Execute `gcloud compute security-policies rules update`:284285```bash286gcloud compute security-policies rules update PRIORITY \287 --security-policy="POLICY_NAME" \288 --project=PROJECT_ID \289 --expression="UPGRADED_EXPRESSION"290```291292#### Delivering Preview Mode Upgrade293294Deploy preview rules at a numeric priority strictly between the immediately295preceding rule and `ENFORCED_PRIORITY` (`PREV_PRIORITY < PREVIEW_PRIORITY <296ENFORCED_PRIORITY`) using `rules create`:297298```bash299gcloud compute security-policies rules create PREVIEW_PRIORITY \300 --security-policy="POLICY_NAME" \301 --project=PROJECT_ID \302 --expression="UPGRADED_EXPRESSION" \303 --action="ACTION" \304 --preview \305 --description="PREVIEW: Upgraded CRS 4.22 Rule for Priority ENFORCED_PRIORITY"306```307308#### Telemetry Verification in Cloud Logging309310Instruct the customer to inspect preview logs before cutover:311312```bash313gcloud logging read '314 resource.type="http_load_balancer" AND315 jsonPayload.enforcedSecurityPolicy.name="POLICY_NAME" AND316 jsonPayload.previewSecurityPolicy.matchedRulePriority:*317' --project=PROJECT_ID --limit=20318```319320--------------------------------------------------------------------------------321322## Critical Gotchas and Domain Rules3233241. **`evaluatePreconfiguredExpr` is NEVER Opt-In**: The array in legacy325 `evaluatePreconfiguredExpr` was strictly an exclusion (opt-out) list.326 Treating it as opt-in would inadvertently disable all other signatures in327 that ruleset!3282. **Never Re-introduce Deprecated Signatures**: All 15 retired CRS 3.0/3.3329 signature numbers (`981172`, `981173`, `980130`, `949110`; SQLi: `942110`;330 RCE: `932100`, `932105`, `932106`, `932110`, `932115`, `932150`; Scanner331 Detection: `913101`, `913102`, `913110`, `913120`) were removed in CRS 4.22.332 Keeping them in `opt_out_rule_ids` or `targetRuleIds` causes Cloud Armor API333 schema rejections.3343. **Method Enforcement Defaults**: CRS 4.22 Method Enforcement blocks `PUT`,335 `PATCH`, and `DELETE`. Never perform a silent in-place upgrade of method336 enforcement without user confirmation.3374. **Preview Rule Priorities and Cutover Safety**: Cloud Armor evaluates rules338 in ascending priority order (`0` to `2147483647`). A preview rule must339 evaluate *before* the enforcing rule it previews, but *after* any preceding340 rule (`PREV_PRIORITY < PREVIEW_PRIORITY < ENFORCED_PRIORITY`) so it never341 crosses intervening `allow` or custom rules. During cutover to full342 enforcement, update the original `ENFORCED_PRIORITY` rule in-place to CRS343 4.22 and delete `PREVIEW_PRIORITY` rather than promoting `PREVIEW_PRIORITY`344 in place.3455. **Atomic Import for Structured Exclusions**: When a policy contains complex346 `preconfiguredWafConfig` blocks, prefer exporting the policy JSON,347 transforming it, and applying it via `gcloud compute security-policies348 import` to ensure atomic updates.3496. **Preserve Standalone CVE Signatures (`cve-canary`)**: `cve-canary` is an350 out-of-band rule for specific vulnerabilities (for example, Log4j351 CVE-2021-44228 / CVE-2021-45046, React RCE CVE-2025-55182). Its signature352 IDs (`owasp-crs-v030001-id044228-cve`, `id144228-cve`, `id244228-cve`,353 `id344228-cve`) are valid and retain the `v030001` prefix. Only upgrade the354 syntax to `evaluatePreconfiguredWaf('cve-canary', ...)`; never rewrite them355 to `v042200` or drop them as deprecated.356357--------------------------------------------------------------------------------358359## References and Resources360361- [ruleset_mappings.md](references/ruleset_mappings.md): Full CRS 3.0 / 3.3 to362 4.22 ruleset mapping, sensitivity levels, and signature counts.363- [fine_tuning_and_cel.md](references/fine_tuning_and_cel.md): CEL syntax364 options, structured `preconfiguredWafConfig` exclusions, and method365 enforcement mitigations.366- [gcloud_recipes.md](references/gcloud_recipes.md): Copy-pasteable `gcloud`367 recipes for audit, preview mode, and Cloud Logging queries.368- [upgrade_policy.py](scripts/upgrade_policy.py): Deterministic CLI helper369 script.370- [contributing.md](references/contributing.md): Domain and code invariants371 for maintaining this skill.