From 1a5ec832bd0f5dbb13d5253cbcf85e4dbf6edae6 Mon Sep 17 00:00:00 2001 From: dextermallo Date: Mon, 5 Aug 2024 17:01:45 +0800 Subject: [PATCH 01/11] feat: restructure; update naming pattern and weight; fix inner-link --- .../1-1-crs-installation.md} | 16 +++---- .../1-2-extended_install.md} | 10 ++--- .../1-3-using-containers.md} | 2 +- .../1-4-engine_integration_options.md} | 2 +- .../_index.md | 4 +- .../2-2-paranoia_levels.md} | 2 +- .../2-3-false-positives-and-tuning.md} | 45 ++++++++++--------- .../2-4-sampling_mode.md} | 2 +- .../{concepts => 2-how-crs-works}/_index.md | 2 +- .../anomaly_scoring/as_inbound.svg | 0 .../anomaly_scoring/as_inbound_no_fonts.svg | 0 .../anomaly_scoring/index.md | 6 +-- .../{operation => 3-about-rules}/_index.md | 6 ++- content/{rules => 3-about-rules}/creating.md | 4 +- content/{rules => 3-about-rules}/metadata.md | 0 .../rule_writing.md | 2 +- content/{rules => 3-about-rules}/ruleid.md | 0 content/{rules => 3-about-rules}/rules.md | 0 .../4-1-what-is-plugin.md} | 6 +-- .../4-2-writing-plugins.md} | 2 +- content/4-about-plugins/_index.md | 8 ++++ .../5-1-self-contained-mode.md} | 2 +- .../5-2-log-handling.md} | 2 +- .../5-3-kubernetes-ingress-controller.md} | 2 +- .../_index.md | 6 +-- .../6-1-contribution-guidelines.md} | 10 ++--- .../6-2-crs-toolchain.md} | 4 +- .../6-3-assembling-regular-expressions.md} | 10 ++--- .../6-4-using-the-crs-sandbox.md} | 2 +- .../6-5-testing-the-rule-set.md} | 4 +- .../6-6-useful_tools.md} | 4 +- .../{development => 6-development}/_index.md | 6 ++- .../_index.md} | 6 +-- .../_index.md | 4 +- content/_index.md | 2 +- content/rules/_index.md | 6 --- 36 files changed, 98 insertions(+), 91 deletions(-) rename content/{deployment/install.md => 1-getting-started/1-1-crs-installation.md} (92%) rename content/{deployment/extended_install.md => 1-getting-started/1-2-extended_install.md} (95%) rename content/{operation/containers.md => 1-getting-started/1-3-using-containers.md} (98%) rename content/{deployment/engine_integration_options.md => 1-getting-started/1-4-engine_integration_options.md} (99%) rename content/{deployment => 1-getting-started}/_index.md (54%) rename content/{concepts/paranoia_levels.md => 2-how-crs-works/2-2-paranoia_levels.md} (99%) rename content/{concepts/false_positives_tuning.md => 2-how-crs-works/2-3-false-positives-and-tuning.md} (90%) rename content/{concepts/sampling_mode.md => 2-how-crs-works/2-4-sampling_mode.md} (99%) rename content/{concepts => 2-how-crs-works}/_index.md (90%) rename content/{concepts => 2-how-crs-works}/anomaly_scoring/as_inbound.svg (100%) rename content/{concepts => 2-how-crs-works}/anomaly_scoring/as_inbound_no_fonts.svg (100%) rename content/{concepts => 2-how-crs-works}/anomaly_scoring/index.md (97%) rename content/{operation => 3-about-rules}/_index.md (51%) rename content/{rules => 3-about-rules}/creating.md (99%) rename content/{rules => 3-about-rules}/metadata.md (100%) rename content/{development => 3-about-rules}/rule_writing.md (72%) rename content/{rules => 3-about-rules}/ruleid.md (100%) rename content/{rules => 3-about-rules}/rules.md (100%) rename content/{concepts/plugins.md => 4-about-plugins/4-1-what-is-plugin.md} (98%) rename content/{development/plugin_writing.md => 4-about-plugins/4-2-writing-plugins.md} (99%) create mode 100644 content/4-about-plugins/_index.md rename content/{miscellaneous/self_contained_mode.md => 5-advanced-usages/5-1-self-contained-mode.md} (99%) rename content/{operation/log_handling.md => 5-advanced-usages/5-2-log-handling.md} (94%) rename content/{operation/kubernetes_ingress.md => 5-advanced-usages/5-3-kubernetes-ingress-controller.md} (99%) rename content/{miscellaneous => 5-advanced-usages}/_index.md (73%) rename content/{development/contribution_guidelines.md => 6-development/6-1-contribution-guidelines.md} (97%) rename content/{development/crs_toolchain.md => 6-development/6-2-crs-toolchain.md} (97%) rename content/{development/regex_assembly.md => 6-development/6-3-assembling-regular-expressions.md} (97%) rename content/{development/sandbox.md => 6-development/6-4-using-the-crs-sandbox.md} (99%) rename content/{development/testing.md => 6-development/6-5-testing-the-rule-set.md} (98%) rename content/{development/useful_tools.md => 6-development/6-6-useful_tools.md} (96%) rename content/{development => 6-development}/_index.md (50%) rename content/{operation/known_issues.md => 7-known-issues/_index.md} (98%) rename content/{resources => 8-additional-resources}/_index.md (99%) delete mode 100644 content/rules/_index.md diff --git a/content/deployment/install.md b/content/1-getting-started/1-1-crs-installation.md similarity index 92% rename from content/deployment/install.md rename to content/1-getting-started/1-1-crs-installation.md index b8467d03..b9397da4 100644 --- a/content/deployment/install.md +++ b/content/1-getting-started/1-1-crs-installation.md @@ -1,11 +1,11 @@ --- -title: Installing CRS -weight: 20 +title: CRS Installation +weight: 11 disableToc: false chapter: false --- -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 "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 @@ -73,7 +73,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 "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. @@ -113,7 +113,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 "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 @@ -123,7 +123,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 "false_positives_tuning.md" %}}). +Now that everything has been configured, it should be possible to restart and being 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-how-crs-works/2-3-false-positives-and-tuning.md" >}}). ```bash systemctl restart httpd.service @@ -131,7 +131,7 @@ systemctl restart httpd.service ## Alternative: Using Containers -Another quick option is to use the official CRS [pre-packaged containers]({{% ref "../development/useful_tools/#official-crs-maintained-docker-images" %}}). Docker, Podman, or any compatible container engine can be used. The official CRS images are published on [Docker Hub](https://hub.docker.com/r/owasp/modsecurity-crs/) and [GitHub Container Repository](https://github.com/coreruleset/modsecurity-crs-docker/pkgs/container/modsecurity-crs). The image most often deployed is `modsecurity-crs` (`owasp/modsecurity-crs` from Docker Hub or `ghcr.io/coreruleset/modsecurity-crs` from GHCR): it already has everything needed to get up and running quickly. +Another quick option is to use the official CRS [pre-packaged containers]({{% ref "6-development/6-6-useful_tools/#official-crs-maintained-docker-images" %}}). Docker, Podman, or any compatible container engine can be used. The official CRS images are published on [Docker Hub](https://hub.docker.com/r/owasp/modsecurity-crs/) and [GitHub Container Repository](https://github.com/coreruleset/modsecurity-crs-docker/pkgs/container/modsecurity-crs). The image most often deployed is `modsecurity-crs` (`owasp/modsecurity-crs` from Docker Hub or `ghcr.io/coreruleset/modsecurity-crs` from GHCR): it already has everything needed to get up and running quickly. The CRS project pre-packages both Apache and Nginx web servers along with the appropriate corresponding ModSecurity engine. More engines, like [Coraza](https://coraza.io/), will be added at a later date. @@ -183,7 +183,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 "plugins.md" %}}). +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/deployment/extended_install.md b/content/1-getting-started/1-2-extended_install.md similarity index 95% rename from content/deployment/extended_install.md rename to content/1-getting-started/1-2-extended_install.md index a214a20b..33a577b5 100644 --- a/content/deployment/extended_install.md +++ b/content/1-getting-started/1-2-extended_install.md @@ -1,11 +1,11 @@ --- title: Extended Install -weight: 30 +weight: 12 disableToc: false chapter: false --- -> 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 "install.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 @@ -176,7 +176,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 "anomaly_scoring.md" %}} "Anomaly"). +- Make sure to configure the anomaly scoring thresholds. For more information see [Anomaly]({{< ref "2-how-crs-works/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. @@ -191,7 +191,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 "#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-how-crs-works/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 @@ -202,7 +202,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 "rules" %}}) 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/operation/containers.md b/content/1-getting-started/1-3-using-containers.md similarity index 98% rename from content/operation/containers.md rename to content/1-getting-started/1-3-using-containers.md index bb3750bb..79723806 100644 --- a/content/operation/containers.md +++ b/content/1-getting-started/1-3-using-containers.md @@ -1,6 +1,6 @@ --- title: Using Containers -weight: 20 +weight: 13 disableToc: false chapter: false --- diff --git a/content/deployment/engine_integration_options.md b/content/1-getting-started/1-4-engine_integration_options.md similarity index 99% rename from content/deployment/engine_integration_options.md rename to content/1-getting-started/1-4-engine_integration_options.md index 87e1d859..499c808a 100644 --- a/content/deployment/engine_integration_options.md +++ b/content/1-getting-started/1-4-engine_integration_options.md @@ -1,6 +1,6 @@ --- title: Engine and Integration Options -weight: 10 +weight: 14 disableToc: false chapter: false --- diff --git a/content/deployment/_index.md b/content/1-getting-started/_index.md similarity index 54% rename from content/deployment/_index.md rename to content/1-getting-started/_index.md index 209a5be0..0c82fb16 100644 --- a/content/deployment/_index.md +++ b/content/1-getting-started/_index.md @@ -1,6 +1,6 @@ --- -title: Getting CRS -weight: 10 +title: Getting Started +weight: 1 pre: "1. " chapter: true --- diff --git a/content/concepts/paranoia_levels.md b/content/2-how-crs-works/2-2-paranoia_levels.md similarity index 99% rename from content/concepts/paranoia_levels.md rename to content/2-how-crs-works/2-2-paranoia_levels.md index 2c85cd93..43081aa4 100644 --- a/content/concepts/paranoia_levels.md +++ b/content/2-how-crs-works/2-2-paranoia_levels.md @@ -1,6 +1,6 @@ --- title: Paranoia Levels -weight: 20 +weight: 22 disableToc: false chapter: false --- diff --git a/content/concepts/false_positives_tuning.md b/content/2-how-crs-works/2-3-false-positives-and-tuning.md similarity index 90% rename from content/concepts/false_positives_tuning.md rename to content/2-how-crs-works/2-3-false-positives-and-tuning.md index b235dec0..e2ed52c1 100644 --- a/content/concepts/false_positives_tuning.md +++ b/content/2-how-crs-works/2-3-false-positives-and-tuning.md @@ -1,6 +1,6 @@ --- title: False Positives and Tuning -weight: 30 +weight: 23 disableToc: false chapter: false --- @@ -9,25 +9,9 @@ chapter: false ## What are False Positives? -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. The following image describes the possible scenarios for an individual request: - -```mermaid -%%{init: {"themeVariables": {"quadrant1Fill": "#00ff00", "quadrant2Fill": "#ff0000", "quadrant4Fill": "#ffff00"} }}%% -quadrantChart - title WAF detection quadrant - x-axis Allowed --> Blocked - y-axis Normal Traffic --> Real attack - quadrant-1 True Positive - quadrant-2 False Negative - quadrant-3 Business as usual - quadrant-4 False Positive -``` - -In an ideal setting, CRS would _allow all valid requests_ and _block all real attacks_. These two scenarios are depicted in the image as `Business as usual` and `True positive`. - -In reality, no system is ideal and CRS will sometimes _block a valid request_ (`False Positive`) or _allow a real attack_ (`False Negative`). Obviously, false negatives are the worse of the two because of the potential repercussions of a successful intrusion. +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 "paranoia_levels" %}} "Page describing paranoia levels."). While paranoia level 1 is designed to cause few 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, and the more time must be invested to tune CRS to reduce false positives. There is no value to a system with a high paranoia level that produces many false positives, as it will likely be unusable by benign clients. +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 @@ -97,7 +81,7 @@ There are alternative ways to deal with false positives, as described below. The #### Overview -The WAF engine has flexible ways to tune away false positives. It provides several *rule exclusion* (RE) mechanisms which allow rules to be modified *without* directly changing the rules themselves. This makes it possible to work with third-party rule sets, like CRS, by adapting rules as needed while leaving the rule set files intact and unmodified. This allows for easy rule set updates. +The ModSecurity WAF engine has flexible ways to tune away false positives. It provides several *rule exclusion* (RE) mechanisms which allow rules to be modified *without* directly changing the rules themselves. This makes it possible to work with third-party rule sets, like CRS, by adapting rules as needed while leaving the rule set files intact and unmodified. This allows for easy rule set updates. Two fundamentally different types of rule exclusions are supported: @@ -353,11 +337,28 @@ CRS ships with prebuilt *rule exclusion packages* for a selection of popular web The packages should be viewed as a good *starting point* from which to build upon. Some false positives may still occur, for example if working at a high paranoia level, if using a very new or old version of the application, if using plug-ins, add-ons, or user customizations. -If using a native CRS installation, rule exclusion packages can be downloaded as [plugins]({{% ref "plugins.md" %}}). +If using a native CRS installation, rule exclusion packages can be enabled in the file `crs-setup.conf`. Modify rule 900130 to select the web applications in question, e.g. to enable the DokuWiki rule exclusion package use `setvar:tx.crs_exclusions_dokuwiki=1`, and then uncomment the rule to enable it. If running CRS where it has been integrated into a commercial product or CDN then support varies. Some vendors expose rule exclusion packages in the GUI while other vendors require custom rules to be written which set the necessary variables. Unfortunately, there are also vendors that don't allow rule exclusion packages to be used at all. -The list of plugins supporting rule exclusions can be found [here](https://github.com/coreruleset/plugin-registry). The names of rule exclusion plugins end with `rule-exclusions`. +{{% notice tip %}} +If running multiple web applications, it is highly recommended to enable a rule exclusion package only for the location where the corresponding web application resides. For example, to enable the WordPress rule exclusion package only for locations under '/wordpress', a rule like the following could be used: + +```apache +SecRule REQUEST_URI "@beginsWith /wordpress/" setvar:tx.crs_exclusions_wordpress=1... +``` +{{% /notice %}} + +Rule exclusion packages are currently available for the following web applications: + +- [cPanel](https://cpanel.net) +- [DokuWiki](https://www.dokuwiki.org) +- [Drupal](https://www.drupal.org) +- [Nextcloud](https://nextcloud.com) +- [phpBB](https://www.phpbb.com) +- [phpMyAdmin](https://www.phpmyadmin.net) +- [WordPress](https://wordpress.org) +- [XenForo](https://xenforo.com) The CRS project is always looking to work with other communities and individuals to add support for additional web applications. Please get in touch via [GitHub](https://github.com/coreruleset/coreruleset) to discuss writing a rule exclusion package for a specific web application. diff --git a/content/concepts/sampling_mode.md b/content/2-how-crs-works/2-4-sampling_mode.md similarity index 99% rename from content/concepts/sampling_mode.md rename to content/2-how-crs-works/2-4-sampling_mode.md index 9ce05357..d411000f 100644 --- a/content/concepts/sampling_mode.md +++ b/content/2-how-crs-works/2-4-sampling_mode.md @@ -1,6 +1,6 @@ --- title: Sampling Mode -weight: 50 +weight: 24 disableToc: false chapter: false --- diff --git a/content/concepts/_index.md b/content/2-how-crs-works/_index.md similarity index 90% rename from content/concepts/_index.md rename to content/2-how-crs-works/_index.md index a74f077a..d0d6b8d0 100644 --- a/content/concepts/_index.md +++ b/content/2-how-crs-works/_index.md @@ -1,6 +1,6 @@ --- title: How CRS Works -weight: 20 +weight: 2 pre: "2. " chapter: true --- diff --git a/content/concepts/anomaly_scoring/as_inbound.svg b/content/2-how-crs-works/anomaly_scoring/as_inbound.svg similarity index 100% rename from content/concepts/anomaly_scoring/as_inbound.svg rename to content/2-how-crs-works/anomaly_scoring/as_inbound.svg diff --git a/content/concepts/anomaly_scoring/as_inbound_no_fonts.svg b/content/2-how-crs-works/anomaly_scoring/as_inbound_no_fonts.svg similarity index 100% rename from content/concepts/anomaly_scoring/as_inbound_no_fonts.svg rename to content/2-how-crs-works/anomaly_scoring/as_inbound_no_fonts.svg diff --git a/content/concepts/anomaly_scoring/index.md b/content/2-how-crs-works/anomaly_scoring/index.md similarity index 97% rename from content/concepts/anomaly_scoring/index.md rename to content/2-how-crs-works/anomaly_scoring/index.md index 0305aba8..c06789d9 100644 --- a/content/concepts/anomaly_scoring/index.md +++ b/content/2-how-crs-works/anomaly_scoring/index.md @@ -1,6 +1,6 @@ --- title: Anomaly Scoring -weight: 10 +weight: 21 disableToc: false chapter: false --- @@ -63,9 +63,9 @@ SecRule REQUEST_HEADERS:Content-Length "!@rx ^\d+$" \ ``` {{% notice info %}} -Notice that the anomaly score variable name has the suffix `pl1`. Internally, CRS keeps track of anomaly scores on a *per* [*paranoia level*]({{< ref "paranoia_levels" >}} "Page describing paranoia levels.") basis. The individual paranoia level anomaly scores are added together before each round of blocking evaluation takes place, allowing the total combined inbound or outbound score to be compared to the relevant anomaly score threshold. +Notice that the anomaly score variable name has the suffix `pl1`. Internally, CRS keeps track of anomaly scores on a *per* [*paranoia level*]({{< ref "2-2-paranoia_levels" >}} "Page describing paranoia levels.") basis. The individual paranoia level anomaly scores are added together before each round of blocking evaluation takes place, allowing the total combined inbound or outbound score to be compared to the relevant anomaly score threshold. -Tracking the anomaly score per paranoia level allows for clever scoring mechanisms to be employed, such as the [executing paranoia level]({{< ref "paranoia_levels#moving-to-a-higher-paranoia-level" >}} "Section describing the executing paranoia level feature.") feature. +Tracking the anomaly score per paranoia level allows for clever scoring mechanisms to be employed, such as the [executing paranoia level]({{< ref "2-2-paranoia_levels#moving-to-a-higher-paranoia-level" >}} "Section describing the executing paranoia level feature.") feature. {{% /notice %}} The rules files `REQUEST-949-BLOCKING-EVALUATION.conf` and `RESPONSE-959-BLOCKING-EVALUATION.conf` are responsible for executing the inbound (request) and outbound (response) rounds of blocking evaluation, respectively. The rules in these files calculate the total inbound or outbound transactional anomaly score and then make a blocking decision, by comparing the result to the defined threshold and taking blocking action if required. diff --git a/content/operation/_index.md b/content/3-about-rules/_index.md similarity index 51% rename from content/operation/_index.md rename to content/3-about-rules/_index.md index 16048db4..85fa7ad3 100644 --- a/content/operation/_index.md +++ b/content/3-about-rules/_index.md @@ -1,6 +1,8 @@ --- -title: Operation -weight: 30 +title: About Rules +weight: 3 pre: "3. " chapter: true --- + +# Rules diff --git a/content/rules/creating.md b/content/3-about-rules/creating.md similarity index 99% rename from content/rules/creating.md rename to content/3-about-rules/creating.md index 3f510718..020e3526 100644 --- a/content/rules/creating.md +++ b/content/3-about-rules/creating.md @@ -1,6 +1,6 @@ --- -title: Making -weight: 30 +title: Making Rules +weight: 31 disableToc: false chapter: false --- diff --git a/content/rules/metadata.md b/content/3-about-rules/metadata.md similarity index 100% rename from content/rules/metadata.md rename to content/3-about-rules/metadata.md diff --git a/content/development/rule_writing.md b/content/3-about-rules/rule_writing.md similarity index 72% rename from content/development/rule_writing.md rename to content/3-about-rules/rule_writing.md index 7b992cf6..fe7e4faf 100644 --- a/content/development/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 "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-development/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/rules/ruleid.md b/content/3-about-rules/ruleid.md similarity index 100% rename from content/rules/ruleid.md rename to content/3-about-rules/ruleid.md diff --git a/content/rules/rules.md b/content/3-about-rules/rules.md similarity index 100% rename from content/rules/rules.md rename to content/3-about-rules/rules.md diff --git a/content/concepts/plugins.md b/content/4-about-plugins/4-1-what-is-plugin.md similarity index 98% rename from content/concepts/plugins.md rename to content/4-about-plugins/4-1-what-is-plugin.md index 350a65f4..db536740 100644 --- a/content/concepts/plugins.md +++ b/content/4-about-plugins/4-1-what-is-plugin.md @@ -1,6 +1,6 @@ --- -title: Plugin Mechanism -weight: 40 +title: What is Plugin +weight: 41 disableToc: false chapter: false --- @@ -161,7 +161,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 "plugin_writing.md" %}}). +For information on writing a new plugin, refer to the development documentation on [writing plugins]({{< ref "4-about-plugins/4-2-writing-plugins.md" >}}). ## Collection Timeout diff --git a/content/development/plugin_writing.md b/content/4-about-plugins/4-2-writing-plugins.md similarity index 99% rename from content/development/plugin_writing.md rename to content/4-about-plugins/4-2-writing-plugins.md index 017ac01d..7f820486 100644 --- a/content/development/plugin_writing.md +++ b/content/4-about-plugins/4-2-writing-plugins.md @@ -1,6 +1,6 @@ --- title: Writing Plugins -weight: 50 +weight: 42 disableToc: false chapter: false --- diff --git a/content/4-about-plugins/_index.md b/content/4-about-plugins/_index.md new file mode 100644 index 00000000..ab015710 --- /dev/null +++ b/content/4-about-plugins/_index.md @@ -0,0 +1,8 @@ +--- +title: About Plugins +weight: 4 +pre: "4. " +chapter: true +--- + +# Development diff --git a/content/miscellaneous/self_contained_mode.md b/content/5-advanced-usages/5-1-self-contained-mode.md similarity index 99% rename from content/miscellaneous/self_contained_mode.md rename to content/5-advanced-usages/5-1-self-contained-mode.md index a82e74c7..3bee735a 100644 --- a/content/miscellaneous/self_contained_mode.md +++ b/content/5-advanced-usages/5-1-self-contained-mode.md @@ -1,6 +1,6 @@ --- title: Self-Contained Mode -weight: 10 +weight: 51 disableToc: false chapter: false --- diff --git a/content/operation/log_handling.md b/content/5-advanced-usages/5-2-log-handling.md similarity index 94% rename from content/operation/log_handling.md rename to content/5-advanced-usages/5-2-log-handling.md index 282c6eff..aed77821 100644 --- a/content/operation/log_handling.md +++ b/content/5-advanced-usages/5-2-log-handling.md @@ -1,6 +1,6 @@ --- title: Log Handling -weight: 40 +weight: 52 disableToc: false chapter: false --- diff --git a/content/operation/kubernetes_ingress.md b/content/5-advanced-usages/5-3-kubernetes-ingress-controller.md similarity index 99% rename from content/operation/kubernetes_ingress.md rename to content/5-advanced-usages/5-3-kubernetes-ingress-controller.md index 7b387f46..e384f03b 100644 --- a/content/operation/kubernetes_ingress.md +++ b/content/5-advanced-usages/5-3-kubernetes-ingress-controller.md @@ -1,6 +1,6 @@ --- title: Kubernetes Ingress Controllers -weight: 30 +weight: 53 disableToc: false chapter: false --- diff --git a/content/miscellaneous/_index.md b/content/5-advanced-usages/_index.md similarity index 73% rename from content/miscellaneous/_index.md rename to content/5-advanced-usages/_index.md index 7222e206..0cabcd77 100644 --- a/content/miscellaneous/_index.md +++ b/content/5-advanced-usages/_index.md @@ -1,7 +1,7 @@ --- -title: Miscellaneous -weight: 70 -pre: "7. " +title: Advanced Usages +weight: 5 +pre: "5. " chapter: true --- diff --git a/content/development/contribution_guidelines.md b/content/6-development/6-1-contribution-guidelines.md similarity index 97% rename from content/development/contribution_guidelines.md rename to content/6-development/6-1-contribution-guidelines.md index 557626cf..b11ae22d 100644 --- a/content/development/contribution_guidelines.md +++ b/content/6-development/6-1-contribution-guidelines.md @@ -1,6 +1,6 @@ --- title: Contribution Guidelines -weight: 10 +weight: 61 disableToc: false chapter: false --- @@ -112,12 +112,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 "crs_toolchain" %}}) for building optimized regular expressions. +* It works with the [crs-toolchain]({{< ref "6-development/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 "crs_toolchain" %}}). +* It doesn't work with [crs-toolchain]({{< ref "6-development/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]`. @@ -274,7 +274,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 "crs_toolchain" %}})) could look like this: +An optimized version (produced by the [crs-toolchain]({{< ref "6-development/6-2-crs-toolchain.md" >}})) could look like this: ```python m(?:a(?:ilto|ven)|umble|ms) @@ -282,7 +282,7 @@ 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 "crs_toolchain" %}}) 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-development/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. diff --git a/content/development/crs_toolchain.md b/content/6-development/6-2-crs-toolchain.md similarity index 97% rename from content/development/crs_toolchain.md rename to content/6-development/6-2-crs-toolchain.md index 92e30908..c6753ed5 100644 --- a/content/development/crs_toolchain.md +++ b/content/6-development/6-2-crs-toolchain.md @@ -1,6 +1,6 @@ --- title: crs-toolchain -weight: 12 +weight: 62 disableToc: false chapter: false --- @@ -67,7 +67,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 "regex_assembly" %}}) 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-development/6-3-assembling-regular-expressions.md" >}}) for more details). ### Example Use diff --git a/content/development/regex_assembly.md b/content/6-development/6-3-assembling-regular-expressions.md similarity index 97% rename from content/development/regex_assembly.md rename to content/6-development/6-3-assembling-regular-expressions.md index ea39e14f..86dbd9a1 100644 --- a/content/development/regex_assembly.md +++ b/content/6-development/6-3-assembling-regular-expressions.md @@ -1,6 +1,6 @@ --- title: Assembling Regular Expressions -weight: 15 +weight: 63 disableToc: false chapter: false --- @@ -9,7 +9,7 @@ chapter: false ## 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 "crs_toolchain" %}}). +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-development/6-2-crs-toolchain.md" >}}). ### Example @@ -109,7 +109,7 @@ The following example is intentionanlly simple (and meaningless) to illustrates ##!< ``` -Processors are defined in the [crs-toolchain]({{% ref "crs_toolchain" %}}). +Processors are defined in the [crs-toolchain]({{< ref "6-development/6-2-crs-toolchain.md" >}}). ### Nesting @@ -321,7 +321,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 "crs_toolchain" %}}). +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-development/6-2-crs-toolchain.md" >}}). The contents of an include file could, for example, be the alternation of accepted HTTP methods: @@ -357,7 +357,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 "regex_assembly#include-except-processor" %}}) for how suffix replacements work. +Please see [Include-Except processor]({{< ref "6-development/6-3-assembling-regular-expressions.md#include-except-processor" >}}) for how suffix replacements work. ## Include-Except processor diff --git a/content/development/sandbox.md b/content/6-development/6-4-using-the-crs-sandbox.md similarity index 99% rename from content/development/sandbox.md rename to content/6-development/6-4-using-the-crs-sandbox.md index e9389298..f9dc99a7 100644 --- a/content/development/sandbox.md +++ b/content/6-development/6-4-using-the-crs-sandbox.md @@ -1,6 +1,6 @@ --- title: Using the CRS Sandbox -weight: 60 +weight: 64 disableToc: false chapter: false --- diff --git a/content/development/testing.md b/content/6-development/6-5-testing-the-rule-set.md similarity index 98% rename from content/development/testing.md rename to content/6-development/6-5-testing-the-rule-set.md index c76809f5..27dbc23d 100644 --- a/content/development/testing.md +++ b/content/6-development/6-5-testing-the-rule-set.md @@ -1,6 +1,6 @@ --- title: Testing the Rule Set -weight: 40 +weight: 65 disableToc: false chapter: false --- @@ -48,7 +48,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 "install.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-getting-started/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/development/useful_tools.md b/content/6-development/6-6-useful_tools.md similarity index 96% rename from content/development/useful_tools.md rename to content/6-development/6-6-useful_tools.md index 5e53cd9b..d73177ec 100644 --- a/content/development/useful_tools.md +++ b/content/6-development/6-6-useful_tools.md @@ -1,6 +1,6 @@ --- title: Useful Tools -weight: 30 +weight: 66 disableToc: false chapter: false --- @@ -30,7 +30,7 @@ Include ../coreruleset/rules/*.conf https://github.com/coreruleset/crs-toolchain -The CRS developer's toolbelt. Documentation lives at [crs-toolchain]({{% ref "crs_toolchain" %}}). +The CRS developer's toolbelt. Documentation lives at [crs-toolchain]({{< ref "6-development/6-2-crs-toolchain.md" >}}). ## Go-FTW diff --git a/content/development/_index.md b/content/6-development/_index.md similarity index 50% rename from content/development/_index.md rename to content/6-development/_index.md index c48632b0..642df813 100644 --- a/content/development/_index.md +++ b/content/6-development/_index.md @@ -1,6 +1,8 @@ --- title: Development -weight: 50 -pre: "5. " +weight: 6 +pre: "6. " chapter: true --- + +# Operation diff --git a/content/operation/known_issues.md b/content/7-known-issues/_index.md similarity index 98% rename from content/operation/known_issues.md rename to content/7-known-issues/_index.md index 7a6a17ae..fc91a9c8 100644 --- a/content/operation/known_issues.md +++ b/content/7-known-issues/_index.md @@ -1,8 +1,8 @@ --- -title: Known Issues -weight: 10 +title: 7. Known Issues +weight: 7 disableToc: false -chapter: false +chapter: true --- > There are some *known issues* with CRS and some of its compatible WAF engines. This page describes these issues. Get in touch if you think something is missing. diff --git a/content/resources/_index.md b/content/8-additional-resources/_index.md similarity index 99% rename from content/resources/_index.md rename to content/8-additional-resources/_index.md index ea472a11..b4cc76ad 100644 --- a/content/resources/_index.md +++ b/content/8-additional-resources/_index.md @@ -1,7 +1,7 @@ --- title: Additional Resources -weight: 60 -pre: "6. " +weight: 8 +pre: "8. " chapter: true --- diff --git a/content/_index.md b/content/_index.md index d817b9ac..5047a197 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 "development/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-development/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/content/rules/_index.md b/content/rules/_index.md deleted file mode 100644 index 1dbe9d4f..00000000 --- a/content/rules/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Rules -weight: 40 -pre: "4. " -chapter: true ---- From b624b80ee991368feb0a5cbe10d40d83f59bfbe7 Mon Sep 17 00:00:00 2001 From: dextermallo Date: Mon, 14 Oct 2024 15:48:44 +0800 Subject: [PATCH 02/11] fix: typo --- content/1-getting-started/1-1-crs-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/1-getting-started/1-1-crs-installation.md b/content/1-getting-started/1-1-crs-installation.md index b9397da4..49533cb4 100644 --- a/content/1-getting-started/1-1-crs-installation.md +++ b/content/1-getting-started/1-1-crs-installation.md @@ -123,7 +123,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 being 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-how-crs-works/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-how-crs-works/2-3-false-positives-and-tuning.md" >}}). ```bash systemctl restart httpd.service From 1afb012dd1ceb235d421e38f38f24a7de7f4a63f Mon Sep 17 00:00:00 2001 From: dextermallo Date: Mon, 5 Aug 2024 17:01:45 +0800 Subject: [PATCH 03/11] feat: restructure; update naming pattern and weight; fix inner-link --- .../{anomaly_scoring => 2-1-anomaly_scoring}/as_inbound.svg | 0 .../as_inbound_no_fonts.svg | 0 .../{anomaly_scoring => 2-1-anomaly_scoring}/index.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename content/2-how-crs-works/{anomaly_scoring => 2-1-anomaly_scoring}/as_inbound.svg (100%) rename content/2-how-crs-works/{anomaly_scoring => 2-1-anomaly_scoring}/as_inbound_no_fonts.svg (100%) rename content/2-how-crs-works/{anomaly_scoring => 2-1-anomaly_scoring}/index.md (100%) diff --git a/content/2-how-crs-works/anomaly_scoring/as_inbound.svg b/content/2-how-crs-works/2-1-anomaly_scoring/as_inbound.svg similarity index 100% rename from content/2-how-crs-works/anomaly_scoring/as_inbound.svg rename to content/2-how-crs-works/2-1-anomaly_scoring/as_inbound.svg diff --git a/content/2-how-crs-works/anomaly_scoring/as_inbound_no_fonts.svg b/content/2-how-crs-works/2-1-anomaly_scoring/as_inbound_no_fonts.svg similarity index 100% rename from content/2-how-crs-works/anomaly_scoring/as_inbound_no_fonts.svg rename to content/2-how-crs-works/2-1-anomaly_scoring/as_inbound_no_fonts.svg diff --git a/content/2-how-crs-works/anomaly_scoring/index.md b/content/2-how-crs-works/2-1-anomaly_scoring/index.md similarity index 100% rename from content/2-how-crs-works/anomaly_scoring/index.md rename to content/2-how-crs-works/2-1-anomaly_scoring/index.md From 5499729514f80bfed96c18db0fb9ba89ff76f1eb Mon Sep 17 00:00:00 2001 From: Max Leske <250711+theseion@users.noreply.github.com> Date: Sat, 9 Nov 2024 16:57:34 +0100 Subject: [PATCH 04/11] fix: fix stale links (#147) --- lychee.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lychee.toml b/lychee.toml index bc873731..05e21d9a 100644 --- a/lychee.toml +++ b/lychee.toml @@ -1,4 +1,4 @@ -exclude = ["github.com/coreruleset/coreruleset/blob/?$", "https://www.akamai.com/products/app-and-api-protector", "https://www.drupal.org"] +exclude = ["github.com/coreruleset.*/SECURITY.md", "github.com/coreruleset.*/.github/.*", "github.com/coreruleset/coreruleset/blob/?$", "https://www.akamai.com/products/app-and-api-protector", "https://www.drupal.org"] user_agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:132.0) Gecko/20100101 Firefox/132.0" no_progress = true cache = true From 4b117444f63b6c0f6ce8b6ab2906d3eb1519eb61 Mon Sep 17 00:00:00 2001 From: Max Leske <250711+theseion@users.noreply.github.com> Date: Sun, 10 Nov 2024 11:44:10 +0100 Subject: [PATCH 05/11] chore: fix lychee settings (#148) --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 6c6c3d29..e7627458 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -61,5 +61,5 @@ jobs: id: lychee uses: lycheeverse/lychee-action@f796c8b7d468feb9b8c0a46da3fac0af6874d374 # for v1.9.0 with: - args: "--cookie-jar /tmp/lychee-cookies './content/**/*.md'" + args: "--cookie-jar /tmp/lychee-cookies './content/**/*.md'" jobSummary: true From c3889df3318e5b1afd2b631052736e93ce5f5fc0 Mon Sep 17 00:00:00 2001 From: dextermallo Date: Wed, 13 Nov 2024 08:31:50 +0800 Subject: [PATCH 06/11] chore/fix: fix a pre tag; update wording --- .../4-about-plugins/{4-1-what-is-plugin.md => 4-1-plugins.md} | 2 +- .../5-1-self-contained-mode.md | 0 .../5-2-log-handling.md | 0 .../5-3-kubernetes-ingress-controller.md | 0 content/{5-advanced-usages => 5-advanced-topics}/_index.md | 2 +- content/7-known-issues/_index.md | 3 ++- 6 files changed, 4 insertions(+), 3 deletions(-) rename content/4-about-plugins/{4-1-what-is-plugin.md => 4-1-plugins.md} (99%) rename content/{5-advanced-usages => 5-advanced-topics}/5-1-self-contained-mode.md (100%) rename content/{5-advanced-usages => 5-advanced-topics}/5-2-log-handling.md (100%) rename content/{5-advanced-usages => 5-advanced-topics}/5-3-kubernetes-ingress-controller.md (100%) rename content/{5-advanced-usages => 5-advanced-topics}/_index.md (88%) diff --git a/content/4-about-plugins/4-1-what-is-plugin.md b/content/4-about-plugins/4-1-plugins.md similarity index 99% rename from content/4-about-plugins/4-1-what-is-plugin.md rename to content/4-about-plugins/4-1-plugins.md index db536740..dfeaafd0 100644 --- a/content/4-about-plugins/4-1-what-is-plugin.md +++ b/content/4-about-plugins/4-1-plugins.md @@ -1,5 +1,5 @@ --- -title: What is Plugin +title: Plugins weight: 41 disableToc: false chapter: false diff --git a/content/5-advanced-usages/5-1-self-contained-mode.md b/content/5-advanced-topics/5-1-self-contained-mode.md similarity index 100% rename from content/5-advanced-usages/5-1-self-contained-mode.md rename to content/5-advanced-topics/5-1-self-contained-mode.md diff --git a/content/5-advanced-usages/5-2-log-handling.md b/content/5-advanced-topics/5-2-log-handling.md similarity index 100% rename from content/5-advanced-usages/5-2-log-handling.md rename to content/5-advanced-topics/5-2-log-handling.md diff --git a/content/5-advanced-usages/5-3-kubernetes-ingress-controller.md b/content/5-advanced-topics/5-3-kubernetes-ingress-controller.md similarity index 100% rename from content/5-advanced-usages/5-3-kubernetes-ingress-controller.md rename to content/5-advanced-topics/5-3-kubernetes-ingress-controller.md diff --git a/content/5-advanced-usages/_index.md b/content/5-advanced-topics/_index.md similarity index 88% rename from content/5-advanced-usages/_index.md rename to content/5-advanced-topics/_index.md index 0cabcd77..1595b390 100644 --- a/content/5-advanced-usages/_index.md +++ b/content/5-advanced-topics/_index.md @@ -1,5 +1,5 @@ --- -title: Advanced Usages +title: Advanced Topics weight: 5 pre: "5. " chapter: true diff --git a/content/7-known-issues/_index.md b/content/7-known-issues/_index.md index fc91a9c8..86437584 100644 --- a/content/7-known-issues/_index.md +++ b/content/7-known-issues/_index.md @@ -1,6 +1,7 @@ --- -title: 7. Known Issues +title: Known Issues weight: 7 +pre: "7. " disableToc: false chapter: true --- From 769bbbd2eed888da15cef3325fd71c9ccf8635b2 Mon Sep 17 00:00:00 2001 From: Felipe Zipitria Date: Thu, 2 Jan 2025 08:42:03 -0300 Subject: [PATCH 07/11] fix: links in renaming Signed-off-by: Felipe Zipitria --- content/deployment/release.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 content/deployment/release.md diff --git a/content/deployment/release.md b/content/deployment/release.md new file mode 100644 index 00000000..b7e0e8d6 --- /dev/null +++ b/content/deployment/release.md @@ -0,0 +1,10 @@ +# Release steps + +Update install.md file from the hugo repository to: + +```sh +sed -e 's/{{< param crs_latest_release >}}/4.0.0/g' \ +-e 's/{{< param crs_dev_branch >}}/main/g' \ +-e 's:{{< param crs_install_dir >}}:/etc/crs4:g' \ +-e 's,{{< ref "1-2-extended_install.md" >}},https://coreruleset.org/docs/deployment/extended_install/,g' +``` From e03d26d455ad046fb3f6eadbed567c1d249fc0f6 Mon Sep 17 00:00:00 2001 From: Max Leske <250711+theseion@users.noreply.github.com> Date: Sun, 5 Jan 2025 10:14:29 +0100 Subject: [PATCH 08/11] chore: update Hugo theme --- themes/hugo-relearn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/themes/hugo-relearn b/themes/hugo-relearn index 80e448e5..bd1f3d34 160000 --- a/themes/hugo-relearn +++ b/themes/hugo-relearn @@ -1 +1 @@ -Subproject commit 80e448e5bdaa92c87ee0d0d86f1125c8606ebf5f +Subproject commit bd1f3d3432632c61bb12e7ec0f7673fed0289f19 From d14fc4333e2a060f5c0ee418c65e7e1e97c8d3e4 Mon Sep 17 00:00:00 2001 From: dextermallo Date: Mon, 13 Jan 2025 11:56:41 +0800 Subject: [PATCH 09/11] fix: shorten reference link --- content/1-getting-started/1-1-crs-installation.md | 4 ++-- content/1-getting-started/1-2-extended_install.md | 4 ++-- content/3-about-rules/rule_writing.md | 2 +- content/4-about-plugins/4-1-plugins.md | 2 +- content/6-development/6-1-contribution-guidelines.md | 8 ++++---- content/6-development/6-2-crs-toolchain.md | 2 +- .../6-development/6-3-assembling-regular-expressions.md | 8 ++++---- content/6-development/6-5-testing-the-rule-set.md | 2 +- content/6-development/6-6-useful_tools.md | 2 +- content/_index.md | 2 +- 10 files changed, 18 insertions(+), 18 deletions(-) diff --git a/content/1-getting-started/1-1-crs-installation.md b/content/1-getting-started/1-1-crs-installation.md index 49533cb4..3c6cf590 100644 --- a/content/1-getting-started/1-1-crs-installation.md +++ b/content/1-getting-started/1-1-crs-installation.md @@ -123,7 +123,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-how-crs-works/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 @@ -131,7 +131,7 @@ systemctl restart httpd.service ## Alternative: Using Containers -Another quick option is to use the official CRS [pre-packaged containers]({{% ref "6-development/6-6-useful_tools/#official-crs-maintained-docker-images" %}}). Docker, Podman, or any compatible container engine can be used. The official CRS images are published on [Docker Hub](https://hub.docker.com/r/owasp/modsecurity-crs/) and [GitHub Container Repository](https://github.com/coreruleset/modsecurity-crs-docker/pkgs/container/modsecurity-crs). The image most often deployed is `modsecurity-crs` (`owasp/modsecurity-crs` from Docker Hub or `ghcr.io/coreruleset/modsecurity-crs` from GHCR): it already has everything needed to get up and running quickly. +Another quick option is to use the official CRS [pre-packaged containers]({{% ref "6-6-useful_tools/#official-crs-maintained-docker-images" %}}). Docker, Podman, or any compatible container engine can be used. The official CRS images are published on [Docker Hub](https://hub.docker.com/r/owasp/modsecurity-crs/) and [GitHub Container Repository](https://github.com/coreruleset/modsecurity-crs-docker/pkgs/container/modsecurity-crs). The image most often deployed is `modsecurity-crs` (`owasp/modsecurity-crs` from Docker Hub or `ghcr.io/coreruleset/modsecurity-crs` from GHCR): it already has everything needed to get up and running quickly. The CRS project pre-packages both Apache and Nginx web servers along with the appropriate corresponding ModSecurity engine. More engines, like [Coraza](https://coraza.io/), will be added at a later date. diff --git a/content/1-getting-started/1-2-extended_install.md b/content/1-getting-started/1-2-extended_install.md index 33a577b5..c81e5b05 100644 --- a/content/1-getting-started/1-2-extended_install.md +++ b/content/1-getting-started/1-2-extended_install.md @@ -176,7 +176,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-how-crs-works/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. @@ -191,7 +191,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-how-crs-works/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 diff --git a/content/3-about-rules/rule_writing.md b/content/3-about-rules/rule_writing.md index fe7e4faf..2c53da53 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-development/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/4-about-plugins/4-1-plugins.md b/content/4-about-plugins/4-1-plugins.md index dfeaafd0..3d30343b 100644 --- a/content/4-about-plugins/4-1-plugins.md +++ b/content/4-about-plugins/4-1-plugins.md @@ -161,7 +161,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-about-plugins/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 b11ae22d..9b4c9a25 100644 --- a/content/6-development/6-1-contribution-guidelines.md +++ b/content/6-development/6-1-contribution-guidelines.md @@ -112,12 +112,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-development/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-development/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]`. @@ -274,7 +274,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-development/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) @@ -282,7 +282,7 @@ 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-development/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. diff --git a/content/6-development/6-2-crs-toolchain.md b/content/6-development/6-2-crs-toolchain.md index c6753ed5..08b4d354 100644 --- a/content/6-development/6-2-crs-toolchain.md +++ b/content/6-development/6-2-crs-toolchain.md @@ -67,7 +67,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-development/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 86dbd9a1..eb88f020 100644 --- a/content/6-development/6-3-assembling-regular-expressions.md +++ b/content/6-development/6-3-assembling-regular-expressions.md @@ -9,7 +9,7 @@ chapter: false ## 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-development/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 @@ -109,7 +109,7 @@ The following example is intentionanlly simple (and meaningless) to illustrates ##!< ``` -Processors are defined in the [crs-toolchain]({{< ref "6-development/6-2-crs-toolchain.md" >}}). +Processors are defined in the [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}). ### Nesting @@ -321,7 +321,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-development/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: @@ -357,7 +357,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-development/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 27dbc23d..18811516 100644 --- a/content/6-development/6-5-testing-the-rule-set.md +++ b/content/6-development/6-5-testing-the-rule-set.md @@ -48,7 +48,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-getting-started/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 d73177ec..7dbad509 100644 --- a/content/6-development/6-6-useful_tools.md +++ b/content/6-development/6-6-useful_tools.md @@ -30,7 +30,7 @@ Include ../coreruleset/rules/*.conf https://github.com/coreruleset/crs-toolchain -The CRS developer's toolbelt. Documentation lives at [crs-toolchain]({{< ref "6-development/6-2-crs-toolchain.md" >}}). +The CRS developer's toolbelt. Documentation lives at [crs-toolchain]({{< ref "6-2-crs-toolchain.md" >}}). ## Go-FTW diff --git a/content/_index.md b/content/_index.md index 5047a197..68dd468d 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-development/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 From c496e281ac28593dee00b9a455a554bdfdc67a3d Mon Sep 17 00:00:00 2001 From: dextermallo Date: Mon, 13 Jan 2025 11:57:02 +0800 Subject: [PATCH 10/11] fix: guideline path --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65dd5182..feab22d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,3 @@ # Contribution Guidelines -Please refer to [contribution_guidelines.md](content/development/contribution_guidelines.md). \ No newline at end of file +Please refer to [contribution_guidelines.md](content/6-development/6-1-contribution-guidelines.md). \ No newline at end of file From 4828b8d882017e5cb0ef279eed6ddd2f536477ab Mon Sep 17 00:00:00 2001 From: dextermallo Date: Mon, 13 Jan 2025 11:57:14 +0800 Subject: [PATCH 11/11] chore: doc for doc guideline --- .../6-1-contribution-guidelines.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/content/6-development/6-1-contribution-guidelines.md b/content/6-development/6-1-contribution-guidelines.md index 9b4c9a25..fb02dff5 100644 --- a/content/6-development/6-1-contribution-guidelines.md +++ b/content/6-development/6-1-contribution-guidelines.md @@ -96,6 +96,31 @@ instead of SecRule ARGS "foo" "id:1,phase:1,pass,t:none" ``` +### For CRS Documentation Contributions + +- Directory naming: Use lowercase letters and hyphens to separate words. For example: + ``` + . + ├── 1-getting-started + │ ├── 1-1-crs-installation.md + │ ├── 1-2-extended_install.md + │ ├── 1-3-using-containers.md + │ ├── 1-4-engine_integration_options.md + │ └── _index.md + ... + ``` +- Inner-link referencing should be used with the following format: + ``` + # general markdown format + {{}} + + # this will point to the directory 2-how-crs-works + {{}} + + # this will point to the .md + {{}} + ``` + ## Variable Naming Conventions * Variable names should be lowercase and should use the characters a-z, 0-9, and underscores only.