Apocalypse Meow Pro: Hook & Filter Reference

Actions and filters are provided to allow custom themes or plugins to reference or utilize the Apocalypse Meow brute-force protection system.

 

See Also: Read-Only SettingsWP-CLI

Back: Apocalypse Meow

Actions

The following actions can be used to leverage Apocalypse Meow to track arbitrary login successes and failures in any custom form. The usual plugin settings for things like fail windows, etc., still apply.

meow_log_ban

This action causes an IP address or subnet to be temporarily banned from logging in.

<?php
do_action('meow_log_ban', $args);

Parameters

  • (array) $args: an array containing the following arguments:
    • (string) (optional) 'date_expires'**: the ban's expiration in YYYY-MM-DD HH:MM:SS format. Default: NOW + fail_window
    • (string) (optional) 'ip'**: an IP address OR...
    • (string) (optional) 'subnet'**: a subnet

The arguments must contain an IP address or a subnet; you should not pass both. If neither are passed, the current visitor's IP will be used.

This does not need to be explicitly triggered if you are already triggering login successes and failures; if the critical number of failures is reached for a given network address, a ban will automatically be issued.

While this does record a ban in the database, it will not automatically prevent robots or evildoers from accessing a custom login form. Refer to the filters meow_is_banned and meow_failures_remaining for accessing the current ban state.

meow_log_fail

This action adds a failure to the login records.

<?php
do_action('meow_log_fail', $args);

Parameters

  • (array) $args: an array containing the following arguments:
    • (string) (optional) 'ip'**: an IP address. Default: current visitor IP
    • (string) (optional) 'username'**: a username

meow_log_success

This action adds a success to the login records.

<?php
do_action('meow_log_success', $args);

Parameters

  • (array) $args: an array containing the following arguments:
    • (string) (optional) 'ip'**: an IP address. Default: current visitor IP
    • (string) (optional) 'username'**: a username

The following actions are triggered by Apocalypse Meow, allowing you to perform further actions, such as event logging.

meow_logged_ban

This action is fired when an IP address or subnet is temporarily banned from logging in.

This action comes with a single argument, an array, containing the following fields:

<?php
// Example arguments.
$args = array(
    'ip'=>'', // The IP address.
    'subnet'=>'', // The subnet.
    'date_created'=>'0000-00-00 00:00:00', // The creation datetime.
    'date_expires'=>'0000-00-00 00:00:00', // The expiration datetime.
    'type'=>'ban', // The type of action performed.
    'username'=>'', // The username submitted, if any; this does not apply to "ban".
    'count'=>1, // The number of times the ban error was shown to a blocked visitor, e.g. "persistence". This is only meaningful for "ban" actions.
);

// Use it like:
add_action('meow_logged_ban', 'my_callback_function', 10, 1);
function my_callback_function($args) { ... }

Because a ban applies to an IP address or a subnet, but not both, one will contain a proper value, the other will be set to "0". For fail and success types, both values will be set.

meow_logged_fail

This action is fired when someone has submitted an invalid login attempt.

This action comes with a single argument, an array. See meow_logged_ban for details.

meow_logged_success

This action is fired when someone has successfully logged in.

This action comes with a single argument, an array. See meow_logged_ban for details.


Filters

The following filters can be used to access Apocalypse Meow data in a clean way. They aren't necessarily intended to be hooked into via add_filter(), but I suppose you could. :)

meow_failures_remaining

Returns the number of failures remaining for a given visitor. Both IP- and Subnet-based limits are checked; the lower of the two values (i.e. the one that will hit sooner) is returned.

<?php
// Usage example:
$remaining = apply_filters('meow_failures_remaining', 500, '44.44.44.44');
if ($remaining < 5) {
    echo sprintf('Be careful, you will be banned after %d more tries.', $remaining);
}

Parameters

  • (int) $remaining: the number of failures remaining
  • (string) (optional) $ip: the IP address to check. Default: current visitor IP

Returns

Returns an integer representing the remaining failures (before a visitor will be banned). If the IP address is whitelisted or otherwise not subject to a ban (because it is a local address, etc.), the value returned will always be the failure limit.

meow_is_banned

Check whether an IP address is currently banned or not.

<?php
// Usage example:
$banned = apply_filters('meow_is_banned', false, '44.44.44.44');
if ($banned) {
    wp_die('Sorry, you are not allowed to view this right now.');
}

Parameters

  • (bool) $banned: ban status
  • (string) (optional) $ip: the IP address to check. Default: current visitor IP

Returns

Returns TRUE if the IP is banned, FALSE if not.

meow_is_whitelisted

Check whether an IP address is part of the global whitelist.

<?php
// Usage example:
$whitelisted = apply_filters('meow_is_whitelisted', false, '44.44.44.44');
if ($whitelisted) {
    echo 'Fail as much as you want! Nobody can stop you!';
}

Parameters

  • (bool) $whitelisted: whitelist status
  • (string) (optional) $ip: the IP address to check. Default: current visitor IP

Returns

Returns TRUE if the IP is whitelisted or in any way not subject to bans, FALSE if not.