coreruleset / documentation Goto Github PK

The ENGINE AND INTEGRATION OPTIONS page lists WAF engines that are compatible with the ModSecurity configuration language. Several of our products package a variant of ModSecurity, which we have customized for performance.

Is it appropriate to add our customized ModSecurity WAF module to this page?

Thank you,
Nick Ramirez

If completely replacing a CRS phase 1 rule (not just updating a rule target etc. but completely replacing a rule, i.e. the operator is being modified) then this cannot occur in the REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf file because any anomaly scoring will be wiped and set to 0 immediately after when REQUEST-901-INITIALIZATION.conf executes.

RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf is also no good as the replacement rule needs to come before REQUEST-949-BLOCKING-EVALUATION.conf/RESPONSE-959-BLOCKING-EVALUATION.conf so that the replacement rule correctly contributes to anomaly scoring totals. Otherwise, things like early blocking mode can start to break.

Document corner case as a known issue.

Include two ideas as solutions:

• SecRuleRemoveById and then add new rule, all after the includes
• Add in a custom REQUEST-902-CUSTOM-RULES-POST-INIT file, or something similar, if there are going to be many such replacement rules

Reference: coreruleset/coreruleset#2878

As per: https://github.com/coreruleset/coreruleset/pull/3223/files

.data files are now .ra files.

With the move of ModSecurity from Trustwave to OWASP, there is now a need to update our documentation to reflect this, particularly where we discuss engine options and the status of ModSecurity.

CRS Project decided to stop producing two sets of containers, but nobody updated the documentation to reflect this change.

Findings by @dune73:

• I had to install docker-compose (Ubuntu 22.04). Docker compose command becomes docker-compose. The documentation explains the need for docker-compose in older installs, but it only explains this under go-ftw, not in the docker section, where I kind of expect such an explanation.
• The code block uses > as prompt, while other code blocks use $.
• The code block does not explain you need to be root to run this. sudo would probably make this easier. The twist is that you may not be root to install go-ftw afterwards or the binary can't be found for the testing user.
• The docker ps is a bit hidden within the same code block as the compose.
• I'm getting a go-httpbin container instead of the httpbin indicated in the docker ps output
• The ftw files presented further down below in the documentation do not correspond with the docker container composed. That means you need to adjust the log file within the .ftw.yaml. The doc explains that we're mounting the log volumes, but it does not indicate the path and I had to look for it in the compose file without this being explained anywhere. We are providing docker-compose.yaml. Why don't we provide a preconfigured .ftw.apache.docker.yaml etc.?

Motivation

We need more input from new contributors. Currently, we are relying more and more on a lot of internal and external tools to write our rules. Not everybody may know them, while they are so helpful to create better rules.

I think we should have something like a "Great tools for rule writers" page to bring the rule writing practices from the 2000s to the 2020s.

And maybe even end with a full-fledged "rule writing walkthrough" that strings all the tools together to create a sample rule (could be moved to a separate issue if we want to do that).

Proposed solution

At least, we could make a list of useful tools and links to them.

For example:

• CRS-toolchain (would link to our own upcoming documentation page about the new regexp assembler)
• go-ftw (link to our own upcoming documentation)
• https://regex101.com - This is essential
• https://onecompiler.com/mysql - live running MySQL commands (great site btw)
• https://onecompiler.com/mongodb - live running MongoDB commands
• https://sqliteonline.com - live running SQLite commands
• https://onecompiler.com/redis - live running Redis commands
• ...anything else that you love?

At best we could have the list, and also create a 'walkthrough' for creating a rule that goes from:

• a payload
• to one of the online IDEs above to play with payload variances and backend behavior with regards to spacing, comments, etc.
• to thinking of a regexp
• to making and testing it in regex101
• when to modify an existing rule and when to create a new rule (which should be somewhat discouraged unless it's really a new attack technique.)
• then to create a regexp-assemble data file
• generate the rule with crs-toolchain
• testing the rule (link to our own upcoming documentation on go-ftw)

Alternatives

Karel always just does a web search for 'execute postgres online'. But there's a bigger chance that people might give up.

Additional context

N/A

Every time that I copy-paste one of the agreed 'example tests' from the Contribution Guidelines document, my PR gets errors.

We need to verify that the template "gold standard" tests are correct.

Link to the test templates: https://github.com/coreruleset/documentation/blob/main/content/development/contribution_guidelines.md#positive-tests

@dune73 is happy for his blog post on working with paranoia levels to be used as the foundation of the official documentation on the subject.

The work just needs to be done.

https://www.youtube.com/@owaspmodsecuritycoreruleset

Once the 'Early Blocking' blog post is finalised and published, I will merge the new content into the existing content we have on early blocking mode.

Some of the existing content is probably out of date. Also, the blog post probably has some clearer explanations here and there.

I'm going to do a pass over the extended install.

New options have been added to CONTRIBUTING.MD, e.g. paranoia level tag advice.

We need to make sure everything is up to date and nothing gets lost between the two (the MD file and the documentation page).

Motivation

Currently we don’t have documented how to set up and run go-ftw for rule developers.

Proposed solution

Create a documentation page under development and explain:

• links to installing and running docker & docker-compose
• downloading go-ftw
• for macOS, trusting the ftw binary one time with right click and Open
• add template for .ftw.yaml
• running ftw
• running ftw on one rule only
• running ftw on a subset (regexp)
• remembering to docker-compose down & up after changing a rule

Btw, my .ftw.yaml (if it's not already doc'd somewhere) is:

---
logfile: 'tests/logs/modsec2-apache/error.log'
logtype:
  name: 'apache'
  timeregex:  '\[([A-Z][a-z]{2} [A-z][a-z]{2} \d{1,2} \d{1,2}\:\d{1,2}\:\d{1,2}\.\d+? \d{4})\]'
  timeformat: 'ddd MMM DD HH:mm:ss.S YYYY'

We should have Nginx/Coraza too, maybe in the future and do it in steps.

Alternatives

Explain it manually to people 30 times. 😉

Additional context

N/A

As far as we know, the AWS WAF "Core rule set (CRS) managed rule group" is not based on the OWASP CRS. (If anyone from AWS is reading this and knows otherwise, please reach out to us.)

This needs to be stated to avoid anyone getting confused and thinking the AWS CRS is the actual CRS.

@RedXanadu's presentation on our CRS Dublin 2023 summit proposed interesting questions. One idea was to add information about how to do logging, what is important, etc.

The new
https://github.com/jcchavezs/coraza-httpbin
Coraza container makes it easy to test CRS by using a pre-built Coraza container.

We should add this as a listed tool to make it easy for anyone to test CRS with Coraza.

File data/IdNumbering.csv is missing, link to it is here.

Found it here so it's probably just misplaced.

Some parts of our documentation will face the problem that they need to describe different major versions, with non-compatible changes.

After reviewing a bit our options, we can:

• have a base file that can be included. This base file should be (somehow) independent of the version. For version-specific stuff, we use the include shortcode from the theme
  An example layout for this is:

base/install.md (base with no "specific" version)
v3/install.md 
  - (include "base/install.md)
  - add specific content (files, etc)
v4/install.md
  - (include "base/install.md)
  - add specific content (files, etc)

Another option is to use tabbed content with a specific version. This has the advantage that you always have the content in one file.

Let me know what you think.