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

Check out our new API beta site!

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

Description

This function modifies cPHulk's configuration settings.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/save_cphulk_config?api.version=1&brute_force_period_mins=5
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/save_cphulk_config?api.version=1&brute_force_period_mins=5
 Command Line
whmapi1 save_cphulk_config brute_force_period_mins=5 
 Output (JSON)
{
  "data": {
    "restart_ssh": 0,
    "warning": "",
	"cphulk_config":{ 
         "command_to_run_on_excessive_brute_force":"",
         "ip_based_protection":1,
         "block_excessive_brute_force_with_firewall":1,
         "brute_force_period_sec":300,
         "username_based_protection_for_root":0,
         "lookback_time":21600,
         "notify_on_brute":0,
         "block_brute_force_with_firewall":0,
         "brute_force_period_mins":5,
         "command_to_run_on_brute_force":"",
         "max_failures_byip":5,
         "notify_on_root_login":0,
         "username_based_protection_local_origin":1,
         "username_based_protection":0,
         "can_temp_ban_firewall":1,
         "is_enabled":1,
         "ip_brute_force_period_mins":15,
         "max_failures":15,
         "ip_brute_force_period_sec":900,
         "notify_on_root_login_for_known_netblock":0,
         "lookback_period_min":360,
         "mark_as_brute":30
      }
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": 1,
    "command": "save_cphulk_config"
  }
}

 Output (XML)
<result>
    <data>
        <restart_ssh>0</restart_ssh>
        <warning/>
        <cphulk_config>
         <block_brute_force_with_firewall>0</block_brute_force_with_firewall>
         <block_excessive_brute_force_with_firewall>1</block_excessive_brute_force_with_firewall>
         <brute_force_period_mins>5</brute_force_period_mins>
         <brute_force_period_sec>300</brute_force_period_sec>
         <can_temp_ban_firewall>1</can_temp_ban_firewall>
         <command_to_run_on_brute_force />
         <command_to_run_on_excessive_brute_force />
         <ip_based_protection>1</ip_based_protection>
         <ip_brute_force_period_mins>15</ip_brute_force_period_mins>
         <ip_brute_force_period_sec>900</ip_brute_force_period_sec>
         <is_enabled>1</is_enabled>
         <lookback_period_min>360</lookback_period_min>
         <lookback_time>21600</lookback_time>
         <mark_as_brute>30</mark_as_brute>
         <max_failures>15</max_failures>
         <max_failures_byip>5</max_failures_byip>
         <notify_on_brute>0</notify_on_brute>
         <notify_on_root_login>0</notify_on_root_login>
         <notify_on_root_login_for_known_netblock>0</notify_on_root_login_for_known_netblock>
         <username_based_protection>0</username_based_protection>
         <username_based_protection_for_root>0</username_based_protection_for_root>
         <username_based_protection_local_origin>1</username_based_protection_local_origin>
      </cphulk_config>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>save_cphulk_config</command>
    </metadata>
</result>


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample

block_brute_force_with_firewall

Boolean

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

This parameter defaults to 0.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

block_excessive_brute_force_with_firewall

Boolean

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

This parameter defaults to 0.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

brute_force_period_mins

integer

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

This parameter defaults to 5.

A valid integer.5

command_to_run_on_brute_force

string

The command to run when an IP address triggers brute force protection.

Note:

For a list of commands, read the Command variables section of our cPHulk Brute Force Protection documentation.

This parameter defaults to an empty string.

  • A valid command.
  • An empty string.
""

command_to_run_on_excessive_brute_force

string

The command to run when the system blocks an IP address for a one day period.

Note:

For a list of commands, read the Command variables section of our cPHulk Brute Force Protection documentation.

This parameter defaults to an empty string.

  • A valid command.
  • An empty string.
""

ip_based_protection

Boolean

Whether to enable IP address-based protection on all requests.

Note:

If you set the ip_based_protection parameter to 0, you cannot use the following parameters:

  • block_brute_force_with_firewall
  • block_excessive_brute_force_with_firewall
  • ip_brute_force_period_mins

This parameter defaults to 1.

  • 1 — Enable IP-based protection.
  • 0 — Disable IP-based protection.
1

ip_brute_force_period_mins

integer

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

The parameter defaults to 15.

A valid integer.15

lookback_period_min

integer

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

This parameter defaults to 360.

A valid integer.360

mark_as_brute

integer

The maximum number of failures from a specific IP address before cPHulk blocks that address for a two-week period.

This parameter defaults to 30.

A valid integer.30

max_failures

integer

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

This parameter defaults to 30.

A valid integer.30

max_failures_byip

integer

The maximum number of failures from a specific IP address before cPHulk locks out that address.

This parameter defaults to 5.

A valid integer.5

notify_on_brute

Boolean

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

This parameter defaults to 0 .


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

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.

This parameter defaults to 0.

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

notify_on_root_login_for_known_netblock

Boolean

Whether cPHulk sends a notification upon successful root login when the IP address is not on the whitelist, but from a known netblock.

This parameter defaults to 0.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
0
skip_enabled_check Boolean

Whether to skip checking if cPHulk runs on the server.

Note:

If cPHulk is disabled, the function returns the following message:

cPHulk is disabled on the server.


This parameter defaults to 0.

  • 1 — Don't check cPHulk's status.
  • 0 — Check cPHulk's status.
0 

username_based_protection

Boolean

Whether to enable username-based protection on all requests.

This parameter defaults to 0.

  • 1 — Enable.
  • 0 — Disable.
0

username_based_protection_for_root

Boolean

Whether to allow username-based protection to lock out the root user.

This parameter defaults to 0 .

  • 1 — Allow.
  • 0 — Do not allow.
0

username_based_protection_local_origin

Boolean

Whether to enable username-based protection only on requests that originate from a local IP address.

This parameter defaults to 1 .

  • 1 — Enable.
  • 0 — Disable.
1

Returns

ReturnTypeDescriptionPossible valuesExample
restart_ssh Boolean

Whether the system disabled UseDNS in the sshd.conf file and restarted the sshd daemon to allow cPHulk to add IP addresses to the whitelist.

Note:

This return only appears if the UseDNS setting is yes in the /etc/ssh/sshd_config file.

Because UseDNS and cPHulk are incompatible, the system sets the UseDNS setting to no when you enable cPHulk.

  • 1 — Disabled UseDNS in the sshd daemon and restarted the sshd service.
  • 0 — Did not alter the sshd.conf file or restart the sshd service.
1 
warning string

A warning message about the restart.

Note:

The function only returns this value if the restart_ssh return's value is 1.

  • null
  • A valid string.
null 
cphulk_confighash

A hash of cPHulk configuration settings.



This hash contains the 

block_brute_force_with_firewall, block_excessive_brute_force_with_firewall, brute_force_period_mins, brute_force_period_sec, can_temp_ban_firewall, command_to_run_on_brute_force, command_to_run_on_excessive_brute_force, country_blacklist, country_whitelist, ip_based_protection, ip_brute_force_period_mins, ip_brute_force_period_sec, is_enabled
lookback_period_min, lookback_time, mark_as_brute, max_failures, max_failures_byip, notify_on_brute, notify_on_root_login, notify_on_root_login_for_known_netblock, username_based_protection, username_based_protection_for_root, and username_based_protection_local_origin returns.


block_brute_force_with_firewall

Boolean

Whether to use cPanel & WHM's firewall to block brute force attacks.

The function returns this value in the cphulk_config hash.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

block_excessive_brute_force_with_firewall

Boolean

Whether to use cPanel & WHM's firewall to block excessive brute force attacks.

The function returns this value in the cphulk_config hash.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

brute_force_period_mins

integer

The number of minutes 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.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.300

can_temp_ban_firewall

Boolean

Whether the system firewall can apply temporary IP address bans.

The function returns this value in the cphulk_config hash.

  • 1 — Can temporarily apply IP address bans.
  • 0 Cannot temporarily apply IP address bans.

Note:

If this return's value is 0, then the ip_based_protection parameter is not available, which means that you cannot use the following parameters:

  • block_brute_force_with_firewall
  • block_excessive_brute_force_with_firewall
  • ip_brute_force_period_mins
  • ip_brute_force_period_sec
1

command_to_run_on_brute_force

string

The command to run when an IP address triggers brute force protection.

The function returns this value in the cphulk_config hash.

  • A valid command.
  • An empty string.
""

command_to_run_on_excessive_brute_force

string

The command to run when the system blocks an IP address blocked for a one day period.

The function returns this value in the cphulk_config hash.

  • A valid command.
  • An empty string.
""

ip_based_protection

Boolean

Whether IP address-based protection on all requests 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 in which cPHulk measures an attacker's login attempts.

The function returns this value in the cphulk_config hash.

A valid integer.15

ip_brute_force_period_sec

integer

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

The function returns this value in the cphulk_config hash.

A valid integer.900

is_enabled

Boolean

Whether the cPHulk service is enabled.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

lookback_period_min

integer

The number of minutes over 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 over which cPHulk counts failed logins against a user.

The function returns this value in the cphulk_config hash.

A valid integer.21600

mark_as_brute

integer

The maximum number of failures from a specific IP address before cPHulk blocks that address for a two-week period.

The function returns this value in the cphulk_config hash.

A valid integer.30

max_failures

integer

The maximum number of failures that cPHulk allows 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 from a specific IP address before cPHulk locks out that address.

The function returns this value in the cphulk_config hash.

A valid integer.5

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 the notification.
  • 0 — Do not send the notification.
0

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 the notification.
  • 0 — Do not send the notification.
0

notify_on_root_login_for_known_netblock

Boolean

Whether cPHulk sends a notification upon successful root login when the IP address is not on the whitelist, but from a known netblock.

The function returns this value in the cphulk_config hash.

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

username_based_protection

Boolean

Whether username-based protection on all requests is enabled.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0Disabled.
0

username_based_protection_for_root

Boolean

Whether username-based protection can lock out the root user.

The function returns this value in the cphulk_config hash.

  • 1 — Allowed.
  • 0Not allowed.
0

username_based_protection_local_origin

Boolean

Whether username-based protection only on requests that originate from a local IP address.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0 — Disabled.
1