Page tree
Skip to end of metadata
Go to start of metadata

Overview

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

Note:

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

How to 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.

Notes:

  • The metadata file uses the YAML format.
  • The filename must use the prefix "meta_".
  • The filename must match you vendor's unique short name (vendor_id).
  • The filename must end with the . yaml file extension.
  • You must make the file available for the system to download file over a secure (HTTPS) connection.

Attributes

A vendor's metadata file contains the following attributes:

NameTypeDescriptionExample

#.#.#

(ModSecurity version)

 

hash

A hash that contains the information that identifies the archive.

Notes:

  • This key changes based on the ModSecurirty 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

SHA512string

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

string

The distribution's unique identifier.

Note:

  • Two different versions of the same rule set cannot share the same distribution identifier.
  • You must use a different unique identifier for each version of the ruleset.
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
attributeshash

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 How to Create a Report Receiver API for the ModSecurity Rule Reports documentation.

https://server.example.com/report

File examples

Note:

The WHM API 1 - WHM API 1 Functions - modsec_add_vendor API function accepts a single URL that contains all the information necessary to install a new vendor rule set.

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

Note:

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

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

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

    Note:

    For more information about the vendor_id parameter, read our WHM API 1 Functions - modsec_add_vendor documentation.

Create the rule set package

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:

[root@server:~]#md5sum myvendor001.zip 
02e20c3e46431cff58b84137d801d4f0 myvendor001.zip

Additional documentation