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 1 to identify its rules and where to download them. This file allows the WHM API 1 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