All the information needed to properly install CRS is presented on this page. The installation concepts are expanded upon and presented in more detail than the quick start guide.
Installing the CRS isn’t very difficult but does have one major requirement: a compatible engine. The reference engine used throughout this page is ModSecurity.
In order to successfully run CRS
3.x using ModSecurity it is recommended to use the latest version available. For Nginx use the
3.x branch of ModSecurity, and for Apache use the latest
Installing a Compatible WAF Engine
Two different methods to get an engine up and running are presented here:
- using the chosen engine as provided and packaged by the OS distribution
- compiling the chosen engine from source
A ModSecurity installation is presented in the examples below, however the install documentation for the Coraza engine can be found here.
Option 1: Installing Pre-Packaged ModSecurity
ModSecurity is frequently pre-packaged and is available from several major Linux distributions.
- Debian: Friends of the CRS project DigitalWave package and, most importantly, keep ModSecurity updated for Debian and derivatives.
- Fedora: Execute
dnf install mod_securityfor Apache + ModSecurity v2.
- RHEL compatible: Install EPEL and then execute
yum install mod_security.
For Windows, get the latest MSI package from https://github.com/SpiderLabs/ModSecurity/releases.
Distributions might not update their ModSecurity releases frequently.
As a result, it is quite likely that a distribution’s version of ModSecurity may be missing important features or may even contain security vulnerabilities. Additionally, depending on the package and package manager used, the ModSecurity configuration will be laid out slightly differently.
As the different engines and distributions have different layouts for their configuration, to simplify the documentation presented here the prefix
<web server config>/ will be used from this point on.
<web server config>/ include:
/etc/apache2in Debian and derivatives
/etc/httpdin RHEL and derivatives
/usr/local/apache2if Apache was compiled from source using the default prefix
C:\Program Files\ModSecurity IIS\(or Program Files(x86), depending on configuration) on Windows
Option 2: Compiling ModSecurity From Source
Compiling ModSecurity is easy, but slightly outside the scope of this document. For information on how to compile ModSecurity, refer to:
- the official ModSecurity documentation on GitHub
- the compilation recipes for ModSecurity v3 on the ModSecurity wiki
- the netnea tutorials for Apache or Nginx
Note that the following configurations are not supported. They do not work as expected. The CRS project recommendation is to avoid these setups:
- Nginx with ModSecurity v2
- Apache with ModSecurity v3
Testing the Compiled Module
Once ModSecurity has been compiled, there is a simple test to see if the installation is working as expected. After compiling from source, use the appropriate directive to load the newly compiled module into the web server. For example:
LoadModule security2_module modules/mod_security2.so
Now restart the web server. ModSecurity should output that it’s being used.
Nginx should show something like:
2022/04/21 23:45:52 [notice] 1#1: ModSecurity-nginx v1.0.2 (rules loaded inline/local/remote: 0/6/0)
Apache should show something like:
[Thu Apr 21 23:55:35.142945 2022] [:notice] [pid 2528:tid 140410548673600] ModSecurity for Apache/2.9.3 (http://www.modsecurity.org/) configured. [Thu Apr 21 23:55:35.142980 2022] [:notice] [pid 2528:tid 140410548673600] ModSecurity: APR compiled version="1.6.5"; loaded version="1.6.5" [Thu Apr 21 23:55:35.142985 2022] [:notice] [pid 2528:tid 140410548673600] ModSecurity: PCRE compiled version="8.39 "; loaded version="8.39 2016-06-14" [Thu Apr 21 23:55:35.142988 2022] [:notice] [pid 2528:tid 140410548673600] ModSecurity: LUA compiled version="Lua 5.1" [Thu Apr 21 23:55:35.142991 2022] [:notice] [pid 2528:tid 140410548673600] ModSecurity: YAJL compiled version="2.1.0" [Thu Apr 21 23:55:35.142994 2022] [:notice] [pid 2528:tid 140410548673600] ModSecurity: LIBXML compiled version="2.9.4" [Thu Apr 21 23:55:35.142997 2022] [:notice] [pid 2528:tid 140410548673600] ModSecurity: Status engine is currently disabled, enable it by set SecStatusEngine to On. [Thu Apr 21 23:55:35.187082 2022] [mpm_event:notice] [pid 2530:tid 140410548673600] AH00489: Apache/2.4.41 (Ubuntu) configured -- resuming normal operations [Thu Apr 21 23:55:35.187125 2022] [core:notice] [pid 2530:tid 140410548673600] AH00094: Command line: '/usr/sbin/apache2'
Microsoft IIS with ModSecurity 2.x
The initial configuration file is
modsecurity_iis.conf. This file will be parsed by ModSecurity for both ModSecurity directives and
Additionally, in the Event Viewer, under
Windows Logs\Application, it should be possible to see a new log entry showing ModSecurity being successfully loaded.
At this stage, the ModSecurity on IIS setup is working and new directives can be placed in the configuration file as needed.
Downloading the OWASP Core Rule Set
With a compatible WAF engine installed and working, the next step is typically to download and install the OWASP CRS. The CRS project strongly recommends using a supported version.
Official CRS releases can be found at the following URL: https://github.com/coreruleset/coreruleset/releases.
For production environments, it is recommended to use the latest release, which is v3.3.4. For testing the bleeding edge CRS version, nightly releases are also provided.
Releases are signed using the CRS project’s GPG key (fingerprint: 3600 6F0E 0BA1 6783 2158 8211 38EE ACA1 AB8A 6E72). Releases can be verified using GPG/PGP compatible tooling.
To retrieve the CRS project’s public key from public key servers using
gpg --keyserver pgp.mit.edu --recv 0x38EEACA1AB8A6E72 (this ID should be equal to the last sixteen hex characters in the fingerprint).
It is also possible to use
gpg --fetch-key https://coreruleset.org/security.asc to retrieve the key directly.
The following steps assume that a *nix operating system is being used. Installation is similar on Windows but likely involves using a zip file from the CRS releases page.
To download the release file and the corresponding signature:
wget https://github.com/coreruleset/coreruleset/archive/refs/tags/v3.3.4.tar.gz wget https://github.com/coreruleset/coreruleset/releases/download/v3.3.4/coreruleset-3.3.4.tar.gz.asc
To verify the integrity of the release:
gpg --verify coreruleset-3.3.4.tar.gz.asc v3.3.4.tar.gz gpg: Signature made Wed Jun 30 10:05:48 2021 -03 gpg: using RSA key 36006F0E0BA167832158821138EEACA1AB8A6E72 gpg: Good signature from "OWASP Core Rule Set <firstname.lastname@example.org>" [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 3600 6F0E 0BA1 6783 2158 8211 38EE ACA1 AB8A 6E72
If the signature was good then the verification succeeds. If a warning is displayed, like the above, it means the CRS project’s public key is known but is not trusted.
To trust the CRS project’s public key:
gpg edit-key 36006F0E0BA167832158821138EEACA1AB8A6E72 gpg> trust Your decision: 5 (ultimate trust) Are you sure: Yes gpg> quit
The result when verifying a release will then look like so:
gpg --verify coreruleset-3.3.2.tar.gz.asc v3.3.2.tar.gz gpg: Signature made Wed Jun 30 15:05:48 2021 CEST gpg: using RSA key 36006F0E0BA167832158821138EEACA1AB8A6E72 gpg: Good signature from "OWASP Core Rule Set <email@example.com>" [ultimate]
With the CRS release downloaded and verified, the rest of the set up can continue.
Setting Up OWASP CRS
OWASP CRS contains a setup file that should be reviewed prior to completing set up. The setup file is the only configuration file within the root ‘coreruleset-3.3.4’ folder and is named
crs-setup.conf.example. Examining this configuration file and reading what the different options are is highly recommended.
At a minimum, keep in mind the following:
- CRS does not configure features such as the rule engine, audit engine, logging, etc. This task is part of the initial engine setup and is not a job for the rule set. For ModSecurity, if not already done, see the recommended configuration.
- Decide what ModSecurity should do when it detects malicious activity, e.g., drop the packet, return a 403 Forbidden status code, issue a redirect to a custom page, etc.
- Make sure to configure the anomaly scoring thresholds. For more information see Anomaly.
- By default, the CRS rules will consider many issues with different databases and languages. If running in a specific environment, e.g., without any SQL database services present, it is probably a good idea to limit this behavior for performance reasons.
- Make sure to add any HTTP methods, static resources, content types, or file extensions that are needed, beyond the default ones listed.
Once reviewed and configured, the CRS configuration file should be renamed by changing the file suffix from
mv crs-setup.conf.example crs-setup.conf
In addition to
crs-setup.conf.example, there are two other “.example” files within the CRS repository. These are:
These files are designed to provide the rule maintainer with the ability to modify rules (see false positives and tuning) without breaking forward compatibility with rule set updates. These two files should be renamed by removing the
.example suffix. This will mean that installing updates will not overwrite custom rule exclusions. To rename the files in Linux, use a command similar to the following:
mv rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf mv rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf
Proceeding with the Installation
The engine should support the
Include directive out of the box. This directive tells the engine to parse additional files for directives. The question is where to put the CRS rules folder in order for it to be included.
Looking at the CRS files, there are quite a few “.conf” files. While the names attempt to do a good job at describing what each file does, additional information is available in the rules section.
Includes for Apache
It is recommended to create a folder specifically to contain the CRS rules. In the example presented here, a folder named
modsecurity.d has been created and placed within the root
<web server config>/ directory. When using Apache, wildcard notation can be used to vastly simplify the
Include rules. Simply copying the cloned directory into the
modsecurity.d folder and specifying the appropriate
Include directives will install OWASP CRS. In the example below, the
modsecurity.conf file has also been included, which includes recommended configurations for ModSecurity.
<IfModule security2_module> Include modsecurity.d/modsecurity.conf Include modsecurity.d/coreruleset-3.3.4/crs-setup.conf Include modsecurity.d/coreruleset-3.3.4/rules/*.conf </IfModule>
Includes for Nginx
Nginx will include files from the Nginx configuration directory (
/usr/local/nginx/conf/, depending on the environment). Because only one
ModSecurityConfig directive can be specified within
nginx.conf, it is recommended to name that file
modsec_includes.conf and include additional files from there. In the example below, the cloned
owasp-modsecurity-crs folder was copied into the Nginx configuration directory. From there, the appropriate include directives are specified which will include OWASP CRS when the server is restarted. In the example below, the
modsecurity.conf file has also been included, which includes recommended configurations for ModSecurity.
include modsecurity.conf include coreruleset-3.3.2/crs-setup.conf include coreruleset-3.3.2/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf include coreruleset-3.3.2/rules/REQUEST-901-INITIALIZATION.conf include coreruleset-3.3.2/rules/REQUEST-903.9001-DRUPAL-EXCLUSION-RULES.conf include coreruleset-3.3.2/rules/REQUEST-903.9002-WORDPRESS-EXCLUSION-RULES.conf include coreruleset-3.3.2/rules/REQUEST-903.9003-NEXTCLOUD-EXCLUSION-RULES.conf include coreruleset-3.3.2/rules/REQUEST-903.9004-DOKUWIKI-EXCLUSION-RULES.conf include coreruleset-3.3.2/rules/REQUEST-903.9005-CPANEL-EXCLUSION-RULES.conf include coreruleset-3.3.2/rules/REQUEST-903.9006-XENFORO-EXCLUSION-RULES.conf include coreruleset-3.3.2/rules/REQUEST-905-COMMON-EXCEPTIONS.conf include coreruleset-3.3.2/rules/REQUEST-910-IP-REPUTATION.conf include coreruleset-3.3.2/rules/REQUEST-911-METHOD-ENFORCEMENT.conf include coreruleset-3.3.2/rules/REQUEST-912-DOS-PROTECTION.conf include coreruleset-3.3.2/rules/REQUEST-913-SCANNER-DETECTION.conf include coreruleset-3.3.2/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf include coreruleset-3.3.2/rules/REQUEST-921-PROTOCOL-ATTACK.conf include coreruleset-3.3.2/rules/REQUEST-930-APPLICATION-ATTACK-LFI.conf include coreruleset-3.3.2/rules/REQUEST-931-APPLICATION-ATTACK-RFI.conf include coreruleset-3.3.2/rules/REQUEST-932-APPLICATION-ATTACK-RCE.conf include coreruleset-3.3.2/rules/REQUEST-933-APPLICATION-ATTACK-PHP.conf include coreruleset-3.3.2/rules/REQUEST-934-APPLICATION-ATTACK-NODEJS.conf include coreruleset-3.3.2/rules/REQUEST-941-APPLICATION-ATTACK-XSS.conf include coreruleset-3.3.2/rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf include coreruleset-3.3.2/rules/REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION.conf include coreruleset-3.3.2/rules/REQUEST-944-APPLICATION-ATTACK-JAVA.conf include coreruleset-3.3.2/rules/REQUEST-949-BLOCKING-EVALUATION.conf include coreruleset-3.3.2/rules/RESPONSE-950-DATA-LEAKAGES.conf include coreruleset-3.3.2/rules/RESPONSE-951-DATA-LEAKAGES-SQL.conf include coreruleset-3.3.2/rules/RESPONSE-952-DATA-LEAKAGES-JAVA.conf include coreruleset-3.3.2/rules/RESPONSE-953-DATA-LEAKAGES-PHP.conf include coreruleset-3.3.2/rules/RESPONSE-954-DATA-LEAKAGES-IIS.conf include coreruleset-3.3.2/rules/RESPONSE-959-BLOCKING-EVALUATION.conf include coreruleset-3.3.2/rules/RESPONSE-980-CORRELATION.conf include coreruleset-3.3.2/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf