Configuration Settings

CRS is configured through crs-setup.conf. This page lists every setting in that file, its default, and when to change it. It is a reference; the concepts behind the main settings are explained in the other pages of this chapter.

How Settings Work

The file crs-setup.conf.example ships with every release. Copy it to crs-setup.conf and include it before the rule files, as described in the installation guide.

Almost every setting is a SecAction rule with an ID in the 900xxx range that sets a transaction variable with setvar. Most of these rules are commented out: the rule file REQUEST-901-INITIALIZATION.conf applies the default value whenever a variable has not been set. To change a setting, uncomment its rule in crs-setup.conf and edit the value.

Default Actions

Plain SecDefaultAction directives at the top of the file set the engine behavior for rules that don’t specify their own. Since CRS 4.28.0 a default is set for every phase, so phases 3 to 5 (response and logging) log the same way as the request phases:

SecDefaultAction "phase:1,log,auditlog,pass"
SecDefaultAction "phase:2,log,auditlog,pass"
SecDefaultAction "phase:3,log,auditlog,pass"
SecDefaultAction "phase:4,log,auditlog,pass"
SecDefaultAction "phase:5,log,auditlog,pass"

The default pass action is what makes anomaly scoring work: individual rules only add to the score and the blocking decision is taken at the end of the phase. Replace log with nolog to write alerts only to the audit log. Changing pass to deny switches to self-contained mode, which is discouraged.

Anomaly Scoring

See anomaly scoring for the concepts.

Paranoia Levels

See paranoia levels for the concepts.

HTTP Policy

These settings feed the protocol enforcement rules in REQUEST-920-PROTOCOL-ENFORCEMENT.conf. Lists use a delimiter around each entry so that the @within operator matches exactly: pipes for content types and charsets, slashes for file extensions and headers, spaces for methods and versions.

Allowed Content Types

The default list is:

|application/x-www-form-urlencoded| |multipart/form-data| |text/xml| |application/xml| |application/soap+xml| |application/json|

In addition, two rules in REQUEST-901-INITIALIZATION.conf extend this list at runtime since CRS 4.30.0, and switch on the JSON body processor in the same rule so there is no bypass risk:

• Rule 901370 allows any application/*+json type (RFC 6839 structured syntax suffix), for example application/ld+json, application/problem+json, or application/vnd.api+json.
• Rule 901360 allows the AWS types application/x-amz-json-1.0 and application/x-amz-json-1.1.

To turn either off, remove the rule with ctl:ruleRemoveById the same way as any other CRS rule. Content types without a corresponding body processor, such as text/plain or application/octet-stream, must never be added to the list without also forcing a body processor; see example 9 in false positives and tuning.

Restricted Headers

The default basic list blocks headers that let a client alter how the request is processed: content-encoding, proxy, lock-token, content-range, if, x-http-method-override, x-http-method, x-method-override, x-middleware-subrequest, and expect. The expect entry blocks Expect-based request smuggling. .NET’s HttpWebRequest sends this header by default; set ServicePointManager.Expect100Continue to false in the client if that is a problem.

Request Body Processing

Argument and Upload Limits

Enforced by rules 920360 to 920410 at paranoia level 1.

Other Settings