Configuring the Web Application Firewall

Configuring the WAF requires configuring these three aspects:

1. Configuring the ModSecurity engine.
2. Specifying the ModSecurity rules.
3. Specifying which requests the WAF processes.

Refer to the following YAML reference page for details on setting this configuration entry: /policies/waf.

The ModSecurity engine configuration and rules are provided as a collection of files, which can be either a .zip file, or a directory. Inside these collections, files with a '.conf' suffix are loaded as configuration files and all other files are treated as data files. The first file that is loaded is modsecurity.conf in the configuration collection, if it exists. Then the remaining configuration files in the configuration collection are loaded in alphabetical order. Finally, the configuration files in the rules collection are loaded in alphabetical order.

Full documentation of the ModSecurity engine configuration is available in the ModSecurity Reference Manual.

A common approach to configuring ModSecurity is to use the ModSecurity recommended configuration and the OWASP CRS as a base and modify them to suit your environment.

For each request, the request match entries are evaluated in order. The first entry to match the request's method, path, and version is used. The phases controls at which points during the HTTP transaction the WAF runs. If no entries are matched, WAF only processes the request if triggered by an HTTP transformation.

For example, consider the following configuration:

version: "25.03"

policies:
  waf:
    configuration:
      content: waf_config
      type: path
    rules:
      content: "@waf_rules.zip"
      type: zip
    request_match:
      - version: HTTP/1.0
        path: "*"
      - method: GET
        path: /secure/*
        phases:
          request_headers: true
          request_body: true
          response_headers: false
          response_body: false
          logging: true
      - method: *
        path: /secure/*

In this example, the WAF processes any requests that are made by HTTP/1.0 clients at all points in the request and response cycle. For other clients, the WAF only processes requests to resources under /secure/, with WAF processing only the requests for GET requests, and processing both requests and responses for other methods.

Using the ModSecurity recommended configuration

The ModSecurity project provides a configuration file that contains their recommended values for the various configuration items. To use these recommended settings:

1. Download modsecurity.conf-recommended and unicode.mapping files from the ModSecurity project.
2. Rename modsecurity.conf-recommended to modsecurity.conf.
3. Adjust any configuration items within modsecurity.conf.
4. Add the modsecurity.conf and unicode.mapping files to the configuration collection.

Note that the ModSecurity recommended configuration starts the ModSecurity engine in DetectionOnly mode, which means that it logs any issues that are encountered but does not act. In order to enforce the rules, the ModSecurity engine the SecRuleEngine configuration entry must be set to On.

Using the OWASP CRS

The OWASP CRS is a set of ModSecurity rules that cover a wide variety of attacks, including the OWASP Top Ten vulnerabilities. To use the OWASP CRS:

1. Download the OWASP CRS package from their website. The exact file name depends on the version, but is named like coreruleset-4.6.0-minimal.zip
2. Extract the content of the archive locally.
3. Rename crs-setup.conf.example to crs-setup.conf.
4. Adjust any configuration items within crs-setup.conf.
5. Add the crs-setup.conf file to the configuration collection.
6. Adjust any rules within the rules directory.
7. Add all the files in the rules directory to the rules collection.

Note that the OWASP CRS rules directory contains some example configuration files with a .conf.example suffix that describe how to configure common scenarios, such as allowing all requests from a vulnerability scanner. To load these example configuration files, they must be renamed to have a .conf suffix.

Using HTTP Transformations to trigger WAF processing

Calling the Control.triggerWAF function during the request phase indicates that the WAF must process the current request. Detailed documentation of the lua modules can be found on the Lua Module Documentation page.

For more information on how to configure and use HTTP Transformations, see the HTTP Transformations topic.