Ansible Role for Installing Nginx, Setting Up ModSecurity3, and Installing OWASP CRS v3 Ruleset

ModSecurity3 is a robust, open-source firewall for web applications that works across different platforms.

Originally found at: https://modsecurity.org/, it is now managed by https://owasp.org/.

ModSecurity3 works with a collection of rules called OWASP CRS. Note that while this role often mentions CRS3, version 4 has also been released.

You can find more information here:

• Original ruleset: https://modsecurity.org/crs/
• Current location: https://owasp.org/www-project-modsecurity-core-rule-set/
• Additional resources: https://coreruleset.org/ and https://github.com/coreruleset/coreruleset/

This role is designed to work with Nginx as the web server. Although Nginx can also work with Apache, this role only supports Nginx.

More info about Nginx: https://www.nginx.com

The role will automatically install all libraries and packages that ModSecurity3 needs. It will also install any compilers and build tools required for the installation process, and remove these tools if they weren’t originally on the system.

Nginx support is mainly provided by the ansible-role-nginx role from jdauphant.

You can find it at: https://github.com/jdauphant/ansible-role-nginx

By default, this role installs Nginx from the repositories provided by your operating system. It is recommended to change this to the official Nginx repository.

You can do this by setting the following variable:

nginx_official_repo: true

Optionally, this role can also include GeoIP and/or MaxMind Nginx modules for geolocation features. To use the MaxMind module, you will need a licensed copy of an up-to-date database from https://www.maxmind.com/en/geoip-databases.

You can enable these features using the variables below:

nginx_modsec3_crs3_geoip_enabled: false
nginx_modsec3_crs3_maxmind_enabled: true

Note: If you change options like the modules you want to include, make sure to delete the Makefile and remove any .so files from the objs/ folder to avoid issues during compilation.

Requirements

Before running a playbook using this role:

1. Install any required Ansible roles listed in requirements.yml. You can view it here.

Use the following command to install the roles:

ansible-galaxy install -r requirements.yml

Important: This role uses tasks from the nginx role, so ensure it is installed in the same location with the specific name "ansible-role-nginx".

In your project's playbook’s requirements.yml (not the one for this role), you need to include both this role and the nginx role like this:

- src: perryk.nginx_modsec3_crs3

- src: https://github.com/jdauphant/ansible-role-nginx
  version: master

Role Variables

You can check the role's defaults/main.yml and vars/main.yml files for variables you might want to change in your playbook.

Currently, there are no notable variables set. However, there are many variables in the nginx role. You can find explanations for these in the role's README.md file.

Example Playbook

Here’s an example playbook using this role to add and enable ModSecurity for the default Nginx site:

- hosts: servers

  vars:

    nginx_pkgs:
      - nginx
    nginx_install_epel_repo: false
    nginx_official_repo: true
    nginx_official_repo_mainline: true
    nginx_module_configs:
      - ngx_http_modsecurity_module
      - ngx_http_geoip2_module
    nginx_modules_disable:
      - ngx_http_geoip_module
    nginx_sites:
      default:
       - listen 80
       - server_name _
       - "modsecurity on"
       - "modsecurity_rules_file /etc/nginx/modsec/main.conf"
       - root "/usr/share/nginx/html"
       - index index.html

  roles:
    - perryk.nginx-modsec3-crs3

License

MIT

Author Information

Perry Kollmorgen - https://github.com/perryk