diff --git a/content/1-getting-started/1-1-crs-installation.md b/content/1-getting-started/1-1-crs-installation.md index 7dbe6d10..0193fe46 100644 --- a/content/1-getting-started/1-1-crs-installation.md +++ b/content/1-getting-started/1-1-crs-installation.md @@ -6,7 +6,7 @@ chapter: false aliases: ["../deployment/install"] --- -This guide aims to get a CRS installation up and running. This guide assumes that a compatible ModSecurity engine is already present and working. If unsure then refer to the [extended install]({{< ref "1-2-extended_install.md" >}}) page for full details. +This guide aims to get a CRS installation up and running. This guide assumes that a compatible ModSecurity engine is already present and working. If unsure then refer to the [extended install]({{% ref "1-2-extended_install.md" %}}) page for full details. ## Downloading the Rule Set @@ -74,7 +74,7 @@ gpg: Good signature from "OWASP CRS " [ultimate] 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 "1-2-extended_install.md" >}}) page. +The examples presented below demonstrate using Apache. For information on configuring Nginx or IIS see the [extended install]({{% ref "1-2-extended_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. @@ -114,7 +114,7 @@ mv crs-setup.conf.example crs-setup.conf ### Include-ing the Rule Files -The last step is to tell the web server where the rules are. This is achieved by `include`-ing the rule configuration files in the `httpd.conf` file. Again, this example demonstrates using Apache, but the process is similar on other systems (see the [extended install]({{< ref "1-2-extended_install.md" >}}) page for details). +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 "1-2-extended_install.md" %}}) page for details). ```bash echo 'IncludeOptional {{< param crs_install_dir >}}/crs-setup.conf' >> /etc/httpd/conf/httpd.conf @@ -124,7 +124,7 @@ echo 'IncludeOptional {{< param crs_install_dir >}}/rules/*.conf' >> /etc/httpd/ echo 'IncludeOptional {{< param crs_install_dir >}}/plugins/*-after.conf' >> /etc/httpd/conf/httpd.conf ``` -Now that everything has been configured, it should be possible to restart and begin using the OWASP CRS. 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 "2-3-false-positives-and-tuning.md" >}}). +Now that everything has been configured, it should be possible to restart and begin using the OWASP CRS. 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 "2-3-false-positives-and-tuning.md" %}}). ```bash systemctl restart httpd.service @@ -184,7 +184,7 @@ Depending on your configurated thresholds, this should be detected as a maliciou ### Upgrading from CRS 3.x to CRS 4 -The most impactful change is the removal of application exclusion packages in favor of a plugin system. If you had activated the exclusion packages in CRS 3, you should download the plugins for them and place them in the plugins subdirectory. We maintain the list of plugins in our [Plugin Registry](https://github.com/coreruleset/plugin-registry). You can find detailed information on working with plugins in our [plugins documentation]({{< ref "4-about-plugins/" >}}). +The most impactful change is the removal of application exclusion packages in favor of a plugin system. If you had activated the exclusion packages in CRS 3, you should download the plugins for them and place them in the plugins subdirectory. We maintain the list of plugins in our [Plugin Registry](https://github.com/coreruleset/plugin-registry). You can find detailed information on working with plugins in our [plugins documentation]({{% ref "4-about-plugins/" %}}). In terms of changes to the detection rules, the amount of changes is smaller than in the CRS 2—3 changeover. Most rules have only evolved slightly, so it is recommended that you keep any existing custom exclusions that you have made under CRS 3. diff --git a/content/1-getting-started/1-2-extended_install.md b/content/1-getting-started/1-2-extended_install.md index 7e9826d7..4507c4f1 100644 --- a/content/1-getting-started/1-2-extended_install.md +++ b/content/1-getting-started/1-2-extended_install.md @@ -6,7 +6,7 @@ chapter: false aliases: ["../deployment/extended_install"] --- -> 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 "1-1-crs-installation.md" >}}). +> 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 "1-1-crs-installation.md" %}}). ## Contact Us @@ -177,7 +177,7 @@ At a minimum, keep in mind the following: - CRS does not configure features such as the rule engine, audit engine, logging, etc. This task is part of the initial *engine* setup and is not a job for the rule set. For ModSecurity, if not already done, see the [recommended configuration](https://github.com/owasp-modsecurity/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 "2-1-anomaly_scoring.md" >}} "Anomaly"). +- Make sure to configure the anomaly scoring thresholds. For more information see [Anomaly]({{% ref "2-1-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. - Make sure to add any HTTP methods, static resources, content types, or file extensions that are needed, beyond the default ones listed. @@ -192,7 +192,7 @@ In addition to `crs-setup.conf.example`, there are two other ".example" files wi - `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 "2-3-false-positives-and-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: +These files are designed to provide the rule maintainer with the ability to modify rules (see [false positives and tuning]({{% ref "2-3-false-positives-and-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 @@ -203,7 +203,7 @@ mv rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf.example rules/RESPONSE-999- 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 "3-about-rules/rules.md" >}}) section. +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 "3-about-rules/rules.md" %}}) section. ### Includes for Apache diff --git a/content/2-how-crs-works/2-3-false-positives-and-tuning.md b/content/2-how-crs-works/2-3-false-positives-and-tuning.md index adbcefee..fa00a388 100644 --- a/content/2-how-crs-works/2-3-false-positives-and-tuning.md +++ b/content/2-how-crs-works/2-3-false-positives-and-tuning.md @@ -12,7 +12,7 @@ aliases: ["../concepts/false_positives_tuning"] CRS provides _generic_ attack detection capabilities. A fresh CRS deployment has no awareness of the web services that may be running behind it, or the quirks of how those services work. It is possible that *genuine* transactions may cause some CRS rules to match in error, if the transactions happen to match one of the generic attack behaviors or patterns that are being detected. Such a match is referred to as a *false positive*, or false alarm. -False positives are particularly likely to happen when operating at higher [paranoia levels]({{< ref "2-2-paranoia_levels.md" >}} "Page describing paranoia levels."). While paranoia level 1 is designed to cause few, ideally zero, false positives, higher paranoia levels are increasingly likely to cause false positives. Each successive paranoia level introduces additional rules, with *higher* paranoia levels adding *more aggressive* rules. As such, the higher the paranoia level is the more likely it is that false positives will occur. That is the cost of the higher security provided by higher paranoia levels: the additional time it takes to tune away the increasing number of false positives. +False positives are particularly likely to happen when operating at higher [paranoia levels]({{% ref "2-2-paranoia_levels.md" %}} "Page describing paranoia levels."). While paranoia level 1 is designed to cause few, ideally zero, false positives, higher paranoia levels are increasingly likely to cause false positives. Each successive paranoia level introduces additional rules, with *higher* paranoia levels adding *more aggressive* rules. As such, the higher the paranoia level is the more likely it is that false positives will occur. That is the cost of the higher security provided by higher paranoia levels: the additional time it takes to tune away the increasing number of false positives. ### Example False Positive diff --git a/content/3-about-rules/rule_writing.md b/content/3-about-rules/rule_writing.md index 2c53da53..caca53cf 100644 --- a/content/3-about-rules/rule_writing.md +++ b/content/3-about-rules/rule_writing.md @@ -7,7 +7,7 @@ chapter: false > From years of experience, the CRS project has assembled a wealth of knowledge and advice on how to write clear and efficient WAF rules, as this page outlines. -The CRS project's advice on rule writing is contained within the [contribution guidelines]({{< ref "6-1-contribution-guidelines.md" >}}), a document which can also be found in plain text form in CRS releases for offline reference. The guidelines contain invaluable guidance and tips on how to write rules, including: +The CRS project's advice on rule writing is contained within the [contribution guidelines]({{% ref "6-1-contribution-guidelines.md" %}}), a document which can also be found in plain text form in CRS releases for offline reference. The guidelines contain invaluable guidance and tips on how to write rules, including: - effective regular expression writing - consistent formatting and indentation diff --git a/content/3-about-rules/rules.md b/content/3-about-rules/rules.md index 5693d2e4..4ccaffea 100644 --- a/content/3-about-rules/rules.md +++ b/content/3-about-rules/rules.md @@ -1,5 +1,5 @@ --- -title: What's In The Rules +title: "What's In The Rules" weight: 20 disableToc: false chapter: false diff --git a/content/4-about-plugins/4-1-plugins.md b/content/4-about-plugins/4-1-plugins.md index 04adda99..73198f95 100644 --- a/content/4-about-plugins/4-1-plugins.md +++ b/content/4-about-plugins/4-1-plugins.md @@ -162,7 +162,7 @@ Available plugins include: ## How to Write a Plugin -For information on writing a new plugin, refer to the development documentation on [writing plugins]({{< ref "4-2-writing-plugins.md" >}}). +For information on writing a new plugin, refer to the development documentation on [writing plugins]({{% ref "4-2-writing-plugins.md" %}}). ## Collection Timeout diff --git a/content/6-development/6-1-contribution-guidelines.md b/content/6-development/6-1-contribution-guidelines.md index c9c18067..787c3245 100644 --- a/content/6-development/6-1-contribution-guidelines.md +++ b/content/6-development/6-1-contribution-guidelines.md @@ -138,12 +138,12 @@ SecRule ARGS "foo" "id:1,phase:1,pass,t:none" CRS uses `\x5c` to represent the backslash `\` character in regular expressions. Some of the reasons for this are: * It's portable across web servers and WAF engines: it works with Apache, Nginx, and Coraza. -* It works with the [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}) for building optimized regular expressions. +* It works with the [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}}) for building optimized regular expressions. The older style of representing a backslash using the character class `[\\\\]` must _not_ be used. This was previously used in CRS to get consistent results between Apache and Nginx, owing to a quirk with how Apache would "double un-escape" character escapes. For future reference, the decision was made to stop using this older method because: * It can be confusing and difficult to understand how it works. -* It doesn't work with [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}). +* It doesn't work with [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}}). * It doesn't work with Coraza. * It isn't obvious how to use it in a character class, e.g., `[a-zA-Z]`. @@ -300,7 +300,7 @@ Optimizing regular expressions is hard. Often, a change intended to improve the mailto|mms|mumble|maven ``` -An optimized version (produced by the [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}})) could look like this: +An optimized version (produced by the [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}})) could look like this: ```python m(?:a(?:ilto|ven)|umble|ms) @@ -308,13 +308,13 @@ m(?:a(?:ilto|ven)|umble|ms) The above expression is an optimization because it reduces the number of backtracking steps when a branch fails. The regular expressions in the CRS are often comprised of lists of tens or even hundreds of words. Reading such an expression in an optimized form is difficult: even the _simple_ optimized example above is difficult to read. -In general, contributors should not try to optimize contributed regular expressions and should instead strive for clarity. New regular expressions will usually be required to be submitted as a `.ra` file for the [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}) to process. In such a file, the regular expression is decomposed into individual parts, making manual optimizations much harder or even impossible (and unnecessary with the `crs-toolchain`). The `crs-toolchain` performs some common optimizations automatically, such as the one shown above. +In general, contributors should not try to optimize contributed regular expressions and should instead strive for clarity. New regular expressions will usually be required to be submitted as a `.ra` file for the [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}}) to process. In such a file, the regular expression is decomposed into individual parts, making manual optimizations much harder or even impossible (and unnecessary with the `crs-toolchain`). The `crs-toolchain` performs some common optimizations automatically, such as the one shown above. Whether optimizations make sense in a contribution is assessed for each case individually. ## Rules Compliance with Paranoia Levels -The rules in CRS are organized into **paranoia levels** (PLs) which makes it possible to define how aggressive CRS is. See the documentation on [paranoia levels]({{< ref "2-2-paranoia_levels" >}}) for an introduction and more detailed explanation. +The rules in CRS are organized into **paranoia levels** (PLs) which makes it possible to define how aggressive CRS is. See the documentation on [paranoia levels]({{% ref "2-2-paranoia_levels" %}}) for an introduction and more detailed explanation. Each rule that is placed into a paranoia level must contain the tag `paranoia-level/N`, where *N* is the PL value, however this tag can only be added if the rule does **not** use the nolog action. diff --git a/content/6-development/6-2-crs-toolchain.md b/content/6-development/6-2-crs-toolchain.md index 14f6a376..28bd6844 100644 --- a/content/6-development/6-2-crs-toolchain.md +++ b/content/6-development/6-2-crs-toolchain.md @@ -68,7 +68,7 @@ crs-toolchain --help ## The `regex` Command -The `regex` command provides sub-commands for everything surrounding regular expressions, especially the "assembly" of regular expressions from a specification of its components (see [Assembling Regular Expressions]({{< ref "6-3-assembling-regular-expressions.md" >}}) for more details). +The `regex` command provides sub-commands for everything surrounding regular expressions, especially the "assembly" of regular expressions from a specification of its components (see [Assembling Regular Expressions]({{% ref "6-3-assembling-regular-expressions.md" %}}) for more details). ### Example Use diff --git a/content/6-development/6-3-assembling-regular-expressions.md b/content/6-development/6-3-assembling-regular-expressions.md index e0746813..37e946b2 100644 --- a/content/6-development/6-3-assembling-regular-expressions.md +++ b/content/6-development/6-3-assembling-regular-expressions.md @@ -10,7 +10,7 @@ aliases: ["../development/regex_assembly"] ## Specification Format -The files containing regular expression specifications (`.ra` suffix, under `regex-assembly`) contain one regular expression per line. These files are meant to be processed by the [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}). +The files containing regular expression specifications (`.ra` suffix, under `regex-assembly`) contain one regular expression per line. These files are meant to be processed by the [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}}). ### Example @@ -110,7 +110,7 @@ The following example is intentionanlly simple (and meaningless) to illustrates ##!< ``` -Processors are defined in the [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}). +Processors are defined in the [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}}). ### Nesting @@ -322,7 +322,7 @@ The exact contents of the included file, including processor directives, with su ### Description -The include processor reduces repetition across assembly files. Repeated blocks can be put into a file in the `include` directory and then be included with the `include` processor comment. Include files are normal assembly files, hence include files can also contain further include directives. The only restriction is that included files must not contain the prefix or suffix markers. This is a technical limitation in the [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}). +The include processor reduces repetition across assembly files. Repeated blocks can be put into a file in the `include` directory and then be included with the `include` processor comment. Include files are normal assembly files, hence include files can also contain further include directives. The only restriction is that included files must not contain the prefix or suffix markers. This is a technical limitation in the [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}}). The contents of an include file could, for example, be the alternation of accepted HTTP methods: @@ -358,7 +358,7 @@ it{{quotes}}s{{opt-lazy-wspace}}possible Note that the include processor does not have a body, thus the end marker is optional. -Please see [Include-Except processor]({{< ref "6-3-assembling-regular-expressions.md#include-except-processor" >}}) for how suffix replacements work. +Please see [Include-Except processor]({{% ref "6-3-assembling-regular-expressions.md#include-except-processor" %}}) for how suffix replacements work. ## Include-Except processor diff --git a/content/6-development/6-5-testing-the-rule-set.md b/content/6-development/6-5-testing-the-rule-set.md index c6b0cfcf..fd81145f 100644 --- a/content/6-development/6-5-testing-the-rule-set.md +++ b/content/6-development/6-5-testing-the-rule-set.md @@ -49,7 +49,7 @@ Excellent, our containers are running, now we can start our tests. ### Using your own environment for testing {#use-own-env} -If you have your own environment set up, you can configure that for testing. Please [follow these instructions]({{< ref "1-1-crs-installation.md#installing-a-compatible-waf-engine" >}}) to install the WAF server locally. +If you have your own environment set up, you can configure that for testing. Please [follow these instructions]({{% ref "1-1-crs-installation.md#installing-a-compatible-waf-engine" %}}) to install the WAF server locally. > [!NOTE] > Remember: The supported platform is ModSecurity 2 with Apache httpd. If you want to run the tests against nginx, you can do that too, but nginx uses libmodsecurity3, which is not fully compatible with Apache httpd + ModSecurity 2. diff --git a/content/6-development/6-6-useful_tools.md b/content/6-development/6-6-useful_tools.md index b03b3301..e934b945 100644 --- a/content/6-development/6-6-useful_tools.md +++ b/content/6-development/6-6-useful_tools.md @@ -31,7 +31,7 @@ Include ../coreruleset/rules/*.conf https://github.com/coreruleset/crs-toolchain -The CRS developer's toolbelt. Documentation lives at [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}). +The CRS developer's toolbelt. Documentation lives at [crs-toolchain]({{% ref "6-2-crs-toolchain.md" %}}). ## Go-FTW @@ -82,4 +82,4 @@ We have a syntax highlighting extension for Visual Studio Code that helps with w ### ModSecurity SecLang -A community member has created an experimental syntax highlighter extension for the ModSecurity SecLang for Visual Studio Code. It has a nice documentation feature for syntax elements and variables. Both highlighting and documentation have been generated using GPT-5, so expect some issues and inaccuracies. https://github.com/louis-lau/vscode-secrule-language-plugin. \ No newline at end of file +A community member has created an experimental syntax highlighter extension for the ModSecurity SecLang for Visual Studio Code. It has a nice documentation feature for syntax elements and variables. Both highlighting and documentation have been generated using GPT-5, so expect some issues and inaccuracies. https://github.com/louis-lau/vscode-secrule-language-plugin. diff --git a/content/_index.md b/content/_index.md index 68dd468d..d46351a7 100644 --- a/content/_index.md +++ b/content/_index.md @@ -15,7 +15,7 @@ OWASP® (Open Worldwide Application Security Project) CRS (previously Core Rule ## How to Get Involved -For information on how to join the vibrant community of CRS developers, start by checking out the project's [GitHub repository](https://github.com/coreruleset/coreruleset). When ready to make a contribution, have a read of the project's [contribution guidelines]({{< ref "6-1-contribution-guidelines/" >}}) which are used to keep the project consistent, well managed, and of a high quality. +For information on how to join the vibrant community of CRS developers, start by checking out the project's [GitHub repository](https://github.com/coreruleset/coreruleset). When ready to make a contribution, have a read of the project's [contribution guidelines]({{% ref "6-1-contribution-guidelines/" %}}) which are used to keep the project consistent, well managed, and of a high quality. ## CRS Change Policy diff --git a/data/filesdescription.yaml b/data/filesdescription.yaml index 28d734f0..a20215f4 100644 --- a/data/filesdescription.yaml +++ b/data/filesdescription.yaml @@ -4,7 +4,7 @@ common: This file is used to add LOCAL exceptions for your site. Often in this file we would see rules that short-circuit inspection and allow certain transactions to skip through inspection. - + `Example: SecRule REMOTE_ADDR "@ipMatch 192.168.1.100" "phase:1,id:'981033',t:none,nolog,pass,ctl:ruleEngine=Off"` REQUEST-901-INITIALIZATION.conf: TODO REQUEST-913-SCANNER-DETECTION.conf: > @@ -71,7 +71,6 @@ common: This file is used to add LOCAL exceptions for your site. Often in this file we would see rules that short-circuit inspection and allow certain transactions to skip through inspection. - RESPONSE-980-CORRELATION.conf: TODO versioned: "3":