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

Description

This function retrieves the ModSecurity™ rules from one or more ModSecurity configuration files.

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_get_rules?api.version=1&vendor_id=SomeVendor
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/modsec_get_rules?api.version=1&vendor_id=SomeVendor
 Command Line
whmapi1 modsec_get_rules vendor_id=SomeVendor


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": {
        "chunks": [
            {
                "disabled": 0,
                "vendor_id": "SomeVendor",
                "vendor_active": "0",
                "rule": "SecRule REQUEST_FILENAME \"config\" \"deny,id:662452,msg:'Denied dangerous config traffic',severity:1,auditlog\"\n",
                "config_active": "0",
                "staged": 0,
                "id": "662452",
                "config": "modsec_vendor_configs/SomeVendor/config.conf",
                "meta_msg": "Denied dangerous config traffic"
            },
            {
                "disabled": 0,
                "vendor_id": "SomeVendor",
                "vendor_active": "0",
                "rule": "SecRule REQUEST_FILENAME \"config\" \"deny,id:662452,msg:'Denied dangerous config traffic',severity:1,auditlog\"\n",
                "config_active": "0",
                "staged": 0,
                "id": "662452",
                "config": "modsec_vendor_configs/SomeVendor/config.conf",
                "meta_msg": "Denied dangerous config traffic"
            },
            {
                "disabled": 0,
                "vendor_id": "SomeVendor",
                "vendor_active": "0",
                "rule": "SecRule REQUEST_FILENAME \"banana\" \"deny,id:93213,msg:'Denied dangerous banana traffic',severity:1,auditlog\"\n",
                "config_active": "0",
                "staged": 0,
                "id": "93213",
                "config": "modsec_vendor_configs/SomeVendor/banana.conf",
                "meta_msg": "Denied dangerous banana traffic"
            }
        ],
        "staged_changes": 0
    },
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": 1,
        "command": "modsec_get_rules"
    }
}
 Output (XML)
<result>
   <data>
      <chunks>
         <element>
            <config>modsec_vendor_configs/SomeVendor/config.conf</config>
            <config_active>0</config_active>
            <disabled>0</disabled>
            <id>662452</id>
            <meta_msg>Denied dangerous config traffic</meta_msg>
            <rule>SecRule REQUEST_FILENAME "config" "deny,id:662452,msg:'Denied dangerous config traffic',severity:1,auditlog"</rule>
            <staged>0</staged>
            <vendor_active>0</vendor_active>
            <vendor_id>SomeVendor</vendor_id>
         </element>
         <element>
            <config>modsec_vendor_configs/SomeVendor/config.conf</config>
            <config_active>0</config_active>
            <disabled>0</disabled>
            <id>662452</id>
            <meta_msg>Denied dangerous config traffic</meta_msg>
            <rule>SecRule REQUEST_FILENAME "config" "deny,id:662452,msg:'Denied dangerous config traffic',severity:1,auditlog"</rule>
            <staged>0</staged>
            <vendor_active>0</vendor_active>
            <vendor_id>SomeVendor</vendor_id>
         </element>
         <element>
            <config>modsec_vendor_configs/SomeVendor/banana.conf</config>
            <config_active>0</config_active>
            <disabled>0</disabled>
            <id>93213</id>
            <meta_msg>Denied dangerous banana traffic</meta_msg>
            <rule>SecRule REQUEST_FILENAME "banana" "deny,id:93213,msg:'Denied dangerous banana traffic',severity:1,auditlog"</rule>
            <staged>0</staged>
            <vendor_active>0</vendor_active>
            <vendor_id>SomeVendor</vendor_id>
         </element>
      </chunks>
      <staged_changes>0</staged_changes>
   </data>
   <metadata>
      <command>modsec_get_rules</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

Note:

You must include either the vendor_id or the config parameters.

ParameterTypeDescriptionPossible valuesExample
vendor_idstring

The vendor's unique short name.

 

A valid string.

Note:

You can use a comma-delimited list of multiple vendors.

SomeVendor, Anothervendor
configstring

The file path to the configuration file.

 

A valid path, relative to the /usr/local/apache/conf/ directory.

Note:

You can use a comma-delimited list of multiple configuration files.

 Click to view...

modsec_vendor_configs/SomeVendor/config.conf, modsec_vendor_configs/Anothervendor/config.conf

exclude_other_directivesBoolean

Whether the function only returns the SecRule and SecAction directives from the configuration file, and comments that are not associated with a rule.

This parameter's value defaults to 1.

  • 1 — Only returns SecRule and SecAction directives and comments that are not associated with a rule.
  • 0 — Returns all directives and comments.
1
exclude_bare_commentsBoolean

Whether to exclude comments that are not associated with any directives.

This parameter's value defaults to 1.

  • 1 — Exclude.
  • 0 — Do not exclude.
1  

Returns

ReturnTypeDescriptionPossible valuesExample
chunksarray of hashesAn array of hashes that contains elements that represent the contents of each configuration file's rules.Each hash includes the disabled, vendor_id, vendor_active, rule, config_active, staged, id, config, and  meta_msg returns. 

disabled

Boolean

Whether the rule is active.

The function returns this value in the chunks array.

  • 1 — Not Active.
  • 0 — Active.
0

vendor_id

string

The vendor's unique short name.

The function returns this value in the chunks array.

A valid string.SomeVendor

vendor_active

Boolean

Whether the vendor is active.

This functions return this value in the chunks array.

  • 1 — Active.
  • 0 — Not active.

0

rule

string

The rule's text.

This functions return this value in the chunks array.

A valid string.

Note:

This return may include multiple directives and comments if they are all part of the same rule.

 Click to view...

SecRule REQUEST_FILENAME "config" "deny,id:662452,msg:'Denied dangerous config traffic',severity:1,auditlog" 

config_active

Boolean

Whether the configuration file is active.

The function returns this value in the chunks array.

  • 1 — Active.
  • 0 — Not active.
0

staged

Boolean

Whether the system has added the rule to the ModSecurity configuration file.

The function returns this value in the chunks array.

  • 1 — Rule staged.
  • 0 — Rule not staged.
0

id

integer

The ModSecurity rule's ID number.

Note:

The function does not always return this parameter.

The function returns this value in the chunks array.

A positive integer.662452

config

string

The file path to the configuration file.

The function returns this value in the chunks array.

A valid path, relative to the /usr/local/apache/conf/ directory.
 Click to view...

modsec_vendor_configs/SomeVendor/config.conf

 

 

meta_msg

string

The description of the rule.

The function returns this parameter in the chunks array.

A valid string.
 Click to view...

Denied dangerous config traffic

staged_changesBooleanWhether the chunks array includes staged changes that the system has not yet added to the ModSecurity configuration file.
  • 1 — Staged changes in output.
  • 0 — No staged changes in output.
0