                           _____ _____   _____   ____
                          / ____|  __ \ / ____| |___ \
                         | |    | |__) | (___     __) |
                         | |    |  _  / \___ \   |__ <
                         | |____| | \ \ ____) |  ___) |
                          \_____|_|  \_\_____/  |____/

                            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. 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:
    ```
	<IfModule security2_module>
                Include modsecurity.d/owasp-modsecurity-crs/crs-setup.conf
                Include modsecurity.d/owasp-modsecurity-crs/rules/*.conf
    </IfModule>
	```
    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="><script>alert(1);</script>```
    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.

