How to Tune Google Cloud Armor WAF Rules

2026-07-29T10:00:00+10:00

Cloud Armor evaluates security-policy rules by priority. The request log shows the preview rule that matched and the enforced rule that decided the request.

An allow rule at priority 100 accepts the request before a SQL injection rule at priority 1000 can inspect it. A WAF rule in preview records the action it would have taken while an enforced rule decides the request.

Preview one WAF rule

Cloud Armor preview belongs to individual security-policy rules. The configured action is recorded while policy evaluation continues to an enforced rule. Both results appear in the request log when the preview rule takes priority. Google documents this evaluation behaviour and the --preview flag.

The commands below use a global service-level security policy. Add --region=REGION to each command when working with a regional policy.

Create or update the WAF rule with a deny action and preview enabled:

gcloud compute security-policies rules create 1000 \
    --security-policy app-policy \
    --expression "evaluatePreconfiguredWaf('sqli-v422-stable', {'sensitivity': 1})" \
    --action deny-403 \
    --preview \
    --description "SQLi v4.22 sensitivity 1"

Sensitivity 1 is a sensible starting point for most applications. It enables the higher-confidence signatures and usually produces less noise than higher levels. Google recommends starting new preconfigured WAF rules at sensitivity 1 and validating them in preview. The current Cloud Armor best-practices guide gives both recommendations.

Read both policy results in the request log

Cloud Armor adds its policy results to the load balancer’s per-request log. Request logging is disabled by default for new backend services, so enable it before starting the preview. Look for previewSecurityPolicy to see the preview match and enforcedSecurityPolicy to see the enforced result. The preconfiguredExprIds array contains every WAF signature that triggered the matching policy rule. Google lists the logging prerequisite and policy fields in the Cloud Armor request-logging reference.

A Logs Explorer query can isolate the preview rule:

resource.type="http_load_balancer"
jsonPayload.previewSecurityPolicy.name="app-policy"
jsonPayload.previewSecurityPolicy.priority=1000

Group the results by:

preconfiguredExprIds;
request path and method;
preview rule priority;
enforced outcome;
client or application flow;
time and release version.

Use our general WAF tuning guide to classify those repeated matches and choose the smallest safe exception.

Enable verbose logging for a short investigation when the ordinary log shows the signature but omits the input. It adds matchedFieldType, matchedFieldName and a short matchedFieldValue snippet for requests matching preconfigured WAF rules. Those snippets can contain customer or personal data. Google recommends disabling verbose logging during normal operation. The verbose-logging guide describes the extra fields and privacy risk.

Match the signature ID to the ruleset version

The name sqli-v422-stable identifies the SQL injection ruleset built from CRS 4.22. A signature inside it has the same version in its ID, such as:

owasp-crs-v042200-id942350-sqli

Use the ID written by the policy log. Cloud Armor requires an opted-out signature ID to match the ruleset version, and rejects mismatched versions. Google shows the versioned naming and requirement in its WAF tuning guide.

A ruleset upgrade can add or change signatures. Put the new version in preview, compare its matches with the enforced version and promote it after reviewing the result.

Google also publishes canary rulesets. Its recommended arrangement runs the canary at a higher priority in preview and the stable ruleset at a lower priority in enforcement. The canary records the requests it would deny while the stable rule protects the service. Google describes this stable-and-canary arrangement in its best practices.

Choose the sensitivity level first

Sensitivity levels run from 0 to 4. Choosing level 2 enables signatures at levels 1 and 2. Higher levels inspect for more patterns and tend to produce more false positives. Level 0 enables no signatures unless you explicitly opt them in. Google maps Cloud Armor sensitivity to CRS paranoia levels in the tuning documentation.

Choose a level that fits the application and the time available to investigate. A public marketing site with conventional inputs may run cleanly at a higher level. An API accepting templates or query fragments may need more work.

Keep the chosen sensitivity and exclude the named field from the affected signature.

Opt out one noisy signature

If a signature is irrelevant wherever the policy rule applies, list its versioned ID in opt_out_rule_ids:

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

The WAF rule runs every SQL injection signature enabled at sensitivity 1 and 2 except the named signature.

Use an opt-out after reviewing where the policy rule applies. A rule matching every request to a shared backend gives the exception the same reach.

Enable selected signatures at sensitivity 0

Set sensitivity to 0 when the rule needs only a few named signatures:

evaluatePreconfiguredWaf(
  'xss-v422-stable',
  {
    'sensitivity': 0,
    'opt_in_rule_ids': [
      'owasp-crs-v042200-id941150-xss'
    ]
  }
)

Cloud Armor permits opt_in_rule_ids only at sensitivity 0. Google recommends this approach when you want fewer signatures than you would otherwise opt out. The setup guide documents the constraint and provides current CLI examples.

An opt-in rule enables only the named signatures for the traffic matched by that policy rule. Record why each signature was selected and when to review the set.

Exclude the field that carries legitimate content

A request-field exclusion keeps a signature active and removes a selected input from its inspection.

Cloud Armor can exclude named header values, cookie values, query-parameter values and URIs from an entire preconfigured ruleset or selected signatures. Header, cookie and query-parameter names remain inspected when their values are excluded. URI exclusions remove the matching URI from inspection for the selected target. Google documents each field’s behaviour and available match operators.

Suppose the cookie analytics_id repeatedly triggers signature 942100. Add an exclusion to the existing SQLi policy rule:

gcloud compute security-policies rules add-preconfig-waf-exclusion 1000 \
    --security-policy app-policy \
    --target-rule-set sqli-v422-stable \
    --target-rule-ids owasp-crs-v042200-id942100-sqli \
    --request-cookie-to-exclude "op=EQUALS,val=analytics_id"

The signature continues to inspect the cookie name and every other request field, excluding only the value of analytics_id.

Request query parameters need one extra check. Cloud Armor rebuilds the URI and request line after removing an excluded query parameter. A signature that inspects the entire REQUEST_BODY continues to inspect it, so the same parameter can trigger a body-wide signature. Google calls out this behaviour in the query-parameter exclusion documentation.

A policy rule with request-field exclusions cannot use the allow action. Use the WAF’s deny action and let unmatched requests continue through the policy. This restriction appears in the current preconfigured WAF limitations.

Apply the tuned WAF rule to one route

Cloud Armor uses Common Expression Language expressions for advanced matches. Combine the route condition and WAF evaluation in one rule when an exception belongs to one application area:

request.path.startsWith('/api/messages') &&
evaluatePreconfiguredWaf('sqli-v422-stable', {'sensitivity': 1})

Create a separate SQLi rule for the rest of the application and exclude /api/messages from its expression. The route is then evaluated once under the tuned rule.

!request.path.startsWith('/api/messages') &&
evaluatePreconfiguredWaf('sqli-v422-stable', {'sensitivity': 1})

Priority decides which matching rule takes effect. A smaller number has higher priority. An earlier allow rule ends evaluation for the matching request, so later WAF rules never see it. Google explains the evaluation order and demonstrates the effect of an early allow.

Replay three requests when testing route logic:

a legitimate request containing the known false-positive value;
an attack string in the excluded field;
an attack string in another field.

The legitimate request should pass. The attack string in the excluded field shows the exposure created by the exception. The attack string in another field should still trigger the WAF rule.

Set the request-body inspection limit

Cloud Armor inspects a configurable prefix of the request body: 8, 16, 32, 48 or 64 kB. The limit applies across the preconfigured WAF rules in the policy, and 64 kB is the maximum. Content after the limit can reach the backend without WAF body-signature inspection. Google documents the available sizes and provides the policy update command.

Choose the size from the requests the application accepts. Check uploads, GraphQL, JSON APIs and form submissions separately. Google supports parsed URL-encoded and JSON bodies; other content and encodings, including XML, gzip, UTF-16 and multipart form data, receive rules over raw data. The security-policy overview describes the current body parsing behaviour.

Verbose logs include inspectedBodySize, which helps confirm the active limit. Decide how the application handles larger bodies. Google suggests a separate content-length rule when the application can safely reject requests beyond the inspection limit, though Content-Length deserves the same validation you would apply to any client-supplied header.

Identify who manages the policy

Service-level backend security policies attach to backend services. Send their false positives to the team that manages the backend policy.

Hierarchical policies attach at the organization, folder or project level and flow down to projects. Send inherited false positives to the team that manages the hierarchical policy.

Creating a hierarchical security policy requires Cloud Armor Enterprise Paygo and can enrol the project automatically. Google documents the commercial requirement and ownership model in the hierarchical policy guide.

Include the matched policy name and priority in each false-positive report. Give the policy team the field, route and application behaviour needed to review the exception.

Hierarchical and service-level policies support different feature sets. Check the current feature table before moving a tuned rule between them. Google maintains the comparison in its security-policy overview.

Disable preview after reviewing the matches

Run normal traffic, scheduled jobs and important application flows through the preview rule. Classify each recurring signature and field, then disable preview:

gcloud compute security-policies rules update 1000 \
    --security-policy app-policy \
    --no-preview

Cloud Armor rule changes usually take several minutes to propagate. Watch the enforced policy outcome after the change and replay the requests used during tuning. Google lists propagation time among the preconfigured WAF limitations.

Keep the previous expression and exclusions in version control. Record the policy, priority, ruleset version, sensitivity, signature IDs, excluded fields and test requests.

Peakhour.IO - Google Cloud