From 7ee6693d9293706c32d4123aa5f8caff34bdc5da Mon Sep 17 00:00:00 2001 From: Felipe Zipitria Date: Thu, 21 Apr 2022 15:36:37 -0700 Subject: [PATCH 1/8] docs: update quickstart with container information Signed-off-by: Felipe Zipitria --- content/deployment/quickstart.md | 38 ++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/content/deployment/quickstart.md b/content/deployment/quickstart.md index 6ef6319b..42245a89 100644 --- a/content/deployment/quickstart.md +++ b/content/deployment/quickstart.md @@ -116,3 +116,41 @@ see [false positives and tuning]({{< ref "false_positives_tuning.md" >}}). Enjoy ```bash systemctl restart httpd.service ``` + +## Using Containers + +Another quick option is to leverage our pre-packaged containers. You can use docker, podman, or any container compatible engine. Our images are published in the docker hub. The one you probably want is the `owasp/modsecurity-crs`: it already has everything to get you up and running quickly. + +We already pre-package both Apache and Nginx Web servers with the corresponding ModSecurity engine. More engines (like Coraza) will come later. + +So to protect your running Web Server, just get the image and use these configuration variables to make the WAF receive the requests and proxy your server. + +This is an example `docker-compose` that can be used to pull the container images. You just need to change the `BACKEND` server so it points to your own server: + +```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 it! Now just starting that container will give you the latest stable CRS protecting your site. There are [plenty of additional variables](https://github.com/coreruleset/modsecurity-crs-docker) you can use to configure the container image and its behaviour. Be sure to check those out! \ No newline at end of file From 6c2d1cd1cce0125f30d73c8a0621bd2fb603c336 Mon Sep 17 00:00:00 2001 From: Felipe Zipitria Date: Thu, 21 Apr 2022 15:37:16 -0700 Subject: [PATCH 2/8] docs: remove update script Signed-off-by: Felipe Zipitria --- content/deployment/install.md | 352 +++++++--------------------------- 1 file changed, 66 insertions(+), 286 deletions(-) diff --git a/content/deployment/install.md b/content/deployment/install.md index 0b304e33..7cb2f2e9 100644 --- a/content/deployment/install.md +++ b/content/deployment/install.md @@ -2,146 +2,82 @@ title: "Installing CoreRuleSet" menuTitle: "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 %}} +#### TODO: insert TOC If you need mode information than the one in the [quickstart guide]({{< ref "quickstart.md" >}}), here we extend with additional details so keep reading. -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). +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). ## 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 hard but it does have one major requirement: a compatible engine. The base reference engine shown here 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. +In order to run the CRS `3.x` using ModSecurity we recommend you to use the latest version available. For Nginx please use the `3.x` branch of ModSecurity, and for Apache use the latest `2.x` branch. {{% /notice %}} -## Finding where to edit in your configuration +## How to install a compatible 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. +Here we will cover two different ways of getting your engine up and running: you can use your favorite engine provided by your OS distribution, or it can be compiled from source. Here we will cover ModSecurity installs, but you can see the Coraza install documents [here](https://www.coraza.io). + +### Installing ModSecurity in your Linux distribution + +Pre-packaged modsecurity can be get from major distributions. -### Apache 2.x with ModSecurity 2.x Compiled +- Debian: our friends at [DigitalWave](https://modsecurity.digitalwave.hu) package and keep updates of ModSecurity for debian and derivatives +- Fedora: + - `dnf install mod_security` for Apache + ModSecurity2 + - `dnf install libmodse +- RHEL compatible: you will need to install epel and then `yum install mod_security`. -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. +### Compiling ModSecurity + +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. ```apache SecRuleEngine On SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" ``` -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 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. +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: +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: ```bash SecRuleEngine On SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" ``` -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. - -### Nginx with ModSecurity 2.x Compiled - -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. - -```nginx -location / { - ModSecurityEnabled on; - ModSecurityConfig modsec_includes.conf; -} -``` - -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`: +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. -```Apache -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" -``` +{{% notice error %}} +**Nginx with ModSecurity 2.x** -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 🚀. +This is not supported. It doesn't work as expected. +{{% /notice %}} ### Nginx with ModSecurity 3.x (libmodsecurity) Compiled - +TBD ### Microsoft IIS with ModSecurity 2.x -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. - -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. +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. + 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. -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`: +By default all installations of ModSecurity without [SecRuleEngine]() declared will start in DetectionOnly mode. IIS, by default, explicitly declares [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 SecRuleEngine On @@ -152,7 +88,7 @@ This rule will be triggered when you go to your web page and pass the testparam 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: -\ +TBD: insert log image If you have gotten to this step ModSecurity is functioning on IIS and you now know where to place new directives. @@ -167,7 +103,7 @@ To get our key using gpg: `gpg --keyserver pgp.mit.edu --recv 0x38EEACA1AB8A6E72 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. +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: @@ -177,6 +113,7 @@ wget https://github.com/coreruleset/coreruleset/releases/download/v{{< param crs ``` 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 @@ -198,6 +135,7 @@ 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 @@ -216,26 +154,26 @@ the root 'coreruleset-{{< param crs_latest_release >}}' folder and is named 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. +- 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 @@ -274,6 +212,13 @@ to do a good job at describing what each file does additional information is available in the [rules](rules.md) section. +## Finding where to edit in your configuration + +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. + ### Includes for Apache Apache will include from the Apache Root directory (`/etc/httpd/`, @@ -345,168 +290,3 @@ 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" >}}). From 6cdd09c0dd710921fb15e45b7766bcf2a52b9444 Mon Sep 17 00:00:00 2001 From: Felipe Zipitria Date: Thu, 21 Apr 2022 17:08:19 -0700 Subject: [PATCH 3/8] docs: update extended install Signed-off-by: Felipe Zipitria --- content/deployment/install.md | 257 +++++++++++++--------------------- 1 file changed, 98 insertions(+), 159 deletions(-) diff --git a/content/deployment/install.md b/content/deployment/install.md index 7cb2f2e9..f4c80577 100644 --- a/content/deployment/install.md +++ b/content/deployment/install.md @@ -6,8 +6,6 @@ disableToc: false weight: 20 --- -#### TODO: insert TOC - If you need mode information than the one in the [quickstart guide]({{< ref "quickstart.md" >}}), here we extend with additional details so keep reading. 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). @@ -24,73 +22,75 @@ In order to run the CRS `3.x` using ModSecurity we recommend you to use the late Here we will cover two different ways of getting your engine up and running: you can use your favorite engine provided by your OS distribution, or it can be compiled from source. Here we will cover ModSecurity installs, but you can see the Coraza install documents [here](https://www.coraza.io). -### Installing ModSecurity in your Linux distribution +### Installing ModSecurity -Pre-packaged modsecurity can be get from major distributions. +Pre-packaged modsecurity can be get from major Linux distributions. -- Debian: our friends at [DigitalWave](https://modsecurity.digitalwave.hu) package and keep updates of ModSecurity for debian and derivatives -- Fedora: +- Debian: our friends at [DigitalWave](https://modsecurity.digitalwave.hu) package and most importantly **keep ModSecurity updated** for debian and derivatives, so check their repo! +- Fedora: - `dnf install mod_security` for Apache + ModSecurity2 - - `dnf install libmodse -- RHEL compatible: you will need to install epel and then `yum install mod_security`. +- RHEL compatible: you will need to install EPEL and then `yum install mod_security`. -### Compiling ModSecurity +For Windows, get the latest MSI package from https://github.com/SpiderLabs/ModSecurity/releases. -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. +{{% notice tip %}} +**Distributions might not update their releases frequently** -```apache -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" -``` +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. +{{% /notice %}} -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`. +As the different engines and distributions have differeent layouts for their configuration, and to simplify our documentation, we will use the prefix `/` from now on. -If you obtained a 403 status code your ModSecurity instance is functioning correctly with Apache and you now know where to place directives. +Examples of this `/` are: +- `/etc/apache2` in Debian and derivatives +- `/etc/httpd` in RHEL and derivatives +- `/usr/local/apache2` if you compiled apache from source with the default prefix +- `C:\Program Files\ModSecurity IIS\` (or Program Files(x86) depending on your configuration) on Windows +- `/etc/nginx` -### Apache 2.x with ModSecurity 2.x Packaged (RHEL) +### Compiling ModSecurity -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. +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](https://github.com/SpiderLabs/ModSecurity/wiki). Having compiled ModSecurity there is a simple test to see if your installation is working. If you have compiled from source you would need to include the directive to **load your module** in your Web Server. -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: +Examples: +- apache: `LoadModule security2_module modules/mod_security2.so` +- nginx: `load_module modules/ngx_http_modsecurity_module.so;` -```bash -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" +Now you restart your server and modsecurity should output that it is being used. Examples: +``` +2022/04/21 23:45:52 [notice] 1#1: ModSecurity-nginx v1.0.2 (rules loaded inline/local/remote: 0/6/0) +``` +Apache shows: +``` +[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' ``` -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. - -{{% notice error %}} -**Nginx with ModSecurity 2.x** +{{% notice warning "Nginx with ModSecurity 2.x" "skull-crossbones" %}} -This is not supported. It doesn't work as expected. +This is **not** supported. It doesn't work as expected. Our recommendation is to avoid this setup. {{% /notice %}} ### Nginx with ModSecurity 3.x (libmodsecurity) Compiled -TBD +You can found the compilation recipe in the [ModSecurity wiki](https://github.com/SpiderLabs/ModSecurity/wiki/Compilation-recipes-for-v3.x). ### Microsoft IIS with ModSecurity 2.x -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. - 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. +The inital configuration file, is `modsecurity_iis.conf`. This file will be parsed by the ModSecurity for both ModSecurity and `'Include'` directives. -By default all installations of ModSecurity without [SecRuleEngine]() declared will start in DetectionOnly mode. IIS, by default, explicitly declares [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 -SecRuleEngine On -SecRule ARGS:testparam "@contains test" "id:1234,deny,status:403,msg:'Our test rule has triggered'" -``` - -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`. - -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: +Additionally, in your Event Viewer, under `Windows Logs\Application'`, we should see a new log that looks like the following: TBD: insert log image -If you have gotten to this step ModSecurity is functioning on IIS and you now know where to place new directives. +If you have gotten to this step ModSecurity is working on IIS and you now know where to place new directives. ## Downloading OWASP CRS @@ -147,146 +147,85 @@ Once you downloaded and verified the release, you are ready to continue with the ### 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`: +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 features such as the rule engine, the audit engine, logging etc. This task is part of your initial setup. For ModSecurity, if you haven't done this yet please check out the [recommended 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 our rules will consider many issues with different databases and languages. If you are running in 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`: ```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 +In addition to `csr-setup.conf.example` there are two other .example files within our repository. These files are: +`rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf.example` and `rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.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 compatibility 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: ```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. - -## Finding where to edit in your configuration - -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. +The engine should support the `Include` directive out of the box. The directive tells the engine to parse additional files for 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. ### 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 +We recommend you creating a folder specifically for the rules. In our example we have named this `modsecurity.d` and placed in within the root `/` 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 appropiate 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 ```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 from the Nginx conf directory (`/etc/nginx` or `/usr/local/nginx/conf/` depending on the environment). Because only one `ModSecurityConfig` directive can be specified within nginx.conf we recommend 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 specify the appropiate 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 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. +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 +``` \ No newline at end of file From 193188a0eeca9091e7aab60e15e4ab0f86f6a06d Mon Sep 17 00:00:00 2001 From: Felipe Zipitria Date: Thu, 21 Apr 2022 17:15:04 -0700 Subject: [PATCH 4/8] fix: update to american english Signed-off-by: Felipe Zipitria --- content/deployment/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/deployment/quickstart.md b/content/deployment/quickstart.md index 42245a89..1a299c48 100644 --- a/content/deployment/quickstart.md +++ b/content/deployment/quickstart.md @@ -153,4 +153,4 @@ services: - "80:80" ``` -That's it! Now just starting that container will give you the latest stable CRS protecting your site. There are [plenty of additional variables](https://github.com/coreruleset/modsecurity-crs-docker) you can use to configure the container image and its behaviour. Be sure to check those out! \ No newline at end of file +That's it! Now just starting that container will give you the latest stable CRS protecting your site. There are [plenty of additional variables](https://github.com/coreruleset/modsecurity-crs-docker) you can use to configure the container image and its behavior. Be sure to check those out! \ No newline at end of file From c3347f0749ac9bb6bb768299849f646a637d3410 Mon Sep 17 00:00:00 2001 From: Xanadu Date: Sun, 24 Apr 2022 13:18:23 +0100 Subject: [PATCH 5/8] Make titles consistent with the other pages --- content/deployment/install.md | 7 +++---- content/deployment/{quickstart.md => quick_start.md} | 7 +++---- 2 files changed, 6 insertions(+), 8 deletions(-) rename content/deployment/{quickstart.md => quick_start.md} (97%) diff --git a/content/deployment/install.md b/content/deployment/install.md index f4c80577..c077d438 100644 --- a/content/deployment/install.md +++ b/content/deployment/install.md @@ -1,12 +1,11 @@ --- -title: "Installing CoreRuleSet" -menuTitle: "Extended Install" +title: "Extended Install" chapter: false disableToc: false weight: 20 --- -If you need mode information than the one in the [quickstart guide]({{< ref "quickstart.md" >}}), here we extend with additional details so keep reading. +If you need mode information than the one in the [quick start guide]({{< ref "quick_start.md" >}}), here we extend with additional details so keep reading. 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). @@ -228,4 +227,4 @@ include coreruleset-{{< param crs_latest_release >}}/rules/RESPONSE-954-DATA-LEA 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 -``` \ No newline at end of file +``` diff --git a/content/deployment/quickstart.md b/content/deployment/quick_start.md similarity index 97% rename from content/deployment/quickstart.md rename to content/deployment/quick_start.md index 1a299c48..5e722031 100644 --- a/content/deployment/quickstart.md +++ b/content/deployment/quick_start.md @@ -1,11 +1,10 @@ --- -title: "OWASP CRS Quickstart" -menuTitle: "Quickstart" +title: "Quick Start Guide" chapter: false weight: 10 --- -Welcome to the OWASP Core RuleSet (CRS) quickstart guide. We will +Welcome to the OWASP Core RuleSet (CRS) quick start 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. @@ -153,4 +152,4 @@ services: - "80:80" ``` -That's it! Now just starting that container will give you the latest stable CRS protecting your site. There are [plenty of additional variables](https://github.com/coreruleset/modsecurity-crs-docker) you can use to configure the container image and its behavior. Be sure to check those out! \ No newline at end of file +That's it! Now just starting that container will give you the latest stable CRS protecting your site. There are [plenty of additional variables](https://github.com/coreruleset/modsecurity-crs-docker) you can use to configure the container image and its behavior. Be sure to check those out! From 0dde83d5060468cd83ff082a58ac21a30a613a38 Mon Sep 17 00:00:00 2001 From: Xanadu Date: Sun, 24 Apr 2022 14:21:00 +0100 Subject: [PATCH 6/8] Tweak lanaguage, make consistent with other pages --- content/deployment/quick_start.md | 99 +++++++++++++++---------------- 1 file changed, 48 insertions(+), 51 deletions(-) diff --git a/content/deployment/quick_start.md b/content/deployment/quick_start.md index 5e722031..d78ac7e1 100644 --- a/content/deployment/quick_start.md +++ b/content/deployment/quick_start.md @@ -4,35 +4,37 @@ chapter: false weight: 10 --- -Welcome to the OWASP Core RuleSet (CRS) quick start 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. +> This quick start guide aims to get a CRS installation up and running as quickly as possible. This guide assumes that ModSecurity is already working. If unsure then refer to the [extended install]({{< ref "install.md" >}}) page for full details. -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. +## Downloading the Rule Set -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_. +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). -### Verifying our release +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 [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 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. +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 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 @@ -43,7 +45,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 @@ -53,7 +57,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 @@ -61,70 +66,62 @@ gpg: using RSA key 36006F0E0BA167832158821138EEACA1AB8A6E72 gpg: Good signature from "OWASP Core Rule Set " [ultimate] ``` -### Installing the files +## Installing the Rule Set + +### Extracting 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. +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 ``` -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`. +### 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`. -(Note: Other aspects of ModSecurity are controlled by the -recommended ModSecurity configuration rules, packaged with ModSecurity) +{{% 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 %}} -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" >}}). +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 you have changed any settings within the configuration file, as -needed, you should rename it to remove the .example portion +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 ``` -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. +### 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 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! +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 ``` -## Using Containers +## Alternative: Using Containers -Another quick option is to leverage our pre-packaged containers. You can use docker, podman, or any container compatible engine. Our images are published in the docker hub. The one you probably want is the `owasp/modsecurity-crs`: it already has everything to get you up and running quickly. +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. -We already pre-package both Apache and Nginx Web servers with the corresponding ModSecurity engine. More engines (like Coraza) will come later. +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. -So to protect your running Web Server, just get the image and use these configuration variables to make the WAF receive the requests and proxy your server. +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. -This is an example `docker-compose` that can be used to pull the container images. You just need to change the `BACKEND` server so it points to your own 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: @@ -133,7 +130,7 @@ services: image: owasp/modsecurity-crs:apache environment: SERVERNAME: modsec2-apache - BACKEND: http:// + BACKEND: http:// PORT: "80" MODSEC_RULE_ENGINE: DetectionOnly BLOCKING_PARANOIA: 2 @@ -152,4 +149,4 @@ services: - "80:80" ``` -That's it! Now just starting that container will give you the latest stable CRS protecting your site. There are [plenty of additional variables](https://github.com/coreruleset/modsecurity-crs-docker) you can use to configure the container image and its behavior. Be sure to check those out! +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. From e0f88c00be07d10113b48669d80042379da56dce Mon Sep 17 00:00:00 2001 From: Xanadu Date: Sun, 24 Apr 2022 14:23:58 +0100 Subject: [PATCH 7/8] Tweak preamble --- content/deployment/quick_start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/deployment/quick_start.md b/content/deployment/quick_start.md index d78ac7e1..4ee4f2e2 100644 --- a/content/deployment/quick_start.md +++ b/content/deployment/quick_start.md @@ -4,7 +4,7 @@ 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 working. If unsure then refer to the [extended install]({{< ref "install.md" >}}) page for full details. +> 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 From 6af1a02e4d319175190d2460716b9bedbd5641a9 Mon Sep 17 00:00:00 2001 From: Xanadu Date: Sun, 24 Apr 2022 17:17:46 +0100 Subject: [PATCH 8/8] Tweak lanaguage, make consistent with other pages --- content/deployment/install.md | 160 ++++++++++++++++++++-------------- 1 file changed, 95 insertions(+), 65 deletions(-) diff --git a/content/deployment/install.md b/content/deployment/install.md index c077d438..50ba50d3 100644 --- a/content/deployment/install.md +++ b/content/deployment/install.md @@ -5,61 +5,87 @@ disableToc: false weight: 20 --- -If you need mode information than the one in the [quick start guide]({{< ref "quick_start.md" >}}), here we extend with additional details so keep reading. +> 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" >}}). -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). +## Contact Us + +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: a compatible engine. The base reference engine shown here is ModSecurity. +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` using ModSecurity we recommend you to use the latest version available. For Nginx please use the `3.x` branch of ModSecurity, and for Apache use the latest `2.x` branch. +{{% 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 %}} -## How to install a compatible engine +## Installing a Compatible WAF Engine + +Two different methods to get an engine up and running are presented here: -Here we will cover two different ways of getting your engine up and running: you can use your favorite engine provided by your OS distribution, or it can be compiled from source. Here we will cover ModSecurity installs, but you can see the Coraza install documents [here](https://www.coraza.io). +- using the chosen engine as provided and packaged by the OS distribution +- compiling the chosen engine from source -### Installing ModSecurity +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). -Pre-packaged modsecurity can be get from major Linux distributions. +### Option 1: Installing Pre-Packaged ModSecurity -- Debian: our friends at [DigitalWave](https://modsecurity.digitalwave.hu) package and most importantly **keep ModSecurity updated** for debian and derivatives, so check their repo! -- Fedora: - - `dnf install mod_security` for Apache + ModSecurity2 -- RHEL compatible: you will need to install EPEL and then `yum install mod_security`. +ModSecurity is frequently pre-packaged and is available from several major Linux distributions. + +- **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`. For Windows, get the latest MSI package from https://github.com/SpiderLabs/ModSecurity/releases. -{{% notice tip %}} -**Distributions might not update their releases frequently** +{{% notice warning %}} +**Distributions might not update their ModSecurity releases 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. +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 %}} -As the different engines and distributions have differeent layouts for their configuration, and to simplify our documentation, we will use the prefix `/` from now on. +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. + +Examples of `/` include: -Examples of this `/` are: - `/etc/apache2` in Debian and derivatives - `/etc/httpd` in RHEL and derivatives -- `/usr/local/apache2` if you compiled apache from source with the default prefix -- `C:\Program Files\ModSecurity IIS\` (or Program Files(x86) depending on your configuration) on Windows +- `/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` -### Compiling ModSecurity +### Option 2: Compiling ModSecurity From Source + +Compiling ModSecurity is easy, but slightly outside the scope of this document. For information on how to compile ModSecurity, refer to: + +- the official [ModSecurity documentation](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*: + +- Nginx with ModSecurity v2 +- Apache with ModSecurity v3 +{{% /notice %}} + +#### Testing the Compiled Module -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](https://github.com/SpiderLabs/ModSecurity/wiki). Having compiled ModSecurity there is a simple test to see if your installation is working. If you have compiled from source you would need to include the directive to **load your module** in your Web Server. +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: -Examples: -- apache: `LoadModule security2_module modules/mod_security2.so` -- nginx: `load_module modules/ngx_http_modsecurity_module.so;` +- **Apache:** `LoadModule security2_module modules/mod_security2.so` +- **Nginx:** `load_module modules/ngx_http_modsecurity_module.so;` + +Now restart the web server. ModSecurity should output that it's being used. + +Nginx should show something like: -Now you restart your server and modsecurity should output that it is being used. Examples: ``` 2022/04/21 23:45:52 [notice] 1#1: ModSecurity-nginx v1.0.2 (rules loaded inline/local/remote: 0/6/0) ``` -Apache shows: + +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" @@ -72,46 +98,42 @@ Apache shows: [Thu Apr 21 23:55:35.187125 2022] [core:notice] [pid 2530:tid 140410548673600] AH00094: Command line: '/usr/sbin/apache2' ``` -{{% notice warning "Nginx with ModSecurity 2.x" "skull-crossbones" %}} - -This is **not** supported. It doesn't work as expected. Our recommendation is to avoid this setup. -{{% /notice %}} - -### Nginx with ModSecurity 3.x (libmodsecurity) Compiled +##### Microsoft IIS with ModSecurity 2.x -You can found the compilation recipe in the [ModSecurity wiki](https://github.com/SpiderLabs/ModSecurity/wiki/Compilation-recipes-for-v3.x). +The initial configuration file is `modsecurity_iis.conf`. This file will be parsed by ModSecurity for both ModSecurity directives and `'Include'` directives. -### Microsoft IIS with ModSecurity 2.x +Additionally, in the Event Viewer, under `Windows Logs\Application`, it should be possible to see a new log entry showing ModSecurity being successfully loaded. -The inital configuration file, is `modsecurity_iis.conf`. This file will be parsed by the ModSecurity for both ModSecurity and `'Include'` directives. +At this stage, the ModSecurity on IIS setup is working and new directives can be placed in the configuration file as needed. -Additionally, in your Event Viewer, under `Windows Logs\Application'`, we should see a new log that looks like the following: +## Downloading the OWASP Core Rule Set -TBD: insert log image +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). -If you have gotten to this step ModSecurity is working on IIS and you now know where to place new directives. +Official CRS releases can be found at the following URL: https://github.com/coreruleset/coreruleset/releases. -## Downloading OWASP CRS +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. -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_. +### 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 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. +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 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 @@ -123,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 @@ -133,7 +157,7 @@ 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 @@ -142,29 +166,33 @@ 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. +With the CRS release downloaded and verified, the rest of the set up can continue. + +## Setting Up OWASP CRS -### 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. -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. +At a minimum, keep in mind the following: -- CRS does not configure features such as the rule engine, the audit engine, logging etc. This task is part of your initial setup. For ModSecurity, if you haven't done this yet please check out the [recommended 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 our rules will consider many issues with different databases and languages. If you are running in a specific environment, you probably want to limit this behavior for performance reasons. +- 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) -- Do make sure you have added any methods, static resources, content types, or file extensions that your site needs beyond the basic ones listed. +- Make sure to add any HTTP methods, static resources, content types, or file extensions that are needed, beyond the default 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`: +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-900-EXCLUSION-RULES-BEFORE-CRS.conf.example` and `rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.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 compatibility 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-900-EXCLUSION-RULES-BEFORE-CRS.conf.example rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf @@ -173,11 +201,13 @@ mv rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example rules/RESPONSE-999- ## Proceeding with the Installation -The engine should support the `Include` directive out of the box. The directive tells the engine to parse additional files for 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 -We recommend you creating a folder specifically for the rules. In our example we have named this `modsecurity.d` and placed in within the root `/` 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 appropiate 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 @@ -189,7 +219,7 @@ We recommend you creating a folder specifically for the rules. In our example we ### Includes for Nginx -Nginx will include from the Nginx conf directory (`/etc/nginx` or `/usr/local/nginx/conf/` depending on the environment). Because only one `ModSecurityConfig` directive can be specified within nginx.conf we recommend 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 specify the appropiate 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