diff --git a/content/deployment/install.md b/content/deployment/install.md index 0b304e33..50ba50d3 100644 --- a/content/deployment/install.md +++ b/content/deployment/install.md @@ -1,182 +1,140 @@ --- -title: "Installing CoreRuleSet" -menuTitle: "Extended Install" +title: "Extended Install" chapter: false +disableToc: false weight: 20 --- -{{% notice note %}} -**The content on this page may be outdated.** We are currently in the process of rewriting all of our documentation: please bear with us while we update our older content. -{{% /notice %}} +> 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]({{< ref "quick_start.md" >}}). -If you need mode information than the one in the [quickstart guide]({{< ref "quickstart.md" >}}), here we extend with additional details so keep reading. +## Contact Us -Below you should find all the information you need to properly install -CRS. If you are having problems feel free to reach out to our [Google Group](https://groups.google.com/a/owasp.org/forum/#!forum/modsecurity-core-rule-set-project), or our [Slack Channel](https://owasp.slack.com/archives/CBKGH8A5P). If you don't have access yet, [get your invite here](https://owasp.org/slack/invite). +To contact the CRS project with questions or problems, reach out via the project's [Google group](https://groups.google.com/a/owasp.org/forum/#!forum/modsecurity-core-rule-set-project) or [Slack channel](https://owasp.slack.com/archives/CBKGH8A5P) (for Slack channel access, [use this link](https://owasp.org/slack/invite) to get an invite). ## Prerequisites -Installing the CRS isn't very hard but it does have one major requirement, ModSecurity. If ModSecurity isn't working properly you will likely run into problems running the CRS. +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. -{{% notice warning %}} -In order to run the CRS `3.x` branch you require AT MINIMUM ModSecurity 2.8 or above, preferably version `3.x` or above. +{{% notice note %}} +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 `2.x` branch. {{% /notice %}} -## Finding where to edit in your configuration +## Installing a Compatible WAF Engine -ModSecurity comes in MANY different version with support for a multitude -of Operating Systems (OS) and Web Servers. The installation locations -may differ greatly between these different options so please be aware -that the following are just some of the more common configurations. +Two different methods to get an engine up and running are presented here: -### Apache 2.x with ModSecurity 2.x Compiled +- using the chosen engine as provided and packaged by the OS distribution +- compiling the chosen engine from source -Compiling ModSecurity is easy, but slightly outside the scope of this -document. If you are interested in learning how to compile ModSecurity -please go to the ModSecurity documentation. Having compiled ModSecurity -there is a simple test to see if your installation is working. If you -have compiled from source you would have needed to include `LoadModule security2_module modules/mod_security2.so` either in `httpd.conf` (`apache2.conf` on Debian) or in some file included from this file. -Anywhere after you load your module you may add the following -ModSecurity directives. +A ModSecurity installation is presented in the examples below, however the install documentation for the Coraza engine can be found [here](https://www.coraza.io). -```apache -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" -``` +### Option 1: Installing Pre-Packaged ModSecurity -If you restart Apache you may now navigate to any page on your web -server passing the parameter `'testparam'` with the value `'test'` (via -post or get) and you should receive a 403. This request will typically -appear similar to as follows: `http://localhost/?testparam=test`. - -If you obtained a 403 status code your ModSecurity instance is -functioning correctly with Apache and you now know where to place -directives. - -### Apache 2.x with ModSecurity 2.x Packaged (RHEL) - -Many operating systems provide package managers in order to aid in the -install of software packages and their associated dependencies. Even -though ModSecurity is relatively straight forward to install, some -people prefer using package managers due to their ease. It should be -noted here that many package managers do not up date their releases very -frequently, as a result it is quite likely that your distribution may be -missing required features or possibly even have security -vulnerabilities. Additionally, depending on your package/package manager -your ModSecurity configuration will be laid out slightly different. - -On Fedora we will find that when you use `dnf install mod_security` -you will receive the base ModSecurity package. Apache's configuration -files are split out within this environment such that there are -different folders for the base config (`/etc/httpd/config`), user -configuration (`/etc/httpd/conf.d`, and module configuration -(`/etc/httpd/conf.modules.d/`). The Fedora ModSecurity 2.x package places -the LoadModule and associated 'Include's within -`/etc/httpd/conf.modules.d/10-mod_security.conf`. Additionally, it places -some of the reccomended default rules in -`/etc/httpd/conf.d/mod_security.conf`. It is this secondary configuration -file that will setup the locations where you should add your rules. By -default it reads in all config files from the `/etc/httpd/modsecurity.d/` -and `/etc/httpd/modsecurity.d/activated_rules/` folder. To keep order I -would reccomend testing this configuration by placing a `rules.conf` file -within the `activated_rules` folder. Within this `rules.conf` file add the -following: +ModSecurity is frequently pre-packaged and is available from several major Linux distributions. -```bash -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" -``` +- **Debian:** Friends of the CRS project [DigitalWave](https://modsecurity.digitalwave.hu) package and, most importantly, **keep ModSecurity updated** for Debian and derivatives. +- **Fedora:** Execute `dnf install mod_security` for Apache + ModSecurity v2. +- **RHEL compatible:** Install EPEL and then execute `yum install mod_security`. -Upon saving and restarting Apache (`systemctl restart httpd.service`) you -should be able to navigate to a your local webserver. Once this is -accomplished try passing the 'testparam' paramater with the value -'test' such as via the following -URL: `http://localhost/?testparam=test`. You should receive a 403 -Forbidden status. If you do congratulations, ModSecurity is ready for -the OWASP CRS rules. +For Windows, get the latest MSI package from https://github.com/SpiderLabs/ModSecurity/releases. -### Nginx with ModSecurity 2.x Compiled +{{% notice warning %}} +**Distributions might not update their ModSecurity releases frequently.** -ModSecurity 2.x currently doesn't support the new Nginx loadable -modules. As a result, it is required that you compile Nginx from source -with ModSecurity. For more information on how to do this see the -ModSecurity documentaiton. Once ModSecurity is compiled in you will have -to specify both 'ModSecurityEnabled' and 'ModSecurityConfig' within -any location block where you want ModSecurity enabled. An example would -look similar to below. +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. +{{% /notice %}} -```nginx -location / { - ModSecurityEnabled on; - ModSecurityConfig modsec_includes.conf; -} -``` +As the different engines and distributions have different layouts for their configuration, to simplify the documentation presented here the prefix `/` will be used from this point on. -Within this `modsec_includes.conf` you may use the `Include` directive to -include other files or any ModSecurity directives. For our testing -purpose we will add the following to our `modsec_includes.conf`: +Examples of `/` include: -```Apache -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" -``` +- `/etc/apache2` in Debian and derivatives +- `/etc/httpd` in RHEL and derivatives +- `/usr/local/apache2` if Apache was compiled from source using the default prefix +- `C:\Program Files\ModSecurity IIS\` (or Program Files(x86), depending on configuration) on Windows +- `/etc/nginx` -Upon saving and restarting Nginx (`./nginx -s reload`) you should be able -to navigate to a your local webserver. Once this is accomplished try -passing the 'testparam' paramater with the value 'test' such as via -the following URL: `http://localhost/?testparam=test`. You should receive -a 403 Forbidden status. If you do congratulations, ModSecurity is ready -for the OWASP CRS rules 🚀. +### Option 2: Compiling ModSecurity From Source -### Nginx with ModSecurity 3.x (libmodsecurity) Compiled +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](https://github.com/SpiderLabs/ModSecurity/wiki) on GitHub +- the compilation recipes for ModSecurity v3 on the [ModSecurity wiki](https://github.com/SpiderLabs/ModSecurity/wiki/Compilation-recipes-for-v3.x) +- the netnea tutorials for [Apache](https://www.netnea.com/cms/apache-tutorial-6_embedding-modsecurity/) or [Nginx](https://www.netnea.com/cms/nginx-tutorial-6_embedding-modsecurity/) +{{% notice warning "Unsupported Configurations" "skull-crossbones" %}} +Note that the following configurations are **not** supported. They do **not** work as expected. The CRS project recommendation is to *avoid these setups*: -### Microsoft IIS with ModSecurity 2.x +- Nginx with ModSecurity v2 +- Apache with ModSecurity v3 +{{% /notice %}} -The most common deployment of ModSecurity for IIS is via the -pre-packaged MSI installer, available at . If you compiled or are looking to compile ModSecurity for IIS this documentation isn't for -you. +#### Testing the Compiled Module -If you used this package to install ModSecurity 2.x on IIS (tested -on IIS 7-10), than your configuration files are located within`C:\Program Files\ModSecurity IIS\` (or Program Files(x86) depending on your configuration). The inital configuration file, that is the one that the remainder are included from, is `modsecurity_iis.conf`. This file will be parsed by the ModSecurity for both ModSecurity and `'Include'` directives. +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: -By default all installations of ModSecurity without [SecRuleEngine](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) declared will start in DetectionOnly mode. IIS, by default, explicitly declares [SecRuleEngine](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) to be DetectionOnly within the included modsecurity.conf file. As a result any rule we make will only show up in the Windows Event Viewer by default. For our example we're going to turn on disruptive actions. To test we should add the following to the end of our `modsecurity_iis.conf`: +- **Apache:** `LoadModule security2_module modules/mod_security2.so` +- **Nginx:** `load_module modules/ngx_http_modsecurity_module.so;` -```apache -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" +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) ``` -This rule will be triggered when you go to your web page and pass the testparam (via either GET or POST) with the test value. This typically will looks similar to the following: `http://localhost/?testparam=test`. +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 `'Include'` directives. + +Additionally, in the Event Viewer, under `Windows Logs\Application`, it should be possible to see a new log entry showing ModSecurity being successfully loaded. -If all went well you should see an HTTP 403 Forbidden in your browser when you navigate to the site in question. Additionally, in your Event Viewer, under 'Windows Logs'-\>'Application', we should see a new log that looks like the following: +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 -If you have gotten to this step ModSecurity is functioning on IIS and you now know where to place new directives. +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](https://github.com/coreruleset/coreruleset/security/policy). -## Downloading OWASP CRS +Official CRS releases can be found at the following URL: https://github.com/coreruleset/coreruleset/releases. -Now that you know where your rules belong typically we'll want to download the OWASP CRS. The best place to get the latest copy of the ruleset will be from [our Github Releases](https://github.com/coreruleset/coreruleset/releases). There we have all our official releases listed. For production we recommend you to use the **latest release**, v{{< param crs_latest_release >}}. If you want to test the bleeding edge version, we also provide _nightly releases_. +For *production* environments, it is recommended to use the latest release, which is v{{< param crs_latest_release >}}. For *testing* the bleeding edge CRS version, nightly releases are also provided. + +### Verifying Releases {{% notice note %}} -Releases are signed using [our GPG key](https://coreruleset.org/security.asc), (fingerprint: 3600 6F0E 0BA1 6783 2158 8211 38EE ACA1 AB8A 6E72). You can verify the release using GPG/PGP compatible tooling. +Releases are signed using the CRS project's [GPG key](https://coreruleset.org/security.asc) (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`, execute: `gpg --keyserver pgp.mit.edu --recv 0x38EEACA1AB8A6E72` (this ID should be equal to the last sixteen hex characters in the fingerprint). -To get our key using gpg: `gpg --keyserver pgp.mit.edu --recv 0x38EEACA1AB8A6E72` (this id should be equal to the last sixteen hex characters in our fingerprint). -You can also use `gpg --fetch-key https://coreruleset.org/security.asc` directly. +It is also possible to use `gpg --fetch-key https://coreruleset.org/security.asc` to retrieve the key directly. {{% /notice %}} -The steps here assume you are using a *nix operating system. For Windows you will be doing a similar install, but probably using the zip file from our releases. +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](https://github.com/coreruleset/coreruleset/releases). -To get the release file and the corresponding signature: +To download the release file and the corresponding signature: ```bash wget https://github.com/coreruleset/coreruleset/archive/refs/tags/v{{< param crs_latest_release >}}.tar.gz wget https://github.com/coreruleset/coreruleset/releases/download/v{{< param crs_latest_release >}}/coreruleset-{{< param crs_latest_release >}}.tar.gz.asc ``` -Optional verification: +To verify the integrity of the release: + ```bash gpg --verify coreruleset-{{< param crs_latest_release >}}.tar.gz.asc v{{< param crs_latest_release >}}.tar.gz gpg: Signature made Wed Jun 30 10:05:48 2021 -03 @@ -187,7 +145,9 @@ 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, the verification succeeded. If you see a warning like the above, it means you know our public key, but you are not trusting it. You can trust it by using the following method: +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: ```bash gpg edit-key 36006F0E0BA167832158821138EEACA1AB8A6E72 @@ -197,7 +157,8 @@ Are you sure: Yes gpg> quit ``` -Then you will see this result when verifying: +The result when verifying a release will then look like so: + ```bash 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 @@ -205,308 +166,95 @@ gpg: using RSA key 36006F0E0BA167832158821138EEACA1AB8A6E72 gpg: Good signature from "OWASP Core Rule Set " [ultimate] ``` -Once you downloaded and verified the release, you are ready to continue with the setup. - -### Setting up OWASP CRS - -OWASP CRS contains one setup file that should be reviewed prior to -completing setup. The setup file is the only configuration file within -the root 'coreruleset-{{< param crs_latest_release >}}' folder and is named -`csr-setup.conf.example`. Going through this configuration file -and reading what the different options are is -HIGHLY recommended. At minimum you should keep in mind the following. - -- CRS does not configure ModSecurity features such as the rule engine, - the audit engine, logging etc. This task is part of the ModSecurity - initial setup.If you haven't done this yet please check out the - [recommended ModSecurity configuration](https://github.com/SpiderLabs/ModSecurity/blob/master/modsecurity.conf-recommended) -- By default [SecDefaultAction](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-%28v2.x%29#SecDefaultAction) CRS will redirect to your local domain when an alert is triggered. - This may cause redirect loops depending on your configuration. Take - some time to decide what you want ModSecurity it do (drop the - packet, return a status:403, go to a custom page etc.) when it - detects malicious activity. -- Make sure to configure your anomaly scoring thresholds for more - information see [Anomaly]({{< ref "anomaly_scoring.md" >}} "Anomaly") -- By default ModSecurity looks for lots of issues with different - databases and languages, if you are running a specific environment, - you probably want to limit this behavior for performance reasons. -- ModSecurity supports [Project Honeypot](https://www.projecthoneypot.org/) blacklists. This is a - great project and all you need to do to leverage it is sign up for - an [API key](https://www.projecthoneypot.org/httpbl_api.php) (⚠️ it might be outdated) -- Do make sure you have added any methods, static resources, content - types, or file extensions that your site needs beyond the basic ones - listed. - -For more information please see the page on -[configuration]({{< ref "crs.md" >}} "configuration"). Once you have reviewed -and configured CRS you should rename the file suffix from `.example` to -`.conf`: +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-{{< param crs_latest_release >}}' folder and is named `csr-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](https://github.com/SpiderLabs/ModSecurity/blob/master/modsecurity.conf-recommended). +- 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]({{< ref "anomaly_scoring.md" >}} "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. +- ModSecurity supports [Project Honeypot](https://www.projecthoneypot.org/) blacklists. This is a great project and all you need to do to leverage it is sign up for an [API key](https://www.projecthoneypot.org/httpbl_api.php) (⚠️ it might be outdated) +- 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 `.example` to `.conf`: ```bash mv csr-setup.conf.example csr-setup.conf ``` -In addition to `csr-setup.conf.example` there are two other .example files -within our repository. These files are: -`rules/REQUEST-00-LOCAL-WHITELIST.conf.example` and -`rules/RESPONSE-99-EXCEPTIONS.conf.example`. These files are designed to -provide the rule maintainer the capability to modify rules (see -[false positives and tuning]({{< ref "../configuring/false_positives_tuning.md" >}}#rule-exclusions)) without breaking forward -compatability with updates. As such you should rename these two files, -removing the `.example` suffix. This will make it so that even when -updates are installed they do not overwrite your custom updates. To -rename the files in Linux one would use a command similar to the -following: +In addition to `csr-setup.conf.example`, there are two other ".example" files within the CRS repository. These are: + +- `rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example` +- `rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example` + +These files are designed to provide the rule maintainer with the ability to modify rules (see [false positives and tuning]({{< ref "../configuring/false_positives_tuning.md" >}}#rule-exclusions)) 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: ```bash -mv rules/REQUEST-00-LOCAL-WHITELIST.conf.example rules/REQUEST-00-LOCAL-WHITELIST.conf -mv rules/RESPONSE-99-EXCEPTIONS.conf.example rules/RESPONSE-99-EXCEPTIONS.conf +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 -Both ModSecurity 2.x (via APR) and ModSecurity 3.x support the Include -directive and what it tells the ModSecurity core to do is parse the -additional files for ModSecurity directives. But where do you place this -folder for it to be included? If you were to look at the CRS files, -you'd note 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](rules.md) -section. +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]({{< ref "../rules/" >}}) section. ### Includes for Apache -Apache will include from the Apache Root directory (`/etc/httpd/`, -`/etc/apache2/`, or `/usr/local/apache2/` depending on the envirovment). -Typically we reccomend following the Fedora practice of creating a -folder specificlly for ModSecurity rules. In our example we have named -this modsecurity.d and placed in within the root Apache directory. When -using Apache we can use the wildcard notation to vastly simplify our -rules. Simply copying our cloned directory to our modsecurity.d folder -and specifying the appropertie include directives will allow us to -install OWASP CRS. In the example below we have also included our -`modsecurity.conf` file which includes reccomended configurations for -ModSecurity +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 `/` 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. ```apache Include modsecurity.d/modsecurity.conf - Include modsecurity.d/owasp-modsecurity-crs/csr-setup.conf - Include modsecurity.d/owsp-modsecurity-crs/rules/*.conf + Include modsecurity.d/coreruleset-{{< param crs_latest_release >}}/csr-setup.conf + Include modsecurity.d/coreruleset-{{< param crs_latest_release >}}/rules/*.conf ``` ### Includes for Nginx -Nginx will include from the Nginx conf directory (`/usr/local/nginx/conf/` -depending on the envirovment). Because only one `ModSecurityConfig` -directive can be specified within nginx.conf we reccomend naming that -file `modsec_includes.conf` and including additional files from there. In -the example below we copied our cloned `owasp-modsecurity-crs` folder into -our Nginx configuration directory. From there we specifying the -appropertie include directives which will include OWASP CRS when the -server is restarted. In the example below we have also included our -`modsecurity.conf` file which includes reccomended configurations for -ModSecurity +Nginx will include files from the Nginx configuration directory (`/etc/nginx` or `/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. ```nginx include modsecurity.conf -include owasp-modsecurity-crs/csr-setup.conf -include owasp-modsecurity-crs/rules/REQUEST-00-LOCAL-WHITELIST.conf -include owasp-modsecurity-crs/rules/REQUEST-01-COMMON-EXCEPTIONS.conf -include owasp-modsecurity-crs/rules/REQUEST-10-IP-REPUTATION.conf -include owasp-modsecurity-crs/rules/REQUEST-11-METHOD-ENFORCEMENT.conf -include owasp-modsecurity-crs/rules/REQUEST-12-DOS-PROTECTION.conf -include owasp-modsecurity-crs/rules/REQUEST-13-SCANNER-DETECTION.conf -include owasp-modsecurity-crs/rules/REQUEST-20-PROTOCOL-ENFORCEMENT.conf -include owasp-modsecurity-crs/rules/REQUEST-21-PROTOCOL-ATTACK.conf -include owasp-modsecurity-crs/rules/REQUEST-30-APPLICATION-ATTACK-LFI.conf -include owasp-modsecurity-crs/rules/REQUEST-31-APPLICATION-ATTACK-RFI.conf -include owasp-modsecurity-crs/rules/REQUEST-32-APPLICATION-ATTACK-RCE.conf -include owasp-modsecurity-crs/rules/REQUEST-33-APPLICATION-ATTACK-PHP.conf -include owasp-modsecurity-crs/rules/REQUEST-41-APPLICATION-ATTACK-XSS.conf -include owasp-modsecurity-crs/rules/REQUEST-42-APPLICATION-ATTACK-SQLI.conf -include owasp-modsecurity-crs/rules/REQUEST-43-APPLICATION-ATTACK-SESSION-FIXATION.conf -include owasp-modsecurity-crs/rules/REQUEST-49-BLOCKING-EVALUATION.conf -include owasp-modsecurity-crs/rules/RESPONSE-50-DATA-LEAKAGES-IIS.conf -include owasp-modsecurity-crs/rules/RESPONSE-50-DATA-LEAKAGES-JAVA.conf -include owasp-modsecurity-crs/rules/RESPONSE-50-DATA-LEAKAGES-PHP.conf -include owasp-modsecurity-crs/rules/RESPONSE-50-DATA-LEAKAGES.conf -include owasp-modsecurity-crs/rules/RESPONSE-51-DATA-LEAKAGES-SQL.conf -include owasp-modsecurity-crs/rules/RESPONSE-59-BLOCKING-EVALUATION.conf -include owasp-modsecurity-crs/rules/RESPONSE-80-CORRELATION.conf -include owasp-modsecurity-crs/rules/RESPONSE-99-EXCEPTIONS.conf -``` - -## Setting up automated updates - -todo: The OWASP Core Rule Set is designed with the capability to be -frequently updated in mind. New threats and techniques and updates are -provided frequently as part of the rule set and as a result, in order to -combat the latest threats effectivly it is imperative that constant -updates should be part of your strategy. - -### An update script - -As part of our continuing effort to provide the most user friendly rule -set available we provide an example script that you can use for updating -your ruleset: - -```python -# -*- coding: utf-8 -*- -""" -This script is designed to allow users to automatically -update their ModSecurity OWASP Core Rule Set. It can -be called by a cronjob or scheduled task in order to -allow for automation. Note that it can either replace -the whole CRS directory or just update the rules folder, -which is the default. -""" - -from __future__ import print_function -import argparse -import os -import uuid -import shutil -import logging - -try: - from git import Repo -except ImportError: - print("This script requires the GitPython module (pip install gitpython).") - -__author__ = "Chaim Sanders" -__copyright__ = "Copyright 2016, Trustwave Inc" -__credits__ = ["Chaim Sanders"] -__license__ = "ASL 2.0" -__version__ = "1.0" -__maintainer__ = "Chaim Sanders" -__git__ = "csanders-git" -__status__ = "Production" - -def check_arguments(logger): - """Control arguments and set args variable""" - example_string = "Examples: python %(prog)s --full -p ./owasp-modsecurity-crs/" \ - " or python %(prog)s --folder=util/ --path=./owasp-modsecurity-crs/util" \ - " or python %(prog)s" - parser = argparse.ArgumentParser(description='Update OWASP CRS rules', - formatter_class=argparse.ArgumentDefaultsHelpFormatter, - epilog=example_string) - parser.add_argument('-b', '--branch', default="v3.0.0-rc1", type=str, - required=False, help='The GitHub branch you want to download.') - parser.add_argument('-r', '--repo', - default="https://github.com/SpiderLabs/owasp-modsecurity-crs", - type=str, required=False, help='The GitHub repository you want to use.') - parser.add_argument('-p', '--path', default="./owasp-modsecurity-crs/rules/", type=str, - required=False, help='The path where the rules files should be placed') - group = parser.add_mutually_exclusive_group(required=False) - group.add_argument('--full', action='store_true', - required=False, - help='Copy the whole repo to the path specified instead of just the rules') - group.add_argument('--folder', default="rules/", type=str, - required=False, - help='The toplevel folder within the repo to copy. Can\'t be used with full') - parser.add_argument('-d', '--debug', action='store_true', - required=False, help='Display debug logging.') - args = parser.parse_args() - if args.debug: - logger.setLevel(logging.DEBUG) - logger.debug("Debugging mode has been enabled.") - logger.debug("The following arguments were assigned: " + str(args) + ".") - return args - -def download_rules(args, logger): - """Download and replace our rules""" - if args.path[-1] != os.path.sep: - dst_dir = args.path + os.path.sep - else: - dst_dir = args.path - logger.debug("The final path was set to " + str(dst_dir) + ".") - rand_fold = "./" + str(uuid.uuid4()) - logger.debug("The temporary repo folder was set to " + str(rand_fold) + ".") - # If the user wants the whole directory set that otherwise just rules/ - if args.full: - copy_fold = rand_fold - else: - copy_fold = rand_fold + os.path.sep + args.folder - logger.debug("Set the folder to be copied to " + copy_fold + ".") - Repo.clone_from(args.repo, rand_fold, branch=(args.branch)) - logger.debug("Cloned the repo successfully.") - for src_dir, _, files in os.walk(copy_fold): - for file_ in files: - if file_[-8:] != ".example": - src_file = os.path.join(src_dir, file_) - # If its the full copy we need the new prefix path - if args.full: - copy_path = src_file.replace(rand_fold, "")[1:] - else: - # Remove the overlap in folders - copy_path = src_file.replace(os.path.join(rand_fold, args.folder), "") - dst_file = os.path.join(dst_dir, copy_path) - cwd = os.path.dirname(dst_file) - # Check if the directory structure exists - if not os.path.exists(cwd): - os.makedirs(cwd) - if os.path.exists(dst_file): - os.remove(dst_file) - logger.debug("Removed existing " + dst_file + ".") - try: - shutil.move(src_file, cwd) - except shutil.Error as exc: - print(exc) - logger.debug("Moved " + file_ + " to " + cwd + ".") - logger.debug("Copying completed successfully") - shutil.rmtree(rand_fold) - logger.debug("Deleted the temporary folder.") - -def main(): - """Initiate logging and run subroutines""" - logging.basicConfig(level=logging.INFO) - logger = logging.getLogger(os.path.basename(__file__)) - args = check_arguments(logger) - download_rules(args, logger) - -if __name__ == "__main__": - main() -``` - -## Problems with installation - -### Apache Line Continuation - -In Apache 2.4.x before 2.4.11 there is a bug where the use of line -continuations in a config size may cause the line continuation to be -truncated. This will lead to an error similar to the following: - -```bash -Syntax error on line 24 of /etc/httpd/modsecurity.d/activated_rules/RESPONSE-50-DATA-LEAKAGES-PHP.conf: -Error parsing actions: Unknown action: \ -``` - -This is not an error with ModSecurity or OWASP CRS. In order to fix this -issue you can simply add a space before the continuation on the -offending line. For more information see [apache bugzilla](https://bz.apache.org/bugzilla/show_bug.cgi?id=55910). - -### Anomaly Mode Doesn't Work - -Sometimes on IIS or Nginx users run into an instance where anamoly mode -doesn't work as expected. In fact upon careful inspection of logs one -would notice that rules don't fire in the order we would expect. In -general this is a result of using the `'*'` operator within these -environments as it does not act the same way as in Apache. In general -within both Apache and IIS one should expliticly include the various -files present within the OWASP CRS instead of using the `'*'`. - -### Webserver returns error after CRS install - -This is likley due to a rule triggering. For instance in some cases a -rule is enabled that prohibits access via an IP address. Depending on -your -[SecDefaultAction](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecDefaultAction) -and -[SecRuleEngine](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) -configurations, this may result in a redirect loop or a status code. If -this is the problem you are experiencing you should consult your -error.log (or event viewer for IIS). From this location you can -determine the offending rule and add an exception if neccessary see -[false positives and tuning]({{< ref "../configuring/false_positives_tuning.md" >}}). +include coreruleset-{{< param crs_latest_release >}}/crs-setup.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-901-INITIALIZATION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-903.9001-DRUPAL-EXCLUSION-RULES.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-903.9002-WORDPRESS-EXCLUSION-RULES.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-903.9003-NEXTCLOUD-EXCLUSION-RULES.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-903.9004-DOKUWIKI-EXCLUSION-RULES.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-903.9005-CPANEL-EXCLUSION-RULES.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-903.9006-XENFORO-EXCLUSION-RULES.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-905-COMMON-EXCEPTIONS.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-910-IP-REPUTATION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-911-METHOD-ENFORCEMENT.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-912-DOS-PROTECTION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-913-SCANNER-DETECTION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-920-PROTOCOL-ENFORCEMENT.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-921-PROTOCOL-ATTACK.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-930-APPLICATION-ATTACK-LFI.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-931-APPLICATION-ATTACK-RFI.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-932-APPLICATION-ATTACK-RCE.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-933-APPLICATION-ATTACK-PHP.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-934-APPLICATION-ATTACK-NODEJS.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-941-APPLICATION-ATTACK-XSS.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-942-APPLICATION-ATTACK-SQLI.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-943-APPLICATION-ATTACK-SESSION-FIXATION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-944-APPLICATION-ATTACK-JAVA.conf +include coreruleset-{{< param crs_latest_release >}}/rules/REQUEST-949-BLOCKING-EVALUATION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-950-DATA-LEAKAGES.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-951-DATA-LEAKAGES-SQL.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-952-DATA-LEAKAGES-JAVA.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-953-DATA-LEAKAGES-PHP.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-954-DATA-LEAKAGES-IIS.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-959-BLOCKING-EVALUATION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-980-CORRELATION.conf +include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf +``` diff --git a/content/deployment/quick_start.md b/content/deployment/quick_start.md new file mode 100644 index 00000000..4ee4f2e2 --- /dev/null +++ b/content/deployment/quick_start.md @@ -0,0 +1,152 @@ +--- +title: "Quick Start Guide" +chapter: false +weight: 10 +--- + +> This quick start guide aims to get a CRS installation up and running as quickly as possible. This guide assumes that ModSecurity is already present and working. If unsure then refer to the [extended install]({{< ref "install.md" >}}) page for full details. + +## Downloading the Rule Set + +The first step is to download the Core Rule Set itself. The CRS project strongly recommends using a [supported version](https://github.com/coreruleset/coreruleset/security/policy). + +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 v{{< param crs_latest_release >}}. For *testing* the bleeding edge CRS version, nightly releases are also provided. + +### Verifying Releases + +{{% notice note %}} +Releases are signed using the CRS project's [GPG key](https://coreruleset.org/security.asc) (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`, execute: `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. +{{% /notice %}} + +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](https://github.com/coreruleset/coreruleset/releases). + +To download the release file and the corresponding signature: + +```bash +wget https://github.com/coreruleset/coreruleset/archive/refs/tags/v{{< param crs_latest_release >}}.tar.gz +wget https://github.com/coreruleset/coreruleset/releases/download/v{{< param crs_latest_release >}}/coreruleset-{{< param crs_latest_release >}}.tar.gz.asc +``` + +To verify the integrity of the release: + +```bash +gpg --verify coreruleset-{{< param crs_latest_release >}}.tar.gz.asc v{{< param crs_latest_release >}}.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 " [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: + +```bash +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: + +```bash +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 " [ultimate] +``` + +## Installing the Rule Set + +### Extracting the Files + +Once the rule set has been downloaded and verified, extract the rule set files to a well known location on the server. This will typically be somewhere in the web server directory. + +The examples presented below demonstrate using Apache. For information on configuring Nginx or IIS see the [extended install]({{< ref "install.md" >}}) page. + +Note that while it's common practice to make a new `modsecurity.d` folder, as outlined below, this isn't strictly necessary. The path scheme outlined is common on RHEL-based operating systems; the Apache path used may need to be adjusted to match the server's installation. + +```bash +mkdir /etc/httpd/modsecurity.d +tar -zxvf v{{< param crs_latest_release >}}.tar.gz -C /etc/httpd/modsecurity.d/owasp-modsecurity-crs +``` + +### Setting Up the Main Configuration File + +After extracting the rule set files, the next step is to set up the main OWASP Core Rule Set configuration file. An example configuration file is provided as part of the release package, located in the main directory: `csr-setup.conf.example`. + +{{% notice note %}} +Other aspects of ModSecurity, particularly engine-specific parameters, are controlled by the ModSecurity "recommended" configuration rules, `modsecurity.conf-recommended`. This file comes packaged with ModSecurity itself. +{{% /notice %}} + +In many scenarios, the default example CRS configuration will be a good enough starting point. It is, however, a good idea to take the time to look through the example configuration file *before* deploying it to make sure it's right for a given environment. For more information see [configuration]({{< ref "../configuring/crs.md" >}}). + +Once any settings have been changed within the example configuration file, as needed, it should be renamed to remove the .example portion, like so: + +```bash +cd /etc/httpd/modsecurity.d/owasp-modsecurity-crs/ +mv csr-setup.conf.example csr-setup.conf +``` + +### Include-ing the Rule Files + +The last step is to tell the web server where the rules are. This is achieved by `include`-ing the rule configuration files in the `httpd.conf` file. Again, this example demonstrates using Apache, but the process is similar on other systems (see the [extended install]({{< ref "install.md" >}}) page for details). + +```bash +echo 'IncludeOptional /etc/httpd/owasp-modsecurity-crs/csr-setup.conf' >> /etc/httpd/conf/httpd.conf +echo 'IncludeOptional /etc/httpd/owasp-modsecurity-crs/rules/*.conf' >> /etc/httpd/conf/httpd.conf +``` + +Now that everything has been configured, it should be possible to restart and being using the OWASP Core Rule Set. The CRS rules typically require a bit of tuning with rule exclusions, depending on the site and web applications in question. For more information on tuning, see [false positives and tuning]({{< ref "false_positives_tuning.md" >}}). + +```bash +systemctl restart httpd.service +``` + +## Alternative: Using Containers + +Another quick option is to use the official CRS [pre-packaged containers]({{< ref "../development/useful_tools/#official-crs-maintained-docker-images" >}}). Docker, Podman, or any compatible container engine can be used. The official CRS images are published in the Docker Hub. The image most often deployed is `owasp/modsecurity-crs`: it already has everything needed to get up and running quickly. + +The CRS project pre-packages both Apache and Nginx web servers along with the appropriate corresponding ModSecurity engine. More engines, like [Coraza](https://coraza.io/), will be added at a later date. + +To protect a running web server, all that's required is to get the appropriate image and set its configuration variables to make the WAF receives requests and proxies them to your backend server. + +Below is an example `docker-compose` file that can be used to pull the container images. All that needs to be changed is the `BACKEND` variable so that the WAF points to the backend server in question: + +```docker-compose +services: + modsec2-apache: + container_name: modsec2-apache + image: owasp/modsecurity-crs:apache + environment: + SERVERNAME: modsec2-apache + BACKEND: http:// + PORT: "80" + MODSEC_RULE_ENGINE: DetectionOnly + BLOCKING_PARANOIA: 2 + TZ: "${TZ}" + ERRORLOG: "/var/log/error.log" + ACCESSLOG: "/var/log/access.log" + MODSEC_AUDIT_LOG_FORMAT: Native + MODSEC_AUDIT_LOG_TYPE: Serial + MODSEC_AUDIT_LOG: "/var/log/modsec_audit.log" + MODSEC_TMP_DIR: "/tmp" + MODSEC_RESP_BODY_ACCESS: "On" + MODSEC_RESP_BODY_MIMETYPE: "text/plain text/html text/xml application/json" + COMBINED_FILE_SIZES: "65535" + volumes: + ports: + - "80:80" +``` + +That's all that needs to be done. Simply starting the container described above will instantly provide the protection of the latest stable CRS release in front of a given backend server or service. There are [lots of additional variables](https://github.com/coreruleset/modsecurity-crs-docker) that can be used to configure the container image and its behavior, so be sure to read the full documentation. diff --git a/content/deployment/quickstart.md b/content/deployment/quickstart.md deleted file mode 100644 index 6ef6319b..00000000 --- a/content/deployment/quickstart.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: "OWASP CRS Quickstart" -menuTitle: "Quickstart" -chapter: false -weight: 10 ---- - -Welcome to the OWASP Core RuleSet (CRS) quickstart guide. We will -attempt to get you up and running with CRS as quick as possible. This -guide assumes ModSecurity is already working. If you are unsure see the -[extended install]({{< ref "install.md" >}}) page. Otherwise, lets jump in. - -You'll first need to download the ruleset. Our strong recommendation is that you [use a supported version](https://github.com/coreruleset/coreruleset/security/policy). Using a browser (or -equivalent) visit the following URL: https://github.com/coreruleset/coreruleset/releases. - -There we have all our official releases listed. For production we recommend you to use the latest release, v{{< param crs_latest_release >}}. If you want to test the bleeding edge version, we also provide _nightly releases_. - -### Verifying our release - -{{% notice note %}} -Releases are signed using [our GPG key](https://coreruleset.org/security.asc), (fingerprint: 3600 6F0E 0BA1 6783 2158 8211 38EE ACA1 AB8A 6E72). You can verify the release using GPG/PGP compatible tooling. - -To get our key using gpg from public servers: `gpg --keyserver pgp.mit.edu --recv 0x38EEACA1AB8A6E72` (this id should be equal to the last sixteen hex characters in our fingerprint). -You can also use `gpg --fetch-key https://coreruleset.org/security.asc` directly. -{{% /notice %}} - -The steps here assume you are using a *nix operating system. For Windows you will be doing a similar install, but probably using the zip file from our releases. - -To get the release file and the corresponding signature: - -```bash -wget https://github.com/coreruleset/coreruleset/archive/refs/tags/v{{< param crs_latest_release >}}.tar.gz -wget https://github.com/coreruleset/coreruleset/releases/download/v{{< param crs_latest_release >}}/coreruleset-{{< param crs_latest_release >}}.tar.gz.asc -``` - -Optional verification: -```bash -gpg --verify coreruleset-{{< param crs_latest_release >}}.tar.gz.asc v{{< param crs_latest_release >}}.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 " [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, the verification succeeded. If you see a warning like the above, it means you know our public key, but you are not trusting it. You can trust it by using the following method: - -```bash -gpg edit-key 36006F0E0BA167832158821138EEACA1AB8A6E72 -gpg> trust -Your decision: 5 (ultimate trust) -Are you sure: Yes -gpg> quit -``` - -Then you will see this result when verifying: -```bash -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 " [ultimate] -``` - -### Installing the files - -Once you downloaded and verified the release, extract it somewhere well known on your server. -Typically this will be in the webserver directory. We are demonstrating -with Apache below. For information on configuring Nginx or IIS see -the [extended install]({{< ref "install.md" >}}) page. Additionally, while it is a -successful practice to make a new `modsecurity.d` folder as outlined -below, it isn't strictly necessary. The path scheme outlined is the -common to RHEL based operating systems, you may have to adjust the -Apache path used to match your installation. - -```bash -mkdir /etc/httpd/modsecurity.d -tar -zxvf v{{< param crs_latest_release >}}.tar.gz -C /etc/httpd/modsecurity.d/owasp-modsecurity-crs -``` - -After extracting the rule set we have to set up the main OWASP Core Rule Set -configuration file. We provide an example configuration file as part of -the package located in the main directory: `csr-setup.conf.example`. - -(Note: Other aspects of ModSecurity are controlled by the -recommended ModSecurity configuration rules, packaged with ModSecurity) - -For many people -this will be a good enough starting point but you should take the time -to look through this file before deploying it to make sure it's right -for your environment. For more information see [configuration]({{< ref "../configuring/crs.md" >}}). - -Once you have changed any settings within the configuration file, as -needed, you should rename it to remove the .example portion - -```bash -cd /etc/httpd/modsecurity.d/owasp-modsecurity-crs/ -mv csr-setup.conf.example csr-setup.conf -``` - -Only one more step! We now have to tell our web server where our rules -are. We do this by including the rule configuration files in our -httpd.conf file. Again, we are demonstrating using Apache but it is -similar on other systems see the [extended install]({{< ref "install.md" >}}) page for details. - -```bash -echo 'IncludeOptional /etc/httpd/owasp-modsecurity-crs/csr-setup.conf' >> /etc/httpd/conf/httpd.conf -echo 'IncludeOptional /etc/httpd/owasp-modsecurity-crs/rules/*.conf' >> /etc/httpd/conf/httpd.conf -``` - -Now that we have configured everything you should be able to restart and -enjoy using the OWASP Core Rule Set. Typically these rules will require -a bit of exception tuning, depending on your site. For more information -see [false positives and tuning]({{< ref "false_positives_tuning.md" >}}). Enjoy! - -```bash -systemctl restart httpd.service -```