We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

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. To deploy the rule, use the WHM API 1 Functions - modsec_deploy_all_rule_changes function. 

Important:

In cPanel & WHM version 76 and later, when you disable the Web Server role, the system disables this function.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/modsec_add_rule?api.version=1&rule=SecAction%20%22phase%3A1%2Cid%3A168%2Cnolog%2Cpass%2Csetvar%3Atx.REMOTE_ADDR%3D%2F%25%7BREMOTE_ADDR%7D%2F%22&config=%2Fmodsec%2Fmodsec2.user.conf
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/modsec_add_rule?api.version=1&rule=SecAction%20%22phase%3A1%2Cid%3A168%2Cnolog%2Cpass%2Csetvar%3Atx.REMOTE_ADDR%3D%2F%25%7BREMOTE_ADDR%7D%2F%22&config=%2Fmodsec%2Fmodsec2.user.conf
 Command Line
whmapi1 modsec_add_rule rule=SecAction%22pass%2Cauditlog%2Cid%3A1234567'%2Cmsg%3A'Example%20rule%20message'%22&config=modsec_vendor_configs%2Fexample.conf


Notes:

  • Unless otherwise noted, 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)
{
	"metadata": {
		"version": 1,
		"command": "modsec_add_rule",
		"reason": "OK",
		"result": 1
	},
	"data": {
		"rule": {
			"config": "/modsec/modsec2.user.conf",
			"rule": "SecAction \"phase:1,id:11234,nolog,pass,setvar:tx.REMOTE_ADDR=/%{REMOTE_ADDR}/\"",
			"disabled": 0,
			"id": "11234",
			"staged": 1,
			"meta_msg": "Example rule message",
			"vendor_active": 0,
			"vendor_id": "",
			"config_active": 0
		}
	}
}
 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 /etc/apache/conf.d/ 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 \"phase:1,id:168,nolog,pass,setvar:tx.REMOTE_ADDR=/%{REMOTE_ADDR}/\"

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.
168

rule

string

The ModSecurity rule's text.

The function returns this value in the rule hash.

 A valid ModSecurity rule.
 Click to view...

SecAction \"phase:1,id:168,nolog,pass,setvar:tx.REMOTE_ADDR=/%{REMOTE_ADDR}/\"

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