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

Description

This function adds a new rule to a ModSecurity™ configuration staging file. For example, if you choose to add a rule for the example.conf file, the function stages the rule in the example.conf.STAGE file.

Important:

This function does not actually deploy the rule. 

Important:

In cPanel & WHM version 76 and later, when you disable the WebServer role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/modsec_add_rule?api.version=1&rule=SecAction%22pass%2Cauditlog%2Cid%3A1234567'%2Cmsg%3A'Example%20rule%20message'%22&config=modsec_vendor_configs%2Fexample.conf
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/modsec_add_rule?api.version=1&rule=SecAction%22pass%2Cauditlog%2Cid%3A1234567'%2Cmsg%3A'Example%20rule%20message'%22&config=modsec_vendor_configs%2Fexample.conf
 Command Line
whmapi1 modsec_add_rule rule=SecAction\"pass,auditlog,id:1234567',msg:'Example rule message'\" config=modsec_vendor_configs%2Fexample.conf


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/whmapi1

 Output (JSON)
{
    "data": {
        "rule": {
            "disabled": 0,
            "rule": "SecAction "pass,auditlog,id:1234567',msg:'Example rule message'"",
            "id": "1234567",
            "meta_msg": "Example rule message"
        }
    },
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": 1,
        "command": "modsec_add_rule"
    }
}
 Output (XML)
<result>
  <data>
    <name>rule</name>
    <disabled>0</disabled>
    <id>1234567</id>
    <meta_msg>Example rule message</meta_msg>
    <rule>SecAction &quot;pass,auditlog,id:1234567',msg:'Example rule message'&quot;</rule>
  </data>
  <metadata>
    <command>modsec_add_rule</command>
    <reason>OK</reason>
    <result>1</result>
    <version>1</version>
  </metadata>
</result>


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
configstring

Required

The ModSecurity configuration file.

The path to a ModSecurity rule .conf file, relative to the /usr/local/apache/conf/ directory.
modsec_vendor_configs/example.conf
rulestring

Required

The rule's text.

A valid ModSecurity rule or set of rules.

Note:

If you provide multiple directives in the same rule, use only one ModSecurity rule ID.

 Click to view...

SecAction "pass,auditlog,id:1234567',msg:'Example rule message'"

Returns

ReturnTypeDescriptionPossible valuesExample
rulehashA hash that contains information about the new ModSecurity rule.This hash includes the id, rule, disabled, meta_msg, and duplicate returns. 

id

integer

The ModSecurity rule's ID.

The function returns this value in the rule hash.

 A valid ModSecurity rule ID.
1234567

rule

string

The ModSecurity rule's text.

The function returns this value in the rule hash.

 A valid ModSecurity rule.
 Click to view...

SecAction "pass,auditlog,id:1234567',msg:'Example rule message'"

disabled

Boolean

Whether the rule is disabled.

The function returns this value in the rule hash.

  • 1 — Disabled.
  • 0 — Enabled.
0

meta_msg

string

The ModSecurity rule's description.

The function returns this value in the rule hash.

A valid string.
Example rule message

duplicate

Boolean

Whether the rule already exists in the ModSecurity configuration staging file.

The function returns this value in the rule hash.

  • 1 — Exists.
  • 0 — Does not exist.
0