You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

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

Description

This function retrieves the server's ModSecurity™ configuration settings. The system stores these settings in the /usr/local/apache/conf/modsec2.conf file.

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


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":{  
      "command":"modsec_get_settings",
      "reason":"OK",
      "result":1,
      "version":1
   },
   "data":{  
      "settings":[  
         {  
            "type":"radio",
            "directive":"SecAuditEngine",
            "description":"This setting controls the behavior of the audit engine.",
            "engine":1,
            "default":"Off",
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secauditengine",
            "setting_id":0,
            "name":"Audit Log Level",
            "state":"",
            "radio_options":[  
               {  
                  "name":"Log all transactions.",
                  "option":"On"
               },
               {  
                  "name":"Do not log any transactions.",
                  "option":"Off"
               },
               {  
                  "option":"RelevantOnly",
                  "name":"Only log noteworthy transactions."
               }
            ],
            "missing":1
         },
         {  
            "description":"This setting controls the behavior of the connections engine.",
            "engine":1,
            "default":"Off",
            "type":"radio",
            "directive":"SecConnEngine",
            "missing":1,
            "setting_id":1,
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secconnengine",
            "state":"",
            "name":"Connections Engine",
            "radio_options":[  
               {  
                  "option":"On",
                  "name":"Process the rules."
               },
               {  
                  "option":"Off",
                  "name":"Do not process the rules."
               },
               {  
                  "option":"DetectionOnly",
                  "name":"Process the rules in verbose mode, but do not execute disruptive actions."
               }
            ]
         },
         {  
            "missing":1,
            "name":"Rules Engine",
            "state":"",
            "radio_options":[  
               {  
                  "name":"Process the rules.",
                  "option":"On"
               },
               {  
                  "name":"Do not process the rules.",
                  "option":"Off"
               },
               {  
                  "name":"Process the rules in verbose mode, but do not execute disruptive actions.",
                  "option":"DetectionOnly"
               }
            ],
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secruleengine",
            "setting_id":2,
            "engine":1,
            "default":"Off",
            "description":"This setting controls the behavior of the rules engine.",
            "type":"radio",
            "directive":"SecRuleEngine"
         },
         {  
            "description":"Disables backend compression while leaving the frontend compression enabled.",
            "default":"Off",
            "type":"radio",
            "directive":"SecDisableBackendCompression",
            "missing":1,
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secdisablebackendcompression",
            "setting_id":3,
            "name":"Backend Compression",
            "state":"",
            "radio_options":[  
               {  
                  "name":"Disabled",
                  "option":"On"
               },
               {  
                  "name":"Enabled",
                  "option":"Off"
               }
            ]
         },
         {  
            "missing":1,
            "validation":[  
               "path"
            ],
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secgeolookupdb",
            "setting_id":4,
            "name":"Geolocation Database",
            "state":"",
            "description":"Specify a path for the geolocation database.",
            "directive":"SecGeoLookupDb",
            "type":"text"
         },
         {  
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secgsblookupdb",
            "setting_id":5,
            "state":"",
            "name":"Google Safe Browsing Database",
            "missing":1,
            "validation":[  
               "path"
            ],
            "directive":"SecGsbLookupDb",
            "type":"text",
            "description":"Specify a path for the Google Safe Browsing Database."
         },
         {  
            "validation":[  
               {  
                  "name":"startsWith",
                  "arg":"[|]"
               },
               "path"
            ],
            "missing":1,
            "state":"",
            "name":"Guardian Log",
            "setting_id":6,
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secguardianlog",
            "description":"Specify an external program to pipe transaction log information to for additional analysis. The syntax is analogous to the .forward file, in which a pipe at the beginning of the field indicates piping to an external program.",
            "type":"text",
            "directive":"SecGuardianLog"
         },
         {  
            "description":"Specify a Project Honey Pot API Key for use with the @rbl operator.",
            "type":"text",
            "directive":"SecHttpBlKey",
            "validation":[  
               "honeypotAccessKey"
            ],
            "missing":1,
            "state":"",
            "name":"Project Honey Pot Http:BL API Key",
            "setting_id":7,
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#sechttpblkey"
         },
         {  
            "directive":"SecPcreMatchLimit",
            "type":"number",
            "default":1500,
            "description":"Define the match limit of the Perl Compatible Regular Expressions library.",
            "name":"Perl Compatible Regular Expressions Library Match Limit",
            "state":"",
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit",
            "setting_id":8,
            "missing":1,
            "validation":[  
               "positiveInteger"
            ]
         },
         {  
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimitrecursion",
            "setting_id":9,
            "state":"",
            "name":"Perl Compatible Regular Expressions Library Match Limit Recursion",
            "missing":1,
            "validation":[  
               "positiveInteger"
            ],
            "directive":"SecPcreMatchLimitRecursion",
            "type":"number",
            "description":"Define the match limit recursion of the Perl Compatible Regular Expressions library.",
            "default":1500
         }
      ]
   }
}
 Output (XML)
<result>
    <metadata>
        <version>1</version>
        <result>1</result>
        <reason>OK</reason>
        <command>modsec_get_settings</command>
    </metadata>
    <data>
        <settings>
            <directive>SecAuditEngine</directive>
            <missing>1</missing>
            <default>Off</default>
            <engine>1</engine>
            <description>
                This setting controls the behavior of the audit engine.
            </description>
            <state/>
            <type>radio</type>
            <setting_id>0</setting_id>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secauditengine
            </url>
            <name>Audit Log Level</name>
            <radio_options>
                <name>Log all transactions.</name>
                <option>On</option>
            </radio_options>
            <radio_options>
                <name>Do not log any transactions.</name>
                <option>Off</option>
            </radio_options>
            <radio_options>
                <name>Only log noteworthy transactions.</name>
                <option>RelevantOnly</option>
            </radio_options>
        </settings>
        <settings>
            <name>Connections Engine</name>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secconnengine
            </url>
            <setting_id>1</setting_id>
            <radio_options>
                <option>On</option>
                <name>Process the rules.</name>
            </radio_options>
            <radio_options>
                <name>Do not process the rules.</name>
                <option>Off</option>
            </radio_options>
            <radio_options>
                <name>
                    Process the rules in verbose mode, but do not execute disruptive actions.
                </name>
                <option>DetectionOnly</option>
            </radio_options>
            <directive>SecConnEngine</directive>
            <description>
                This setting controls the behavior of the connections engine.
            </description>
            <missing>1</missing>
            <engine>1</engine>
            <default>Off</default>
            <type>radio</type>
            <state/>
        </settings>
        <settings>
            <radio_options>
                <option>On</option>
                <name>Process the rules.</name>
            </radio_options>
            <radio_options>
                <option>Off</option>
                <name>Do not process the rules.</name>
            </radio_options>
            <radio_options>
                <name>
                    Process the rules in verbose mode, but do not execute disruptive actions.
                </name>
                <option>DetectionOnly</option>
            </radio_options>
            <setting_id>2</setting_id>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secruleengine
            </url>
            <name>Rules Engine</name>
            <state/>
            <type>radio</type>
            <engine>1</engine>
            <missing>1</missing>
            <default>Off</default>
            <description>
                This setting controls the behavior of the rules engine.
            </description>
            <directive>SecRuleEngine</directive>
        </settings>
        <settings>
            <type>radio</type>
            <state/>
            <directive>SecDisableBackendCompression</directive>
            <description>
                Disables backend compression while leaving the frontend compression enabled.
            </description>
            <default>Off</default>
            <missing>1</missing>
            <name>Backend Compression</name>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secdisablebackendcompression
            </url>
            <setting_id>3</setting_id>
            <radio_options>
                <option>On</option>
                <name>Disabled</name>
            </radio_options>
            <radio_options>
                <name>Enabled</name>
                <option>Off</option>
            </radio_options>
        </settings>
        <settings>
            <name>Geolocation Database</name>
            <setting_id>4</setting_id>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secgeolookupdb
            </url>
            <type>text</type>
            <state/>
            <validation>path</validation>
            <directive>SecGeoLookupDb</directive>
            <description>Specify a path for the geolocation database.</description>
            <missing>1</missing>
        </settings>
        <settings>
            <setting_id>5</setting_id>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secgsblookupdb
            </url>
            <name>Google Safe Browsing Database</name>
            <directive>SecGsbLookupDb</directive>
            <missing>1</missing>
            <description>
                Specify a path for the Google Safe Browsing Database.
            </description>
            <state/>
            <type>text</type>
            <validation>path</validation>
        </settings>
        <settings>
            <state/>
            <type>text</type>
            <validation>
                <arg>[|]</arg>
                <name>startsWith</name>
            </validation>
            <validation>path</validation>
            <directive>SecGuardianLog</directive>
            <missing>1</missing>
            <description>
                Specify an external program to pipe transaction log information to for additional analysis. The syntax is analogous to the .forward file, in which a pipe at the beginning of the field indicates piping to an external program.
            </description>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secguardianlog
            </url>
            <setting_id>6</setting_id>
            <name>Guardian Log</name>
        </settings>
        <settings>
            <setting_id>7</setting_id>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#sechttpblkey
            </url>
            <name>Project Honey Pot Http:BL API Key</name>
            <missing>1</missing>
            <description>
                Specify a Project Honey Pot API Key for use with the @rbl operator.
            </description>
            <directive>SecHttpBlKey</directive>
            <validation>honeypotAccessKey</validation>
            <state/>
            <type>text</type>
        </settings>
        <settings>
            <name>
                Perl Compatible Regular Expressions Library Match Limit
            </name>
            <setting_id>8</setting_id>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit
            </url>
            <type>number</type>
            <state/>
            <validation>positiveInteger</validation>
            <directive>SecPcreMatchLimit</directive>
            <description>
                Define the match limit of the Perl Compatible Regular Expressions library.
            </description>
            <missing>1</missing>
            <default>1500</default>
        </settings>
        <settings>
            <name>
                Perl Compatible Regular Expressions Library Match Limit Recursion
            </name>
            <setting_id>9</setting_id>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimitrecursion
            </url>
            <directive>SecPcreMatchLimitRecursion</directive>
            <description>
                Define the match limit recursion of the Perl Compatible Regular Expressions library.
            </description>
            <default>1500</default>
            <missing>1</missing>
            <type>number</type>
            <state/>
            <validation>positiveInteger</validation>
        </settings>
    </data>
</result>


Note:

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

Parameters

This function does not accept parameters.

Returns

ReturnTypeDescriptionPossible valuesExample
settingsarray of hashes

A array of ModSecurity global configuration setting hashes.

Each hash includes the setting_id, name, default, description, engine, directive, type, state, and url returns and the radio_options and validation arrays.

setting_id

integer

The setting ID.

The function returns this value in the settings array.

A positive integer.0

name

string

The setting's name.

The function returns this value in the settings array.

A valid string.Audit logging level

default

string

The setting's default value.

The function returns this value in the settings array.

A positive integer.


1500

description

string

The setting's description.

The function returns this value in the settings array.

A valid string.
 Click to view...

This setting allows you to define the match limit of the PCRE library.

engine

Boolean

Whether the setting is an engine directive.

The function returns this value in the settings array.

  • 1 — Engine directive.
  • 0 — Normal directive.
1

directive

string

The setting's Apache configuration directive.

The function returns this value in the settings array.

A valid directive name.SecPcreMatchLimitRecursion

type

string

The form element that the WHM interface uses to display this setting.

The function returns this value in the settings array.

  • text — WHM users modify this setting via a text box.
  • radio — WHM users modify this setting via a radio button.
  • number — WHM users modify this setting via a text box that only allows numeric values.
text

state

string

The setting's current state.

The function returns this value in the settings array.

A valid option name.On

url

string

The URL of the setting's entry in the ModSecurity reference manual.

The function returns this value in the settings array.

A valid URL.
 Click to view...

https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit

radio_options

array of hashes

An array of hashes of the options that the client should display, as radio buttons, for this setting in a user interface.

Note:

The function only returns this array of hashes when the type parameter's value is radio.

The function returns this array in the  settings array. 

Each hash includes the option  and name returns.

option 

string

The setting that the system used to select the setting's state.

Note:

This value is identical to the string that the client sends in as state value when users select the specified setting. In most cases, you should not display this value to the user. Instead, display the name value.

The function returns this value in the radio_options array.

A valid string.On 

name 

string

The setting name to display to the user. The user's locale may translate this value.

The function returns this value in the radio_options array.

A valid string.Log all transactions. 

validation

array

A validator or array of validators to apply. Use these validators to perform frontend validation through your preferred implementation methods.

Note:

The function may represent each validator as either a string or a hash.

  • When the function represents the validator as a string, no arguments exist for the validator. 
  • When the function returns the validator as a hash, the API may also include an argument for the validator.

The function returns this array in the settings array. 

  • path — An instruction to verify whether the user's input is a valid path.
  • A regular expression that contains startsWith — An instruction to verify that the user's input begins with the pattern the regular expression specifies.

  • honeypotAccessKey — An instruction to verify whether the user's input fits the constraints of an Http:BL API access key.
  • positiveInteger — An instruction to verify whether the user's input is a positive integer.
{
"name":"startsWith",
"arg":"[Ee]xample"
}

Note:

This example is JSON-encoded, to illustrate the validator's structure.