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

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. For more information to set the Report Receiver endpoint URL, read our How to Create a ModSecurity Vendor documentation.

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

Input

TypeDescription
hitsarray 

meta_id

integerThe unique ID number, as the id action of the ModSecurity rule specifies it.

id

integer

The line number from the modsec database.

ip

stringThe client's source IP address.

http_version

stringThe Hypertext Transfer Protocol (HTTP) version number.

meta_line

integerThe 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

stringThe HTTP method that the client used to generate the hit.

http_status

integerThe HTTP status code that the web server returned.

timezone

integerThe server's configured timezone as a number of minutes offset from Greenwich Mean Time (GMT).

meta_file

stringThe 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

stringThe transaction data fragment from the ModSecurity rule's logdata action.

path

stringThe relative path to the virtual host's document root.

host

stringThe 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

integerThe 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

stringThe human-readable message from the ModSecurity rule's msg action.

file_exists

BooleanIf 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.
typestring

The 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_textstring

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-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)

string

A short message about the error.

Note:

This value is optional unless an error occurs.

Additional documentation