Brute-Force Protection: Setup, Tuning, and Locked-Out IP Recovery

What Brute-Force Protection Actually Does

The module hooks the WordPress authenticate filter at priority 30 and the wp_login_failed + application_password_failed_authentication actions. Every failed sign-in from every surface — wp-login.php, WooCommerce /my-account/, MemberPress, BuddyPress, theme login forms, and REST API Application Passwords — feeds the same per-IP counter. That’s important: an attacker who tries wp-login.php three times then switches to the REST API doesn’t get a fresh counter.

The block flow, with default settings (max attempts 5, lockout duration 15 minutes, permanent ban threshold 3):

• Attempts 1–4 fail normally — WordPress’s built-in "invalid username or password" error is shown, the failure is recorded to the gp_failed_logins table with the IP and timestamp, and nothing user-visible changes.
• On attempt 5, the IP is inserted into gp_ip_blocklist with an unblock_at timestamp 15 minutes in the future. From this moment on, every sign-in attempt from that IP is rejected before the password is even checked, with the message “Too many failed login attempts. Please try again in N minutes.”
• One "IP Address Blocked" email is sent to your configured alert address, with the reason string carrying the attempt count. (This is the 1.6.40 flow — prior versions sent a warning email at attempt 4 plus the block email, two emails per attacker; the extra warning was dropped in 1.6.40 as noise.)
• When unblock_at passes, the block silently expires. The lockout_count for that IP persists across cycles.
• When an IP hits its 3rd temporary lockout (default threshold), the block escalates to permanent. is_permanent is set to 1, unblock_at is set to NULL, and the reason changes to “Permanently banned after 3 temporary lockouts.” Only manual admin action can lift a permanent ban.

Two supplementary counters run alongside this:

• Per-username throttle (1.6.4) — if a single username accumulates brute_force_username_max_attempts failures (default 10) across any combination of IPs within the lockout window, further attempts for that username are throttled with a generic "too many attempts" message. This stops distributed attacks that use hundreds of IPs, each sending a few attempts against the same admin account.
• MCP / OAuth carve-out (1.6.35+) — if you’ve enabled Allow MCP / Agent Traffic under GuardPress → Settings → Firewall & Protection, requests to Royal MCP’s REST namespace and the OAuth token-exchange endpoints skip the brute-force counter entirely. Long Claude conversations and Apify / n8n / Make automations fire dozens of tool calls per minute and would otherwise trip the lockout on legitimate use.

The Four Settings You Can Tune

All four live at GuardPress → Settings → Login Protection. The Recommended label on the top toggle is intentional — leaving brute-force protection disabled is one of the fastest ways to get a site compromised.

Enable Brute-Force Protection

Option name: guardpress_brute_force_enabled. Master on / off toggle. When disabled, no failed logins are counted, no IPs are blocked, and the per-IP and per-username counters both go dormant. Existing entries in gp_failed_logins and gp_ip_blocklist are not deleted — if you re-enable the feature later, previously blocked IPs stay blocked until they expire or you unblock them manually.

Max Login Attempts

Option name: guardpress_brute_force_max_attempts. Default: 5. Range: 1–20. The number of failed attempts allowed within the lockout window before the IP is blocked. Lowering this to 3 or 4 makes the site more paranoid; raising it to 10+ is only appropriate if you have a lot of forgetful users and are okay accepting more brute-force surface.

Lockout Duration

Option name: guardpress_brute_force_lockout_duration. Default: 900 seconds (15 minutes). Range: 60–86400 (1 minute to 24 hours). How long a temporarily-blocked IP stays blocked before it can try again. This is also the window used to count failed attempts — failures older than the lockout duration don’t count toward the threshold.

Longer lockouts (1–4 hours) put more friction on real users who genuinely mistyped and got caught; shorter lockouts (5–15 minutes) are kinder to real users but let a patient attacker resume sooner. 15 minutes is the balance most sites want.

Permanent Ban Threshold

Option name: guardpress_permanent_ban_threshold. Default: 3. Range: 0–50. When an IP is about to be locked out and its cumulative lockout count reaches this number (including the block being applied right now), the block escalates to permanent instead of temporary. With the default of 3, that means: 1st lockout temporary, 2nd temporary, 3rd permanent. Set to 0 to disable permanent bans entirely (everything stays temporary and auto-expires).

Permanent bans only apply to IPs that have already demonstrated persistent attack behaviour — a real user who mistypes once and gets one 15-minute lockout is nowhere near this threshold. Attackers doing rotating credential stuffing hit it quickly.

Unlocking a Legit IP from wp-admin

Sometimes a real user (or you) gets caught in the lockout — forgot the password, typed it wrong five times, now their IP is blocked for 15 minutes. If you have wp-admin access from a different IP or an existing session:

Locked Out with No Admin Session? Change Your IP

If your only IP is blocked and you have no existing wp-admin session anywhere else, brute-force protection doesn’t ship a wp-config bypass constant — there’s no GUARDPRESS_BRUTE_FORCE_BYPASS. The intentional recovery paths, in decreasing order of convenience:

• Wait for the lockout to expire. If you know your temporary lockout is 15 minutes, wait 15 minutes and try once with the correct password. This is the boring answer, and often the right one.
• Sign in from a different IP. Switch off Wi-Fi and use your phone’s cellular hotspot. The lockout is per-IP, and your cellular IP is different from your home Wi-Fi IP. Once signed in, unblock your home IP and whitelist it.
• Ask another admin. If you’re on a multi-admin site, message the other admin. They can unblock your IP from GuardPress → IP Management in ten seconds.
• Delete the block row directly from the database. If you have MySQL / phpMyAdmin access via your host, run: DELETE FROM wp_gp_ip_blocklist WHERE ip_address = ‘YOUR.IP.HERE’; (substitute your table prefix). This is the "I have SSH but no wp-admin sessions and no phone hotspot" last resort. Also clear DELETE FROM wp_gp_failed_logins WHERE ip_address = ‘YOUR.IP.HERE’; so you don’t immediately re-trigger the block.

What the Alert Email Contains

When an IP hits the lockout, GuardPress sends one HTML-formatted email to the address configured in GuardPress → Settings → Email Alerts (or falls back to the WordPress admin_email if that’s empty). Subject line: “[Your Site] Security Alert: IP Address Blocked.” The body includes:

• A colour-coded severity banner (MEDIUM for a temporary brute-force block, styled in orange)
• The alert title: “IP Address Blocked”
• The main message: “IP address 203.0.113.42 has been blocked”
• A Details section carrying the reason string: “Reason: Brute force attempt detected — N failed login attempts” (this is where the attempt count lives since 1.6.40)
• Alert Type: ip_blocked
• Time (recorded in UTC)
• IP Address
• A “View Security Dashboard” button linking to your wp-admin

Since 1.6.40 this is the only email you get per attacker within the throttle window. Prior versions sent a “Multiple Failed Login Attempts Detected” warning on attempt 4 then this block email on attempt 5 — two emails per attacker, plus the warning misreported the count as one attempt ahead of reality. That was noise; 1.6.40 dropped the warning and folded the attempt count into this email’s reason string so no information is lost.

A separate throttle (default 1 hour per IP + alert type) suppresses duplicate block emails if the same attacker keeps probing after their block expires and re-triggers. When the throttle window closes, you get one summary email like “Repeat attacker summary: IP 203.0.113.42 triggered 47 ip_blocked events over 58 minutes.” Configure that at Settings → Email Alerts → Alert Throttling. Full details in Quieting GuardPress Security Alert Emails.

Common Mistakes

Setting max attempts to 1 or 2 "for extra security"

You’ll spend more time unlocking your own users than you save in defence. Real users mistype and correct; attackers script and don’t care. Keep max attempts at 3–5.

Turning off permanent bans without a plan

Setting Permanent Ban Threshold to 0 means every block auto-expires no matter how many times an IP re-offends. That’s fine if you review the audit log daily and manually blacklist repeat offenders. If you don’t, the same attacker will hammer you for weeks. Keep the default of 3 unless you have a specific reason.

Forgetting to whitelist office / home IPs

The first time you mistype your own password five times, you’ll wish you had. Whitelist your regular IPs the day you install the plugin — the "Whitelist My IP" shortcut on the IP Management page does it in one click.

Blocking Cloudflare edge IPs instead of your real visitors

If your site is behind Cloudflare and GuardPress can’t see the real visitor IP, every failed login looks like it’s coming from a Cloudflare edge IP — and the block will end up hitting Cloudflare’s IP instead of the attacker’s. Fixed automatically in 1.6.30+ (auto-detects Cloudflare, honours CF-Connecting-IP). If you’re on an older version, upgrade. If you’re on 1.6.30+ and still seeing this, check the diagnostic in Country Blocking and the Cloudflare Real-IP Gotcha.

Confusing brute-force lockouts with manual blacklist entries

The Active Lockouts & Permanent Bans table shows entries created automatically by the brute-force counter. The IP Blacklist table shows entries you added manually. They’re independent lists — removing an IP from Active Lockouts doesn’t remove it from the manual Blacklist and vice versa. See IP Blocking, Whitelisting, and Managing Locked-Out IPs for the full breakdown.

Still Stuck? Email Priority Support

If brute-force protection is misbehaving in a way that isn’t covered above — legit users getting locked out with no obvious cause, blocked IPs that won’t unblock, permanent bans firing on the wrong threshold:

Email support@royalplugins.com with the diagnostic info below. Priority email support is included with your GuardPress Pro license — typical response time is within 24 hours.