Update login security configuration settings

This function modifies a single cPHulk configuration settings as specified.

SecurityBasicAuth
Request
query Parameters
key
required
string

The configuration key for the setting to set/modify.

It should be one of the following:

  • block_brute_force_with_firewall - Whether to use cPanel & WHM's firewall to block brute force attacks.
  • block_excessive_brute_force_with_firewall - Whether to use cPanel & WHM's firewall to block excessive brute force attacks.
  • brute_force_period_mins - The number of minutes over which cPHulk measures all login attempts to a specific user's account.
  • brute_force_period_sec - The number of seconds over which cPHulk measures all login attempts to a specific user's account.
  • command_to_run_on_brute_force - The command to run when an IP address triggers brute force protection.
  • command_to_run_on_excessive_brute_force - The command to run when the system blocks an IP address blocked for a one day period.
  • country_blacklist - The countries to blacklist.
  • country_whitelist - The countries to whitelist.
  • ip_based_protection - Whether to enable IP address-based protection on all requests.
  • ip_brute_force_period_mins - The number of minutes in which cPHulk measures an attacker's login attempts.
  • ip_brute_force_period_sec - The number of seconds in which cPHulk measures an attacker's login attempts.
  • is_enabled - Whether to enable the cPHulk service.
  • lookback_period_min - The number of minutes over which cPHulk counts failed logins against a user.
  • lookback_time - The number of seconds over which cPHulk counts failed logins against a user.
  • mark_as_brute - The maximum number of failures from a specific IP address before cPHulk blocks that address for a two-week period.
  • max_failures - The maximum number of failures that cPHulk allows per account within the defined time range.
  • max_failures_byip - The maximum number of failures from a specific IP address before cPHulk locks out that address.
  • notify_on_brute - Whether cPHulk will send a notification when it detects a brute force attack.
  • notify_on_root_login - Whether cPHulk will send a notification when the root user successfully logs in from an IP address that is not on the whitelist.
  • notify_on_root_login_for_known_netblock - Whether cPHulk sends a notification upon successful root login when the IP address is not on the whitelist, but from a known netblock.
  • username_based_protection - Whether to enable username-based protection on all requests.
  • username_based_protection_for_root - Whether to allow username-based protection to lock out the root user.
  • username_based_protection_local_origin - Whether to enable username-based protection only on requests that originate from a local IP address.
Enum: "block_brute_force_with_firewall" "block_excessive_brute_force_with_firewall" "brute_force_period_mins" "brute_force_period_sec" "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" "username_based_protection_local_origin"
Example: key=is_enabled
required
string or integer

The new value for the specified key. The allowable value depends on which key is being set.

For the following keys, the value must be 0 or 1:

  • block_brute_force_with_firewall
  • block_excessive_brute_force_with_firewall
  • ip_based_protection
  • is_enabled
  • notify_on_brute
  • notify_on_root_login
  • notify_on_root_login_for_known_netblock
  • username_based_protection
  • username_based_protection_for_root
  • username_based_protection_local_origin

For the following keys, the value must be an integer which specifies a number of minutes or seconds:

  • brute_force_period_mins
  • brute_force_period_sec
  • ip_brute_force_period_mins
  • ip_brute_force_period_sec
  • lookback_period_min
  • lookback_time - This one is in seconds despite not having sec in the name

These keys require the value to be a string containing a command to be run: (For a list of commands, read the Command Variables section of our cPHulk Brute Force Protection documentation.)

  • command_to_run_on_brute_force
  • command_to_run_on_excessive_brute_force

These keys require the value to be a string containing a comma-separated list of country codes: (For a list of countries, run the WHM API 1 get_countries_with_known_ip_ranges function.)

  • country_blacklist
  • country_whitelist

The following keys require an integer representing a maximum number of failures

  • mark_as_brute
  • max_failures
  • max_failures_byip
Example: value=1
Responses
200

HTTP Request was successful.

Response Schema: application/json
object
object
get/set_cphulk_config_key
Request samples
whmapi1 --output=jsonpretty \
  set_cphulk_config_key key=is_enabled value=1
Response samples
application/json
{
  • "data": {
    • "cphulk_config": {
      • "block_brute_force_with_firewall": 0,
      • "block_excessive_brute_force_with_firewall": 0,
      • "brute_force_period_mins": 5,
      • "brute_force_period_sec": 300,
      • "can_temp_ban_firewall": 1,
      • "command_to_run_on_brute_force": "",
      • "command_to_run_on_excessive_brute_force": "",
      • "country_blacklist": "PK,BR",
      • "country_whitelist": "US,AU",
      • "ip_based_protection": 1,
      • "ip_brute_force_period_mins": 15,
      • "ip_brute_force_period_sec": 900,
      • "is_enabled": 1,
      • "lookback_period_min": 360,
      • "lookback_time": 21600,
      • "mark_as_brute": 30,
      • "max_failures": 30,
      • "max_failures_byip": 5,
      • "notify_on_brute": 0,
      • "notify_on_root_login": 0,
      • "notify_on_root_login_for_known_netblock": 0,
      • "username_based_protection": 0,
      • "username_based_protection_for_root": 0,
      • "username_based_protection_local_origin": 1
      }
    },
  • "metadata": {
    • "command": "set_cphulk_config_key",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}