Development Guides Home >> Quickstart Development Guide

Tutorial - Create a ModSecurity Vendor

Introduction

This tutorial describes how to create a custom ModSecurity® vendor. To install ModSecurity rules, read our ModSecurity Tools documentation.

WHM's ModSecurity Vendors interface (WHM >> Home >> Security Center >> ModSecurity™ Vendors) provides the ability to install third-party ModSecurity rules as a vendor.

Create the vendor metadata file

Each vendor requires a metadata file that provides the information for the WHM API to identify its rules and where to download them. This file allows the WHM API to accept a single URL that contains all information necessary to install a new vendor rule set.

  • The metadata file uses the YAML format.
  • The filename must use the meta_ prefix and the .yaml file extension. ModSecurity uses the filename for your vendor's unique short name (vendor_id).
  • You must ensure that the file is available for the system to download file over a secure (HTTPS) connection.

A vendor's metadata file contains the following attributes:

Name Type Description Example
#.#.# (ModSecurity version) hash A hash that contains the information that identifies the archive.
  • This key changes based on the ModSecurity version for which this rule set applies.
  • This attribute allows you to provide multiple versions of rule sets for backwards compatibility.
  • You should keep a separate entry for each version of ModSecurity that you intend to support.
  • If you only intend to support a single version of ModSecurity, keep a single entry for that version.
This hash includes the md5, SHA512, distribution and url attributes.
     MD5 string The download's MD5 checksum. MD5: 3f4d0cc23dd1146c1c29772b70500276
     SHA512 string The SHA512 checksum of the download. SHA512: 85d18c74aa2b009f77be481d2cee6c71ca51c53a49d9c9be5e14f5b9c16341c6d0ebdeff58481d9efa763ba1e09027419ffd70c4e35a8af61326692c5bf9aee6
    distribution string The distribution's unique identifier. distribution: myvendor-1
    url string The URL to the archive that contains the rules.
  • The URL must point to a .zip file.
  • The .zip file must extract as a single directory whose name matches your vendor's vendor_id short name.
https://www.example.com/myvendor000.zip
attributes hash A hash of vendor identity information This hash contains the description , name , vendor_url , and report attributes.
    description string The description of the vendor rule set. This setting allows you to define the match limit of the PCRE library.
    name string The vendor's name. My Vendor
    vendor_url string The URL of the vendor's website. https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit
    report_url string Optional
The URL to a Report Receiver API endpoint.
For more information, read our Guide to Report Receiver APIs for the ModSecurity Rule Reports documentation.
https://server.example.com/report

A complete vendor metadata file (for example, meta_myvendor.yaml) will resemble one of the following examples:

Note:

WHM API 1's modsec_add_vendor function accepts a single URL that contains all of the necessary information to install a new vendor rule set.


Single version

---
2.8.0:
  MD5: 3f4d0cc23dd1146c1c29772b70500276
  distribution: myvendor-1
  url: https://www.example.com/myvendor001.zip
attributes:
  description: 'Here is an extended description of the vendor rule set called YourVendor.'
  name: 'Example ModSecurity Rule Set'
  vendor_url: https://www.example.com/
  report_url: https://www.example.com/report

Multiple versions

---
2.8.0:
  MD5: b7aaafc6d138a5bb62117a7844c75554
  distribution: myvendor-1
  url: https://www.example.com/myvendor001.zip
2.7.7:
  MD5: 1f9ab3b68b9d87283e0bc33d16663459
  distribution: myvendor-0
  url: https://www.example.com/myvendor000.zip
attributes:
  description: 'Here is an extended description of the vendor rule set called YourVendor.'
  name: 'Example ModSecurity Rule Set'
  vendor_url: https://www.example.com/
  report_url: https://www.example.com/report

Create the vendor rule set package

When you create the vendor rule set package, the package must meet the following requirements of WHM's ModSecurity API:

  • The rule set package must exist as a .zip file.
  • The rule set package must unzip as a directory. The name directory must match your vendor's vendor_id short name.

To create the vender's rule set package, run the following commands as the root user:

zip -r myvendor001.zip myvendor001
llh myvendor001.zip

The output from these commands will resemble the following example:

[root@server:~]#zip -r myvendor001.zip myvendor001
  adding: myvendor001/ (stored 0%)
  adding: myvendor001/myvendor001.conf (stored 0%)
[root@server:~]#llh myvendor001.zip
-rw-r--r--. 1 root root 342 Sep 24 14:57 myvendor001.zip

For information on how to create your own ModSecurity rules, read the ModSecurity Reference Manual.

Identify your rule set package's MD5 checksum

To identify the .zip file's MD5 checksum, run the following command as the root user:

md5sum myvendor001.zip
02e20c3e46431cff58b84137d801d4f0 myvendor001.zip