Peakhour.IO - Coraza

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.