Installation

Requirements

CRS 3 requires a web server with ModSecurity. We recommend the following versions:

Download

Our release archives are the preferred way to download the release version 3.3.2:

zip https://github.com/coreruleset/coreruleset/archive/refs/tags/v3.3.2.zip
SHA: 88f336ba32a89922cade11a4b8e986f2e46a97cf
tar.gz https://github.com/coreruleset/coreruleset/archive/refs/tags/v3.3.2.tar.gz
SHA: 63aa8ee3f3c9cb23f5639dd235bac1fa1bc64264

Our next release is in the process of being tested. If you want to help test or preview the latest improvements, download the release candidate 4.0.0-RC1:

zip https://github.com/coreruleset/coreruleset/archive/refs/tags/v4.0.0-rc1.zip
SHA: 49ddee12de42c3de089758a9ee14de9612d6433c
tar.gz https://github.com/coreruleset/coreruleset/archive/refs/tags/v4.0.0-rc1.tar.gz
SHA: 31aac6e253ab102f3cdada4fc318ae8c5af5f7e8

Use Git if you want to test or collaborate on our development branch 4.0:

GitHub https://github.com/coreruleset/coreruleset
Git git clone git@github.com:coreruleset/coreruleset.git

Find more files and GPG signatures at our GitHub release page.

Configuration

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 (inserting your correct path):

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

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

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

In general, you can update by unzipping our new release over your older one, and updating the crs-setup.conf file with any new settings.  However, CRS 3.0 is a major rewrite, 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.

Upgrading from CRS 3.x to CRS 4

The most impactful change is the removal of application exclusion packages in favor of a plugin system. If you had activated the exclusion packages in CRS 3, you should download the plugins for them and place them in the plugins subdirectory. We maintain the list of plugins in our Plugin Registry. You can find detailed information on working with plugins in our plugins documentation.

In terms of changes to the detection rules, the amount of changes is smaller than in the CRS 2—3 changeover. Most rules have only evolved slightly, so it is recommended that you keep any existing custom exclusions that you have made under CRS 3.

We recommend to start over by copying our crs-setup.conf.example to crs-setup.conf with a copy of your old file at hand, and re-do the customizations that you had under CRS 3.

Please note that we added a large number of new detections, and any new detection brings a certain risk of false alarms. Therefore, we recommend to test first before going live.