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 - load_cphulk_config
Skip to end of metadata
Go to start of metadata

Description

This function returns cPHulk's current settings.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/load_cphulk_config?api.version=1
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/load_cphulk_config?api.version=1
 Command Line
whmapi1 load_cphulk_config 


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)
{
	"data": {
		"cphulk_config": {
			"ip_brute_force_period_mins": 15,
			"block_brute_force_with_firewall": 0,
			"notify_on_brute": "0",
			"ip_based_protection": 1,
			"max_failures": 15,
			"notify_on_root_login_for_known_netblock": 0,
			"mark_as_brute": 30,
			"block_excessive_brute_force_with_firewall": 0,
			"notify_on_root_login": 0,
			"lookback_time": 21600,
			"brute_force_period_mins": 5,
			"username_based_protection_for_root": 0,
			"brute_force_period_sec": 300,
			"command_to_run_on_excessive_brute_force": "",
			"command_to_run_on_brute_force": "",
			"ip_brute_force_period_sec": 900,
			"is_enabled": 1,
			"lookback_period_min": 360,
			"username_based_protection_local_origin": 1,
			"username_based_protection": 0,
			"max_failures_byip": 5,
			"can_temp_ban_firewall": 1
		}
	},
	"metadata": {
		"version": 1,
		"reason": "OK",
		"result": 1,
		"command": "load_cphulk_config"
	}
}
 Output (XML)

Important:

cPanel & WHM version 66 deprecated XML output.

<result>
    <data>
        <cphulk_config>
            <is_enabled>1</is_enabled>
            <ip_brute_force_period_mins>15</ip_brute_force_period_mins>
            <max_failures>15</max_failures>
            <brute_force_period_sec>300</brute_force_period_sec>
            <lookback_period_min>360</lookback_period_min>
            <mark_as_brute>30</mark_as_brute>
            <ip_brute_force_period_sec>900</ip_brute_force_period_sec>
            <lookback_time>21600</lookback_time>
            <brute_force_period_mins>5</brute_force_period_mins>
            <notify_on_brute>0</notify_on_brute>
            <notify_on_root_login>0</notify_on_root_login>
            <max_failures_byip>5</max_failures_byip>
        </cphulk_config>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>load_cphulk_config</command>
    </metadata>
</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
cphulk_configHashA hash of cPHulk's current settings.This hash contains the is_enabled, ip_brute_force_period_mins, ip_brute_force_period_sec, block_brute_force_with_firewall, block_excessive_brute_force_with_firewall, can_temp_ban_firewall, command_to_run_on_brute_force, command_to_run_on_excessive_brute_force, ip_based_protection, brute_force_period_mins, brute_force_period_sec, max_failures, max_failures_byip, mark_as_brute, lookback_period_min, lookback_time, notify_on_brute, notify_on_root_login, notify_on_root_login_for_known_netblock, username_based_protectionusername_based_protection_for_root, and username_based_protection_local_origin returns. 

is_enabled

Boolean

Whether the cPHulk service is enabled.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

ip_brute_force_period_mins

integer

The number of minutes during which cPHulk measures an attacker's login attempts.

The function returns this value in the cphulk_config hash.

A valid integer, in minutes.15

ip_brute_force_period_sec

integer

The number of seconds during which cPHulk measures an attacker's login attempts.

The function returns this value in the cphulk_config hash.

A valid integer, in seconds.300

block_brute_force_with_firewall

Boolean

Whether to use the server's firewall to block brute force attacks.

The function returns this value in the cphulk_config hash.

  • 1 — Block.
  • 0 — Don't block.
1

block_excessive_brute_force_with_firewall

Boolean

Whether to use the server's firewall to block excessive brute force attacks.

The function returns this value in the cphulk_config hash.

  • 1 — Block.
  • 0 — Don't block.
1

can_temp_ban_firewall

Boolean

Whether to add temporary IP bans via the server's firewall.

The function returns this value in the cphulk_config hash.

  • 1 — Add.
  • 0 — Don't add.
1

command_to_run_on_brute_force

string

The command to run when the system detects a brute force attack.

The function returns this value in the cphulk_config hash.

A valid BASH command.echo "BRUTE"

command_to_run_on_excessive_brute_force

string

The command to run when the system detects an excessive brute force attack.

The function returns this value in the cphulk_config hash.

A valid BASH command.echo "TOO MUCH BRUTE"

ip_based_protection

Boolean

Whether cPHulk will track failed login attempts via IP addresses.

The function returns this value in the cphulk_config hash.

  • 1 — Track.
  • 0 — Don't track.
1

brute_force_period_mins

integer

The number of minutes during which cPHulk measures all login attempts to a specific user's account.

The function returns this value in the cphulk_config hash.

A valid integer, in minutes.5

brute_force_period_sec

integer

The number of seconds over which cPHulk measures all login attempts to a specific user's account.

The function returns this value in the cphulk_config hash.

A valid integer, in seconds.360

max_failures

integer

The maximum number of failures that cPHulk will allow per account within the defined time range.

The function returns this value in the cphulk_config hash.

A valid integer.30

max_failures_byip

integer

The maximum number of failures that cPHulk will allow per account from a specific IP address within the defined time range.

The function returns this value in the cphulk_config hash.

A valid integer.5

mark_as_brute

integer

The maximum number of failures that cPHulk will allow per account from a specific IP address before the system locks out that address for two weeks.

The function returns this value in the cphulk_config hash.

A valid integer.30

lookback_period_min

integer

The number of minutes during which cPHulk counts failed logins against a user.

The function returns this value in the cphulk_config hash.

A valid integer.360

lookback_time

integer

The number of seconds during which cPHulk counts failed logins against a user.

The function returns this value in the cphulk_config hash.

A valid integer.21600

notify_on_brute

Boolean

Whether cPHulk will send a notification when it detects a brute force attack.

The function returns this value in the cphulk_config hash.

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

notify_on_root_login

Boolean

Whether cPHulk will send a notification when the root user successfully logs in from an IP address that is not on the whitelist.

The function returns this value in the cphulk_config hash.

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

notify_on_root_login_for_known_netblock

Boolean

Whether cPHulk will send a notification when the root user successfully logs in from an IP address in the same netblock.

The function returns this value in the cphulk_config hash.

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

username_based_protection

 
Boolean

Whether cPHulk will track failed logins by username.

The function returns this value in the cphulk_config hash.

  • 1 — Track.
  • 0 — Don't track.
1 

username_based_protection_for_root

 
Boolean

Whether cPHulk will track the root user's failed logins.

The function returns this value in the cphulk_config hash.

  • 1 — Track.
  • 0 — Don't track.
1 

username_based_protection_local_origin

 
Boolean

Whether cPHulk will only track failed logins for requests originating locally.

The function returns this value in the cphulk_config hash.

  • 1 — Track.
  • 0 — Don't track.
1