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 total-security-wp 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 Total Security WP in the admin menu. The Setup Wizard starts automatically on first run.
4. Work through the wizard, then review Total Security WP → Settings and enable two-factor authentication for every administrator.

Installing via WP-CLI

wp plugin install total-security-wp --activate
wp total-security-wp status

The Setup Wizard

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 Total Security WP admin menu, entirely inside wp-admin. It is independent of your active theme and works identically on block and classic themes.

Capability

Access is gated on the manage_total_security_wp 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.

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.

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 — progressive lockout on repeated failed logins, counted per IP and per username so an attacker cannot rotate one to escape the other.
• DDoS shielding — detects request floods and sheds load before they reach the WordPress bootstrap.
• Bad-bot blocker — blocks scrapers and vulnerability scanners by user-agent and behaviour, with verification for bots that claim to be search engines.
• Geo-blocking — country-level allow or deny lists, appliable to the whole site or to the login and admin surfaces only.

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 patching applies approved patches as new CVEs are published, without waiting for you to log in. 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. Total Security WP 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.

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.

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, with CSV export. Free
• Extended retention, scheduled email digests and PDF export. 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.

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. Free
• WooCommerce delta backup — capturing orders and customer records between full backups, where a nightly-only cadence would lose a day of transactions. Pro

Emergency recovery

The worst moment to discover your recovery plan needs a working wp-admin is when wp-admin will not load. Total Security WP 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.
• 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.
• Session management — see every active session for an account and terminate any of them.
• 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 on the login form. Off by default; enabling it loads that provider's script on the login page only.
• 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.
• Impossible-travel detection — flags a login from a location the account could not physically have reached since its last one. 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 uptime monitoring, for teams already running an on-call rotation.

WP-CLI

All commands live under the wp total-security-wp namespace.

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

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

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

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

# Clear a locked-out user's 2FA enrolment
wp total-security-wp 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/total-security-wp/v1/

Every route requires the manage_total_security_wp 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: TOTALSECWP_VERSION, TOTALSECWP_SLUG, TOTALSECWP_REST_NAMESPACE, TOTALSECWP_CAP, TOTALSECWP_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: aggressive rate limits, a bot challenge wall, REST/XML-RPC/login lockdown, and automatic expiry so you cannot leave it on by accident.
• Sentinel AI — builds a redacted evidence bundle for a suspicious actor and returns a threat verdict with a recommended action. Opt-in, consent-gated, and it falls back to local rule-based triage when disabled.
• Cloud reputation — distributed file and IP verdicts from a shared reputation network, cached locally.
• Compliance reporting — control coverage mapped to common frameworks, exportable as PDF for an auditor.
• Agency tooling — white-label dashboard, security roles, multisite support, and a hub-and-satellite model where many sites report into one console.

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