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 endpointYou can customize the endpoint URL to meet your individual needs.
Methods acceptedPOST
Request body Content-Typeapplication/json
Body details
InputTypeDescription
hitsarray
meta_idintegerThe unique ID number, as the id action of the ModSecurity rule specifies it.
idintegerThe line number from the modsec database.
ipstringThe client’s source IP address.
http_versionstringThe Hypertext Transfer Protocol (HTTP) version number.
meta_lineintegerThe line number of the rule that generated the hit within the ModSecurity configuration file.
timestampstringThe time of the hit.

Note:

This parameter uses the server’s configured time zone.

meta_uristringThe client-requested URI.

Note:

This data is not always available.

http_methodstringThe HTTP method that the client used to generate the hit.
http_statusintegerThe HTTP status code that the web server returned.
timezoneintegerThe server’s configured timezone as a number of minutes offset from Greenwich Mean Time (GMT).
meta_filestringThe file that contains the ModSecurity rule that generated the hit.
action_descstringThe text that the web server posted to the client.
meta_logdatastringThe transaction data fragment from the ModSecurity rule’s logdata action.
pathstringThe relative path to the virtual host’s document root.
hoststringThe virtual host’s domain name.
handlerstringThis parameter only returns null.
meta_offsetintegerThe byte offset where a match occurred within the target data.

Note:

This data is not always available.

meta_revintegerThe revision number from the ModSecurity rule’s rev action.
justificationstringThe specific criteria from the ModSecurity rule that generated the hit.
meta_severitystringThe hit severity level from the ModSecurity rule’s severity action.
meta_msgstringThe human-readable message from the ModSecurity rule’s msg action.
file_existsBooleanIf the value is 1, the file that the meta_file parameter lists exists. If the value is 0, the file does not exist.
emailstringThe email address that the submitter providers for future contact with the rule maintainers.
typestringThe type of report.

Note:

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

messagestringA short message from the submitter about the rule’s issue.
rule_textstringThe 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
StatusThe 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-Typeapplication/json
Body details
OutputTypeDetails
statusBooleanIf the value is 1, the receiver accepted the report. If the value is 0, the receiver encountered an error.
error

(optional)

stringA short message about the error.

Note:

This value is optional unless an error occurs.

Was this article helpful?

Related Articles

Leave A Comment?

You must be logged in to post a comment.