How to Create a Report Receiver API for the ModSecurity Rule Reports in WHM

How to Create a Report Receiver API for the ModSecurity Rule Reports in WHM

Overview

cPanel & WHM provides an API to transmit ModSecurity™ rule hits to a customizable URL. The report function allows rule distributors to receive feedback about problems that users encounter with their ModSecurity rules.

How to set the Report Receiver endpoint URL

Each vendor requires a metadata file. This file provides the information that the WHM API uses to identify the rules, where to download the rules, and the report URL.

How to implement a Report Receiver API endpoint

REQUEST

The report sender API provides the request data.

HTTP details
Path to API endpoint You can customize the endpoint URL to meet your individual needs.
Methods accepted POST
Request body Content-Type application/json
Body details
Input Type Description
hits array
meta_id integer The unique ID number, as the id action of the ModSecurity rule specifies it.
id integer The line number from the modsec database.
ip string The client’s source IP address.
http_version string The Hypertext Transfer Protocol (HTTP) version number.
meta_line integer The line number of the rule that generated the hit within the ModSecurity configuration file.
timestamp string The time of the hit.

Note:

This parameter uses the server’s configured time zone.

meta_uri string The client-requested URI.

Note:

This data is not always available.

http_method string The HTTP method that the client used to generate the hit.
http_status integer The HTTP status code that the web server returned.
timezone integer The server’s configured timezone as a number of minutes offset from Greenwich Mean Time (GMT).
meta_file string The file that contains the ModSecurity rule that generated the hit.
action_desc string The text that the web server posted to the client.
meta_logdata string The transaction data fragment from the ModSecurity rule’s logdata action.
path string The relative path to the virtual host’s document root.
host string The virtual host’s domain name.
handler string This parameter only returns null.
meta_offset integer The byte offset where a match occurred within the target data.

Note:

This data is not always available.

meta_rev integer The revision number from the ModSecurity rule’s rev action.
justification string The specific criteria from the ModSecurity rule that generated the hit.
meta_severity string The hit severity level from the ModSecurity rule’s severity action.
meta_msg string The human-readable message from the ModSecurity rule’s msg action.
file_exists Boolean If the value is 1, the file that the meta_file parameter lists exists. If the value is 0, the file does not exist.
email string The email address that the submitter providers for future contact with the rule maintainers.
type string The type of report.

Note:

This field has no specified format. You can treat the field as freeform text.

message string A short message from the submitter about the rule’s issue.
rule_text string The exact text of the rule at the time of submission.

Note:

You may encounter submissions of a report from an old hit, if the submission occurred after an update to the rule. Use the meta_rev field to track the rule revision that caused the problem.

RESPONSE

The report receiver API provides the response data.

HTTP details
Status The status must always use 200 on success.

Notes:

  • For any failure that still results in a JSON response, we recommend that you use a 200 status and the body to communicate the error. This status instructs the report sender API to attempt to parse the response.
  • For complete failure to use a relevant JSON response, use 4xx or 5xx error codes.
Reponse body Content-Type application/json
Body details
Output Type Details
status Boolean If the value is 1, the receiver accepted the report. If the value is 0, the receiver encountered an error.
error

(optional)

string A short message about the error.

Note:

This value is optional unless an error occurs.

Was this article helpful?

Related Articles

Leave A Comment?