WordPress plugin guide

Quickstart

1. Open Plugins → Add New Plugin, search for Witen Blocker, then install and activate it. Login lockout, comment checks, and daily scans start immediately.
2. Add your own address under Witen → Firewall → Never-block list. Behind a proxy or CDN? Check the client address first.
3. Choose which crawlers may read your site under Witen → Firewall → Bots and AI crawlers.
4. Set up two-factor sign-in from your user profile and keep the recovery codes somewhere safe.
5. Review Witen → Dashboard and Witen → Scan. Never test a ban against your own address.

Everything above works without a Witen account. Connecting one is optional and covered below.

Requirements

• WordPress 6.2 or newer and PHP 8.1 or newer.
• An administrator account that can install plugins.
• For shared intelligence: a Witen account and a free slot on your plan. Local login protection, bot controls, and file-integrity checks work without enrollment.
• To connect: outbound HTTPS to Witen, or access to Warden's ingest socket on the same server.

Check it's working

• Witen → Settings shows the installed version.
• Witen → Firewall → Never-block list and Witen → Firewall → Bots and AI crawlers show the addresses and policies you chose.
• A run of Witen → Scan completes. Check each finding before deleting anything; some are false positives.
• Witen → Dashboard fills with activity as requests arrive. An empty list is normal on a quiet site.

These checks do not require an enrollment token or a connection.

Login limits

Five failed logins in five minutes earn a one-hour ban. Add your own address to the allowlist before you change anything, and keep SFTP or hosting-panel access as a way back in.

Open Witen → Login to save limits or restore the configured defaults. The same controls are available in Settings. With WP-CLI, set them directly (seconds, failures, seconds):

wp option update witen_login_window_sec_override 300
wp option update witen_login_max_failures_override 5
wp option update witen_login_ban_sec_override 3600

Limits: a window up to 86,400 seconds, up to 100 failures, and a ban up to 864,000 seconds. On Multisite, add --url=https://your-site.example. Saved overrides take precedence over WITEN_LOGIN_* constants, which take precedence over built-in defaults. Delete the three options or restore defaults in Login to use your configured constants again. Changing a limit doesn't lift an existing ban.

Locked out? Follow Recover login access.

Connect to the Witen network

Connecting adds the shared threat feed and sends security events to Witen. See what's shared first.

1. In your Witen dashboard, open Add Protected Asset and choose WordPress.
2. Name the site and generate a one-time enrollment token.
3. Paste the token into Witen → Settings, or define it in wp-config.php above the “stop editing” line.

define( 'WITEN_ENROLLMENT_TOKEN', 'wte-one-time-token' );

// Only for a self-hosted collector.
define( 'WITEN_COLLECTOR_URL', 'https://collector.example' );

// Only when Warden runs on the same server.
define( 'WITEN_SOCKET_PATH', '/run/witen/warden-ingest.sock' );
define( 'WITEN_WARDEN_CREDENTIAL_FILE', '/var/lib/witen-wordpress/caller.token' );

// Optional: a fixed site ID instead of the generated one.
define( 'WITEN_SITE_ID', 'shop-production' );
define( 'WITEN_SYNC_INTERVAL', 300 );

Check the connection

Connected installations only.

• Witen → Settings shows a credential and a recent maintenance run.
• The Dashboard shows the mode you expect: Warden socket or collector HTTPS.
• A blocklist sync has completed without errors.
• Your Witen dashboard lists the site with a recent report.
• WordPress cron runs. If maintenance stalls for ten minutes, administrators see a warning.

Plugin pages

Without Warden, the plugin bans for repeated login failures itself. With Warden, the plugin reports the failures and Warden decides, counting each attempt once. Warden then holds the ban, and the Witen blocklist, in the server firewall. The IP Blocklist marks those addresses Held by Warden and shows how to lift them on the server.

Security scan

1. Open Witen → Scan and start with the summary.
2. For each finding, check the file path, type, evidence, and severity.
3. Compare unexpected files with a clean copy or backup.
4. Remove or quarantine a file only once you're sure it isn't legitimate code.
5. Scan again and check the site still works.

Connected sites download signed detection catalogs. The plugin checks each catalog's signature, hash, and version before using it, and never runs catalog content as code.

Data and privacy

WITEN_NO_TELEMETRY turns off the daily WordPress, PHP, and plugin version report. To stop reporting entirely, remove the stored credential, unused tokens, and any socket settings. The full field list is in What data Witen receives.

WordPress Multisite

Each site in a network keeps its own state, queue, and identity. Unless you define WITEN_SITE_ID, each gets a generated ID starting with wordpress-. If you set one, keep it unique per site.

• Activate and connect each site in its own context.
• Check each site appears in your Witen dashboard.
• Never copy a credential from one site to another.
• Test cron and blocklist sync on each site, not just the main one.

Upgrade and remove

Troubleshooting