Tools

Tools that are useful when writing, testing and operating ModSecurity rules. Projects are listed with the organization that maintains them; the OWASP CRS project and the digitalwave team (one of the ModSecurity maintainers) produce most of the current tooling.

Rule sets

  • OWASP CRS - the rule set almost every ModSecurity deployment runs. Repository, documentation, plugin registry for application-specific exclusions (WordPress, Nextcloud, Drupal, phpBB, phpMyAdmin, DokuWiki, cPanel, XenForo) and add-ons such as the DoS-protection, antivirus, body-decompress, fake-bot and auto-decoding plugins.
  • Comodo free ModSecurity rules - a commercial vendor’s free rule set.

Writing and checking rules

  • SecLang specification - the engine-independent specification of the rules language, with a compatibility matrix for ModSecurity v2, libModSecurity v3 and Coraza.
  • Coraza playground - run a rule against a request in the browser.
  • crs-toolchain - the CRS developers’ command-line tool: assembles regular expressions from .ra files, renumbers and updates rules. Installable from the CRS Homebrew tap.
  • crs-linter - checks rules files against the CRS formatting and naming conventions.
  • msc_pyparser - a Python parser for SecLang that produces an abstract syntax tree and writes rules back, for bulk edits, linting and analysis.
  • secrules_parsing and seclang_parser - the CRS project’s Python and ANTLR parsers for the language.
  • msc_retest - measures how long a regular expression takes in the PCRE and PCRE2 engines, for spotting patterns that are slow or vulnerable to regular-expression denial of service.
  • vscode-language-modsecurity - SecLang syntax highlighting for Visual Studio Code, and regexp-assemble-syntax for the .ra files.

Testing rules and engines

  • go-ftw - the Framework for Testing WAFs: sends the HTTP requests described in YAML test files to a web server running ModSecurity and checks the logs for the expected rule matches. It is how the CRS test suite runs; the YAML format is defined by ftw-tests-schema. The older Python ftw is no longer developed.
  • ftwrunner - runs the same FTW test files directly against libModSecurity, without a web server.
  • secrules-language-tests - the regression test cases shared by ModSecurity v2 and v3 (a git submodule of the engine) that any SecLang implementation can use to check itself.
  • MRTS - the ModSecurity Regression Test Set.
  • modsecurity-crs-docker - the official container images with ModSecurity v2 on Apache httpd or libModSecurity on NGINX and the OWASP CRS preinstalled, the quickest way to get a test instance.
  • The engine’s own test tools: tests/msc_test and run-unit-tests.pl in the v2 tree, test/regression_tests, test/unit_tests and test/benchmark in the v3 tree (see Contributing).

Working with logs

  • libmsclogparser - a C library (with Python bindings) that parses ModSecurity audit and error log entries.
  • modsecurity-parser - analyzes native and JSON audit logs and produces JSON, Excel and chart summaries.
  • ModSecurity-log-utilities - command-line tools from the former maintainer that turn audit logs into summaries.
  • logstash-modsecurity - Logstash filters for the native audit log format. With SecAuditLogFormat JSON most log pipelines need no special parser.
  • modsec-sdbm-util - inspects and shrinks the SDBM files that ModSecurity v2 uses for persistent collections.
  • WAF-FLE - a web console for audit logs; no longer maintained but still used.

Integrating the engine