Installation

CRS 3 requires an Apache/IIS/Nginx web server with ModSecurity 2.8.0 or higher.

Our GitHub repository is the preferred way to download and update CRS.

HTTPS git clone https://github.com/SpiderLabs/owasp-modsecurity-crs.git
SSH git clone [email protected]:SpiderLabs/owasp-modsecurity-crs.git

After download, copy crs-setup.conf.example to crs-setup.conf. Optionally edit this file to configure your CRS settings. Then include the files in your webserver configuration:

Include /.../crs-setup.conf
Include /.../rules/*.conf

For detailed installation instructions, see the INSTALL document. Also review the CHANGES and KNOWN_BUGS documents.

You can update the rule set using the included script util/upgrade.py.

Handling False Positives and Advanced Features

Advanced features are explained in the crs-setup.conf and the rule files themselves. The crs-setup.conf file is generally a very good entry point to explore the features of the CRS.

We are trying hard to reduce the number of false positives (false alerts) in the default installation. But sooner or later, you may encounter false positives nevertheless.

Christian Folini’s tutorials on installing ModSecurity, configuring the CRS and handling false positives provide in-depth information on these topics.

Upgrading from CRS 2.x to CRS 3

CRS 3 is a major release, incompatible with CRS 2.x. Key setup variables have changed their name, and new features have been introduced. Your former modsecurity_crs_10_setup.conf file is thus no longer usable. We recommend you to start with a fresh crs-setup.conf file from scratch.

Most rule IDs have been changed to reorganize them into logical sections. This means that if you have written custom configuration with exclusion rules (e.g. SecRuleRemoveById, SecRuleRemoveTargetById, ctl:ruleRemoveById or ctl:ruleRemoveTargetById) you must renumber the rule numbers in that configuration. You can do this using the supplied utility util/id_renumbering/update.py or find the changes in util/id_renumbering/IdNumbering.csv.

However, a key feature of the CRS 3 is the reduction of false positives in the default installation, and many of your old exclusion rules may no longer be necessary. Therefore, it is a good option to start fresh without your old exclusion rules.

If you are experienced in writing exclusion rules for CRS 2.x, it may be worthwhile to try running CRS 3 in Paranoia Level 2 (PL2). This is a stricter mode, which blocks additional attack patterns, but brings a higher number of false positives — in many situations the false positives will be comparable with CRS 2.x. This paranoia level however will bring you a higher protection level than CRS 2.x or a CRS 3 default install, so it can be worth the investment.