cloud-armor-crs-rule-upgrader

Cloud Armor OWASP 规则升级工具（CRS 3.0/3.3 -> 4.22）

此技能将指导网络安全 Agent 和 Google Cloud 从业者审核、评估和升级 Google Cloud Armor 安全策略，将旧版 OWASP 核心规则集（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
   • 应用默认凭据（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 安全策略可以是全局（全局外部应用负载均衡器的默认设置），也可以是区域（用于区域级外部应用负载均衡器，例如 --region=us-central1； 可通过 gcloud config set compute/region us-central1 设置默认区域）。 有关区域可用性，请参阅 Google Cloud 位置。

7. 价格和资源清理：

   • Cloud Armor 会根据所用层级（Standard 或 Enterprise），按安全策略、规则和每百万次请求收费；请查看 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。

Network Security Agent 的核心升级工作流

重要

Agent 必须遵循的响应行为：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 规则：调用 evaluatePreconfiguredWaf 或 evaluatePreconfiguredExpr，并使用旧版 3.0 / 3.3 规则集 （sqli-stable、xss-stable、rce-stable、methodenforcement-stable 等）。
   • 确定范围外的规则：直通自定义规则（例如纯 IP 允许列表 SRC_IPS_V1、速率限制、不含 WAF 调用的标头匹配规则或默认规则 priority: 2147483647）。保持这些规则不变。
   • 强调签名覆盖范围的扩增情况（例如，RCE 从 11/15 个扩增到 44 个签名；SQLi 在 CRS 4.22 中扩增到 60 个签名）。

第 2 步：审计与风险分类

根据标准运营风险类别评估每条范围内的规则：

风险级别	影响类别	标准与建议操作
🔴 高风险	重大变更	切换后立即存在阻断合法生产流量
: : : 的风险。示例： :
: : : methodenforcement-v422-stable :
: : : 仅允许 GET、HEAD、 :
: : : POST、OPTIONS，并**阻止 :
: : : PUT、PATCH、DELETE** :
: : : 请求。需要客户确认，并为 API :
: : : 路径/签名添加豁免。 :
🟡 中风险	需要关注	应在强制执行前通过预览模式验证的
: : : 行为变化： • :
: : : 覆盖范围扩大： :
: : : 敏感度级别 4 会启用显著更多签名 :
: : : （例如，RCE 从 11/15 个扩展到 :
: : : 44 个签名；SQLi 扩展到 60 个签名）。 • :
: : : 已弃用豁免失效： :
: : : 旧规则选择退出了 15 个已停用的 :
: : : CRS 3.0/3.3 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 中的方法强制执行仅允许 GET、HEAD、POST 和 OPTIONS。如果您的应用处理 REST API 更新（PUT、PATCH、DELETE），这些方法将被阻止并返回 HTTP 403。您是否要为 API 路径添加例外，或选择不启用规则 id911100？”
3. 说明不同模式的区别：
   • 预览模式（推荐）：保留现有旧版规则并继续强制执行，同时以较低的数字优先级（更高的评估优先级，例如 PRIORITY - 5）部署对应的 CRS 4.22 预览规则，并设置 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 规则），提醒客户：> “规则 PRIORITY 无法在预览模式下部署，因为前一条优先级为 PREV_PRIORITY 的规则与 PRIORITY 之间没有空闲优先级编号（而将预览规则放在 PREV_PRIORITY 之前会改变评估顺序）。若要使用预览模式，请调整规则优先级，确保 PRIORITY 之前至少留有一个空闲优先级槽位，或选择原位升级。”
   • 不得自动重新编号现有客户规则：由于规则优先级在 Cloud Armor 中充当主要标识符，并且通常与 Terraform/IaC 资源和 SIEM 告警筛选条件相关联，因此绝不能悄悄更改现有客户规则的优先级来腾出空间。如果客户明确要求您为其调整规则优先级，请先提醒他们可能导致 Terraform/IaC 状态偏移，并在执行任何优先级更改前确认确切的新优先级编号。

第 4 步：规则转换逻辑

A. 规则集名称转换

根据 ruleset_mappings.md 中的映射表转换旧版规则集名称：

• Stable：sqli-stable 转换为 sqli-v422-stable，rce-stable 转换为 rce-v422-stable
• Canary：sqli-canary 转换为 sqli-v422-canary
• 3.3 Stable：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 签名，例如 cve-canary 签名 owasp-crs-v030001-id*-cve 和 google-mrs-*，保留其原始 ID，不得重新映射到 v042200 或删除。）

• 删除所有 15 个已弃用的 CRS 3.0/3.3 签名编号（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. 切勿重新引入已弃用的签名：所有 15 个已退役的 CRS 3.0/3.3 签名 编号（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，而不是就地提升 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：可直接复制粘贴的 gcloud 配方，用于审计、预览模式和 Cloud Logging 查询。
• upgrade_policy.py：确定性 CLI 辅助 脚本。
• contributing.md：维护此技能时需遵守的领域和代码不变量。