publications thesis contact

Improving the FreeBSD ModSecurity port

04 Mar 2014

The FreeBSD www/mod_security port currently does a fairly minimal install. It only installs the Apache module and an example file. Installing the ModSecurity port completely requires some manual steps. It might be a good time to give the port some love.

  • A default configuration file could be installed, rather than just providing a modsecurity.conf-example.
  • Starting users will be helped by enabling the Apache module and the CRS by default.
  • ModSecurity is generally used together with a companion project, the OWASP Core Rule Set (CRS), which supplies default policies and signatures. It seems in the distant past, it has been part of the port. The CRS master branch does not get frequent updates, so it could be included in the port, although it will increase the maintenance load.
  • nginx support would be very nice to have.

Some thoughts and questions

  1. Where and how to install the Apache configuration snippet? My Apache's modules.d directory always seems unused, but it looks like a good candidate. Current users might expect to get their ModSecurity completely unconfigured, so installing this snippet can depend on a port option APACHE_CONFIG. The other hand, the status quo is frustrating to new users (see ports/184181 for instance), and many other Apache module ports do just enable themselves in the Apache config, so the option might be enabled by default.
  2. Where to install the ModSecurity configuration files? There will be multiple config files. They are not necessarily tied to Apache, as in the future nginx might be supported too. Currently, an example file is put in etc. It seems best to me to create a directory, e.g. etc/modsecurity.
  3. How to install the ModSecurity main configuration file? I'd propose to install modsecurity.conf-example but also install it as modsecurity.conf, letting the user modify the last one. I expect almost all users to tweak this file, and I also expect it to be fairly stable across upgrades.
  4. I think almost all ModSecurity users also use the OWASP CRS. It would be worthwhile to automatically install the CRS, but likely it should be a port option, e.g. OWASP_CRS, as currently all users manage the rules themselves.
  5. nginx support would require some more experience with nginx; it seems better to first improve the port's current use case.


I gravitate toward installing functional configuration files, Apache modules.d snippet, and the CRS by default. This makes sure that new users can have a mostly 'instant-on' experience. (Note that the default configuration does not block requests yet; it detects attacks only, so it should not break Apache.) Meanwhile, current users should not be inconvenienced too much, so by unsetting options they can get the old behavior. For now, I propose:

  • to keep all configuration files in a modsecurity directory, which means that all configuration files would be installed under etc/modsecurity instead of etc from now on;
  • to install the recommended ModSecurity configuration file from the project as modsecurity.conf, in addition to the existing modsecurity.conf-example file;
  • to add a port option APACHE_CONFIG, enabled by default, which installs a 000_modsecurity.conf file under etc/apache2*/modules.d that loads the module and includes *.conf from the etc/modsecurity directory;
  • to add a port option OWASP_CRS, enabled by default, which installs a tested version of the OWASP CRS under etc/modsecurity/crs, installs a snippet etc/modsecurity/crs.conf and etc/modsecurity/crs.conf.sample which activates it in the configuration;
  • to add a notice in UPDATING about the new port options, and a hint to unset them in order to keep the old behavior;
  • to add a FreeBSD specific README in doc directory;
  • to display some basic hints and a pointer to the configuration files after port installation.

Supporting nginx will be left as work for a future update.