Child pages
  • Tutorial - Create a ModSecurity Vendor
Skip to end of metadata
Go to start of metadata

Introduction

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

Note:

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

Create 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.

Note:

  • The metadata file uses the YAML format.
  • The filename must use the meta_ prefix and the .yaml file extension, and must match you 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:

 Click to view...
NameTypeDescriptionExample

#.#.#

(ModSecurity version)

 

hash

A hash that contains the information that identifies the archive.

Notes:

  • 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.

Note:

The MD5 attribute is required for compatibility with cPanel & WHM version 11.48 and earlier.

 Click to view...

MD5: 3f4d0cc23dd1146c1c29772b70500276

SHA512

string

The SHA512 checksum of the download.

Note:

The SHA512 attribute is required for compatibility with cPanel & WHM version 11.50 and later.

 Click to view...

SHA512: 85d18c74aa2b009f77be481d2cee6c71ca51c53a49d9c9be5e14f5b9c16341c6d0ebdeff58481d9efa763ba1e09027419ffd70c4e35a8af61326692c5bf9aee6

distribution

stringThe distribution's unique identifier.distribution: myvendor-1

url

string

The URL to the archive that contains the rules.

Notes:

  • 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

stringThe description of the vendor rule set.This setting allows you to define the match limit of the PCRE library.

name

stringThe vendor's name.My Vendor

vendor_url

stringThe 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 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.

 Click to view...
FileExample

Single version

meta_myvendor.yaml

---
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: http://www.example.com/
  report_url: http://www.example.com/report
Multiple versions

meta_myvendor.yaml

---
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: http://www.example.com/
  report_url: http://www.example.com/report

Create the vendor rule set package

Important:

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. For more information about the vendor_id parameter, read our WHM API 1 modsec_add_vendor function documentation.


Note:

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

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

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