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.

Peakhour.IO - Caddy