_____ _____ _____ ____ / ____| __ \ / ____| |___ \ | | | |__) | (___ __) | | | | _ / \___ \ |__ < | |____| | \ \ ____) | ___) | \_____|_| \_\_____/ |____/ OWASP Core Rule Set 3.x Installing ModSecurity ===================== This document does NOT detail how to install ModSecurity. Rather, only information pertaining to the installation of the OWASP Core Rule Set (CRS) is provided. However, ModSecurity is a prerequisite for the CRS installation. Information on installing ModSecurity can be found within the ModSecurity project at https://github.com/SpiderLabs/ModSecurity or at ModSecurity.org. Installing From a Package Manager ================================= The OWASP Core Rule Set (CRS) is available from many sources. On multiple platforms this includes package managers. These packages are maintained by independent packagers who package CRS in their own time. Historically, many of these packages have been out of date. As such, it is recommended that you install, where possible, from our GitHub repository. The following packages are known to exist: *There are currently no known packages of CRS 3.x.* Packages of CRS 2.0 are incompatible with CRS 3.x. Installing From Git =================== Github is the preferred way to download and install CRS. Doing so insures that you have the most recent version of the rules. We encourage you to create scripts that will automatically download updates at regular intervals so that you may be protected against the latest threats that CRS adds protection for. The script util/upgrade.py is an example for script. You can use it as follows: ``` ./util/upgrade.py --crs ``` Prerequisites ------------- CRS is designed to be used with ModSecurity (although many other projects also use the provided rules). CRS version 3.x is designed for ModSecurity 2.8 or above. CRS version 3.x makes use of libinjection and libXML2. Failure to provide these prerequisites may result in serious false negatives and CRS version 3.x should NOT be run without these. Note, however, that libinjection is bundled with ModSecurity since version 2.8. Additionally, if you are downloading from the GitHub repo you will need to install 'git' on your system. Upgrading from CRS 2.x ---------------------- CRS 3.x is a major release incompatible with CRS 2.x. The rule IDs have changed. The file id_renumbering/IdNumbering.csv contains a list with old and new rule IDs. However, a key feature of the release 3.x is the reduction of false positives in the default installation and we recommend you start with a fresh install from scratch. Key parameter 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 install from scratch. Installing on Apache -------------------- 1. Install ModSecurity for Apache 2. Ensure that ModSecurity is loading correctly by checking error.log at start up for lines indicating ModSecurity is installed. An example might appear as follows: ```ModSecurity for Apache/2.9.1 (http://www.modsecurity.org/) configured.``` 3. The most common method of deploying ModSecurity we have seen is to create a new folder underneath the Apache directory (typically /usr/local/apache/, /etc/httpd/, or /etc/apache2). Often this folder is called 'modsecurity.d'. Create this folder and cd into it. 4. Clone the repository into the modsecurity.d folder using: ```git clone https://github.com/SpiderLabs/owasp-modsecurity-crs .``` This will create a new owasp-modsecurity-crs folder. 5. Move the crs-setup.conf.example file to crs-setup.conf. Please take the time to go through this file and customize the settings for your local environment. Failure to do so may result in false negatives and false positives. See the section entitled OWASP CRS Configuration for more detail. 6. Rename rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example and rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example to remove the '.example' extension. This will allow you to add exclusions without updates overwriting them in the future. 7. Add the following line to your httpd.conf/apache2.conf (the following assumes you've cloned CRS into modsecurity.d/owasp-modsecurity-crs). You can alternatively place these in any config file included by Apache: ``` Include modsecurity.d/owasp-modsecurity-crs/crs-setup.conf Include modsecurity.d/owasp-modsecurity-crs/rules/*.conf ``` 8. Restart web server and ensure it starts without errors 9. Make sure your web sites are still running fine. 10. Proceed to the section "Testing the Installation" below. Installing on Nginx ------------------- 1. Compile ModSecurity into Nginx 2. Ensure that ModSecurity is loading correctly by checking error.log at start up for lines indicating ModSecurity is installed. An example might appear as follows: ```ModSecurity for nginx (STABLE)/2.9.1 (http://www.modsecurity.org/) configured.``` 3. The most common method of deploying ModSecurity we have seen is to create a new folder underneath the Nginx directory (typically /usr/local/nginx/conf/). Often this folder is called 'owasp-modsecurity-crs'. Create this folder and cd into it. 4. Clone the repository into the current folder using: ```git clone https://github.com/SpiderLabs/owasp-modsecurity-crs .``` 5. Move the crs-setup.conf.example file to crs-setup.conf. Please take this time to go through this file and customize the settings for your local environment. Failure to do so may result in false negatives and false positives. See the section entitled OWASP CRS Configuration for more detail. 6. Rename rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example and rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example to remove the '.example' extension. This will allow you to add exceptions without updates overwriting them in the future. 7. Nginx requires the configuration of a single ModSecurity configuration file within the nginx.conf file using the 'ModSecurityConfig' directive (when using ModSecurity 2.x). Best practice is to set 'ModSecurityConfig' to a file from which you will include your other ModSecurity configuration files. In this example we will use: ```ModSecurityConfig modsec_includes.conf;``` 7. Within modsec_includes.conf create your includes to the CRS folder similar to as follows (The modsecurity.conf file from the ModSecurity installation is included in this example): ``` include modsecurity.conf include owasp-modsecurity-crs/crs-setup.conf include owasp-modsecurity-crs/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf include owasp-modsecurity-crs/rules/REQUEST-901-INITIALIZATION.conf include owasp-modsecurity-crs/rules/REQUEST-905-COMMON-EXCEPTIONS.conf include owasp-modsecurity-crs/rules/REQUEST-910-IP-REPUTATION.conf include owasp-modsecurity-crs/rules/REQUEST-911-METHOD-ENFORCEMENT.conf include owasp-modsecurity-crs/rules/REQUEST-912-DOS-PROTECTION.conf include owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf include owasp-modsecurity-crs/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf include owasp-modsecurity-crs/rules/REQUEST-921-PROTOCOL-ATTACK.conf include owasp-modsecurity-crs/rules/REQUEST-930-APPLICATION-ATTACK-LFI.conf include owasp-modsecurity-crs/rules/REQUEST-931-APPLICATION-ATTACK-RFI.conf include owasp-modsecurity-crs/rules/REQUEST-932-APPLICATION-ATTACK-RCE.conf include owasp-modsecurity-crs/rules/REQUEST-933-APPLICATION-ATTACK-PHP.conf include owasp-modsecurity-crs/rules/REQUEST-941-APPLICATION-ATTACK-XSS.conf include owasp-modsecurity-crs/rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf include owasp-modsecurity-crs/rules/REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION.conf include owasp-modsecurity-crs/rules/REQUEST-949-BLOCKING-EVALUATION.conf include owasp-modsecurity-crs/rules/RESPONSE-950-DATA-LEAKAGES.conf include owasp-modsecurity-crs/rules/RESPONSE-951-DATA-LEAKAGES-SQL.conf include owasp-modsecurity-crs/rules/RESPONSE-952-DATA-LEAKAGES-JAVA.conf include owasp-modsecurity-crs/rules/RESPONSE-953-DATA-LEAKAGES-PHP.conf include owasp-modsecurity-crs/rules/RESPONSE-954-DATA-LEAKAGES-IIS.conf include owasp-modsecurity-crs/rules/RESPONSE-959-BLOCKING-EVALUATION.conf include owasp-modsecurity-crs/rules/RESPONSE-980-CORRELATION.conf include owasp-modsecurity-crs/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf ``` 8. Restart web server and ensure it starts without errors 9. Make sure your web sites are still running fine. 10. Proceed to the section "Testing the Installation" below. Installing on IIS ----------------- The IIS installer comes with an optional version of CRS built in. To upgrade or install this after the fact follow the following steps. 1. Navigate to "[drive_letters]:\Program Files\ModSecurity IIS\" 2. Clone the repository into the current folder using: ```git clone https://github.com/SpiderLabs/owasp-modsecurity-crs``` 3. Move the crs-setup.conf.example file to crs-setup.conf. Please take this time to go through this file and customize the settings for your local environment. Failure to do so may result in false negatives and false positives. See the section entitled OWASP CRS Configuration for more detail. 4. Rename rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example and rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example to remove the '.example' extension. This will allow you to add exceptions without updates overwriting them in the future. 5. Navigate back to the 'ModSecurity IIS' folder and modify the 'modsecurity_iis' to include the following: ``` include owasp-modsecurity-crs/crs-setup.conf include owasp-modsecurity-crs/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf include owasp-modsecurity-crs/rules/REQUEST-901-INITIALIZATION.conf include owasp-modsecurity-crs/rules/REQUEST-905-COMMON-EXCEPTIONS.conf include owasp-modsecurity-crs/rules/REQUEST-910-IP-REPUTATION.conf include owasp-modsecurity-crs/rules/REQUEST-911-METHOD-ENFORCEMENT.conf include owasp-modsecurity-crs/rules/REQUEST-912-DOS-PROTECTION.conf include owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf include owasp-modsecurity-crs/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf include owasp-modsecurity-crs/rules/REQUEST-921-PROTOCOL-ATTACK.conf include owasp-modsecurity-crs/rules/REQUEST-930-APPLICATION-ATTACK-LFI.conf include owasp-modsecurity-crs/rules/REQUEST-931-APPLICATION-ATTACK-RFI.conf include owasp-modsecurity-crs/rules/REQUEST-932-APPLICATION-ATTACK-RCE.conf include owasp-modsecurity-crs/rules/REQUEST-933-APPLICATION-ATTACK-PHP.conf include owasp-modsecurity-crs/rules/REQUEST-941-APPLICATION-ATTACK-XSS.conf include owasp-modsecurity-crs/rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf include owasp-modsecurity-crs/rules/REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION.conf include owasp-modsecurity-crs/rules/REQUEST-949-BLOCKING-EVALUATION.conf include owasp-modsecurity-crs/rules/RESPONSE-950-DATA-LEAKAGES.conf include owasp-modsecurity-crs/rules/RESPONSE-951-DATA-LEAKAGES-SQL.conf include owasp-modsecurity-crs/rules/RESPONSE-952-DATA-LEAKAGES-JAVA.conf include owasp-modsecurity-crs/rules/RESPONSE-953-DATA-LEAKAGES-PHP.conf include owasp-modsecurity-crs/rules/RESPONSE-954-DATA-LEAKAGES-IIS.conf include owasp-modsecurity-crs/rules/RESPONSE-959-BLOCKING-EVALUATION.conf include owasp-modsecurity-crs/rules/RESPONSE-980-CORRELATION.conf include owasp-modsecurity-crs/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf ``` 6. Restart web server and ensure it starts without errors 7. Make sure your web sites are still running fine. 8. Proceed to the section "Testing the Installation" below. Testing the Installation ======================== To test your installation you should be able to use any number of attacks. A typical request which should trigger CRS would be ```http://localhost/?param=">``` Upon sending this request you should see events reported in the error log (nginx apache) or the event viewer (IIS). If have not changed the defaults with regards to anomaly scoring, blocking and sampling percentage, then this request should have been blocked and access forbidden. Likewise if you have configured ModSecurity debug logging and/or audit logging this event should log to these locations as well. OWASP CRS Configuration ======================= The crs-setup.conf file includes management rules and directives that can control important CRS functions. The crs-setup.conf file comes with extensive comments. This section here brings only the essential parts. By default we do not include settings within the crs-setup.conf that configure ModSecurity itself. Instead those configuration settings are set during the installation of ModSecurity proper. An example for such such a configuration file is available via the ModSecurity project (https://github.com/SpiderLabs/ModSecurity/blob/master/modsecurity.conf-recommended). Be aware the crs-setup.conf file DOES specify configuration directives such as SecDefaultAction. The default is the anomaly scoring mode with the appropriate SecDefaultAction as defined in the crs-setup.conf. Alternative configuration modes are supported and explained in crs-setup.conf. The default anomaly/correlation mode establishes an incoming anomaly score threshold of 5 and an outgoing anomaly score threshold of 4. The default installation has been tuned to reduce false positives in a way that will allow most requests to pass in this default setup. However, testing the setup and tuning false positives before going to production is vital. This is especially true if you raise the paranoia level with is set to 1 by default. Higher paranoia levels ranging from 2 to 4 include more aggressive rules which will raise additional false positives but also raise the security level of your service. If you are unsure about the performance impact of the CRS or if you are unsure about the number of false positives, then you may want to use the sampling percentage. This number, which is set to 100 by default, controls the percentage of requests which is funneled into the CRS. Fresh installs on high traffic sites are advised to start with a low, or very low number of percentages and raise the number slowly up to 100. Be aware that any number below 100 allows a random number of requests to bypass the ruleset completely. Update the TX policy settings for allowed Request Methods, File Extensions, maximum numbers of arguments, etc to better reflect your environment that is being protected. Make sure your GeoIP and Project Honeypot settings are specified if you are using them. The GeoIP database is no longer included with the CRS. Instead you are advised to download it regularly. The script util/upgrade.py brings this functionality. You can use it as follows in cron: ``` 0 2 * * * util/upgrade.py --geoip --cron ``` The use of the option --cron guarantees that the GeoIP download server is not hammered. The use of Project Honeypot requires a free API key. These require an account but can be obtained at https://www.projecthoneypot.org/httpbl_configure.php. Be sure to check out the other settings present within the crs-setup.conf file. There are many other options that have to do with aspects of web application security that are beyond this document but are well explained in crs-setup.conf.