User Security Guard for WordPress

1. Overview

User Security Guard for WordPress protects who can sign in to your site. It counts failed sign-ins per IP address, per username and per email address, notices when many addresses attack one account, recognises bots, default usernames and exploit scanners, and scores every sign-in attempt with one risk engine before it lets the request through or blocks it. Every block stores a reason you can read, and by default a block lasts until an administrator removes it.

This page documents version 1.0.0 (the version in the plugin folder this page was written from). The plugin was earlier called "WP User Security Guard"; a few screen titles, the dashboard widget and some email texts still say "WP User Security". The admin menu is called User Security.

It is written for site owners, agencies and WooCommerce shops that want login protection that does one job: it is not a firewall, a malware scanner or a hardening checklist. The defaults work without changes. A small number of switches (the email sign-in code, the country rule, automatic release of blocks, trusting the address administrators sign in from, early refusal and the sign-in notice) are off until you turn them on.

How it works

1. On wp-login.php, wp-admin, the WooCommerce sign-in forms and XML-RPC the plugin sits on WordPress's authenticate filter (a REST request that carries an application password is checked the same way through a separate core filter; see REST API and application passwords). Before WordPress checks the password it asks one question: is this IP address or this account already blocked? If so the request is refused, even when the password is correct.
2. After a wrong password the plugin records the attempt and runs the risk engine. The engine adds up points from signals such as failures from the same address, failures against the same account, the same account attacked from many addresses, automation tools and default usernames. It answers allow, suspicious or block.
3. A block is written to the block list with a plain-English reason. The visitor still sees the same generic message as for any wrong password, so the login never reveals which usernames exist or that a block exists.
4. You see the result on the User Security → Dashboard, in User Security → Security Logs, in throttled email alerts and in an optional daily, weekly or monthly digest email. You lift a block from User Security → Blocked IPs or User Security → Blocked Users, or with wp wpus unblock.

On an ordinary page view the plugin does not query its own tables. It reads its settings and checks its scheduled jobs (WordPress options). The only front-end request it looks at beyond sign-ins is a request WordPress has already answered with a 404 whose path looks like an exploit probe (see Exploit probing).

At a glance

What it does not do

• It is not a firewall, malware scanner, file integrity monitor or hardening score. It looks at authentication, at XML-RPC and REST credentials, and at 404 requests for known exploit paths.
• It does not add a CAPTCHA, hide or move wp-login.php, enforce a password policy, or support authenticator apps. The only second factor is a code sent by email.
• It does not end sessions that already exist. A block stops new sign-ins; cookies already issued keep working until they expire.
• It does not block the REST API as a whole. Only requests that carry credentials are looked at.
• It does not look up countries. The optional country rule reads a header that your CDN or host adds; there is no GeoIP database.
• It does not score ordinary page views, browsing the shop, viewing My Account or checking out.
• It does not group IPv6 addresses. Counters use the exact address.
• It never blocks an administrator account automatically unless you switch that on, and the automatic rules never create a block for an allowlisted address.

2. Requirements

The plugin has no activation check of its own. If the tables are missing, Settings and Tools show "The security tables are not installed. Deactivate and activate the plugin again, or run the schema installer from WP-CLI." The plugin has no WP-CLI command that installs the schema; deactivating and activating the plugin does it.

3. Installation

1. Download the plugin zip from your account on wpexpertshub.com (My Account → Downloads).
2. In WordPress, open Plugins → Add Plugin → Upload Plugin, choose the zip file and click Install Now.
3. Click Activate Plugin. The plugin creates its tables, saves its default settings, grants its capability to administrators and schedules its jobs. It asks nothing during activation.
4. Open User Security in the admin menu. Start with User Security → Allowlist and add your own IP address (the screen shows the address you are browsing from), so the automatic rules never block that address. (It does not help against a block on your account: see Allowlist.)
5. Open User Security → Settings and read the cards. Behind a CDN or reverse proxy, set Reverse proxies first.
6. Activate your licence under Plugins → WpExperts Hub Licences to receive updates (next section). The plugin works without it.

Licence and updates

The plugin bundles the WpExperts Hub licence and update client (licence/class-wpxh-licence-client.php, version 2.0.0). It loads only where WordPress is in the admin (this includes admin-ajax.php), in cron runs (update checks) and in WP-CLI. It does not load on a normal page view, a wp-login.php sign-in, an XML-RPC call or a REST request, so a slow licence server can never delay a sign-in the plugin is guarding.

1. Open Plugins → WpExperts Hub Licences. A Licence link also appears under the plugin's name on the Plugins screen for users who can manage_options. Until a licence is active, the Plugins screen shows an information notice: "Activate your WpExperts Hub licence to receive updates for: User Security Guard for WordPress." with a "Manage licences" link.
2. Paste the licence key from your purchase email (it is also shown in My Account → Downloads on wpexpertshub.com) and click Activate licence. Only letters, digits and hyphens are kept from what you paste.
3. New versions then appear on Dashboard → Updates and on the Plugins screen, and install like any other plugin update.
4. Lost the key? Open Can't find your key? Email it to me on the same screen, enter the email address used for the purchase and click Send licence key.
5. Before moving the plugin to another live site, click Deactivate licence. The licence is removed from this site even when the licence server cannot be reached.

What activation creates

Activation creates no pages, roles or files. After activation the plugin is working with its default settings.

Updating and deactivating

• Updating through Dashboard → Updates (with an active licence), or by uploading the new zip under Plugins → Add Plugin → Upload Plugin and choosing Replace current with uploaded, keeps your settings, blocks, logs, allowlist and remembered browsers. A newer schema is applied automatically the next time WordPress loads. Settings keys added by a new version take their default value until you save the Settings screen.
• Deactivating removes the two scheduled events and nothing else. Tables, settings and the capability stay, but nothing is protected while the plugin is inactive.
• Deleting the plugin removes its data only when Delete plugin data on uninstall is ticked (it is ticked by default). See Privacy for the full list.

Multisite

Each site has its own tables (with its own prefix), its own wpus_settings option, allowlist, blocks and log. Network activation runs the activation steps for every existing site; when a new site is created while the plugin is network-active, its tables and scheduled events are created at once, and so is the capability when the person creating the site is a super admin. The capability is granted to a site's administrator role only when a super admin activates the plugin (or creates the site). Every account that can manage_options, and every super admin, counts as an administrator for the alerts and the email code. Deleting the plugin with the uninstall option ticked is evaluated per site, using each site's own setting.

4. Quick start

1. Install and activate the plugin. Open User Security → Dashboard and read the warnings, if any.
2. Open User Security → Allowlist, add your own IP address with a label such as "Office" and click Add to allowlist. Only add addresses you control.
3. Make sure the site has a second administrator account. The Dashboard and Settings warn when there is only one: "This site has a single administrator account. Create a second administrator before tightening blocking rules, so you can always get back in."
4. Behind Cloudflare or another proxy: open User Security → Settings → Reverse proxies, tick Trust proxy headers, choose the header your proxy sets and save. Then open User Security → Tools → Sign-in diagnostics and read its message: it says "Working" when the header gives the visitor's address instead of the proxy's.
5. Open User Security → Settings → Notifications. Leave Send notifications to empty to use the site administration address, or enter another address. Keep Security digest at Every week or choose another schedule.
6. If another login-limiting plugin is active, keep only one. Settings and Tools name the plugin.
7. Optional: turn on the email sign-in code. Click Send me a test email first, then tick Ask for a sign-in code, save, and sign in once from a private window to confirm that you receive the code. Remember wp wpus two-factor --disable is the way back in.
8. Activate your licence under Plugins → WpExperts Hub Licences.

5. Features

This section describes how each protection behaves, with its defaults. Every setting named here is listed with its key, default and range under Settings. The screens are described under Admin screens.

How a sign-in attempt is judged

Every authentication request goes through the same steps, in this order.

1. Counting the visit. Each request to wp-login.php, and each submitted WooCommerce sign-in form, is counted in two short-lived counters per address (one for the last minute and one for the last hour). No database row is written for it. On wp-login.php the early refusal in the next step runs first, so a request it refuses is not counted; on the shop form the submission is counted first.
2. Early refusal (optional, off by default). A blocked address gets a bare 403 before the login page is shown. See Blocks.
3. authenticate at priority 1: is this already blocked? If the address is on the block list, or the username, the email address or the user ID is, the request is refused before WordPress checks the password. A correct password does not help. A refused country (see Country rule) and XML-RPC authentication that is switched off are refused at this step too. The step is skipped when the username field is empty.
4. WordPress checks the password. In WordPress 7.1.2 core's own password checks run at priority 20.
5. authenticate at priority 99: the email sign-in code, when it is switched on and the account is covered. See Email sign-in code.
6. authenticate at priority 100: the final word. A block decided at step 3 always wins. A correct password is logged as a success. A wrong password is recorded as a failed attempt, the risk engine runs, and a block or a warning is applied. Whatever happens, the visitor sees the same generic message.

Empty username or password fields are not treated as attempts, and a refused sign-in code is not counted as a wrong password. Another plugin or theme that hooks authenticate later than priority 100 could overrule the plugin's answer. User Security → Tools → Sign-in diagnostics lists such callbacks.

The risk signals

The risk engine runs only after a wrong password. It counts recent failures and adds points for each signal that applies. The counters are read before the failure that just happened is saved, so a limit of 10 takes effect on the 11th failed attempt: the engine sees ten earlier failures and acts.

The decision. A request is blocked when a rule above asks for a block (an account limit, a distributed attack, repeated default usernames) or when the total reaches the block score (Risk score for "block", 80). It is marked suspicious when the total reaches Risk score for "suspicious" (25) but not the block score. Otherwise it is allowed. An account limit or a distributed attack asks for an account block (see Administrator protection for the exception for administrators); repeated default usernames ask for an address block; a block caused only by the score blocks the address. An allowlisted address is not scored at all. With Login protection switched off nothing is scored.

A suspicious result still lets the request take its course (it was a wrong password anyway). It writes a "Suspicious authentication activity" log entry, at most one per address and username every 10 minutes, and fires the wpus_suspicious_activity action. Only the distributed-attack shape (distributed_account_attack) is worth an email.

Three worked examples with the default settings

1. Someone guesses the password of a real, ordinary account from one address with a normal browser. Until five earlier failures exist, nothing happens. From the 6th failed attempt the address scores 25 (suspicious address) plus 20 (suspicious account) and is marked suspicious. On the 11th failed attempt, ten earlier failures exist: 60 plus 20 reaches 80 and the address is blocked, with the reason "Risk score 80 reached the blocking threshold of 80".
2. Someone guesses an administrator account. The administrator limits apply (5). On the 6th failed attempt the account limit (60) is reached, the address scores 25 as suspicious (its "suspicious" limit is 4 here; the 60-point per-IP limit is still 10), and 20 more are added for targeting an administrator. The plugin would block the account, but administrator accounts are not blocked automatically by default, so it blocks the address instead and logs that the account block was refused. You get the alert "Administrator block refused" (see Alerts).
3. A script tries many made-up usernames. Unknown usernames are not stored by name, so only the per-IP limit applies: 60 points on the 11th failed attempt. That is below the block score of 80, so a script that looks like a normal browser is marked suspicious, not blocked. A script that announces itself as curl gets 20 extra points and is blocked on that same attempt (60 plus 20 is 80); together with missing browser headers the bot signals add up to their cap of 35. A default name such as admin adds 15 points per attempt and blocks the address on the third attempt.

Login limits and counters

The counters that feed the limits are rows in the attempts table. A row is written for every failed sign-in and for every request refused because an address or account was already blocked (a refused country is logged but not written here). Successful sign-ins are written to the security log only.

• Per address. Failed and refused rows from the same IP address inside the counting window. Default window: 60 minutes (Counting window (minutes)). Rows older than the window stop counting but stay in the log.
• Per username and per email. Failed rows only, so an attacker who is already blocked cannot lock the real owner out by being refused. For an ordinary account the account limit is the higher of the username limit and the email limit (20 each by default). For an administrator account it is the username limit, lowered to the administrator limit.
• Distinct addresses per account. The number of different IP addresses with failed attempts against the same username or email inside the window. When it reaches Block an account attacked from this many IPs (10) the account is blocked as a distributed attack. The next failed attempt after ten different addresses have already failed triggers it.
• A manual unblock restarts the counters. After you unblock an address or account, only attempts made after the unblock count. The old rows stay for the detail views and the audit trail. The same applies when automatic release lifts a block. Counters also restart when you use Delete all attempt rows on Tools.
• Retention. Attempt rows are deleted after Keep attempt rows for (30 days). The saved value is never lower than the counting window rounded up to whole days, because shorter retention would make every limit undercount.
• What is not stored. A username that does not exist is not stored by name. Text typed into the username box that contains an @ is treated as an email address and stored as typed (lower-cased, first 100 characters), whether or not it is a real address.

Switching Login protection off stops scoring, the recording of failed attempts, blocking at sign-in, the early refusal, and the rewriting of error messages. XML-RPC blocking, the exploit-probing rule and the email code are separate and keep working. The country rule, and the refusal of XML-RPC password logins while Allow XML-RPC authentication is off, are part of the sign-in check and are skipped too.

Administrator protection

An account counts as an administrator when it can manage_options or has the administrator role. This is used only inside the plugin: it is never reflected in an error message or a response.

• Stricter limits (Administrator protection ticked, default on). For an administrator account the username and email limits are lowered to Failed attempts before an admin account is treated as targeted (5) if they are higher. The distinct-address limit becomes half of that, rounded up (3), and the "suspicious" limit becomes that value minus one (4). The per-IP limit that adds 60 points is not lowered: the risk engine always reads Block after failed attempts from one IP (10) for it, even though the Settings screen sentence "Administrator accounts use the stricter limit of 5 attempts instead of 10" suggests otherwise.
• Never blocked automatically by default. With Automatically block administrator accounts off (default), a rule that asks for an administrator account block is refused. The plugin then blocks the source address instead, provided that address has itself failed at least as many times as the "suspicious" limit, so the owner's first typo cannot block an address because an attacker used up the account's failures. The refusal is logged as suspicious activity, fires wpus_account_block_refused and sends the alert "Administrator block refused".
• Turning automatic blocking on means an attacker who reaches the limit can lock that administrator out until you unblock the account by hand. Settings warns about this and the Dashboard shows "Admin accounts auto-blocked: Enabled". Keep a second administrator account, and know wp wpus unblock --account=<login>.
• Dedicated log events. Administrator sign-ins are logged as "Administrator login" and failures as "Administrator login failure" (each can be switched off separately). These events feed the Dashboard card Administrator activity and the "Admin failures" tile.

One generic error

Unknown username, unknown email, wrong password and every refusal by the plugin return one message: "The username or password you entered is incorrect." The filter wpus_generic_login_error replaces the text.

• Only credential errors are rewritten (invalid_username, invalid_email, incorrect_password and the plugin's own refusal codes). Empty-field messages, password-reset messages, registration errors and other plugins' messages are left alone.
• REST requests with bad credentials get HTTP 401, the error code incorrect_password and the same message, so the REST API cannot be used to find out which usernames exist.
• Because blocked and wrong-password answers look the same, a customer who is blocked sees "incorrect password". Check User Security → Blocked IPs and User Security → Blocked Users when someone says their correct password is refused.
• Password reset is never blocked (it is not a sign-in). It is also never refused by the early refusal, never challenged for a sign-in code and never affected by the country rule.

Bot detection

Bot detection produces signals, not decisions. Each signal adds points when a wrong password is scored, and the combined bot contribution is capped at 35. With the default block score of 80, a normal browser is never blocked on bot grounds alone. Signals are only looked at on the sign-in endpoints (wp-login.php, XML-RPC, REST with credentials and the WooCommerce sign-in form).

• When a failed attempt carries bot signals, a "Bot / automation detected" log entry is written with the signal codes.
• A burst on the login page. When one address reaches the high-frequency rate on wp-login.php (every page view and submission counts) or on the WooCommerce sign-in form (submissions only), the plugin writes a "Bot / automation detected" entry (at most once per address every 5 minutes) and fires wpus_attack_spike, which sends the "A burst of traffic on the login page" alert. A sustained burst of GET requests to wp-login.php is also run through the risk engine, so the configured rules decide whether the address is blocked.
• The frequency counters are fixed windows kept in transients (a minute and an hour from the first hit), so slow traffic is not mistaken for a burst.
• Switching Bot detection off removes the signals from scoring. The request counters and the burst alert still run while Login protection is on.

Default usernames

Password-guessing tools start with names such as admin. A real visitor has no reason to try a default name that is not their own, so a failed sign-in with one is stronger evidence than an ordinary wrong password.

• Which names. admin, administrator, root, test, demo, user, guest, webmaster, wpadmin, sysadmin, superadmin, owner, wordpress and adm; the same name followed by up to six digits, with an optional -, _ or . in between (for example admin1, admin_2024, root-01); and the part before the @ of an email address (admin@example.com). The filter wpus_generic_usernames changes the list.
• Only names that are not accounts. If the submitted name is a username or email of a real account, the rule never applies. A site whose administrator really is called admin is protected by the ordinary limits, and Settings suggests renaming it: "An account called admin exists on this site. Because it is a real account it is not covered by this rule, and it is the first name every attacker tries."
• What it does. Each failed attempt adds 15 points. The plugin also counts these attempts per address inside the counting window. Once an address has made Block the address after this many attempts (3), the engine adds 60 points and asks to block the address. The counter is updated before the engine runs, so the third attempt itself triggers the block.
• Only for one identifiable client. The block applies only when the address is attributable (see Reverse proxies). Behind a proxy that the plugin was not told about, each attempt keeps its small 15-point weight and nothing more, because blocking the proxy's address would lock out everyone behind it.
• Allowlisted addresses are never counted. A manual unblock starts the count again. The visitor still sees the same generic message.

Exploit probing (404 requests)

Scanners ask for files such as /.env, /.git/config, wp-config.php.bak or phpmyadmin long before they try a password. On a healthy site every one of those requests answers 404. This rule counts them and blocks the address from signing in when it keeps asking.

• Narrow by design. It runs on template_redirect (priority 0) and only when WordPress has already decided the request is a 404. A page that exists, an ordinary broken link and a query string (the query string is never looked at) are never counted. The visitor still sees your normal 404 page. A path your web server answers with its own 404 never reaches WordPress and is invisible to the plugin.
• What counts as a probe. The path is URL-decoded twice, lower-cased and matched against these patterns: environment files (.env), version-control folders (.git, .svn, .hg, .bzr), hidden config files (.htaccess, .htpasswd, .ds_store, .npmrc, .aws, .ssh and similar), copies of wp-config (.bak, .old, .zip, ~ and similar), PHP info pages (phpinfo.php), database admin tools (phpmyadmin, adminer, pma), backups and dumps (backup.zip, db.sql), log files (debug.log, error_log), web shells (shell.php, c99.php), cgi-bin, vendor/phpunit and similar test runners, path traversal (../, /etc/passwd), project files (composer.json, package.json, docker-compose.yml, web.config), and server status pages (server-status, actuator). The filter wpus_probe_rules lets you remove or add patterns (label and regular expression).
• What happens. The first probe from an address inside the window writes a "Suspicious authentication activity" log entry ("Request for a file that exploit scanners look for (<kind>) answered 404"). Two or more probes add 15 points to that address's later sign-in attempts. At Block after this many probes (5) inside Counting window (minutes) (10) the address is blocked with the reason "N requests for exploit paths that answer 404 within M minutes (last: <kind>)". That is an ordinary automatic block: it stops sign-ins from that address and does not stop it browsing your site.
• Who is ignored. Signed-in users who can edit posts, allowlisted addresses, addresses that are already blocked (no database write for them) and addresses that are not one identifiable client (see Reverse proxies).
• Counters are kept in transients, not table rows, and a manual unblock clears the count.

XML-RPC

XML-RPC is blocked by default (Block XML-RPC, on). It is a legacy endpoint that amplifies credential attacks and almost no site needs it.

• While blocked, every request to xmlrpc.php is refused before WordPress parses it, with HTTP 403 and the generic text "Access to this service is not available." under the title "Forbidden". The plugin also switches off WordPress's xmlrpc_enabled filter. This applies to every address, including allowlisted ones.
• Each refused request is logged as "XML-RPC blocked" and, except from an allowlisted address, recorded as a refused attempt. When an address has this many refused attempts inside the counting window, XML-RPC attempt limit per IP (5), it is blocked with the reason "XML-RPC hammering: N blocked XML-RPC requests (threshold 5)". Each refused request fires wpus_xmlrpc_blocked, which sends the alert "XML-RPC is being hammered" (throttled per address).
• To allow XML-RPC (for Jetpack, the mobile app or another tool) untick Block XML-RPC. Password logins over XML-RPC then stay refused until you also tick Allow XML-RPC authentication: a refused XML-RPC login is logged as "Blocked login" with the reason "XML-RPC authentication is disabled". With both on, XML-RPC logins go through the normal checks, and the per-IP limit for them is the lower of the general limit and the XML-RPC limit.
• With XML-RPC allowed, every call is logged by method name (never the arguments, which routinely contain passwords), at most one entry per address and method per minute. Untick Log XML-RPC activity to stop that, or XML-RPC requests under Logging.
• Settings and the Dashboard warn "XML-RPC is allowed" while it is allowed.

WooCommerce sign-in forms

A wrong password on the My Account page or the checkout login has always been counted, scored and blocked like one on wp-login.php, because WooCommerce signs people in through WordPress. With Protect the shop sign-in form on (default, and only when WooCommerce is active) the plugin also recognises the form as a sign-in page:

• A submission is recognised by its shape: a POST with the fields login, username and password. WooCommerce's nonce is not required, because a bot that leaves it out is still attacking the form. The request is labelled with the endpoint woocommerce in the attempts table and the log.
• It is counted in the same request counters, so bursts raise the same "burst of traffic" alert, and missing browser headers and an empty user agent are scored (see Bot detection).
• With Blocked addresses (early refusal) on, a blocked address is refused with a 403 on this form too.
• The email sign-in code appears on this form, in WooCommerce's own markup, and the optional sign-in notice is printed at the end of the form.
• Viewing My Account, browsing the shop and checking out are ordinary page views and are never scored. The plugin observes the form; it does not replace it.

REST API and application passwords

The REST API is never blocked as a whole. Only requests that carry credentials are looked at.

• In WordPress 7.1.2 a REST request with Basic credentials has its application password checked directly (on determine_current_user), not through the authenticate filters. The plugin hooks application_password_is_api_request to enforce blocks: a blocked address or account cannot authenticate with an application password. The caller is unauthenticated and gets the endpoint's ordinary 401 or 403.
• A failed application-password attempt is recorded and scored like a failed sign-in, using the Basic-auth username as the identifier. A successful one is logged as a sign-in. Basic-auth requests are not given the automation user-agent signal.
• Credential errors from REST authentication are replaced by one generic 401 answer (see One generic error).
• The email sign-in code is never asked for REST, application passwords, XML-RPC, cron or WP-CLI, because they have no form. A covered account's application password therefore keeps working.

Blocks

A block is a row in the block list with a reason. A refused sign-in never changes the visitor's answer: they see the generic message.

What gets blocked

• IP address (type ip). Listed on User Security → Blocked IPs.
• Account (type account for the username, the email address and the identifier that was typed, and type user for the numeric user ID). One account block writes up to three rows, so the account cannot come back through a different sign-in method. All of them are listed on User Security → Blocked Users, while the tab counts each account once. Unblock clears every row of the account together; Delete removes only the row you chose and leaves the others active.

Statuses

• Blocked: active. With automatic release on, an automatic block shows a countdown ("lifts in 3 hours"; "lapsed — release pending" once the time is up but the hourly job has not tidied it yet).
• Permanent: active and never lifts by itself.
• Unblocked: history. The row is kept; blocking the same address or account again re-activates the same row (keeping the first-detected date) and increases its block count.

Reasons

Every block stores a readable reason. Examples: Risk score 80 reached the blocking threshold of 80; Account "bob" reached 20 failed logins (threshold 20); Account "bob" was targeted from 10 different IP addresses (threshold 10); 3 login attempts with default usernames such as "admin" that do not exist here (threshold 3); 5 requests for exploit paths that answer 404 within 10 minutes (last: environment file); XML-RPC hammering: 5 blocked XML-RPC requests (threshold 5). A manual block without a reason says "Blocked manually by an administrator" (from wp wpus block: "Blocked from WP-CLI"). The reason column holds 191 characters; reasons you type are cut to fit.

Manual blocks

• User Security → Blocked IPs → Block an IP address manually: enter an address and a reason, tick Flag as a permanent block if you want one (it starts ticked when Allow permanent blocks (IP blocks) is on). The plugin refuses your own current address ("That is your own IP address. Blocking it would lock you out of this site, so it was not blocked."), an invalid address ("Enter a valid IPv4 or IPv6 address."), and an allowlisted address ("This IP address is on the allowlist. Remove it from the allowlist before blocking it.").
• User Security → Blocked Users → Block an account manually: enter a username or email address and a reason. The username, the email address and the user ID are blocked together. If the text matches no user, only the typed value is blocked.
• Manual blocking in Settings gates both forms and wp wpus block: when it is off they answer "Manual blocking is disabled in the plugin settings." Unblocking still works, and the forms are still shown.
• A block made by an administrator (screens or WP-CLI) never gets an expiry and can replace an active automatic block, for example to make it permanent. An automatic rule never rewrites an active block; it only updates its counters.

Row actions and bulk actions

Each row offers View activity (the Security Logs filtered to that address or username), Unblock, Make permanent (only on active blocks that are not permanent yet) and Delete. The bulk menu offers Unblock (manual), Flag as permanent and Delete record. A confirmation appears before an unblock, a delete or a bulk action, and choosing a bulk action with nothing ticked shows "Select at least one row first, then choose an action."

• Make permanent needs Allow permanent blocks for that kind of block (IP blocks or account blocks) to be ticked; otherwise nothing changes and the notice says "Permanent blocks are switched off for this kind of block in Settings, so nothing was changed." A permanent block loses any expiry.
• Unblock works at once ("The entry can sign in again immediately") and restarts the counters for that address or account.
• Delete removes the block row and its history permanently. On an active IP block that also lifts the block. For an account it removes only the row you chose; the other rows (username, email, user ID) keep the account blocked, so use Unblock to let it sign in again.

Automatic release (opt-in)

Set Release automatic blocks after to a number of hours (0, the default, means never). Then:

• A block that a rule created by itself, and that is not permanent, gets an expiry that many hours after it starts. Enforcement stops the moment the time is up: expired blocks are not enforced and drop out of the Active list even before the hourly job (wpus_release_blocks) tidies the row. The job then marks the row Unblocked with the reason "Released automatically", writes an unblock log entry and fires wpus_block_unblocked.
• Manual and permanent blocks never get an expiry. The counters restart when a block lifts.
• The expiry is set when the block is created. Blocks that already existed when you switched automatic release on carry no expiry and never lift by themselves, and changing the number of hours later does not change the expiry a block already has.
• Emergency mode pauses everything: blocks never lapse and new ones get no expiry while it is on. wp wpus release runs the release on demand.

Longer every time (opt-in)

Longer every time (1 to 10 times; 1 means every block lasts the same) makes each repeat automatic block last that many times longer than the last: with 24 hours and a factor of 3 the lengths are 24, 72, 216, 648 hours, and never more than 8,760 hours (a year). Settings previews the lengths from the values saved. It only matters when automatic release is on. The ladder continues only when the clock ended the earlier block and the address or account was blocked again inside Remember it for days of that block ending. A block an administrator lifted, a block made by hand, or a quiet spell longer than the memory starts again at the base length. A block that is still running is never lengthened.

Repeat offenders

With Repeat offenders on (default) and automatic release in use, an address that was blocked automatically, released by the clock inside the last Remember it for days (30) and is failing again has its per-IP limit and its "suspicious" limit halved (rounded up, never below 1). An address you unblocked yourself is never a repeat offender. Only those two numbers move (the "suspicious" limit is also the one that decides the 20-point account step, so that step moves with it); the account block limits stay.

Early refusal (opt-in)

With Blocked addresses ticked (default off), a blocked address gets a plain 403 ("Access to this page is not available.", titled "Forbidden") on wp-login.php and the WooCommerce sign-in form, and "Access to this service is not available." in plain text on XML-RPC when XML-RPC is allowed, before the page loads. It saves a little work per bot request but announces the block, which is why it is off. Password reset and logout are never refused. Each early refusal is logged at most once per address every 10 minutes.

Allowlist

Allowlisted addresses are exempt from the automatic rules. Open User Security → Allowlist, enter an address or range and an optional label, and click Add to allowlist.

• What you can enter. An IPv4 or IPv6 address (203.0.113.10), a CIDR range with a prefix of 1 to 32 (IPv4) or 1 to 128 (IPv6) (10.0.0.0/24, 2001:db8::/32), or IPv4 shorthand 10.*, 10.0.* or 10.0.0.* (stored as 10.0.0.0/8, 10.0.0.0/16 and 10.0.0.0/24). Wildcards must be at the end. Duplicates are refused. The list shows the address as stored, whether it is an address or a range, the label, who added it and when.
• What it skips. An allowlisted address is never scored, never flagged as a bot on a failed sign-in, never counted for default usernames or exploit probing, never gets an automatic block (a rule that tries is refused), is not recorded for XML-RPC escalation, and is never refused by the country rule. Manual blocking of an allowlisted address is refused.
• What it does not skip. It does not skip the email sign-in code. It does not lift a block that already exists: an address that was blocked before you allowlisted it is still refused at sign-in until you unblock it. An account block applies to an allowlisted address too, including one created later by an attack from other addresses. It does not exempt anyone from the XML-RPC 403 while XML-RPC is blocked. It does not switch off the login-page burst check: a burst of requests from an allowlisted address is still logged as "Bot / automation detected" and still sends the burst alert (see Bot detection). It never makes a wrong password right.
• It is a gap on purpose. Only add addresses you control. A shared office or café address trusts everyone behind it. The Dashboard and Settings warn "Allowlisted IP addresses are exempt from scoring, new IP blocks and the country rule. They are not exempt from account blocks or from a block that already exists. Every allowlist entry is a deliberate gap in the security controls." while the list is not empty.
• Entries you type never expire. Every add and removal is written to the security log, whether it came from the screen, WP-CLI or the plugin itself. The list is cached for 10 minutes and the cache is cleared on every change.

Trusted administrator addresses (opt-in)

With Trust the address administrators sign in from ticked (default off), the address an administrator has just signed in from is added to the allowlist, so your own typos, or an attacker guessing your password while you are away, cannot block the address you use.

• Only a completed, interactive sign-in counts (wp-login.php, wp-admin and the WooCommerce form). Never REST, application passwords or XML-RPC, and never a sign-in that the email-code safety net voided.
• Only an administrator (an account that can manage_options), and only a public address that is one identifiable client (see Reverse proxies). Loopback, private and proxy addresses are never trusted.
• The entry is labelled "Auto-added after administrator sign-in (<login>)" and expires after Trusted for (days) (30). Each sign-in from the address renews it. An expired entry stops counting at once and is removed by the daily job.
• Each administrator keeps at most Addresses kept per administrator (3) automatic entries; the oldest is removed when a new one is added.
• An address that is already allowlisted by hand, or inside a range, is left alone. Deleting or demoting the account removes its automatic entries. Emergency mode pauses the feature.
• The filter wpus_trust_admin_ip lets you refuse an address (for example a company VPN exit) or accept one the checks refuse.

Country rule (opt-in)

The country rule refuses sign-ins from countries you choose, or from every country you do not choose. The site, the login page and password reset stay reachable and anyone already signed in stays signed in.

• Rule: Off (default), Block sign-ins from the countries below or Only allow sign-ins from the countries below.
• Where the country comes from: one header your CDN or host adds. The choices are CF-IPCountry (default), CloudFront-Viewer-Country, X-Vercel-IP-Country, X-AppEngine-Country, GeoIP-Country-Code and GEOIP_COUNTRY_CODE. Nothing else is ever read. There is no GeoIP database to download. Only trust a header that nothing in front of your site lets a visitor set: with no CDN, anyone could send it and the rule protects nothing. Settings shows what the current request carried.
• Countries: a filterable list of 250 ISO 3166-1 two-letter codes (the United Kingdom is GB). Anything that is not one of them, such as XX (no data), T1 (Tor) or garbage, is "unknown", and an unknown country is never refused.
• The answer. A refused sign-in gets the generic message. It is logged as "Blocked login" with the reason "Sign-ins from France (FR) are not allowed" (at most once per address every 10 minutes). It is not written as a failed attempt, so it can never turn into an address block, and the allowlist wins.
• It will not lock out the person saving it. When you save a rule that would refuse your own request, it is switched back off and Settings explains: "Country rule not saved: you are signing in from France (FR), so it would have locked you out. It has been left off." Saving a rule with no countries is switched off with "Country rule not saved: choose at least one country first. It has been left off." When your request carries no country header, the rule is saved with a warning to confirm the header and allowlist your address.
• The way back in: wp wpus country --off, or add your address to the Allowlist.

Email sign-in code (opt-in)

This is the only feature that can refuse a sign-in whose password was correct, so it is off until you tick Ask for a sign-in code under User Security → Settings → Two-factor authentication (email codes).

How it works for the person signing in

1. They enter username and password on any sign-in form. If the password is right, the account is covered and the browser is not remembered, the sign-in is refused with "Your password was correct. Enter the sign-in code we emailed to you to finish signing in." and a six-digit code is emailed to the address on the account (subject "Your sign-in code for <site>").
2. The form shows a Sign-in code box ("We emailed a six-digit code to the address on this account."). They enter the code (and the password again if the form cleared it) and sign in.
3. That browser is remembered for Remember a browser for days (30) and is not asked again until the trust expires.

Who is asked

• The roles ticked under Who is asked (administrator, editor, author and shop manager by default; the administrator role cannot be unticked). Every account that can manage_options, and every super admin, is always asked whatever its role is called. Customers and subscribers are not asked unless you tick them. The filter wpus_two_factor_applies exempts or adds one account.
• An account with no usable email address is not challenged, because refusing it would lock the person out with no way back. The sign-in is logged ("Second factor skipped: the account has no deliverable email address.") and Settings lists those accounts.
• Nobody is asked while the plugin steps aside for another two-factor plugin (see Requirements). Use the filter wpus_two_factor_active for protection PHP cannot see, such as host-level two-factor or single sign-on.

Which forms

Every form a person can type a password into: wp-login.php (and the interim login inside wp-admin), the WooCommerce My Account and checkout login (with its own code box), an embedded wp_login_form(), and any theme, membership or page-builder form that signs people in the normal way. A form that cannot show a code box refuses the sign-in with an extra line, "This form has no box for the code, so finish signing in at <your login URL>.", because the code belongs to the account, not to the form. REST, application passwords, XML-RPC, cron and WP-CLI have no form and are never asked.

No way round it

With Every sign-in form ticked (default), a sign-in for a covered account that would be completed without passing the check (a social-login or magic-link plugin that sets the login cookie itself, a custom form) gets no login cookie. The session WordPress just created is destroyed, the attempt is logged ("Sign-in voided: it did not go through the sign-in code check, so no login cookie was sent."), and a person in a browser is sent to wp-login.php with "For your security this account needs a sign-in code. Sign in here and we will email you one." Untick it only if such a plugin conflicts. Not affected: REST, XML-RPC, cron and WP-CLI; an administrator switching to another user; someone signed in as that user already; a sign-in straight after a password reset by email (the reset link proved the mailbox) or after registering in the same request; and a browser that has already proved the code.

Code rules

• A code lasts Code lifetime (10 minutes). Only a hash is stored (user meta wpus_2fa_pending), with the time sent (wpus_2fa_sent) and the count of wrong tries (wpus_2fa_tries).
• A valid code is never re-sent while it is outstanding, so repeatedly submitting the form cannot mail-bomb an address. A replacement is emailed at most once per 60 seconds (filter wpus_two_factor_resend_seconds). During that minute the person sees "A sign-in code was emailed to you a moment ago. Wait a minute, then sign in again to get a new one."
• After Wrong codes per email (5) wrong codes the code is burnt and a new one is emailed ("Too many wrong codes. We have emailed you a new one."). An expired code is replaced the same way ("That code has expired. We have emailed you a new one."). A wrong code says "That code is not right. Check your email and try again."
• If the email cannot be sent the sign-in is refused: "Your password was correct, but the sign-in code could not be emailed. Ask an administrator to check the site mail settings, or to turn two-factor authentication off for you."
• A blocked address is never sent a code, and a password-reset page is never challenged. Being on the allowlist does not skip the code.
• The code challenge is not a wrong password: it is neither recorded as a failed attempt nor scored, so typing the code wrongly cannot get an administrator blocked. Each code request is logged as a "Blocked login" event with the reason "Second factor required: a sign-in code was emailed." and therefore appears in the Dashboard's "Blocked attempts" tile.

Remembered browsers

After a correct code, the plugin sets one cookie per account, wpus_device_<user id> (HttpOnly, SameSite=Lax, Secure on HTTPS), holding a random 64-character token. The database stores only the SHA-256 hash of the token, a hash of the browser's User-Agent string, a short label (Edg, OPR, Chrome, Firefox, Safari or "Unrecognised browser"), the IP address and the dates. A database leak cannot be replayed as a cookie, and a cookie copied to another browser is useless because the token is bound to the User-Agent string. The same binding means a browser whose User-Agent string changes, for example after an update, is asked for a code again.

• A password change or password reset forgets that user's browsers. User Security → Tools → Remembered browsers (shown while the code is on) lists every browser with Forget and Forget all. Expired entries are removed by the daily job.
• Switching the code off in Settings does not delete remembered browsers (use Forget all first, or wp wpus two-factor --disable, which switches the code off and forgets them). Anyone signed in when you switch it on stays signed in; the code is asked at their next sign-in from an unrecognised browser.
• If the email cannot reach someone: wp wpus two-factor --user=<login> --revoke forgets that person's browsers, and wp wpus two-factor --disable switches the feature off for everyone.

Alerts

Alerts are plain-text emails to the address in Send notifications to (or the site administration address when that is empty), sent with wp_mail(). All alerts need Email notifications ticked and their own switch. Each alert type is throttled per subject (an address, an account) to one email per Repeat window (minutes) (15), so an attack never becomes one email per attempt. Every email carries the heading "User Security Guard — <site name>", the line "This is an automated security notification. Open the security dashboard to review, block or unblock anything.", and a link to the Dashboard.

Accounts to watch chooses the roles behind the three "watched account" alerts: administrator, editor, author and shop manager by default. Administrators and any account that can manage_options are always watched. On the Settings screen each role is a card showing what the role can do, with a "Recommended" tag on the roles that can write or run the shop, a live count, and the quick picks Select recommended roles and Administrators only. A role that does not exist on the site (shop manager without WooCommerce) is never matched.

Security digest

One plain-text email, Every day, Every week (default) or Every month, set with Security digest under User Security → Settings → Notifications (Never switches it off). It follows the Email notifications switch and goes to the notification address. It is a calm summary and also proves the protection is running when nothing happened.

• Subject: "[<site>] Security digest: N failed sign-ins, threat level Low/Medium/High".
• Body: the period; the threat level; failed sign-ins; requests refused because the address or account was already blocked; how many different IP addresses were involved; how many accounts that exist on the site were targeted; successful sign-ins (only when logging and "Successful logins" are on); IP addresses and accounts blocked in the period; what is blocked right now; automation detections and refused XML-RPC requests (only when there were any); the five busiest IP addresses; the five most-targeted accounts; and, when nobody failed to sign in, the line "A quiet period: nobody tried and failed to sign in. The protection was running the whole time."
• Threat level is judged per day, so a monthly digest is not "High" merely because a month is long: High from 200 failed or refused attempts a day or 10 new blocks a day; Medium from 30 attempts or 2 new blocks a day; otherwise Low. The filter wpus_digest_level changes it.
• It never mails out of the blue. The daily maintenance job starts a clock the first time it sees the digest switched on; the first email arrives one full period later (the job treats a digest as due six hours before a full period has passed). Switching the digest off, or email notifications off, makes the next daily run forget the clock, so switching it on again starts a fresh period. A period is 1 day (daily), 7 days (weekly) or 30 days (monthly).
• A failed send is retried by the next daily run. A site that was off for months reports at most 35 days.
• Attempt rows are kept only for Keep attempt rows for days (30), independently of the digest period. When the period is longer, the email says the attempt figures cover only the most recent part and does not claim a quiet period.
• Send one now: User Security → Tools → Security digest (Send a digest now, 1 to 35 days, default 7), or wp wpus digest --send [--days=N]. wp wpus digest prints it. Neither changes the schedule. The digest needs WP-Cron.
• The filter wpus_digest_lines changes the lines.

Security log

The log has 20 event types. Each is controlled by a switch under User Security → Settings → Logging; the events that record an administrator's decision are always written while Logging is on, because they are the ones an audit needs.

• What a row holds: time, event, risk level (Low, Medium, High, Critical) and score, IP address, user ID, username, email, endpoint, request method, user agent (first 191 characters), result (Allowed, Blocked, Failed, Success, Warning), the reason, an administrator flag and a small JSON context.
• Redaction. Passwords, cookies, tokens and request bodies are never stored. In a context, any key whose name contains pass, pwd, secret, token, authorization, cookie, session, nonce, api_key, bearer or credential is replaced by "[redacted]". Values are cut to 200 characters, a context holds at most 25 entries and three levels, and non-scalar values become "[unsupported]". The filter wpus_log_data changes a row just before it is written.
• Retention. Keep log rows for 30, 60, 90 (default), 180 days, 1 year or Forever. A daily job deletes older rows, 1,000 at a time and at most 20,000 per table per run, and writes a "Security log cleaned up" entry. Blocks are never touched by retention.
• Switching Logging off stops all logging, including the administrator-decision events. Blocking, scoring and the digest's attempt figures do not depend on it.

Emergency mode

One switch on User Security → Tools (Turn emergency mode on, with a confirmation) tightens everything at once during an attack. It is never switched on automatically and it only tightens. Your saved values are untouched: Settings keeps showing them, and they apply again when you switch it off. While it is on, a red notice appears on every plugin screen and a chip "Emergency mode" in the header.

Emergency mode does not change Automatically block administrator accounts (the Tools card says administrator account blocking "is allowed" while it is on, but the saved setting still decides), the country rule, the email sign-in code or "Successful logins" logging.

Reverse proxies and the visitor's address

By default the plugin uses REMOTE_ADDR, the address of the connection. Behind a CDN or reverse proxy every visitor then arrives from the proxy's address, so all failures pile up on one address. Turn on Trust proxy headers and choose the header your proxy sets (X-Forwarded-For (default), CF-Connecting-IP, X-Real-IP or True-Client-IP) so the plugin sees the visitor. It is off by default because those headers are trivially faked when no proxy overwrites them, and a faked address would move the counters elsewhere.

• When the chosen header holds a comma-separated list, the plugin uses the last valid address in it: a client can prepend fake entries, but the entry your proxy appended sits at the end.
• When the header is missing or holds no valid address, the connection address is used.
• "One identifiable client". The rules that are cheap for a stranger to trigger (exploit probing, repeated default usernames) and the rule that trusts an address (administrator sign-in) act only on an address that is valid, public (not private, loopback, reserved, carrier-grade NAT, documentation or multicast space) and, while Trust proxy headers is off, not accompanied by a forwarding header (X-Forwarded-For, Forwarded, CF-Connecting-IP, True-Client-IP, X-Real-IP or X-Cluster-Client-IP). Behind a proxy that the plugin was not told about, those rules stay quiet on purpose instead of blocking everyone behind the edge. On a private network that you know is not shared (a lab, local development), return true from wpus_attributable_ip.
• Settings shows "Your site appears to be behind a proxy or CDN: every request arrives from the same address. Without this setting, all traffic is counted as one IP." when a reverse-DNS lookup of the address of the administrator viewing the screen returns a host name containing cloudflare, amazon or googleusercontent (see Privacy). It is a hint; User Security → Tools → Sign-in diagnostics is the reliable check.

Sign-in diagnostics

User Security → Tools → Sign-in diagnostics has two read-only checks that run only when you open the screen (or run wp wpus diagnose), never on a visitor's request.

• Which address does the plugin see for you? Shows the connection address, the address the plugin uses (with "One identifiable client" or "Not one client"), whether proxy trust is on, and every forwarding header your request carried with the address it would give and a "Cannot be selected" marker for Forwarded and X-Cluster-Client-IP. One sentence tells you what to do: that the connection address is correct for a site served directly; that the request passed through a proxy but trust is off and which header to choose (edge headers such as CF-Connecting-IP, True-Client-IP and X-Real-IP are suggested before X-Forwarded-For, which a client can add to); that the header is trusted but missing or invalid; or "Working: the <header> header is trusted and gives the visitor's address (<address>) instead of the proxy's (<address>)." It describes your request only. Open Tools through the same route your visitors use.
• Other plugins on the sign-in path. Lists every callback on authenticate and wp_authenticate_user with its priority and where it comes from (WordPress core, this plugin, a named plugin, a must-use plugin, the theme). A callback from outside that runs after priority 100, where this plugin gives its final answer, is marked "After our final check", because it could overrule a refusal. It is a hint, not a verdict. A known login limiter that is active is named in a warning here and at the top of Settings.

Export and import

On User Security → Tools → Export and import you can download the security data and move a configuration between sites.

• Downloads. Security log (CSV) (with an extra Last 30 days button), Blocked IPs and accounts, with their history (CSV), Allowlist (CSV) and Settings (JSON). File names are wpus-<what>-<date>.csv or .json. Every download needs the managing capability and a valid link, and is itself written to the log ("Exported: <name>").
• Row limit. A log or block CSV holds at most 100,000 rows, oldest first (the filter wpus_export_row_cap changes it). When more exist, the last line says "# Export stopped at the row limit (100,000 rows); newer rows are not in this file. Download a shorter date range for the rest." The log is read in pages of 1,000 by row ID, so an attack in progress cannot repeat or skip rows.
• Spreadsheet safety. A cell that starts with =, +, -, @, a tab or a carriage return gets a leading apostrophe, because usernames, user agents and reasons come from whoever tried to sign in.
• The settings file is JSON with plugin, format (1), version, exported_at and settings (this plugin's own settings only).
• Import settings. Paste the JSON into the box and click Import settings (or run wp wpus import-settings <file>). A file larger than 200,000 bytes, not valid JSON, not from this plugin or made by a newer format is refused with a message and nothing is imported. Values go through the same checks as the Settings screen; unknown keys and non-scalar values are ignored, and a file that names only some settings leaves the rest alone. The result says how many settings changed and names them (up to 12), and names every protection the file switched off (login protection, account blocking, bot detection, administrator protection, XML-RPC blocking, default usernames, exploit probing, WooCommerce protection, repeat offenders, logging, email notifications).
• Thirteen settings are never imported: trust_proxy_headers, proxy_header, notify_email, two_factor_enabled, emergency_mode, delete_data_on_uninstall, admin_account_block, country_mode, country_header, country_codes, trust_admin_ips, block_auto_release_hours and block_escalation_factor. They describe the server, can lock someone out, or loosen a protection you chose to switch on.
• The lists (log, blocks, allowlist) are export-only: an import is not a second way to create blocks that the risk engine never decided on.

Privacy tools

• Sign-in notice (opt-in). Sign-in notice under User Security → Settings → Privacy prints a short line on the WordPress sign-in form (between the password field and the Remember Me checkbox in WordPress 7.1.2, and in the interim login) and at the end of the WooCommerce My Account and checkout login forms. Default wording: "To keep this site secure, your IP address and browser details are recorded when you sign in. {privacy_policy}". Notice text replaces it: up to 600 characters; only links, bold, italics and line breaks are kept (cleaned when saved and again when shown). {privacy_policy} becomes a "Privacy policy" link to your privacy policy page when WordPress has one, and nothing when it has not. It is printed by the server with no script and no cookie, and it does not appear on a form that never fires login_form, such as a fully custom AJAX form or wp_login_form().
• Suggested privacy-policy text appears in Settings → Privacy → Policy Guide under "Security log". An admin notice on every admin screen reminds users who can manage the plugin to publish a privacy policy while the log has rows and no policy page is published.
• Personal-data exporter and eraser ("Security log") appear under Tools → Export Personal Data and Tools → Erase Personal Data. They look up rows by email address, 500 per batch. The exporter returns log rows (event, date, IP address, username, email, endpoint, outcome, reason, risk) and attempt rows (date, IP address, username, endpoint, outcome, reason). The eraser deletes the log rows and, on its first pass, the attempt rows for that email, and writes a "Privacy erasure request" log entry that does not contain the email address. Blocks and allowlist entries are not erased: a block is a security decision, and lifting one silently would break the rule that only an administrator ends a block. The filter wpus_erase_attempts (default true) lets you stop erasure from clearing attempt rows, which are the counters behind the limits.

6. Admin screens

The plugin adds one top-level menu, User Security (menu position 81, a shield icon), with seven screens. Every screen needs the capability wpus_manage_security (administrators have it) and shares one header: the title, a row of chips ("Version 1.0.0", plus "Emergency mode", "Two-factor on", "Country rule: block FR" or "only" and "Auto-release 24h" when those are active) and a tab bar with live counts on the two block lists. The browser page title of the screens reads "WP User Security", the plugin's earlier name.

Dashboard

Titled "Security Dashboard". A switch at the top chooses the period for the event counters: Last 24 hours (the default), Last 7 days, Last 30 days, Last year and All time (?wpus_period=24h|7d|30d|365d|all; an unknown value falls back to 24 hours). The eight tiles are links:

Below the tiles:

• The last 14 days: stacked bars of successful, failed and blocked sign-in events per day, built from the log (so it is empty when logging is off). A visually hidden table carries the same numbers for screen readers. With no activity it says "No sign-in activity has been recorded in this window yet."
• Latest security events: the ten newest log rows (When, Event, Account, IP, Result) and a button Open the full log.
• Administrator activity: administrators on the site; failed attempts, successful administrator logins and "Rejected while an admin account was blocked" for the period (this last figure counts all "Blocked login" events in the period, not only those of administrators); and Admin accounts auto-blocked: "Never (recommended)" or "Enabled". The safety warnings (single administrator, non-empty allowlist, automatic administrator blocking on, XML-RPC allowed) appear here.
• Where to go next: links to the block lists, the allowlist, Tools and Settings.

Security Logs

Titled "Security Logs". Filters: a search box ("Search reason or agent"; it searches the reason, username, email, IP address and user agent), IP address, Username, Email, From date, To date, Event type (all 20 events), Risk level (Low, Medium, High, Critical), Result (Allowed, Blocked, Failed, Success, Warning) and the checkbox Administrator activity only. Buttons: Filter logs and Reset. The table shows 25 rows per page, newest first, with the columns When (with the endpoint underneath), Event (with the user agent and an expandable "detail" line holding the user ID, request method and stored context), Account (username or email, an "admin" pill, and the email), IP address, Reason, Risk and Outcome. When, Event, IP address and Risk are sortable. The bulk action Delete selected log rows deletes only log rows (never blocks). A note under the table says how long rows are kept.

Blocked IPs and Blocked Users

The two screens share one layout. A notice says whether automatic release is on, and the subtitle changes with it ("A block stays until you remove it here — nothing lifts it automatically." or "Automatic blocks lift by themselves after a while; blocks you make by hand and permanent blocks stay until you remove them."). Filters: a search box (address; or username or email; it matches the value, username, email and reason), Status (Active blocks (default), Blocked, Permanent, Unblocked (history), Any status), Period (on the date the block started) and Filter and Reset. 20 rows per page.

• Blocked IPs columns: IP address (with "last tried: <username or email>"), Status, Reason, Attempts, Usernames tried, Last detected, Blocked.
• Blocked Users columns: Account (username, with the email underneath), Status, Reason, User ID ("no matching user" when none), Distinct IPs, Last detected, Blocked. Account blocks and user-ID blocks both appear.
• Status, address or account and "Blocked" date are sortable. Row actions, bulk actions and the manual block forms are described under Blocks. The "Blocked" column also shows "unblocked <date>" for a history row.

Allowlist

Titled "Allowlist", with the warning "An allowlisted address bypasses all login protection." The left card, Add an address, takes IP address or range and an optional Label and shows "You are browsing from <your address>." The right card lists Allowlisted addresses (N) with columns Address or range, Type (Address or Range), Label, Added (date and who, plus "Trusted until <date>" or "Expired <date>" for automatic entries) and a Remove action with a confirmation. See Allowlist for how entries behave.

Settings

One page, one form, a series of cards in this order: Login protection, Administrator protection, Bot detection, WooCommerce sign-in, Default usernames, Exploit probing (404 requests), XML-RPC, Blocking behaviour, Country rule, Logging, Notifications, Reverse proxies, Two-factor authentication (email codes) and Privacy. A section navigation built from the card headings and a sticky Save settings bar ("Changes take effect as soon as you save.") make it easy to move around. Saving shows a green "Settings saved." together with anything the plugin refused (for example a country rule that would have locked you out). Below the form, What this plugin detected lists WordPress version, site URL, timezone, PHP version, memory limit, WP cron, object cache, database schema, plugin version, XML-RPC and proxy-header trust, with a link to the full system information on Tools. Warnings at the top come from the same checks as Tools and from the safety warnings. Every setting is explained under Settings.

While emergency mode is on, a notice says "Emergency mode is on, so the values below are overridden with stricter ones. Turn it off on the Tools screen to edit them again." The form always shows what you saved, so saving never stores the emergency values.

Tools

Titled "Tools", subtitle "Emergency mode, data retention and — if you ever lock yourself out — the way back in." Top warnings: HTTPS missing, tables not installed, WP cron disabled or overdue, a custom-login-URL plugin ("Bot detection keys on the login endpoint, so frequency counting may follow a different path than expected."), another login-limiting plugin, and callbacks after this plugin's final check. Cards, in order:

• Emergency mode: Turn emergency mode on (with a confirmation) or Turn emergency mode off. See Emergency mode.
• Log retention: the number of log rows and how long they are kept, the oldest row, the number of attempt rows; Delete log rows by age (Older than (days), default 90, 1 to 3,650 in the form, Delete those log rows); and Run the daily cleanup now (Apply the retention settings now). Cleanup only deletes log and attempt rows.
• Clear the attempt counters: Delete all attempt rows restarts every failure counter from zero. Existing blocks stay. Occasionally useful after a false alarm, a bad idea during a real attack.
• If you are locked out: the three ways back in (the WordPress recovery email, an allowlist entry from another administrator session, and WP-CLI with wp wpus unblock --account=YOUR_USERNAME, wp wpus unblock --ip=203.0.113.10, wp wpus blocks and, when the code is on, wp wpus two-factor --disable).
• What this plugin stores: counts of blocked IPs, blocked accounts, allowlisted addresses and (with the code on) remembered browsers, and the statement that passwords, cookies, authentication tokens, nonces and request bodies are never stored.
• Remembered browsers (only while the email code is on): user, browser, trusted since, last used, expires, Forget per row and Forget all.
• Sign-in diagnostics: see Sign-in diagnostics.
• Security digest: schedule, last and next digest and recipient, and Send a digest now with Cover the last (days) (default 7, 1 to 35).
• Export and import: see Export and import.
• System information: groups WordPress (version, multisite, site URL, login endpoint, admin language, timezone), PHP (version, memory limit, max_input_vars), Environment (persistent object cache, WP cron, plugin memory in use), Plugin data (database schema, plugin version, managing capability, blocked IPs and accounts) and Posture (XML-RPC, proxy header trust, custom login URL plugin, other login-limiting plugins, WooCommerce sign-in form). A "Check" flag marks anything worth a look.

WordPress Dashboard widget

Users with the managing capability see a widget titled "WP User Security" on Dashboard → Home. It lists Blocked IPs, Blocked users, Failed logins (24h), Blocked attempts (24h) and Admin failures (24h), and a link Open the security dashboard.

7. Settings

All settings live in one option, wpus_settings (73 keys), saved from User Security → Settings through the WordPress Settings API (the form posts to options.php). Tick boxes are stored as 1 or 0. A number outside its range is moved to the nearest limit when you save, and an empty or non-numeric number becomes the lowest allowed value. Unknown keys that another plugin added to the option are kept. Anything that is not a whitelisted choice (the proxy header, the country header, the digest schedule, the log retention) falls back to its default.

The browser form is stricter than the saved range for four settings: Suspicious attempts per IP accepts 1 to 500 in the form, Counting window (minutes) 5 to 10,080, Failed attempts before an admin account is treated as targeted 1 to 100, and Requests per minute that count as high frequency 1 to 600. The tables below give the saved range, which also applies to values from an import, wpus_settings_sanitized and WP-CLI.

The filter wpus_settings can force values from code. The Settings screen shows what you saved, not what the filter or emergency mode forced.

Login protection

The limits that decide when traffic looks suspicious or is blocked. How they combine is explained under How a sign-in attempt is judged. Settings shows the current meaning in one sentence: "Currently: an address becomes suspicious after 5 failed attempts and is blocked after 10 within 60 minutes." (the blocking part also needs the score to reach the block score).

Administrator protection

Bot detection, WooCommerce, default usernames, exploit probing

XML-RPC

Blocking behaviour

Country rule

Logging

Notifications

Reverse proxies

Two-factor authentication (email codes)

Privacy and emergency mode

8. Developer reference

The plugin registers no shortcodes, blocks, REST routes, AJAX handlers or widgets (apart from the WordPress Dashboard widget), and it has no template files to override. What it exposes is WP-CLI commands, actions and filters, one admin POST endpoint and one export endpoint, a capability, one constant you can define, two scheduled events, five tables, one settings option and a few transients. The prefix is wpus_ (classes WPUS_).

WP-CLI

All commands start with wp wpus and are available when WP-CLI is loaded. They write through the same code as the admin screens, so the log and the hooks behave the same way. They are the documented way back in when you are locked out of the browser.

# Back in after a lockout
wp wpus blocks
wp wpus unblock --account=your-admin-login --reason="Locked out"
wp wpus unblock --ip=203.0.113.10
wp wpus two-factor --disable
wp wpus country --off

# Move a configuration from staging
wp wpus export settings > settings.json
wp wpus import-settings settings.json

# Reports
wp wpus logs --event=admin_login_failed --limit=50 --format=csv
wp wpus export logs --days=30 > security-log.csv
wp wpus digest --send --days=7

Actions

<?php
// Write every new address block to the PHP error log.
add_action( 'wpus_ip_block_created', function ( $row, $manual, $reason ) {
	if ( is_array( $row ) ) {
		error_log( sprintf( 'Blocked %s (%s): %s', $row['value'], $manual ? 'manual' : 'automatic', $reason ) );
	}
}, 10, 3 );

Filters

<?php
// Treat a private lab network as one identifiable client each (local development only).
add_filter( 'wpus_attributable_ip', '__return_true' );

// Add your own default usernames.
add_filter( 'wpus_generic_usernames', function ( $names ) {
	$names[] = 'webadmin';
	return $names;
} );

// Stop treating a legitimate path as an exploit probe.
add_filter( 'wpus_probe_rules', function ( $rules ) {
	unset( $rules['php info page'] );
	return $rules;
} );

// Exempt one single-sign-on account from the email code.
add_filter( 'wpus_two_factor_applies', function ( $yes, $user ) {
	return 'sso-service' === $user->user_login ? false : $yes;
}, 10, 2 );

// Add a scoring rule: 10 points for any request on the XML-RPC endpoint.
add_filter( 'wpus_risk_signals', function ( $result, $context, $account ) {
	if ( 'xmlrpc' === $result['endpoint'] ) {
		$result['signals'][] = array( 'code' => 'my_rule', 'score' => 10, 'reason' => 'My rule' );
		$result['score']    += 10;
		$result['reasons'][] = 'My rule';
	}
	return $result;
}, 10, 3 );

The risk result passed to wpus_risk_signals is an array with the keys decision (allow, suspicious or block), level, score, reasons, signals, block_action (null or an array with type (ip or account), value and reason), allowlisted, admin_target, observed (ip_failures, ip_username_count, ip_account_count, account_failures, account_unique_ips), counters, thresholds, identifier, account, endpoint (wp-login, xmlrpc, rest, wp-admin, woocommerce or other), ip and bot (the bot detection result). The filter runs before the decision, so score and block_action changes take effect.

WordPress and WooCommerce hooks the plugin uses

Where the plugin replaces a result, a plugin hooked earlier on the same hook is ignored for that result, and one hooked later can still change it. The priorities below are the ones the plugin registers.

The bundled licence client also hooks plugin_action_links_<plugin file>, in_plugin_update_message-<plugin file>, pre_set_site_transient_update_plugins, plugins_api (priority 20), http_request_args, http_request_host_is_external and upgrader_process_complete, only where it is loaded.

Admin endpoints and request parameters

• admin-post.php?action=wpus_do is the single endpoint for every change made on the plugin screens. It requires the managing capability and a valid nonce (nonce action wpus_action, field _wpnonce), runs the action named by wpus_action, writes a "Security settings changed" log row ("Manual action "<name>" from the admin screens: completed" or "refused"), stores a notice for the user for five minutes and redirects back. The actions are: block_ip, block_user, unblock, bulk_unblock, permanent, bulk_permanent, delete_block, bulk_delete_block, bulk_delete_logs, add_allowlist, remove_allowlist, emergency, purge_logs, purge_attempts, run_retention, revoke_device, revoke_all_devices, test_mail, send_digest and import_settings. An unknown name answers "That action is not recognised."
• admin-post.php?action=wpus_export&what=<logs|blocks|allowlist|settings>[&days=N]&_wpnonce=... streams a download (see Export and import). days limits the log only.
• Settings are saved through options.php with the option group wpus_settings_group and the option wpus_settings. A filter on option_page_capability_wpus_settings_group makes WordPress require the plugin's capability instead of manage_options. A signed-in user who may not manage the plugin changes nothing.
• Screen addresses: admin.php?page=wpus-dashboard, wpus-logs, wpus-blocked-ips, wpus-blocked-users, wpus-allowlist, wpus-settings, wpus-tools.
• Query and form fields: Dashboard wpus_period (24h, 7d, 30d, 365d, all). Logs wpus_date_from, wpus_date_to (YYYY-MM-DD), wpus_ip, wpus_username, wpus_email, wpus_event, wpus_risk, wpus_result, wpus_admin, s. Block lists wpus_status (active, blocked, permanent, unblocked or empty for any), wpus_period, s. Forms wpus_row[] (row IDs), wpus_bulk and wpus_bulk2 (the top and bottom bulk-action selects), wpus_ip, wpus_identifier, wpus_reason, wpus_permanent, wpus_entry, wpus_label, wpus_state (on or off, for emergency mode), wpus_days, wpus_device, wpus_settings_json and wpus_filter (the filter button). The sign-in code is the POST field wpus_code; the redirect after a voided sign-in adds wpus_2fa=required to the login URL.

Capability, constant and roles

• Capability wpus_manage_security gates every screen, button, download and the settings save. It is added to the administrator role on activation (on multisite only when a super admin activates). A role you create later does not get it automatically; grant it with a role editor.
• Constant WPUS_MANAGE_CAP: define it in wp-config.php to require another capability, for example define( 'WPUS_MANAGE_CAP', 'manage_options' );. It takes precedence over the filter wpus_manage_capability.
• Constants the plugin defines (each only if not already defined): WPUS_VERSION (1.0.0), WPUS_DB_VERSION (1.2.0), WPUS_FILE, WPUS_DIR, WPUS_URL, WPUS_SLUG (wp-user-security-guard) and WPUS_TEXTDOMAIN.
• The function wpus_guard() returns the main plugin object.

Scheduled events

Both are removed on deactivation. The hourly event is re-created on wp_loaded when it is missing; the daily event is created at activation (and for a new site on a network), so deactivating and activating the plugin re-creates it. On a multisite network the plugin adds a daily schedule if the site has none.

Database tables

Five tables, created with dbDelta(), each with the site's table prefix. All times are site-local (WordPress timezone) DATETIME values. All SQL lives in one class, WPUS_Database, with prepared statements.

{prefix}wpus_attempts (counters)

Failed and refused attempts only. Columns: id BIGINT unsigned auto-increment (primary key), created_at DATETIME, ip_address VARCHAR(45), username VARCHAR(100), email VARCHAR(100), user_id BIGINT unsigned, endpoint VARCHAR(16) (wp-login, xmlrpc, rest, wp-admin, woocommerce or other), result VARCHAR(16) (failed or blocked), risk_score SMALLINT unsigned, risk_level VARCHAR(12), reason VARCHAR(191), user_agent VARCHAR(191) (present, but the plugin never writes a value into it). Indexes on time, address, username, email, user, result and the combinations address and time, username and time, email and time.

{prefix}wpus_blocks

Columns: id, block_type VARCHAR(16) (ip, account or user), value VARCHAR(191) (the address, the normalised username or email, or the user ID), username, email, user_id, status VARCHAR(16) (blocked, permanent or unblocked), permanent TINYINT, reason VARCHAR(191), detail TEXT (JSON: counters, trigger, escalation level), attempt_count BIGINT, unique_ips INT, first_detected, last_detected, blocked_at, blocked_by (administrator's user ID; 0 for automatic blocks and blocks made from WP-CLI), unblocked_at, unblocked_by, unblock_reason VARCHAR(191) (the marker "Released automatically" for an automatic release), expires_at (only automatic, non-permanent blocks with automatic release on) and block_count INT (starts at 1, increased on every re-block). Unique key on block_type and value; indexes on expiry, status, type and status, user and blocked_at.

{prefix}wpus_logs (the security log)

Columns: id, created_at, event_type VARCHAR(32), risk_level VARCHAR(12), risk_score SMALLINT, ip_address VARCHAR(45), user_id, username, email, endpoint VARCHAR(16), request_method VARCHAR(8), user_agent VARCHAR(191), result VARCHAR(16), reason VARCHAR(191), is_admin TINYINT and context TEXT (redacted JSON). Indexes on time, administrator flag, event, risk, address, user, username, email and result, with combinations.

{prefix}wpus_allowlist

Columns: id, entry VARCHAR(191) (canonical address or CIDR range, unique), entry_type VARCHAR(8) (ip or range), label VARCHAR(191), added_by (the user ID of the administrator who added it, or whose sign-in created an automatic entry; 0 from WP-CLI), added_at and expires_at (NULL for entries typed in by hand).

{prefix}wpus_devices (remembered browsers)

Columns: id, user_id, device_hash CHAR(64) (SHA-256 of the cookie token), ua_hash CHAR(64) (SHA-256 of the User-Agent string), label VARCHAR(191), ip_address VARCHAR(45), created_at, last_seen_at and expires_at. Unique on user_id and device_hash.

Options, user meta, transients and cookies

The hashes in transient names are MD5 of the address (or of the throttle subject), not secrets.

Licence client constants and filters

The bundled client (WPXH_Licence_Client_V2) talks to https://wpexpertshub.com/wp-json/wphub-licence/v1/. The constant WPXH_LICENCE_SERVER and the filter wpxh_licence_server override the server address, and wpxh_licence_sslverify turns certificate checking off (it is automatically off only for a local development server such as .local, .test or localhost). The first copy of the class loaded by any WpExperts Hub plugin is the one that runs, and one screen manages all of those plugins.

File layout

• wp-user-security-guard.php: constants, class loading, activation and deactivation hooks, licence registration.
• uninstall.php: removes data only when Delete plugin data on uninstall is ticked.
• includes/: one class per concern (database, settings, request, roles, allowlist, logger, country, block lifecycle, IP blocker, user protection, bot detection, generic usernames, probe protection, trusted admins, WooCommerce, risk engine, login protection, two-factor, XML-RPC protection, admin protection, notifications, digest, diagnostics, export, system info, privacy, list tables, admin, WP-CLI and the main container).
• admin/views/: dashboard.php, logs.php, blocks.php, allowlist.php, settings.php, tools.php.
• assets/css/admin.css and assets/js/admin.js: loaded only on the plugin screens and on the WordPress Dashboard (for the widget), and only for users who can manage the plugin. The script has no dependencies; it adds confirmations, bulk-action checks, the country filter, the role pickers and the settings navigation.
• licence/: the bundled licence and update client.
• languages/wp-user-security-guard.pot: the translation template. No translations are shipped, and load_plugin_textdomain() is called only when the plugin is not in the folder wp-content/plugins/wp-user-security-guard.

9. Privacy

User Security Guard keeps its security data in your own database and sends none of it to WpExperts Hub or anyone else. The only outside contact is the licence and update check, described below.

10. Troubleshooting

11. FAQ

12. Changelog

1.0.0 - 2026-10-02

• Initial release.
• Login protection with per-IP, per-username and per-email failed-attempt thresholds, a rolling window and a configurable "suspicious" tier.
• Distributed-attack detection: many IP addresses attacking one account.
• Bot and automation detection (frequency buckets, missing browser headers, automation User-Agents, sustained hammering, XML-RPC automation), capped so signals never block a browser on their own.
• A central, filterable authentication risk engine producing one decision per request: allow, suspicious or block.
• Administrator protection: stricter thresholds, dedicated admin logs and a "never auto-block an administrator" guard rail.
• Generic login errors, so failed logins never reveal which usernames exist.
• XML-RPC protection with a generic 403 and per-IP escalation.
• Blocked IP and blocked account screens with View, Unblock, Permanent and Delete actions — manual only, never automatic.
• Allowlist for exact IP addresses, CIDR ranges and 10.0.0.* shorthand.
• Security log with 20 event types, filtering, redaction and configurable retention.
• Dashboard, dashboard widget, settings, tools and system report screens.
• Throttled per-type administrator notifications.
• Optional automatic release of automatic blocks (off by default), repeat-offender memory, a country rule that uses your CDN's country header, and optional early refusal of blocked addresses.
• A redesigned admin: one tab bar, status tiles, a 14-day activity chart, section navigation and a sticky save bar on Settings.
• WooCommerce sign-in form protection (detected automatically), default-username detection, exploit path probing (404s) and optional trusted administrator addresses.
• The optional email sign-in code now covers every sign-in form (including the WooCommerce form) and a list of roles — administrator, editor, author and shop manager by default — with a safety net for a sign-in that would skip it, a one-code-a-minute limit, a per-account trusted-browser cookie and a test email button.
• Alerts to the site owner when somebody tries to get into a watched account (roles are configurable), when somebody has the password but fails the code, and (optionally) when a watched account signs in.
• WordPress privacy tools: suggested policy text plus export and erase for log data.
• Scheduled security digest (daily, weekly or monthly) with a per-day threat level.
• Optional longer blocks for an address that keeps coming back after the automatic release.
• Sign-in diagnostics on Tools: the address the plugin sees, the header to choose behind a CDN, and every other callback or login-limiting plugin on the sign-in.
• CSV export of the log, blocks and allowlist (formula-safe, with a visible marker if a file is cut at the row limit), JSON export of the settings, and a settings import that never touches the server-specific, lockout-prone or opt-in loosening settings and names everything it changed.
• Optional privacy notice under the sign-in forms.
• A block made from WP-CLI (wp wpus block --ip=…) now counts as an administrator's block: it never gets an expiry and can replace an active automatic block.
• WP-CLI commands (wp wpus), including the documented lockout-recovery unblock, digest, diagnose, export and import-settings.
• No database work on ordinary page views; every SQL statement lives in one repository class.

13. Support

Email support@wpexpertshub.com and a person will help. Please include:

• Your order ID (from your purchase email or My Account on wpexpertshub.com).
• The plugin version (shown in the header of every User Security screen, for example "Version 1.0.0"), and the WordPress and PHP versions (User Security → Tools → System information lists them).
• What you expected, what happened, and what you already tried. The relevant rows from User Security → Security Logs (the reason and the detail) and the output of wp wpus diagnose help a great deal.
• Whether the site is behind a CDN or proxy, and whether another security plugin is active.

Please do not email passwords. If you are locked out, try the steps under Troubleshooting first: wp wpus unblock works without a browser session.