Peakhour.IO - OWASP CRS

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.

How to Tune Cloudflare WAF When Rule 949110 Blocks a Request

2026-07-29T09:45:00+10:00

Rule 949110 blocked the request.

In Cloudflare's OWASP managed ruleset, 949110: Inbound Anomaly Score Exceeded checks the total score produced by earlier detections. The rules that raised the score explain the block.

Cloudflare puts that answer in Additional logs.

Start with the blocked event

Open Security > Events in the Cloudflare dashboard and filter to the hostname, path, action and time of the request.

Security Events shows traffic that Cloudflare acted on or flagged. Its top-level views group events by fields such as action, host, country and service. The sampled log beneath them contains a subset of individual security events, so a busy time range may hide the request you need. Narrowing the time range reduces sampling. Cloudflare documents the Security Events views and sampling behaviour.

Capture the details that identify the request:

Ray ID;
timestamp;
hostname and path;
method;
WAF service and action;
displayed rule ID and description;
the application result reported by the user.

One request can produce more than one security event. Keep the Ray ID and timestamp together while you follow the detections.

If the displayed description is 949110: Inbound Anomaly Score Exceeded, open Additional logs. Cloudflare places the OWASP rules triggered by that request there. The Security Events documentation describes those contributing OWASP records.

Additional logs deserve a manual check in the dashboard. Cloudflare says triggered OWASP rules shown there are absent from exported Security Events JSON. A log export containing only the final event can therefore leave out the detections that built the anomaly score. The Security Events documentation records that export limitation.

Find the rule that raised the score

Additional logs may show one contributing rule or several. Record each rule's description and Cloudflare rule ID.

The description may begin with a familiar CRS-style number. Cloudflare's API and exception controls use Cloudflare's opaque rule ID. Use the identifier displayed by Cloudflare when you configure the rule.

Group repeated matches by rule, field and route, then review each group with the application owner. A single support message containing SQL syntax may be legitimate. Different paths or different rules belong in separate investigations. The general WAF tuning guide explains how to classify each group and record an exception.

Ask the developer who owns the route:

what input the endpoint accepts;
whether the request was parsed successfully;
where the matching value is stored or rendered;
which validation runs at the application;
whether the field can carry executable syntax by design.

Choose an override or an exception

An override changes the configuration of a managed rule or ruleset across that deployment. You can change an action, disable selected rules or adjust settings such as the OWASP anomaly score threshold and paranoia level.

An exception matches a set of requests and skips selected managed rules for those requests. Its expression can use the host, URI path, method and other Cloudflare Rules language fields.

Use an override when the rule itself needs a different action across the deployment. Use an exception when a known application route needs different treatment.

Cloudflare allows exceptions to skip:

every remaining managed rule;
one or more managed rulesets;
one or more rules inside managed rulesets.

Select the contributing rule. A whole-ruleset exception removes far more inspection from the matching request. Cloudflare documents the three exception types and their order of precedence.

For a false positive confined to message creation, the expression could be:

http.host eq "api.example.com"
and http.request.uri.path eq "/v1/messages"
and http.request.method eq "POST"

Choose the Cloudflare rule ID found in Additional logs as the rule to skip.

Cloudflare skips that rule for the complete matching request. Another field on POST /v1/messages can trigger the same rule and receive the same exception. Record that consequence.

Place the exception before the managed ruleset

An exception works only on managed-ruleset execution rules listed after it in the same phase. Put the skip rule before the rule that executes the OWASP managed ruleset. Cloudflare's API documentation states that skip rules affect only later execute rules.

Cloudflare can run managed rulesets at account level on Enterprise plans and at zone level. Account-level rulesets execute before zone-level rulesets. An account-level exception affects account-level rules, while a zone-level exception affects zone-level rules. A zone exception cannot prevent an account-level rule from matching first. Cloudflare documents this scope and evaluation order.

Find the execute rule that produced the event. Add the exception at that level and before that execution. If the OWASP ruleset runs at both levels, inspect both deployments and decide which one needs the exception.

Exceptions take priority over overrides. Cloudflare records that precedence in its managed-ruleset documentation.

Test the exception through Cloudflare

Send the original legitimate request through the hostname proxied by Cloudflare. An origin-only replay bypasses the configuration you are testing.

Use a small test set:

the legitimate request on the exempt route;
the same input on another route;
a safe request that triggers the contributing rule on the exempt route;
the same test outside the exception;
normal traffic that should pass unchanged.

Check Security Events after each request. Confirm the Ray ID, action, contributing rules and final result.

The safe trigger on the exempt route shows what the exception allows. The same trigger outside the exception should still raise the contributing rule and reach 949110.

Cloudflare evaluates security products and rules in a defined sequence, and a terminating action stops later evaluation. An earlier custom-rule Block or Managed Challenge can determine the result before Managed Rules run. Cloudflare's WAF concepts guide describes this rule execution behaviour.

Set the anomaly threshold from real traffic

The OWASP anomaly threshold is the cumulative request score at which 949110 applies the configured action. Raising it moves the block point for every request covered by that deployment.

Use Security Events to see which rules contribute to normal requests before changing the threshold. A repeated false positive from one rule and one endpoint points towards an exception. A broad pattern of low-confidence detections may justify a threshold or paranoia-level review.

Cloudflare supports overrides for the full ruleset, rule tags and individual rules. Tag and ruleset overrides can also affect future rules that Cloudflare adds under those selections. Individual rule overrides target the rule IDs you chose. The managed-ruleset documentation explains these override levels.

Test a threshold change with the same care as a rule exception. It changes when 949110 acts across all covered traffic.

Record the exception and its rule IDs

Document:

the Ray IDs and event times reviewed;
the contributing Cloudflare rule IDs and descriptions;
the anomaly threshold and paranoia level;
the exception expression;
the account or zone deployment it belongs to;
its position before the managed-ruleset execute rule;
what the selected rule stops inspecting;
the developer who confirmed the application behaviour;
the requests used for verification;
the review date.

Recheck the exception after application changes and Cloudflare managed-rule updates. A new route can need different conditions. A revised rule can remove the original false positive.

Rule 949110 applies the configured action when the anomaly score crosses the threshold. Tune the rules that supplied the false-positive score.

How to Tune Coraza on Caddy

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

Coraza sits inside another server. The connector presents each request to Coraza, Coraza runs the rules and the connector applies the result.

Handler order decides whether Coraza sees the request in time. Body handling decides which fields the rules can inspect. The logging phase decides what you can investigate later.

The example deployment runs Coraza as Caddy middleware with OWASP Core Rule Set. The same CRS tuning principles apply to other Coraza connectors. Their installation, request handling and logging need their own tests.

Put Coraza in the request path

The official Caddy module is compiled into Caddy:

xcaddy build --with github.com/corazawaf/coraza-caddy/v2

The module documentation requires order coraza_waf first in the global options block, which places Coraza at the start of Caddy's HTTP handler order.

{
    order coraza_waf first
}

api.example.com {
    coraza_waf {
        load_owasp_crs
        directives `
            Include @coraza.conf-recommended
            SecRuleEngine DetectionOnly

            SecAuditEngine RelevantOnly
            SecAuditLog /var/log/coraza/audit.log
            SecAuditLogFormat JSON
            SecAuditLogType Serial
            SecAuditLogParts ABFHZ

            Include @crs-setup.conf.example
            Include @owasp_crs/*.conf
        `
    }

    reverse_proxy app:8080
}

The Caddy connector's load_owasp_crs option exposes the embedded Coraza CRS files. The three Include lines then load the recommended Coraza configuration, the CRS setup and the rules.

Coraza also supports CRS files installed on disk. A file-based installation loads the Coraza configuration first, crs-setup.conf second and the CRS rule files last. Choose one source for CRS and record its version so you can compare rule changes during an upgrade.

SecRuleEngine DetectionOnly runs the rules and suppresses disruptive actions such as deny, drop and redirect. Legitimate requests can complete while you collect matches. Coraza sets SecRequestBodyLimitAction to ProcessPartial in this mode. Watch INBOUND_DATA_ERROR because part of an oversized body may remain uninspected.

Test the Caddy configuration before reloading it. Then send a safe request that triggers a known CRS rule through the public listener. Confirm that the Coraza event appears and the request reaches the upstream in DetectionOnly.

Configure the Coraza audit log

The Caddy access log tells you that a request happened. The Coraza audit log tells you which WAF rule matched.

SecAuditEngine RelevantOnly records transactions that produced a warning or error, along with response statuses selected by SecAuditLogRelevantStatus. CRS rules normally carry the auditlog action, so their matches can enter the audit log.

The example uses Coraza's JSON audit format and leaves request-body part C out of SecAuditLogParts. Request bodies often contain passwords, personal information and customer text. Add body logging only for a controlled investigation, then remove it.

The serial audit log in the example is convenient during initial tuning. Coraza warns that serial logging can slow the server because transactions share one file.

Concurrent, HTTPS and syslog outputs suit deployments that need another destination. Send the records to a protected log system with rotation, retention limits and restricted access.

Start each investigation with these fields:

request time and transaction ID;
hostname, method and URL;
rule ID and message;
CRS tags such as attack-sqli or attack-xss;
matched variable name;
matched data;
request and response status.

The variable name identifies the input to investigate. ARGS:message identifies an application field. REQUEST_COOKIES:campaign identifies a cookie.

Handle matched data as customer data. Keep enough to reproduce the result, then retain the rule ID, field name and explanation in the permanent exception record.

Check what Coraza parsed

CRS can inspect only the fields Coraza extracted from the request.

SecRequestBodyAccess On enables body buffering and processing. The selected processor determines which collections phase 2 rules can inspect. URL-encoded forms, multipart forms, JSON and XML produce different variables.

For an unexpected body match, record:

the request Content-Type;
REQBODY_PROCESSOR;
REQBODY_ERROR and REQBODY_ERROR_MSG;
INBOUND_DATA_ERROR;
the matched variable name.

Coraza's current body-processing documentation shows processor selection by content type. The ctl:requestBodyProcessor reference still describes explicit phase 1 selection for JSON and XML. Check REQBODY_PROCESSOR on the Coraza version and connector you run, then select the processor explicitly when the expected processor is missing.

A parsing error deserves its own investigation. Coraza documents the risk plainly: the application may accept a body that Coraza's parser rejected. Compare the application's parser with Coraza using the same bytes. Fix a wrong content type or processor selection before writing a rule exclusion.

Body limits need the same care. SecRequestBodyLimitAction ProcessPartial inspects the bytes that fit within the limit and sets INBOUND_DATA_ERROR. Raise a limit when the application legitimately accepts larger bodies and the deployment can buffer them safely. Keep an alert for the limit condition so partial inspection remains visible.

Load exclusions in the correct order

CRS provides two places for local exclusions.

Use the general WAF tuning guide to classify the match and define the exception. Load that exception according to the CRS rule order below.

A runtime exclusion runs for matching transactions. Load it before CRS so it can change the transaction before the affected rule executes. CRS includes REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example for this purpose.

A configure-time exclusion changes a loaded rule. Load it after CRS so the rule already exists. CRS includes RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example for these changes.

Keep both files outside the CRS distribution. An upgrade can then replace CRS without replacing your application decisions.

The order in a Caddy deployment looks like this:

directives `
    Include @coraza.conf-recommended
    SecRuleEngine DetectionOnly
    Include @crs-setup.conf.example

    Include /etc/coraza/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf
    Include @owasp_crs/*.conf
    Include /etc/coraza/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf
`

With load_owasp_crs enabled, the Caddy connector merges the embedded CRS filesystem with the operating-system filesystem. The configuration can include embedded @ files and local /etc/coraza exclusion files.

The CRS tuning guide explains the before-and-after placement and the available exclusion actions.

Exclude the field that caused the match

Suppose POST /api/jobs accepts a JSON array. Rule 932125 repeatedly matches legitimate text in each jobDescription field. In this example, the audit log reports variable names such as ARGS:json.0.jobdescription and ARGS:json.1.jobdescription.

Coraza accepts a regular expression for the collection key in ctl:ruleRemoveTargetById:

# REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf
# Local rule ID 10010 must be unique in this deployment.
SecRule REQUEST_FILENAME "@streq /api/jobs" \
    "id:10010,phase:1,pass,nolog,t:none,chain"
    SecRule REQUEST_METHOD "@streq POST" \
        "t:none,ctl:ruleRemoveTargetById=932125;ARGS:/^json\.\d+\.jobdescription$/"

This local rule runs only for POST /api/jobs. Rule 932125 continues to inspect every other field in those requests and every field on other routes.

The /pattern/ form is a Coraza feature. The Coraza action reference states that collection-key matching is case-insensitive because Coraza lowercases variable names. Use an exact key such as ARGS:message when the application has one fixed field. A regular expression earns its place when the application produces a documented family of field names.

A field can trigger several rules in one attack class. Coraza also supports ctl:ruleRemoveTargetByTag, for example:

ctl:ruleRemoveTargetByTag=attack-sqli;ARGS:message

The exception removes the named field from every rule carrying the literal attack-sqli tag. Record that scope and confirm that the application protects the field through parameterised queries and suitable validation.

Configure-time exclusions suit fields with the same meaning everywhere:

# RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf
SecRuleUpdateTargetById 942100 "!REQUEST_COOKIES:campaign"

This removes one named cookie from rule 942100 throughout the configuration. A route-specific runtime exclusion is the better starting point for an application field.

Check where a chained rule reads the field

Some CRS detections are chained rules. The first rule starts the chain and later rules add conditions.

The CRS tuning documentation states that target exclusions by ID affect only the first rule in a chain. An exclusion will have no effect when the field is inspected by a later chain member. Removing the complete rule may be the available answer.

Find the rule in the CRS version you deployed. Check where the target appears in the chain. Then replay the request against that exact version. The rule source and replay result settle the question.

Replay the request before and after

Save the legitimate request that produced the false positive. Preserve its method, path, query string, content type, important headers and body bytes. Replace credentials and personal data with values that reproduce the same match.

For example:

curl --silent --show-error \
    --dump-header before.headers \
    --output before.body \
    --request POST \
    --header 'Content-Type: application/json' \
    --data-binary @false-positive.json \
    https://api.example.com/api/jobs

Run it once in DetectionOnly before adding the exclusion. Confirm that:

the application returns its normal response;
the audit log contains the expected rule ID;
the log names the expected field;
the request body has no parser or size error.

Add the exclusion, validate the Caddy configuration and reload it. Send the same request bytes again:

curl --silent --show-error \
    --dump-header after.headers \
    --output after.body \
    --request POST \
    --header 'Content-Type: application/json' \
    --data-binary @false-positive.json \
    https://api.example.com/api/jobs

The application response should stay the same. The false-positive match should disappear for the excluded field.

Now send a control request that places a known CRS test value in another field on the same route. Rule 932125 should still inspect that field. Send the original test value to another route as well. The rule should still inspect it there.

Expect these results:

the legitimate request works;
the rule still reads neighbouring fields;
the rule still runs on other routes.

Keep the request fixtures in a protected test repository. Run them after Coraza, CRS, Caddy or application upgrades.

Switch Coraza from DetectionOnly to On

Switch SecRuleEngine to On in a staging environment after the common legitimate flows run without unexplained matches. Repeat the false-positive replay, the neighbouring-field control and the application's critical user journeys.

Enable blocking for a limited production audience or hostname when the deployment allows it. Watch WAF responses, upstream errors and business transactions together. A clean audit log has little value when checkout or login has stopped working.

Document every exception beside the configuration:

who approved it;
the affected hostname, method and route;
the rule ID or tag;
the excluded field;
the request that reproduced the match;
the controls that still inspect or validate the field;
the date and CRS version tested.

How to Tune Your WAF Without Turning It Off

2026-07-28T10:30:00+10:00

The OWASP Core Rule Set has never seen your application.

Generic patterns let it recognise common signs of SQL injection, cross-site scripting and protocol attacks. Tuning teaches it that your application stores a search expression in JSON, accepts links in a message field or receives an analytics cookie full of punctuation.

So a new deployment will be noisy.

Faced with that noise, teams often leave the WAF in log-only mode forever or disable each rule that causes a complaint. Teams need a repeatable route from noisy alerts to safe blocking.

The work is repetitive and fairly unglamorous: observe real traffic, group related matches, understand the application field involved, write the narrowest safe exception and repeat until legitimate traffic no longer triggers unexplained alerts.

Start in detection-only mode

Introduce the full OWASP CRS to an existing production application in detection-only mode.

On ModSecurity or Coraza, set SecRuleEngine DetectionOnly. The engine records what the rules would have denied, dropped or redirected while allowing the requests through.

Both engines support this rollout. The ModSecurity FAQ recommends detection-only mode for a new ruleset, and Coraza implements the same setting.

Run it long enough to see the application's real shape. Allow at least a full week, and often one to two weeks, so the sample includes business days, a weekend and any less frequent jobs, imports or campaigns.

Exercise authenticated actions, checkout, password reset, messaging, file upload, API writes and administrative tools manually because ordinary browsing may never reach them.

Detection mode records rule matches while passing every request through, including attacks. Decide in advance what needs to be true before you enable blocking.

What changes between WAF products

The examples below use SecLang and OWASP CRS because they expose the rule ID, attack class and request field that caused a match. Managed WAFs record much the same information under different names, with varying precision for exceptions.

Coraza also runs CRS 4. It is a Go implementation of SecLang, and the CRS project recommends it for new CRS 4 deployments. The Coraza tuning guide covers its audit logging, connectors and runtime exclusions in more detail.

Body processors and chained rules can behave differently between engines and web-server connectors. Replay the requests that caused the false positive through the engine and connector that handle production traffic.

Tuning job	SecLang / CRS	Managed WAF examples
Observe without blocking	`SecRuleEngine DetectionOnly`	Azure Detection mode, AWS rule-action override to Count, Google Cloud Armor preview
Identify the detection	numeric rule ID and message	managed rule ID or name
Identify the class	CRS tag such as `attack-sqli`	rule group, category or emitted label
Identify the input	`REQUEST_COOKIES:name`, `ARGS:field`, header or body target	matched request component or exclusion selector
Narrow the exception	target removal by ID or tag, optionally limited to a route	field exclusion, per-rule exception, label-based follow-on rule or rule skip limited by request conditions

The last row is where the products differ most. ModSecurity and Coraza can stop one rule from inspecting one field on one route. Some managed WAFs can only skip the whole rule for requests matching that route. If that is the smallest exception available, write down exactly what the WAF will stop inspecting and decide whether the route is safe without that rule.

Group alerts before reviewing them

Reviewing WAF alerts one at a time hides repeated false positives.

The same harmless field may trigger the same rule across thousands of requests. Conversely, two alerts with the same rule ID may come from completely different application behaviours and need different decisions.

Group events using at least:

hostname and URL;
HTTP method;
CRS rule ID;
rule class or attack tag, such as attack-sqli or attack-xss;
matched-data variable, including its collection and exact name;
WAF action and response status;
event count, distinct clients and spread over time.

For example, REQUEST_COOKIES:analytics_id is much more useful than “SQL injection rule fired”. So is ARGS:message on POST /api/messages.

The rule ID tells you which detection fired. The attack class tells you which protection an exception would weaken. The matched variable identifies the request field that caused it. The URL and method show where the application uses that field.

Keep a few examples of the matched values long enough to investigate them, but handle them carefully. Request fields can contain credentials, personal information and customer content. The exception record usually needs the variable name and an explanation, not a permanent copy of the raw value.

Expect false positives in a few places

A few kinds of input generate most legitimate matches.

Request cookies

Marketing, attribution, experimentation and client-state cookies often contain encoded or structured values. A generic SQLi, PHP or local-file-inclusion rule may find a suspicious fragment even though the application never treats that cookie as executable input.

Keep inspection active for the REQUEST_COOKIES collection and exclude only the cookie that caused the false positive.

Identify the cookie name, the rules or attack classes it triggers, the routes where it appears, how often it occurs and whether those requests complete normally. If REQUEST_COOKIES:analytics_id repeatedly triggers the same attack class for legitimate requests, consider an exception for that cookie alone.

Cookie names need separate treatment. A rule matching REQUEST_COOKIES_NAMES inspects the names. Capture the exact name safely before writing the exclusion.

Unparsed or malformed request bodies

Parser errors deserve their own investigation.

When a selected body processor cannot parse a body, ModSecurity and Coraza set REQBODY_ERROR. Record the Content-Type and observed REQBODY_PROCESSOR because JSON and XML processor selection varies by engine, connector and version. Confirm that a processor ran before relying on the error flag.

A body that exceeds the configured inspection limit is a different case. It sets INBOUND_DATA_ERROR and may be inspected only partially. In either case, part of the body may go uninspected, and an attacker can deliberately probe that behaviour.

Ask the developer who owns the endpoint what it is meant to accept. Fix incorrect content types and body-processor configuration, reproduce the request, then check whether the application and WAF parse it the same way.

Keep request-body inspection active for the application. Limit any parser exception to the host, URL, method and body behaviour you investigated.

Free-text fields

Messages, descriptions, comments, support tickets and search boxes are expected to contain language that resembles attack syntax. A customer can discuss SQL without attempting SQL injection. A marketplace listing can contain shell characters. A support message can include a URL.

Exclude the named field on the affected route and keep inspection active for the rest of the request body.

For example, the SecLang rule below removes ARGS:message from every rule tagged attack-sqli on the messaging endpoint. That is appropriate only if you have decided that SQLi inspection is too noisy for this field across the whole class. Every other argument still receives SQLi inspection, and scam, malicious-link or other attack classes can continue inspecting the message.

Bring in the developer who owns the endpoint. They can confirm whether the field is genuinely free text, where it is stored or rendered, what server-side validation exists and which security checks still need to see it.

Application-specific structured fields

Some applications accept query languages, filters, templates, product metadata or nested JSON that naturally looks like code. The syntax may be legitimate, but these fields still deserve careful review before they are excluded.

Confirm the schema and business use before creating an exception. Check that MATCHED_VAR_NAME identifies one field, then use that exact named target. Nested JSON naming varies between engines and integrations. Keep SQLi inspection active for the rest of the API when one structured field needs an exception.

Make the smallest exception that works

Work down this list and stop as soon as the known false positive is fixed:

host, exact URL, method, rule ID or attack class, and exact named variable;
host, reviewed URL family, method, class, and named variable;
host, exact URL and rule ID;
host, rule ID;
global named-variable exclusion.

Start with the first option. Move further down only when the logs and the application design justify a wider exception.

A global exception can make sense for a named cookie or header that has no security meaning anywhere in the application. Before adding one, make sure the false positive appears across several routes and clients, and that those requests complete normally. Ask the development team to confirm that no backend interprets the field.

Even then, remove only that named field from the relevant rule or attack class. An exception for REQUEST_COOKIES:analytics_id removes one known input from SQLi inspection. An exception for the whole cookie collection removes every cookie.

Reserve global exceptions for logs that identify the matched field. Unknown body fields, unresolved cookie names and parser failures need manual investigation.

Keep your exceptions outside CRS

Put application-specific exceptions in local configuration and leave the Core Rule Set files unchanged. This keeps CRS upgrades separate from changes made for your application.

To stop one rule inspecting a named field everywhere, ModSecurity and Coraza support:

SecRuleUpdateTargetById 942100 "!REQUEST_COOKIES:analytics_id"

Load this directive after the CRS rules because the engine must load a rule before updating it.

For a route-specific exception, use a runtime control before the CRS rule executes:

# Load before CRS, normally from REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.
# Use this rule only for api.example.com.
# Confirm that local rule ID 10001 is unused.
SecRule REQUEST_FILENAME "@streq /api/messages" \
    "id:10001,phase:1,pass,nolog,t:none,chain"
    SecRule REQUEST_METHOD "@streq POST" \
        "t:none,ctl:ruleRemoveTargetByTag=attack-sqli;ARGS:message"

With this exception, SQLi rules stop reading ARGS:message only on POST /api/messages. They still inspect other fields and routes, while other attack classes can continue inspecting the message.

The CRS false-positive tuning guide documents configure-time and runtime exclusions by rule ID or tag. The attack-sqli selector above is a literal tag that works with both ModSecurity and Coraza. ModSecurity runtime target selectors accept literal collection keys. Coraza also accepts regular expressions for collection keys, using /pattern/ syntax.

A target exclusion may affect only the first rule in a chained CRS detection. Test the exact rules and requests on your deployed engine before relying on the exception.

Use rule IDs or exact attack-class tags. Rule messages can change and may contain request data.

Managed WAFs expose different controls

Each managed provider expresses the exception differently.

AWS Managed Rules can emit a label while an offending rule runs in Count mode. A later custom rule can block that label everywhere except the route that produced the false positive. The exception affects enforcement for the whole managed rule on that route. How to Tune AWS WAF follows that evaluation path from the first counted request to restored blocking.

Azure Application Gateway WAF can exclude a named cookie, header or argument from a particular managed rule. Its request exceptions can instead skip a selected rule for matching traffic, and that feature is currently in preview. A custom Allow rule bypasses the managed CRS, DRS and bot rules for the request. How to Tune Azure Application Gateway WAF shows how to choose among those controls.

Cloudflare exceptions skip a selected managed rule for the whole matching request. Security Events may show rule 949110 as the blocking event because it checks the final anomaly score; Additional logs identify the rules that added that score. How to Tune Cloudflare WAF covers that investigation and the ordering of account-level and zone-level exceptions.

Google Cloud Armor can exclude a named request field from a versioned OWASP signature. Route-specific tuning also depends on the security-policy expression and rule priority, because a general WAF rule may inspect the same request later. How to Tune Google Cloud Armor covers preview, signature selection and field exclusions.

F5 BIG-IP Advanced WAF separates policy enforcement mode, violation actions and signature or entity staging. Its overrides can target a URL parameter, cookie, content profile, URL or the whole policy. How to Tune F5 BIG-IP Advanced WAF follows those controls from Transparent mode to tested blocking.

Provider interfaces, ruleset versions and preview features change. Record the rule name or versioned signature, the field or request being exempted and what the WAF will still inspect. Test the requests that led to the exception before enabling it.

Iterate until the false positives are gone

After adding an exception, group the alerts again. Check whether that false-positive pattern disappeared, whether a related rule started matching the same field and whether another route was affected. Look for legitimate flows that the first observation window missed.

Repeat the cycle:

collect detection-only traffic that covers normal application use;
group by route, method, rule ID, rule class and named variable;
classify abusive traffic separately from legitimate matches;
create or narrow exceptions;
rerun automated and manual application flows;
collect another window.

Aim for zero known false positives in the traffic you observed and the critical flows you tested. A new endpoint, cookie, client or release can produce fresh false positives tomorrow.

Use a higher anomaly threshold only during tuning because it can allow attacks that the normal threshold would have blocked. Write an exception for the rule and field causing the false positive, then return to the intended threshold.

Document every exception

Give every exception an owner, a reason and a review date.

Record:

hostname, URL or URL family, and HTTP method;
CRS version, rule IDs and attack-class tags;
matched collection and exact variable name;
sample event IDs and observation window;
why the traffic is legitimate;
which customer or application flow depends on it;
what protection is removed and what remains active;
developer and security approvers;
date introduced and next review date;
the release, incident or ticket associated with the change.

Keep the exception under version control. Give it a description that another engineer can understand without finding the original chat thread. Review it after CRS upgrades because rule IDs, paranoia levels and rule behaviour can change. The CRS project specifically recommends returning to detection mode long enough to exercise normal traffic after a major migration.

Remove an exception when the application no longer needs it. If the application changes its cookie, parser or validation, restore inspection.

Decide what a WAF hit should do

Security and application owners must decide which matches to log, block, rate limit, challenge or review.

With CRS anomaly scoring, an individual rule normally adds to a transaction score. The WAF blocks when the inbound score crosses the configured threshold, allowing several weak signals to add up before a customer is blocked.

Decide which outcomes you need:

Log: useful during tuning and for low-confidence signals.
Block: appropriate when several signals point to an attack and the affected flow has been tested.
Rate limit: useful for repeated behaviour across several requests.
Challenge or step up: where the product supports it, useful for browser and account flows where a hard block would be unnecessarily disruptive.
Review: appropriate for high-value actions where context matters more than a generic signature.

Respond to a single SQLi alert at the request level. Shared networks, mobile carriers and proxies make IP identity unreliable. Repeated WAF hits on the same route can inform a rate limit, but the limit should use the best available client, session or account key and have a clear window.

Track WAF blocks and rate limits separately. A ModSecurity or Coraza block commonly returns 403; a rate limit commonly returns 429. If the logs say the WAF blocked a request but the origin returned success, find out why before trusting the enforcement reports.

Recheck the WAF after application releases

A release may add an endpoint, rename a field, introduce GraphQL, change JSON shape, add a marketing cookie or move validation between services. Any of those changes can make an old exception too broad or cause a new legitimate field to trigger CRS.

Include the development team in the release process:

list new or changed public routes and methods;
identify free-text, upload and structured fields;
run staging traffic through the same CRS configuration;
test authenticated and high-value journeys;
watch the grouped detections during the production rollout;
give new or substantially changed routes an observation period before enforcing new rules on them;
review whether old exceptions can be removed.

For major CRS upgrades, treat the ruleset itself as a release. A ruleset upgrade can change rule IDs and anomaly-score behaviour while the application stays the same.

Know when tuning is complete

A traditional WAF is ready to enforce when:

normal production traffic, including the less common application flows, has been reviewed;
critical application flows have been tested with developers;
every high-volume legitimate match has a documented, narrow exception;
parser failures and unresolved matched variables have named owners and specific resolutions;
WAF blocks produce the expected response;
rate limiting is handled separately from payload detection;
exceptions are versioned, approved and reviewable;
new rules and releases can be observed before they start blocking.

Once those checks pass, enable blocking in stages and keep watching the same groups of alerts. Revisit the exceptions whenever the application or ruleset changes.

For the broader decision about where a WAF helps and where it does not, see When and Why to Use a WAF. You can also read about Peakhour's web application firewall.