/cloud-armor-crs-rule-upgrader

name: cloud-armor-crs-rule-upgrader
metadata:
  category: Security
  version: "1.0.0"
description: >-
  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.

Cloud Armor OWASP Rule Upgrader (CRS 3.0/3.3 -> 4.22)

<!-- disableFinding(LINE_OVER_80) -->

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](references/attribution.md).

--------------------------------------------------------------------------------

Prerequisites and Environment Setup

Before auditing or modifying Google Cloud Armor security policies, ensure the following prerequisites are met:

1. **Google Cloud SDK**: Install or update the [Google Cloud CLI (`gcloud`)](https://docs.cloud.google.com/sdk/docs/install-sdk). 2. **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)"

3. **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

4. **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"`. 5. **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. 6. **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](https://cloud.google.com/about/locations) for regional availability. 7. **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](https://cloud.google.com/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](references/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-poli