Documentation

Requirements

The admin dashboard is a React application that runs on WordPress core's own bundled wp-element, loaded as native ES modules. Every PHP class is resolved by a small built-in autoloader. There is nothing to build and no vendor directory to install.

Installation

1. Upload the loyal-security folder to /wp-content/plugins/, or install it from Plugins → Add New.
2. Activate it from the Plugins screen. Activation creates the plugin's tables and default settings; it does not yet change anything at the server level.
3. Open Loyal Security in the admin menu. The Setup Wizard starts automatically on first run.
4. Work through the wizard, then review Loyal Security → Settings and enable two-factor authentication for every administrator.

Installing via WP-CLI

wp plugin install loyal-security --activate
wp loyal-security status

The Setup Wizard

Before anything technical happens, the wizard asks what kind of site this is — blog or content site, store, or agency-managed site — and uses the answer for two things: which starting settings it recommends (a store leans on backups and integrity monitoring; an agency setup points you at white-labelling and Hub once the wizard finishes) and which dashboard view you land in by default, Basic for a blog or store, Advanced for an agency setup. Both can be changed later from the dashboard.

The wizard probes your hosting environment and deploys the firewall in the strongest mode the server actually supports, rather than asking you to guess. It runs four steps:

1. Server probe — detects the PHP SAPI (mod_php, CGI, FPM), whether auto_prepend_file can be set, and whether .user.ini is writable.
2. Firewall deployment — writes the prepend bootstrap and bundles the WAF kernel outside the plugin directory so it survives plugin updates.
3. Self-test — issues a loopback request carrying a benign test payload to confirm the deployed firewall actually intercepts traffic.
4. Rollback on failure — if the self-test does not come back clean, the wizard removes what it wrote and falls back to Standard Mode. It never leaves a half-deployed prepend behind.

You can re-run the wizard at any time from the dashboard — for example after moving hosts, where the right firewall mode may have changed.

The dashboard

Everything lives under the Loyal Security admin menu, entirely inside wp-admin. It is independent of your active theme and works identically on block and classic themes.

Basic and Advanced views

Every admin has their own view preference, synced to their account rather than the browser, so it follows them between devices. Basic keeps the dashboard to what a single-site owner actually touches day to day; Advanced exposes the rest — Custom Sources in the CSP manager, the REST route inventory, bypass telemetry, and Agency & Hub. Switch any time from the toggle at the top of the sidebar; nothing is disabled, only hidden until you ask for it.

New installs default to Basic or Advanced based on the site type chosen in the Setup Wizard; installs upgrading from an earlier version keep seeing everything they already had, in Advanced.

Capability

Access is gated on the manage_loyal_security capability, granted to administrators on activation. Grant it to a custom role to give a security contractor access to the dashboard without making them an administrator. On a multisite network only super admins can manage the plugin, because its settings change files the whole network shares (.htaccess, .user.ini, wp-config.php).

Firewall & WAF modes

The web application firewall scores each request against a signature set covering SQL injection, cross-site scripting, local and remote file inclusion, path traversal, remote code execution and SSRF. Requests that cross the block threshold are terminated; requests that score but do not cross it are logged for review.

Getting the real visitor IP right

Behind Cloudflare, a load balancer or any reverse proxy, REMOTE_ADDR is the proxy — blocking on it would ban every visitor at once. Set the trusted proxy header under Settings → Firewall so bans, rate limits and the audit log all record the true client address. Only trust a header your proxy actually sets and strips from inbound requests.

Addresses that arrive with a port attached, as they do behind Azure App Service, are read correctly. Forwarded headers are read from the nearest hop outwards, so a visitor cannot claim an address that is not theirs. If your site sits behind more than one proxy, add each of them under Trusted proxies.

Rate limiting, brute force & bots

• Rate limiter — per-IP request budgets over a rolling window, with a separate, tighter budget for wp-login.php and the REST authentication routes.
• Brute-force protection — after 5 failed sign-ins (adjustable) sign-in is locked for that address, with longer lockouts for repeat offenders. The lock covers signing in only, so a customer who forgot a password can still browse and check out; only clearly automated guessing (four times the limit in one window) bans the address from the site. Failures before your last successful sign-in do not count.
• DDoS shielding — detects request floods and sheds load before they reach the WordPress bootstrap.
• Bot management — an editable, admin-controlled trust/block list for bot signatures, not a fixed filter: whitelist a crawler you rely on, block one you have spotted abusing the site, with reverse-DNS verification for bots that claim to be search engines. Vulnerability scanners are always blocked. Two groups are off by default because legitimate traffic uses them — HTTP clients such as curl and python-requests (payment webhooks, integrations) and SEO crawlers such as Ahrefs and Semrush — and can be switched on under Firewall → Blocked Bot Groups.
• Geo-blocking — country-level allow or deny lists, appliable to the whole site or to the login and admin surfaces only. Works without a CDN, using a bundled IP-to-country table (IP Geolocation by DB-IP); a CDN’s country header is used only when the request really came through it.
• Switching from another security plugin? — one click imports your existing IP block/allow list from Wordfence, Sucuri or iThemes/Solid Security.
• Cloudflare Edge Sync — pushes your blocked bot signatures to Cloudflare Custom Rules so they are rejected at the edge, before they reach your server; any rule you added yourself in Cloudflare is left untouched. Pro
• Trust badge — a [loyal_security_badge] shortcode for your own footer or sidebar, showing a real, live 30-day attack count. Off by default; switch it on from the Firewall screen.

Virtual patching

When a vulnerability is published for a plugin or theme you have installed, there is a gap between disclosure and the moment you can safely apply the vendor's fix. A virtual patch closes that gap at the firewall: a targeted rule that blocks the specific request shape the exploit needs, without touching the vulnerable code.

• Bundled patches ship with the plugin and cover widely exploited CVEs in popular plugins. Free
• Custom patches let you write your own rule for something specific to your stack. Free
• Suggested patches are generated by correlating your installed plugin inventory against known advisories. Free
• Patch-gap intelligence flags plugins with a public CVE but no vendor fix yet — the highest-risk window there is. Pro
• Automatic fixes for vulnerable plugins: when WordPress.org has the version that fixes a published vulnerability in a plugin you run, Pro has WordPress update it within the hour, with WordPress’s own rollback if the update breaks the site. Pro

A virtual patch is a stopgap. Apply the real update as soon as your release process allows.

Hardening

Each hardening control is individually toggleable, states plainly what it changes, and can be reverted from the same screen. Nothing is applied silently.

Content Security Policy

A hand-written CSP usually breaks a WordPress site, because no one can enumerate every script a theme and twenty plugins load. Loyal Security builds one by observation instead:

1. The CSP scanner crawls your own pages and records the sources actually in use.
2. A candidate policy is proposed from that inventory, with each source shown alongside what requested it.
3. You run it in report-only mode. Violations collect in a dashboard list rather than breaking anything.
4. When the violation stream is quiet, you promote the policy to enforcing.

Pending sources are held in their own queue, so a source that appears after a plugin update surfaces as a decision to make rather than as a silently broken page.

In Basic view, this happens automatically: the scanner runs once on first visit to CSP Manager, and if a safe baseline is found (WordPress core plus recognised services like Google Fonts or a CDN) it is applied for you in report-only mode — there is no separate Service Presets step to walk through. Advanced view keeps the full manual workflow, including custom directives and per-source detail.

Once a policy has been quiet in report-only mode for a stretch, the dashboard suggests promoting it to enforcing rather than waiting for you to remember to check. You can promote it straight from the suggestion or ignore it and switch modes manually whenever you're ready.

Malware scanner

The scanner combines three detection strategies, because signature matching alone misses anything new and heuristics alone produce noise:

• Signature matching against a bundled malware signature database.
• Token analysis, which parses PHP into tokens rather than matching raw text — so obfuscation through concatenation, encoding or variable functions does not hide a payload.
• Taint analysis, which traces untrusted input to dangerous sinks to catch backdoors that no signature covers.

What gets scanned

• Every PHP, JavaScript and HTML file under the WordPress root, including mu-plugins and drop-ins.
• The database — posts, comments, options and user meta — for injected spam, malicious redirects and rogue administrator accounts.
• Deep database scan — also page-builder data, categories, snippet plugins and site settings, for outside scripts, obfuscated JavaScript, stored PHP, site-address hijacks, open admin registration and hidden administrators. Findings can be removed in place and put back. Pro
• Rendered pages — a sample of pages is loaded as a desktop visitor, a mobile visitor and a visitor from Google search, and every outside script WordPress did not load itself is reported with where it is stored. Pro

If the site was hacked

The Under Attack screen in Pro has a guided recovery: take a forensic backup, investigate (files, database, pages, accounts, recent changes and audit-log integrity in one report), clean (Clean Site, database findings, unrecognised administrators), lock down (new security keys, everyone else signed out, new passwords, closed registration, no dashboard code editing, two-factor required), then verify and keep a printable incident report. Pro

Scheduling

• On-demand full scans, any time. Free
• A weekly automatic baseline scan on every install. Free
• Daily or twice-daily scheduled scans with emailed results. Pro
• Auto-quarantine of infected files the moment a scan finds them. Pro

Handling false positives

Any finding can be whitelisted, individually or in bulk. Whitelisting is recorded by file and content hash, so a whitelisted file that later changes is flagged again rather than being trusted forever.

File integrity monitoring

Integrity monitoring answers a different question from the scanner: not “does this look malicious?” but “is this the file the author shipped?”

• Checksum verification — core, plugin and theme files are compared against the official WordPress.org checksums, the same source core uses for update checks. Any modification is reported with a diff.
• Baseline diffing — for everything without published checksums (custom themes, premium plugins, mu-plugins, drop-ins), the plugin records a baseline and reports every subsequent addition, change and deletion.

Live Traffic

A real-time feed of requests hitting the site, with each visitor classified as human, verified search engine crawler, or unverified bot. Two views: security events only, or all traffic. Any address can be blocked or unblocked in one click straight from the feed, and the whole view exports to CSV for an incident write-up.

Audit log

A full event trail of everything security-relevant: logins and failures, user and role changes, plugin and theme activity, settings changes, file events and firewall decisions. Each entry records the acting user, the source IP, the proxy chain and the request context.

• 90-day retention by default (adjustable in the audit settings), with CSV export. Free
• A row limit, a storage summary with a “Clear audit log” button, and a Site Health check, so the log cannot quietly outgrow the site. Repeated identical events are summarised in one row. Free
• Scheduled weekly email digests and print-ready reports. Pro

The incident correlator groups related events into a single narrative — a login failure burst, a successful login from a new country, then a plugin file edit reads as one incident rather than three unrelated rows.

Sentinel AI Pro

Sentinel reviews suspicious activity — firewall near-misses, anomalous login patterns, scanner findings that didn't cross the auto-quarantine threshold — and returns a verdict with a recommended action, instead of leaving you to correlate raw events yourself. It runs on a 5-minute cycle and falls back to local rule-based triage whenever the cloud AI is unavailable or you're out of credits, so a quiet month never leaves the site unmonitored.

Switching into Autonomous mode asks for confirmation first, and the kill switch drops Sentinel back to Shadow instantly if it ever needs to be stopped mid-response. Resuming afterwards returns you to whichever mode was active before the kill switch fired — never a silent promotion back to Autonomous.

Allowed actions are opt-in individually: banning or rate-limiting an IP, applying a live virtual patch, terminating a session or user, and escalating into Under Attack Mode. Any autonomous action is reversible, capped at 25 actions an hour, and a full site lockdown always waits for a human to approve it regardless of mode.

Sentinel also watches bot traffic specifically: once it has seen enough requests from a signature to form a verdict, it suggests trusting or blocking it, shown in the Bot Management screen's review queue. In Review mode you accept or reject each suggestion by hand; in Autonomous mode, a high-confidence verdict is applied on its own — it will never touch an already-trusted crawler like Googlebot.

Once a mode has been running quietly for a while, the dashboard suggests moving up a level — Shadow to Review, Review to Autonomous — the same way the CSP manager suggests promoting a quiet policy to enforcing. It's a nudge, not a requirement; the manual mode switch is always there underneath.

Quarantine & repair

Finding an infected file is the easy part. The plugin's incident tooling is built around never making a bad situation worse:

• Quarantine — the file is moved to a protected store rather than deleted, so a false positive is one click from being restored.
• Clean-file recovery — modified core, plugin and theme files are replaced with the authentic copy fetched from WordPress.org.
• Plugin reinstall — a badly infected plugin can be reinstalled from source asynchronously, without a timeout on a large site.
• Repair backups — every repair snapshots what it replaced first, with its own retention setting.
• Permission reset — restores sane file and directory modes after an attacker has loosened them.
• Bulk triage — on a heavily infected site, findings are grouped so you can repair everything of one kind in a single operation.

Backup & restore

On-demand full-site backups covering both files and the database, written in chunks so large sites do not hit a PHP timeout. Backups are listed with their manifest, and the list degrades gracefully rather than erroring if a manifest becomes unreadable.

• On-demand full backup and restore, with a free-space check before a backup starts. Free
• WooCommerce delta backup — capturing orders and customer records between full backups, where a nightly-only cadence would lose a day of transactions. Pro
• Off-site copies — every new backup is copied to storage you own (Amazon S3, Backblaze B2, Wasabi, Cloudflare R2 or any S3-compatible service), and any copy can be brought back, checked against its checksums, and restored. Pro

Emergency recovery

The worst moment to discover your recovery plan needs a working wp-admin is when wp-admin will not load. Loyal Security ships a standalone recovery endpoint that runs independently of WordPress: it can restore a backup even when WordPress itself is fatal.

1. Enable recovery under Settings → Backup.
2. Download the generated recovery script and note its credentials. The script is generated on demand, not shipped as a static file in the plugin — a permanent recovery endpoint sitting in every install would itself be an attack surface.
3. Store it somewhere you can reach without the site. It can be re-downloaded any time while recovery stays enabled.

Two-factor authentication

TOTP-based two-factor authentication, compatible with any standard authenticator app. Enrolment is by QR code, with one-time backup codes issued at the same time.

• Enforcement by role — require 2FA for administrators and editors while leaving subscribers alone.
• A grace period, not a cliff edge — when you turn on required 2FA, affected users get a configurable window (7 days by default) with a dismissible reminder before enforcement bites, so rolling it out doesn't lock your own team out mid-afternoon. An administrator can extend or end the grace period for any individual user.
• Trusted devices — optionally let a user skip the second factor on one browser for 30 days, with a self-service list and one-click revoke. Administrators get the fleet view: search and filter every user's trusted devices across the whole site, and revoke any of them — the tool for the moment you learn a specific laptop was compromised and need it locked out now, not after that user gets around to it.
• Session management — see every active session for an account and terminate any of them.
• Self-service removal — any user can remove their own 2FA from their profile page, even roles below Administrator that don't otherwise have access to the security dashboard. No support ticket required for the common case.
• Admin reset — an administrator can clear a locked-out user's 2FA enrolment, from the dashboard or via WP-CLI.

Login protection

• CAPTCHA — optional Cloudflare Turnstile or Google reCAPTCHA v3, covering the login, registration, and lost-password forms. Off by default (no provider configured); set one up and all three are protected immediately, with a toggle to opt any of them back out individually. The provider's script only loads on wp-login.php, never elsewhere on the site.
• Password policy — minimum length and complexity, enforced per role.
• Breached-password check — on login, the password is checked against the Have I Been Pwned Pwned Passwords corpus using k-anonymity: only the first five characters of a SHA-1 hash ever leave your server, and the password itself never does. It warns the user; it never blocks the login.
• Custom login URL — move wp-login.php to a path of your choosing to shed automated login traffic. On Nginx the plugin shows the exact server rules to copy or download before you save, a recovery note, and sends a confirmation email.
• Emailed sign-in codes — a login from a country the account has not used in 90 days waits for a one-time code sent to the account’s email; accounts with two-factor authentication, passkeys and API logins skip it. Pro
• Impossible-travel detection — flags a login from a location the account could not physically have reached since its last one, and asks for the emailed code (or signs the account out everywhere, if you prefer). Pro

Notifications

Alerts go out by email or webhook — Slack and Microsoft Teams incoming webhooks work out of the box. Every notification carries human-readable guidance explaining what the event means and what to do about it, rather than a bare event code.

• Per-event-type muting, so one chatty rule does not train you to ignore the channel.
• A sent-history log, so you can confirm whether an alert actually went out.
• PagerDuty and Opsgenie adapters, and outside-in uptime monitoring, for teams already running an on-call rotation. Pro

WP-CLI

All commands live under the wp loyal-security namespace.

# Overall posture, module status and security score
wp loyal-security status

# Full malware scan (--quick limits it to high-risk paths)
wp loyal-security scan
wp loyal-security scan --quick

# List active firewall rules and virtual patches
wp loyal-security firewall list

# Take a full backup (files + database)
wp loyal-security backup create

# Audit log size, and trimming it to a row budget
wp loyal-security logs stats
wp loyal-security logs prune --budget=300

# Clear a locked-out user's 2FA enrolment
wp loyal-security twofa reset admin

These are the commands to reach for in a deploy pipeline: run a scan after a release, take a backup before a migration, and check status in a health check.

REST API

The dashboard is a client of the plugin's own REST API, which means anything the dashboard can do, your own tooling can do too. All routes live under:

/wp-json/loyal-security/v1/

Every route requires the manage_loyal_security capability and a valid nonce or application password. Controllers are grouped by module — status, firewall, scanner, quarantine, repair, backup, logs, traffic, hardening, auth, notifications, settings, jobs and the setup wizard — with Pro modules exposing their own routes when licensed.

Long-running work (scans, backups, bulk repairs) runs as a job: the route returns a job handle immediately and progress is polled, so nothing depends on a single long HTTP request surviving.

Configuration constants

Define these in wp-config.php above the “stop editing” line.

Read-only constants you can reference from your own code: LOYALSEC_VERSION, LOYALSEC_SLUG, LOYALSEC_REST_NAMESPACE, LOYALSEC_CAP, LOYALSEC_MIN_PHP.

Pro modules

Pro is aimed at people running security as an ongoing operation rather than a one-time install. Full detail on the Pro page; in short:

• Threat intelligence — hourly WAF signature updates and CVE-matched virtual patching from a live advisory feed, with cryptographically verified signature bundles.
• Under Attack Mode — a one-click emergency shield: a one-second browser check for anonymous visitors (built in, or Cloudflare’s own “I’m Under Attack” level), comments, XML-RPC and anonymous REST writes switched off while WooCommerce checkout and payment callbacks keep working, one failed sign-in locks sign-in from that address for an hour, only administrators stay signed in, every protection its own switch, and automatic expiry so you cannot leave it on by accident.
• Sentinel AI — opt-in, consent-gated autonomous response with a full audit trail. Included monthly credits cover typical usage, with top-up packs for sites under sustained attack — see Sentinel AI above for how modes, the kill switch and allowed actions work, or Pro pricing. Its case history is kept on a schedule, so the database table stays small.
• Cloud reputation — distributed file and IP verdicts from a shared reputation network, cached locally.
• Compliance reporting — control coverage mapped to common frameworks, as a print-ready report an auditor can keep as a PDF.
• Uptime & site monitoring — outside-in checks every 5 minutes, certificate and domain expiry reminders, and a daily outside check for defacement, injected spam and new outside scripts.
• Firewall rule builder — block a kind of request or put a path behind a login from plain choices; each rule is tested with the firewall’s own engine and refused if it would catch everyday requests unless you confirm it.
• Licence status and renewal reminders — the licence card shows the date your licence is valid until. The WordPress admin warns you 14, 7, 3 and 1 days ahead, with a Renew button and a “Remind me later” that hides a reminder for a week. If Pro stops running it says why: a licence to renew, a licence that is no longer valid for this site, or a site that cannot reach our servers.
• Tamper-evident audit log — entries fingerprinted into a hash chain recorded with Loyal Security, with a daily check for edited or deleted entries. Off until you turn it on.
• Agency tooling — white-label dashboard and security roles for any Pro site, a network-admin overview for a real WordPress Multisite network, and, on the Agency plans, Loyal Hub: every client site in one dashboard, acted on in bulk with actions you sign with your passkey and each site checks before it runs.

Troubleshooting

Uninstalling

Deactivating or deleting the plugin behaves predictably, and the two categories are treated differently on purpose:

• Server-level changes are always reverted on delete — the firewall prepend, generated .htaccess and Nginx rules, and wp-config markers. These are removed regardless of your settings, because leaving them behind could break a site that no longer has the plugin to manage them.
• Your security data is kept by default — audit logs, scan history and settings stay in the database so a reinstall picks up where you left off.

For a complete wipe, enable Delete all data on uninstall under Settings before removing the plugin. Once the plugin is gone, its uninstall routine can no longer run.

Support