From 24bc0ed16a70a10957c7dceab9c592c27301003a Mon Sep 17 00:00:00 2001 From: Felipe Zipitria Date: Thu, 22 Jan 2026 19:18:09 -0300 Subject: [PATCH 1/3] docs: add blogpost on CRSLang Signed-off-by: Felipe Zipitria --- ...slang-the-next-generation-rule-language.md | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md diff --git a/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md b/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md new file mode 100644 index 0000000..1df0983 --- /dev/null +++ b/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md @@ -0,0 +1,199 @@ +--- +title: 'Introducing CRSLang: The Next Generation Rule Language for OWASP CRS' +date: '2026-01-22' +author: fzipi +categories: + - Blog +--- + +We're excited to introduce **CRSLang**, a new YAML-based rule language that will replace Seclang in the next major release of OWASP CRS. This represents a significant evolution in how we write, maintain, and deploy WAF rules. + +## Why CRSLang? + +For nearly two decades, the OWASP CRS has relied on ModSecurity's Seclang syntax. While Seclang has served us well, it comes with significant limitations that have become increasingly apparent as the project has grown: + +### The Problems with Seclang + +- **Technology Lock-in**: Rules are tightly coupled to ModSecurity syntax, making it difficult to support other WAF engines +- **Portability Issues**: Direct deployment to alternative WAF platforms requires significant translation efforts +- **Complexity**: Rules are hard to read, write, and maintain, with all components mixed in long strings +- **Learning Curve**: The steep barrier to entry discourages new contributors +- **Limited Expressiveness**: Complex logical conditions (especially OR operations) require workarounds, and there's no support for template functions + +Consider this typical Seclang rule: + +```apache +SecRule REQUEST_LINE "!@rx (?i)^(?:get /[^#\?]..." \ + "id:920100,\ + phase:1,\ + block,\ + t:none,\ + msg:'Method is not allowed by policy',\ + logdata:'Matched Data: %{MATCHED_VAR} found within %{MATCHED_VAR_NAME}',\ + tag:'application-multi',\ + tag:'attack-protocol',\ + ver:'OWASP_CRS/4.0.0',\ + severity:'WARNING'" +``` + +Can you quickly understand what this rule does? The metadata, transformations, operators, and actions are all jumbled together in a single string, making it difficult to parse both for humans and machines. + +## Enter CRSLang + +CRSLang is a YAML-based, technology-agnostic rule language designed to address these limitations while maintaining full backward compatibility with existing Seclang rules. Here's the same rule in CRSLang format: + +```yaml +rule: + metadata: + comment: "Validate request line against the format specified in the HTTP RFC" + phase: 1 + id: 920100 + message: Invalid HTTP Request Line + severity: WARNING + tags: + - application-multi + - attack-protocol + conditions: + - variables: + - name: REQUEST_LINE + operator: + rx: (?i)^(?:get /[^#\?]*...$ + transformations: + - none + actions: + disruptive: block + non-disruptive: + - logdata: "%{request_line}" + - setvar: tx.inbound_anomaly_score_pl1=+%{tx.warning_anomaly_score} +``` + +The difference is immediately apparent. The rule structure is clear, with distinct sections for metadata, conditions, and actions. + +## Key Features + +### 1. Clear Structure and Separation of Concerns + +CRSLang separates metadata, conditions, and actions into distinct, easy-to-understand sections. This makes rules easier to read, validate, and maintain. + +### 2. Improved Logical Expressions + +Seclang's support for complex logical conditions is limited and often requires workarounds. CRSLang provides clean AND/OR syntax: + +```yaml +rule: + id: 1 + phase: 1 + conditions: + - and: + - or: + - variable: ARGS:user + operator: "@streq" + pattern: "admin" + - variable: ARGS:username + operator: "@streq" + pattern: "admin" + - variable: REQUEST_LINE + operator: "@contains" + pattern: "admin" + actions: + - action: block +``` + +### 3. Template Functions + +CRSLang introduces reusable rule components, making it easier to maintain consistent patterns across your rule set: + +```yaml +templates: + admin_check: + conditions: + - or: + - variable: ARGS:user + operator: "@streq" + pattern: "admin" + - variable: ARGS:username + operator: "@streq" + pattern: "admin" + +rules: + - id: 1 + phase: 1 + conditions: + - and: + - template: admin_check + - variable: REQUEST_LINE + operator: "@contains" + pattern: "admin" + actions: + - action: block +``` + +### 4. Bidirectional Translation + +One of CRSLang's most powerful features is its bidirectional translation capability. We've built a robust parser that can: + +- Convert existing Seclang rules to CRSLang format +- Generate valid Seclang from CRSLang rules +- Preserve all semantic information during translation +- Maintain comment and documentation context + +This means you can gradually migrate to CRSLang while maintaining compatibility with existing tools and deployments. The translation engine ensures that no information is lost in the conversion process, and round-trip testing validates correctness. + +## Building on Previous Work + +CRSLang builds upon the foundation laid by earlier parser projects. If you're familiar with our [msc_pyparser]({{% ref "2020-09-01-introducing-msc_pyparser.md" %}}) tool, you'll recognize the concept of converting ModSecurity rules into structured formats. CRSLang takes this concept further by providing a complete, production-ready language specification with full tooling support. + +While msc_pyparser focused on rule manipulation through Python, CRSLang provides a comprehensive language specification with: + +- ANTLR-based parsing with support for multiple target languages (Go, Python, Java) +- Full support for Seclang v2 and v3 +- Validation and testing frameworks +- IDE integration capabilities (syntax highlighting, validation, debugging) + +## The Technology + +CRSLang is powered by a sophisticated parser built with ANTLR, providing: + +- **Multi-language support**: Generated parsers for Go, Python, and Java +- **Version compatibility**: Full support for Seclang v2 and v3 +- **Semantic preservation**: No information loss during translation +- **Comment preservation**: Documentation and context maintained throughout the conversion process + +The project is fully open source and available at [github.com/coreruleset/crslang](https://github.com/coreruleset/crslang). + +## Looking Forward + +CRSLang represents more than just a syntax change—it's a foundation for the future of OWASP CRS. With this new language, we're opening doors to: + +- **Enhanced portability**: Support for multiple WAF technologies beyond ModSecurity +- **Alternative logical engines**: Integration with systems like Google CEL or Wirefilter +- **Better tooling**: IDE support, linting, automated testing, and debugging capabilities +- **Reduced learning curve**: Making it easier for new contributors to join the project +- **Improved maintainability**: Clearer rule structure means fewer bugs and easier updates + +## Timeline and Migration + +CRSLang will replace Seclang as the primary rule language in the next major release of OWASP CRS. We're committed to making this transition as smooth as possible: + +1. **Current state**: CRSLang parser and tooling are available now +2. **Migration period**: Full backward compatibility maintained through translation engine +3. **Next major release**: CRSLang becomes the default format +4. **Long-term support**: Seclang translation capabilities maintained for existing deployments + +You can start exploring CRSLang today by: + +- Visiting the [CRSLang GitHub repository](https://github.com/coreruleset/crslang) +- Converting your existing rules to see the difference +- Providing feedback to help shape the final specification +- Contributing to the parser and tooling development + +## Get Involved + +We're excited about this evolution and would love your feedback. Whether you're a long-time CRS contributor or new to the project, your input is valuable as we shape the future of WAF rule development. + +Join the conversation: +- GitHub: [github.com/coreruleset/crslang](https://github.com/coreruleset/crslang) +- OWASP Slack: [owasp.org/slack/](https://owasp.org/slack/) (#coreruleset channel) +- Mailing list: Join our community discussions + +The future of OWASP CRS is clearer, more maintainable, and more accessible. We can't wait to see what the community builds with CRSLang. From 443929fd3b15cbcd8cd8347cf379f2fcf584c4f2 Mon Sep 17 00:00:00 2001 From: Felipe Zipitria Date: Sun, 1 Feb 2026 01:16:13 -0300 Subject: [PATCH 2/3] fix: code examples Signed-off-by: Felipe Zipitria --- ...slang-the-next-generation-rule-language.md | 106 ++++++++++-------- 1 file changed, 61 insertions(+), 45 deletions(-) diff --git a/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md b/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md index 1df0983..d9e29a3 100644 --- a/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md +++ b/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md @@ -45,26 +45,33 @@ CRSLang is a YAML-based, technology-agnostic rule language designed to address t ```yaml rule: metadata: - comment: "Validate request line against the format specified in the HTTP RFC" + comment: | + "Validate request line against the format specified in the HTTP RFC" phase: 1 id: 920100 message: Invalid HTTP Request Line severity: WARNING tags: - application-multi - - attack-protocol + - language-multi + version: OWASP_CRS/4.0.0 conditions: - variables: - - name: REQUEST_LINE + - REQUEST_LINE operator: - rx: (?i)^(?:get /[^#\?]*...$ + negate: true + rx: (?i)^(?:get /[^#\?]... transformations: - none actions: disruptive: block non-disruptive: - logdata: "%{request_line}" - - setvar: tx.inbound_anomaly_score_pl1=+%{tx.warning_anomaly_score} + - setvar: + collection: TX + operation: =+ + assignments: + - inbound_anomaly_score_pl1: "%{tx.warning_anomaly_score}" ``` The difference is immediately apparent. The rule structure is clear, with distinct sections for metadata, conditions, and actions. @@ -77,55 +84,64 @@ CRSLang separates metadata, conditions, and actions into distinct, easy-to-under ### 2. Improved Logical Expressions -Seclang's support for complex logical conditions is limited and often requires workarounds. CRSLang provides clean AND/OR syntax: +Seclang's support for complex logical conditions is limited and often requires workarounds. CRSLang provides a clean AND syntax, and we are working on extending its logical capabilities. + ```yaml rule: - id: 1 - phase: 1 + metadata: + phase: 1 + id: 920310 + message: Request Has an Empty Accept Header conditions: - - and: - - or: - - variable: ARGS:user - operator: "@streq" - pattern: "admin" - - variable: ARGS:username - operator: "@streq" - pattern: "admin" - - variable: REQUEST_LINE - operator: "@contains" - pattern: "admin" + - collections: + - name: REQUEST_HEADERS + arguments: + - Accept + operator: + rx: ^$ + transformations: + - none + - variables: + - REQUEST_METHOD + operator: + negate: true + rx: ^OPTIONS$ + - collections: + - name: REQUEST_HEADERS + arguments: + - User-Agent + operator: + negate: true + pm: AppleWebKit Android Business Enterprise Entreprise + transformations: + - none actions: - - action: block + disruptive: block ``` ### 3. Template Functions -CRSLang introduces reusable rule components, making it easier to maintain consistent patterns across your rule set: +CRSLang introduces reusable rule components, making it easier to maintain consistent patterns across your rule set. You can also define common patterns and use them with different variables: -```yaml -templates: - admin_check: - conditions: - - or: - - variable: ARGS:user - operator: "@streq" - pattern: "admin" - - variable: ARGS:username - operator: "@streq" - pattern: "admin" - -rules: - - id: 1 - phase: 1 - conditions: - - and: - - template: admin_check - - variable: REQUEST_LINE - operator: "@contains" - pattern: "admin" - actions: - - action: block +``` +detect-pattern-template: &detect-pattern + operator: + rx: "some-pattern" + transformations: + - urlDecode + - lowercase + +rule: + metadata: + phase: "1" + id: 1 + conditions: + - <<: *detect-pattern + variables: + - REQUEST_URI + actions: + disruptive: pass ``` ### 4. Bidirectional Translation @@ -145,7 +161,7 @@ CRSLang builds upon the foundation laid by earlier parser projects. If you're fa While msc_pyparser focused on rule manipulation through Python, CRSLang provides a comprehensive language specification with: -- ANTLR-based parsing with support for multiple target languages (Go, Python, Java) +- ANTLR-based parsing with support for multiple target languages (Go, Python, Java), based on [seclang_parser]({{% ref "2026-01-22-introducing-seclang-parser-unified-antlr-based-parser.md" %}}) - Full support for Seclang v2 and v3 - Validation and testing frameworks - IDE integration capabilities (syntax highlighting, validation, debugging) From 364a15ab159ea50577c202c9b643c590e3c3992f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felipe=20Zipitr=C3=ADa?= <3012076+fzipi@users.noreply.github.com> Date: Sun, 1 Feb 2026 10:40:38 -0300 Subject: [PATCH 3/3] Update content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md Co-authored-by: Max Leske <250711+theseion@users.noreply.github.com> --- ...slang-the-next-generation-rule-language.md | 180 +----------------- 1 file changed, 1 insertion(+), 179 deletions(-) diff --git a/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md b/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md index d9e29a3..208ff00 100644 --- a/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md +++ b/content/blog/2026-01-22-introducing-crslang-the-next-generation-rule-language.md @@ -23,6 +23,7 @@ For nearly two decades, the OWASP CRS has relied on ModSecurity's Seclang syntax Consider this typical Seclang rule: ```apache +# Validate request line against the format specified in the HTTP RFC SecRule REQUEST_LINE "!@rx (?i)^(?:get /[^#\?]..." \ "id:920100,\ phase:1,\ @@ -34,182 +35,3 @@ SecRule REQUEST_LINE "!@rx (?i)^(?:get /[^#\?]..." \ tag:'attack-protocol',\ ver:'OWASP_CRS/4.0.0',\ severity:'WARNING'" -``` - -Can you quickly understand what this rule does? The metadata, transformations, operators, and actions are all jumbled together in a single string, making it difficult to parse both for humans and machines. - -## Enter CRSLang - -CRSLang is a YAML-based, technology-agnostic rule language designed to address these limitations while maintaining full backward compatibility with existing Seclang rules. Here's the same rule in CRSLang format: - -```yaml -rule: - metadata: - comment: | - "Validate request line against the format specified in the HTTP RFC" - phase: 1 - id: 920100 - message: Invalid HTTP Request Line - severity: WARNING - tags: - - application-multi - - language-multi - version: OWASP_CRS/4.0.0 - conditions: - - variables: - - REQUEST_LINE - operator: - negate: true - rx: (?i)^(?:get /[^#\?]... - transformations: - - none - actions: - disruptive: block - non-disruptive: - - logdata: "%{request_line}" - - setvar: - collection: TX - operation: =+ - assignments: - - inbound_anomaly_score_pl1: "%{tx.warning_anomaly_score}" -``` - -The difference is immediately apparent. The rule structure is clear, with distinct sections for metadata, conditions, and actions. - -## Key Features - -### 1. Clear Structure and Separation of Concerns - -CRSLang separates metadata, conditions, and actions into distinct, easy-to-understand sections. This makes rules easier to read, validate, and maintain. - -### 2. Improved Logical Expressions - -Seclang's support for complex logical conditions is limited and often requires workarounds. CRSLang provides a clean AND syntax, and we are working on extending its logical capabilities. - - -```yaml -rule: - metadata: - phase: 1 - id: 920310 - message: Request Has an Empty Accept Header - conditions: - - collections: - - name: REQUEST_HEADERS - arguments: - - Accept - operator: - rx: ^$ - transformations: - - none - - variables: - - REQUEST_METHOD - operator: - negate: true - rx: ^OPTIONS$ - - collections: - - name: REQUEST_HEADERS - arguments: - - User-Agent - operator: - negate: true - pm: AppleWebKit Android Business Enterprise Entreprise - transformations: - - none - actions: - disruptive: block -``` - -### 3. Template Functions - -CRSLang introduces reusable rule components, making it easier to maintain consistent patterns across your rule set. You can also define common patterns and use them with different variables: - -``` -detect-pattern-template: &detect-pattern - operator: - rx: "some-pattern" - transformations: - - urlDecode - - lowercase - -rule: - metadata: - phase: "1" - id: 1 - conditions: - - <<: *detect-pattern - variables: - - REQUEST_URI - actions: - disruptive: pass -``` - -### 4. Bidirectional Translation - -One of CRSLang's most powerful features is its bidirectional translation capability. We've built a robust parser that can: - -- Convert existing Seclang rules to CRSLang format -- Generate valid Seclang from CRSLang rules -- Preserve all semantic information during translation -- Maintain comment and documentation context - -This means you can gradually migrate to CRSLang while maintaining compatibility with existing tools and deployments. The translation engine ensures that no information is lost in the conversion process, and round-trip testing validates correctness. - -## Building on Previous Work - -CRSLang builds upon the foundation laid by earlier parser projects. If you're familiar with our [msc_pyparser]({{% ref "2020-09-01-introducing-msc_pyparser.md" %}}) tool, you'll recognize the concept of converting ModSecurity rules into structured formats. CRSLang takes this concept further by providing a complete, production-ready language specification with full tooling support. - -While msc_pyparser focused on rule manipulation through Python, CRSLang provides a comprehensive language specification with: - -- ANTLR-based parsing with support for multiple target languages (Go, Python, Java), based on [seclang_parser]({{% ref "2026-01-22-introducing-seclang-parser-unified-antlr-based-parser.md" %}}) -- Full support for Seclang v2 and v3 -- Validation and testing frameworks -- IDE integration capabilities (syntax highlighting, validation, debugging) - -## The Technology - -CRSLang is powered by a sophisticated parser built with ANTLR, providing: - -- **Multi-language support**: Generated parsers for Go, Python, and Java -- **Version compatibility**: Full support for Seclang v2 and v3 -- **Semantic preservation**: No information loss during translation -- **Comment preservation**: Documentation and context maintained throughout the conversion process - -The project is fully open source and available at [github.com/coreruleset/crslang](https://github.com/coreruleset/crslang). - -## Looking Forward - -CRSLang represents more than just a syntax change—it's a foundation for the future of OWASP CRS. With this new language, we're opening doors to: - -- **Enhanced portability**: Support for multiple WAF technologies beyond ModSecurity -- **Alternative logical engines**: Integration with systems like Google CEL or Wirefilter -- **Better tooling**: IDE support, linting, automated testing, and debugging capabilities -- **Reduced learning curve**: Making it easier for new contributors to join the project -- **Improved maintainability**: Clearer rule structure means fewer bugs and easier updates - -## Timeline and Migration - -CRSLang will replace Seclang as the primary rule language in the next major release of OWASP CRS. We're committed to making this transition as smooth as possible: - -1. **Current state**: CRSLang parser and tooling are available now -2. **Migration period**: Full backward compatibility maintained through translation engine -3. **Next major release**: CRSLang becomes the default format -4. **Long-term support**: Seclang translation capabilities maintained for existing deployments - -You can start exploring CRSLang today by: - -- Visiting the [CRSLang GitHub repository](https://github.com/coreruleset/crslang) -- Converting your existing rules to see the difference -- Providing feedback to help shape the final specification -- Contributing to the parser and tooling development - -## Get Involved - -We're excited about this evolution and would love your feedback. Whether you're a long-time CRS contributor or new to the project, your input is valuable as we shape the future of WAF rule development. - -Join the conversation: -- GitHub: [github.com/coreruleset/crslang](https://github.com/coreruleset/crslang) -- OWASP Slack: [owasp.org/slack/](https://owasp.org/slack/) (#coreruleset channel) -- Mailing list: Join our community discussions - -The future of OWASP CRS is clearer, more maintainable, and more accessible. We can't wait to see what the community builds with CRSLang.