"Fossies" - the Fresh Open Source Software Archive

Member "owasp-modsecurity-crs-3.1.0/INSTALL" (12 Nov 2018, 16600 Bytes) of package /linux/www/owasp-modsecurity-crs-3.1.0.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "INSTALL": 3.0.2_vs_3.1.0.

    1                            _____ _____   _____   ____
    2                           / ____|  __ \ / ____| |___ \
    3                          | |    | |__) | (___     __) |
    4                          | |    |  _  / \___ \   |__ <
    5                          | |____| | \ \ ____) |  ___) |
    6                           \_____|_|  \_\_____/  |____/
    7 
    8                             OWASP Core Rule Set 3.x
    9 
   10 Installing ModSecurity
   11 =====================
   12 
   13     This document does NOT detail how to install ModSecurity. Rather,
   14     only information pertaining to the installation of the OWASP Core
   15     Rule Set (CRS) is provided. However, ModSecurity is a prerequisite
   16     for the CRS installation. Information on installing ModSecurity
   17     can be found within the ModSecurity project at
   18     https://github.com/SpiderLabs/ModSecurity or at ModSecurity.org.
   19 
   20 Installing From a Package Manager
   21 =================================
   22 
   23     The OWASP Core Rule Set (CRS) is available from many sources. On
   24     multiple platforms this includes package managers. These packages are
   25     maintained by independent packagers who package CRS in their own time.
   26     Historically, many of these packages have been out of date. As such,
   27     it is recommended that you install, where possible, from our GitHub
   28     repository. The following CRS 3.x packages are known to exist:
   29 
   30     modsecurity-crs  - Debian
   31     mod_security_crs - Fedora
   32     modsecurity-crs  - Gentoo 
   33 
   34     Packages of CRS 2.x are incompatible with CRS 3.x.
   35 
   36 Installing From Git
   37 ===================
   38 
   39     Github is the preferred way to download and install CRS. Doing so
   40     insures that you have the most recent version of the rules. We
   41     encourage you to create scripts that will automatically download
   42     updates at regular intervals so that you may be protected against
   43     the latest threats that CRS adds protection for.
   44 
   45     The script util/upgrade.py is an example for script. You can use
   46     it as follows:
   47 
   48     ```
   49     ./util/upgrade.py --crs
   50     ```
   51 
   52 Prerequisites
   53 -------------
   54 
   55     CRS is designed to be used with ModSecurity (although many other
   56     projects also use the provided rules). CRS version 3.x is designed for
   57     ModSecurity 2.8 or above. CRS version 3.x makes use of libinjection
   58     and libXML2. Failure to provide these prerequisites may result in
   59     serious false negatives and CRS version 3.x should NOT be run without
   60     these. Note, however, that libinjection is bundled with ModSecurity
   61     since version 2.8. Additionally, if you are downloading from the
   62     GitHub repo you will need to install 'git' on your system.
   63 
   64 Upgrading from CRS 2.x
   65 ----------------------
   66     CRS 3.x is a major release incompatible with CRS 2.x.
   67     The rule IDs have changed. The file id_renumbering/IdNumbering.csv
   68     contains a list with old and new rule IDs. However, a key feature
   69     of the release 3.x is the reduction of false positives in the
   70     default installation and we recommend you start with a fresh
   71     install from scratch.
   72     Key parameter variables have changed their name and new features
   73     have been introduced. Your former modsecurity_crs_10_setup.conf
   74     file is thus no longer usable.
   75     We recommend you to start with a fresh install from scratch.
   76 
   77 Installing on Apache
   78 --------------------
   79     1. Install ModSecurity for Apache
   80     2. Ensure that ModSecurity is loading correctly by checking error.log
   81     at start up for lines indicating ModSecurity is installed. An example
   82     might appear as follows:
   83     ```ModSecurity for Apache/2.9.1 (http://www.modsecurity.org/) configured.```
   84     3. The most common method of deploying ModSecurity we have seen is
   85     to create a new folder underneath the Apache directory (typically
   86     /usr/local/apache/, /etc/httpd/, or /etc/apache2). Often this folder
   87     is called 'modsecurity.d'. Create this folder and cd into it.
   88     4. Clone the repository into the modsecurity.d folder using:
   89     ```git clone https://github.com/SpiderLabs/owasp-modsecurity-crs .```
   90     This will create a new owasp-modsecurity-crs folder.
   91     5. Move the crs-setup.conf.example file to crs-setup.conf.
   92     Please take the time to go through this file and customize the settings
   93     for your local environment. Failure to do so may result in false 
   94     negatives and false positives. See the section entitled OWASP CRS 
   95     Configuration for more detail.
   96     6. Rename rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example and
   97     rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example to remove the
   98     '.example' extension. This will allow you to add exclusions without updates
   99     overwriting them in the future.
  100     7. Add the following line to your httpd.conf/apache2.conf (the following 
  101     assumes you've cloned CRS into modsecurity.d/owasp-modsecurity-crs). You 
  102     can alternatively place these in any config file included by Apache:
  103     ```
  104 	<IfModule security2_module>
  105                 Include modsecurity.d/owasp-modsecurity-crs/crs-setup.conf
  106                 Include modsecurity.d/owasp-modsecurity-crs/rules/*.conf
  107     </IfModule>
  108 	```
  109     8. Restart web server and ensure it starts without errors
  110     9. Make sure your web sites are still running fine.
  111     10. Proceed to the section "Testing the Installation" below.
  112 
  113 Installing on Nginx
  114 -------------------
  115     1. Compile ModSecurity into Nginx
  116     2. Ensure that ModSecurity is loading correctly by checking error.log
  117     at start up for lines indicating ModSecurity is installed. An example
  118     might appear as follows:
  119     ```ModSecurity for nginx (STABLE)/2.9.1 (http://www.modsecurity.org/) configured.```
  120     3. The most common method of deploying ModSecurity we have seen is
  121     to create a new folder underneath the Nginx directory (typically
  122     /usr/local/nginx/conf/). Often this folder
  123     is called 'owasp-modsecurity-crs'. Create this folder and cd into it.
  124     4. Clone the repository into the current folder using:
  125     ```git clone https://github.com/SpiderLabs/owasp-modsecurity-crs .```
  126     5. Move the crs-setup.conf.example file to crs-setup.conf.
  127     Please take this time to go through this
  128     file and customize the settings for your local environment. Failure to
  129     do so may result in false negatives and false positives. See the
  130     section entitled OWASP CRS Configuration for more detail.
  131     6. Rename rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example and
  132     rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example to remove the
  133     '.example' extension. This will allow you to add exceptions without updates
  134     overwriting them in the future.
  135     7. Nginx requires the configuration of a single ModSecurity
  136     configuration file within the nginx.conf file using the
  137     'ModSecurityConfig' directive (when using ModSecurity 2.x).
  138     Best practice is to set 'ModSecurityConfig' to a file from
  139     which you will include your other ModSecurity configuration
  140     files. In this example we will use:
  141     ```ModSecurityConfig modsec_includes.conf;```
  142     7. Within modsec_includes.conf create your includes to the
  143     CRS folder similar to as follows (The modsecurity.conf file from the
  144     ModSecurity installation is included in this example):
  145     ```
  146     include modsecurity.conf
  147     include owasp-modsecurity-crs/crs-setup.conf
  148     include owasp-modsecurity-crs/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf
  149     include owasp-modsecurity-crs/rules/REQUEST-901-INITIALIZATION.conf
  150     include owasp-modsecurity-crs/rules/REQUEST-905-COMMON-EXCEPTIONS.conf
  151     include owasp-modsecurity-crs/rules/REQUEST-910-IP-REPUTATION.conf
  152     include owasp-modsecurity-crs/rules/REQUEST-911-METHOD-ENFORCEMENT.conf
  153     include owasp-modsecurity-crs/rules/REQUEST-912-DOS-PROTECTION.conf
  154     include owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf
  155     include owasp-modsecurity-crs/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf
  156     include owasp-modsecurity-crs/rules/REQUEST-921-PROTOCOL-ATTACK.conf
  157     include owasp-modsecurity-crs/rules/REQUEST-930-APPLICATION-ATTACK-LFI.conf
  158     include owasp-modsecurity-crs/rules/REQUEST-931-APPLICATION-ATTACK-RFI.conf
  159     include owasp-modsecurity-crs/rules/REQUEST-932-APPLICATION-ATTACK-RCE.conf
  160     include owasp-modsecurity-crs/rules/REQUEST-933-APPLICATION-ATTACK-PHP.conf
  161     include owasp-modsecurity-crs/rules/REQUEST-941-APPLICATION-ATTACK-XSS.conf
  162     include owasp-modsecurity-crs/rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf
  163     include owasp-modsecurity-crs/rules/REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION.conf
  164     include owasp-modsecurity-crs/rules/REQUEST-949-BLOCKING-EVALUATION.conf
  165     include owasp-modsecurity-crs/rules/RESPONSE-950-DATA-LEAKAGES.conf
  166     include owasp-modsecurity-crs/rules/RESPONSE-951-DATA-LEAKAGES-SQL.conf
  167     include owasp-modsecurity-crs/rules/RESPONSE-952-DATA-LEAKAGES-JAVA.conf
  168     include owasp-modsecurity-crs/rules/RESPONSE-953-DATA-LEAKAGES-PHP.conf
  169     include owasp-modsecurity-crs/rules/RESPONSE-954-DATA-LEAKAGES-IIS.conf
  170     include owasp-modsecurity-crs/rules/RESPONSE-959-BLOCKING-EVALUATION.conf
  171     include owasp-modsecurity-crs/rules/RESPONSE-980-CORRELATION.conf
  172     include owasp-modsecurity-crs/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf
  173     ```
  174     8. Restart web server and ensure it starts without errors
  175     9. Make sure your web sites are still running fine.
  176     10. Proceed to the section "Testing the Installation" below.
  177 
  178 Installing on IIS
  179 -----------------
  180     The IIS installer comes with an optional version of CRS built in.
  181     To upgrade or install this after the fact follow the following
  182     steps.
  183     1. Navigate to "[drive_letters]:\Program Files\ModSecurity IIS\"
  184     2. Clone the repository into the current folder using:
  185     ```git clone https://github.com/SpiderLabs/owasp-modsecurity-crs```
  186     3. Move the crs-setup.conf.example file to crs-setup.conf.
  187     Please take this time to go through this
  188     file and customize the settings for your local environment. Failure to
  189     do so may result in false negatives and false positives. See the
  190     section entitled OWASP CRS Configuration for more detail.
  191     4. Rename rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example and
  192     rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example to remove the
  193     '.example' extension. This will allow you to add exceptions without updates
  194     overwriting them in the future.
  195     5. Navigate back to the 'ModSecurity IIS' folder and modify the
  196     'modsecurity_iis' to include the following:
  197     ```
  198     include owasp-modsecurity-crs/crs-setup.conf
  199     include owasp-modsecurity-crs/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf
  200     include owasp-modsecurity-crs/rules/REQUEST-901-INITIALIZATION.conf
  201     include owasp-modsecurity-crs/rules/REQUEST-905-COMMON-EXCEPTIONS.conf
  202     include owasp-modsecurity-crs/rules/REQUEST-910-IP-REPUTATION.conf
  203     include owasp-modsecurity-crs/rules/REQUEST-911-METHOD-ENFORCEMENT.conf
  204     include owasp-modsecurity-crs/rules/REQUEST-912-DOS-PROTECTION.conf
  205     include owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf
  206     include owasp-modsecurity-crs/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf
  207     include owasp-modsecurity-crs/rules/REQUEST-921-PROTOCOL-ATTACK.conf
  208     include owasp-modsecurity-crs/rules/REQUEST-930-APPLICATION-ATTACK-LFI.conf
  209     include owasp-modsecurity-crs/rules/REQUEST-931-APPLICATION-ATTACK-RFI.conf
  210     include owasp-modsecurity-crs/rules/REQUEST-932-APPLICATION-ATTACK-RCE.conf
  211     include owasp-modsecurity-crs/rules/REQUEST-933-APPLICATION-ATTACK-PHP.conf
  212     include owasp-modsecurity-crs/rules/REQUEST-941-APPLICATION-ATTACK-XSS.conf
  213     include owasp-modsecurity-crs/rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf
  214     include owasp-modsecurity-crs/rules/REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION.conf
  215     include owasp-modsecurity-crs/rules/REQUEST-949-BLOCKING-EVALUATION.conf
  216     include owasp-modsecurity-crs/rules/RESPONSE-950-DATA-LEAKAGES.conf
  217     include owasp-modsecurity-crs/rules/RESPONSE-951-DATA-LEAKAGES-SQL.conf
  218     include owasp-modsecurity-crs/rules/RESPONSE-952-DATA-LEAKAGES-JAVA.conf
  219     include owasp-modsecurity-crs/rules/RESPONSE-953-DATA-LEAKAGES-PHP.conf
  220     include owasp-modsecurity-crs/rules/RESPONSE-954-DATA-LEAKAGES-IIS.conf
  221     include owasp-modsecurity-crs/rules/RESPONSE-959-BLOCKING-EVALUATION.conf
  222     include owasp-modsecurity-crs/rules/RESPONSE-980-CORRELATION.conf
  223     include owasp-modsecurity-crs/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf
  224     ```
  225     6. Restart web server and ensure it starts without errors
  226     7. Make sure your web sites are still running fine.
  227     8. Proceed to the section "Testing the Installation" below.
  228 
  229 Testing the Installation
  230 ========================
  231     To test your installation you should be able to use any number
  232     of attacks. A typical request which should trigger CRS would be
  233     ```http://localhost/?param="><script>alert(1);</script>```
  234     Upon sending this request you should see events reported in the
  235     error log (nginx apache) or the event viewer (IIS).
  236 
  237     If have not changed the defaults with regards to anomaly scoring,
  238     blocking and sampling percentage, then this request should have
  239     been blocked and access forbidden. Likewise if you have configured
  240     ModSecurity debug logging and/or audit logging this event should
  241     log to these locations as well.
  242 
  243 OWASP CRS Configuration
  244 =======================
  245     The crs-setup.conf file includes management rules
  246     and directives that can control important CRS functions.
  247     The crs-setup.conf file comes with extensive comments.
  248     This section here brings only the essential parts.
  249 
  250     By default we do not include settings within the crs-setup.conf
  251     that configure ModSecurity itself. Instead those configuration
  252     settings are set during the installation of ModSecurity proper.
  253     An example for such such a
  254     configuration file is available via the ModSecurity project
  255     (https://github.com/SpiderLabs/ModSecurity/blob/master/modsecurity.conf-recommended).
  256     Be aware the crs-setup.conf file DOES specify
  257     configuration directives such as SecDefaultAction. The default
  258     is the anomaly scoring mode with the appropriate
  259     SecDefaultAction as defined in the crs-setup.conf.
  260     Alternative configuration modes are supported and explained
  261     in crs-setup.conf.
  262 
  263     The default anomaly/correlation mode establishes an incoming
  264     anomaly score threshold of 5 and an outgoing anomaly score
  265     threshold of 4. The default installation has been tuned to
  266     reduce false positives in a way that will allow most requests
  267     to pass in this default setup.
  268 
  269     However, testing the setup and tuning false positives
  270     before going to production is vital. This is especially true
  271     if you raise the paranoia level with is set to 1 by default.
  272     Higher paranoia levels ranging from 2 to 4 include more
  273     aggressive rules which will raise additional false positives
  274     but also raise the security level of your service.
  275 
  276     If you are unsure about the performance impact of the CRS
  277     or if you are unsure about the number of false positives, then
  278     you may want to use the sampling percentage. This number,
  279     which is set to 100 by default, controls the percentage
  280     of requests which is funneled into the CRS. Fresh installs
  281     on high traffic sites are advised to start with a low, or
  282     very low number of percentages and raise the number
  283     slowly up to 100. Be aware that any number below 100 allows
  284     a random number of requests to bypass the ruleset completely.
  285 
  286     Update the TX policy settings for allowed Request Methods, File
  287     Extensions, maximum numbers of arguments, etc to better reflect
  288     your environment that is being protected.
  289 
  290     Make sure your GeoIP and Project Honeypot settings are specified
  291     if you are using them.
  292     The GeoIP database is no longer included with the CRS. Instead
  293     you are advised to download it regularly. The script
  294     util/upgrade.py brings this functionality.  You can use it as
  295     follows in cron:
  296 
  297     ```
  298     0 2 * * *  util/upgrade.py --geoip --cron
  299 
  300     ```
  301     The use of the option --cron guarantees that the GeoIP
  302     download server is not hammered.
  303 
  304     The use of Project Honeypot requires a
  305     free API key. These require an account but can be obtained at
  306     https://www.projecthoneypot.org/httpbl_configure.php.
  307 
  308     Be sure to check out the other settings present within the
  309     crs-setup.conf file. There are many other options that have to
  310     do with aspects of web application security that are beyond
  311     this document but are well explained in crs-setup.conf.
  312