Child pages
  • WHM API 1 Functions - modsec_report_rule
Skip to end of metadata
Go to start of metadata

Description

This function submits ModSecurity™ rule error reports to a remote receiver. The third party rule vendors use these error reports to identify problems with their rule sets.

Important:

In cPanel & WHM version 76, the WebServer role affects this function.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/modsec_report_rule?api.version=1&send=1&email=john.doe%40example.com&type=false%20positive&message=Hi.%20We%27re%20having%20some%20trouble%20with%20this%20rule.%20It%20seems%20to%20be%20blocking%20all%20requests.&row_ids=794828
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/modsec_report_rule?api.version=1&send=1&email=john.doe%40example.com&type=false%20positive&message=Hi.%20We%27re%20having%20some%20trouble%20with%20this%20rule.%20It%20seems%20to%20be%20blocking%20all%20requests.&row_ids=794828
 Command Line
whmapi1 modsec_report_rule send=1 email=john.doe%40example.com type=false positive message=\"Hi. We're having some trouble with this rule. It seems to be blocking all requests. row_ids=794828\"


Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/api/whmapi1

 Output (JSON)
{
    "data": {
        "report": {
            "email": "john.doe@example.com",
            "hits": [
                {
                    "meta_id": "12345694",
                    "ip": "10.215.215.236",
                    "http_version": "HTTP/1.1",
                    "meta_line": "1",
                    "timestamp": "2014-12-04 17:34:35",
                    "meta_uri": null,
                    "id": "794828",
                    "http_method": "GET",
                    "http_status": "406",
                    "timezone": "-360",
                    "meta_file": "/usr/local/apache/conf/modsec_vendor_configs/MyVendor/one.conf",
                    "action_desc": "Access denied with code 406 (phase 2).",
                    "meta_logdata": null,
                    "path": "/something",
                    "host": "xtext1.tld",
                    "handler": null,
                    "meta_offset": "0",
                    "meta_rev": null,
                    "justification": "Unconditional match in SecAction.",
                    "meta_severity": null,
                    "meta_msg": null
                }
            ],
            "rule_text": "SecAction \"deny,auditlog,id:'12345694'\"\n",
            "type": "false positive",
            "message": "Hi. We're having some trouble with this rule. It seems to be blocking all requests."
        }
    },
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": 1,
        "command": "modsec_report_rule"
    }
}
 Output (XML)
 <result>
    <data>
        <report>
            <email>john.doe@example.com</email>
            <hits>
                <meta_id>12345694</meta_id>
                <ip>10.215.215.236</ip>
                <http_version>HTTP/1.1</http_version>
                <meta_line>1</meta_line>
                <timestamp>2014-12-04 17:34:35</timestamp>
                <meta_uri/>
                <id>794828</id>
                <http_method>GET</http_method>
                <http_status>406</http_status>
                <timezone>-360</timezone>
                <meta_file>
/usr/local/apache/conf/modsec_vendor_configs/MyVendor/one.conf
</meta_file>
                <action_desc>Access denied with code 406 (phase 2).</action_desc>
                <meta_logdata/>
                <path>/something</path>
                <host>xtext1.tld</host>
                <handler/>
                <meta_offset>0</meta_offset>
                <meta_rev/>
                <justification>Unconditional match in SecAction.</justification>
                <meta_severity/>
                <meta_msg/>
            </hits>
            <rule_text>SecAction "deny,auditlog,id:'12345694'"</rule_text>
            <type>false positive</type>
            <message>
Hi. We're having some trouble with this rule. It seems to be blocking all requests.
</message>
        </report>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>modsec_report_rule</command>
    </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParametersTypeDescriptionPossible valuesExample
row_ids integer

Required

The MySQL® row IDs from the hits table in the modsec database for the audit log event to report.

A comma-separated list of positive integers.

Note:

If you specify more than one row ID:

  • You must comma-separate the rule IDs.
  • The IDs must all correspond to the same ModSecurity rule ID. 

794828

message string

Required

A short message that explains the reason for the report.

 

A valid string.

Note:

You should write this message.

 Click to view...

"Hi. We're having some trouble with this rule. It seems to be blocking all requests".

 

 

email string

Required

The contact email address to send with the error report, to allow the rule's vendor to reply to the user directly.

A valid email address.

john.doe@example.com

type string

Required

The report's type.

A valid string.

Note:

This value does not use a specified format. Treat the value as freeform text.

false positive

send Boolean

Required

Whether the function sends the report to the rule's vendor.

 

  • 1 — Send the report.
  • 0 — Do not send the report.
1

Returns

ReturnTypeDescriptionPossible valuesExample
reportarray of hashesAn array of hashes of information for the report that the function sends, or would send if you set the send value to 1 .

Each hash includes the email, rule_text, type, and message returns and the hits array.

 

email

string

The contact email address to send with the error report, to allow the rule's vendor to reply to the report directly.

The function returns this value in the report array.

A valid email address.

john.doe@example.com  

hits

array

An array that contains information about the hit.

The function returns this array in the report array.

This array includes the meta_id, id, ip, http_version, meta_line, timestamp, meta_uri, http_method, http_status, timezone, meta_file, action_desc, meta_logdata, path, host, handler, meta_offset, meta_rev, justification, meta_severity, and meta_msg returns.

 

meta_id

integer

The ID of the ModSecurity rule that triggered the log entry.

The function returns this value in the hits array.

A valid ModSecurity ID.
12345694

id

integer

The modsec database line number.

The function returns this value in the hits array. 

A positive integer.794828

ip

integer

The client's IP address.

The function returns this value in the hits array. 

A valid IP address.
10.215.215.236

http_version

string

The HTTP version number.

The function returns this value in the hits array. 

A valid string.
HTTP/1.1

meta_line

integer

The line number of the ModSecurity rule that triggered the log entry.

The function returns this value in the hits array. 

A positive integer.1

timestamp

string

The time at which the log entry was made.

The function returns this value in the hits array. 

A valid date in YYYY-MM-DD HH:mm:SS format:

  • YYYY represents the year
  • MM represents the month
  • DD represents the day
  • HH represents the hour
  • mm represents the minute
  • DD represents the day.

Note:

This parameter uses the server's configured time zone.

2014-10-13 07:58:04

meta_uri

string

The client-requested URI.

The function returns this value in the hits array. 

A valid URI.

Note:

This data is not always available.

null

http_method

string

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

The function returns this parameter in the hits array. 

A valid HTTP method.GET

http_status

integer

The HTTP status code that the web server returned.

The function returns this value in the hits array. 

A valid HTTP status code.406

timezone

integer

The server's configured timezone.

The function returns this value in the hits array. 

A valid timezone bias, in minutes difference from UTC/GMT.

-300

meta_file

string

The ModSecurity configuration file that contains the rule that triggered the log entry.

The function returns this value in the hits array. 

A valid file path and name.
 Click to view...

/usr/local/apache/conf/modsec_vendor_configs/MyVendor/one.conf

action_desc

string

The web server's response to the client.

The function returns this value in the hits array. 

A valid string.
 Click to view...

Access denied with code 406 (phase 2).

meta_logdata

string

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

The function returns this value in the hits array. 

A valid string.null

path

string

The accessed file's path.

The function returns this value in the hits array. 

A valid file path and name, relative to the document root.

/something

host

string

The virtual host's domain name.

The function returns this value in the hits array. 

A valid hostname.xtest1.tld

handler

string

This parameter only returns null.

The function returns this value in the hits array. 

null

null

meta_offset

integer

The byte offset at which a match occurred within the target data.

The function returns this value in the hits array. 

A valid integer.

Note:

This data is not always available.

 0

meta_rev

integer

The revision number from the ModSecurity rule's rev action.

The function returns this value in the hits array. 

A positive integer. 1

justification

string

The specific criteria from the ModSecurity rule that generated the hit.

The function returns this value in the hits array. 

A valid string.
 Click to view...

Unconditional match in SecAction.

meta_severity

string

The hit severity level from the ModSecurity rule's severity action.

The function returns this value in the hits array. 

A valid string.CRITICAL

meta_msg

string

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

The function returns this value in the hits array. 

A valid string.
 Click to view...

Method is not allowed by policy

rule_text

string

The rule text from the configuration file.

The function returns this value in the report array.

A valid string.

deny,auditlog,id:'12345694'\"\n

type

string

The report's type.

The function returns this value in the report array.

A valid string.

Note:

This value does not use a specified format. Treat the value as freeform text.

false positive

message

string

A short message that explains the reason for the report.

The function returns this value in the report array.

A valid string.
 Click to view...

Hi. We're having some trouble with this rule. It seems to be blocking all requests.