WordPress Plugin

Plugin Overview

The WebDecoy WordPress plugin provides comprehensive bot protection for WordPress sites without writing any code. All detection and protection works locally — no API key or WebDecoy account required. It combines server-side detection, client-side JavaScript scanning, behavioral scoring, an invisible proof-of-work challenge, and form protection. Connecting to WebDecoy Cloud (optional) adds dashboard sync and cross-site actor intelligence.

Features

Feature	Description
Server-Side Detection	IP analysis, rate limiting, user-agent checking
Client-Side Scanner	JavaScript-based bot and automation detection
Form Protection	Honeypot fields for comments, login, registration
WooCommerce Protection	Checkout velocity limiting, card testing detection
Good Bot Handling	Allowlist for search engines, social bots, AI crawlers
Local Blocking	Block IPs directly in WordPress
Invisible PoW Challenge	Suspicious visitors solve a proof-of-work page before proceeding
Statistics & Export	Local statistics page with trends, CSV export of detections
Cloud Sync (optional)	Sync detections to the WebDecoy dashboard with an API key

How It Works

WordPress Request
       │
       ▼
┌─────────────────────────────┐
│    WebDecoy Plugin         │
├─────────────────────────────┤
│  1. IP Block Check          │
│  2. Rate Limit Check        │
│  3. Good Bot Check          │
│  4. Server-Side Analysis    │
│  5. Client-Side Scanner     │
├─────────────────────────────┤
│  Decision: Allow/Block      │
└─────────────────────────────┘
       │
       ▼
Detection → Stored locally + Synced to WebDecoy

---

Installing the WordPress Plugin

Method 1: Download from CDN (Recommended)

1. Download the Plugin

   • Go to https://cdn.webdecoy.com/wordpress/
   • Download the latest webdecoy-x.x.x.zip file

2. Upload to WordPress

   • In WordPress Admin, go to Plugins → Add New
   • Click Upload Plugin
   • Choose the downloaded ZIP file
   • Click Install Now

3. Activate

   • Click Activate Plugin
   • You’ll see “WebDecoy” in the admin menu

Method 2: Manual Installation

1. Download and Extract

   unzip webdecoy-x.x.x.zip

2. Upload via FTP

   • Upload the webdecoy folder to /wp-content/plugins/

3. Activate in WordPress

   • Go to Plugins in WordPress Admin
   • Find “WebDecoy” and click Activate

Verifying Installation

After activation:

• “WebDecoy” menu appears in WordPress Admin
• Status shows “Plugin Active”
• Database tables are created automatically

---

Plugin Configuration

Accessing Settings

1. Click WebDecoy in the WordPress Admin menu
2. Click Settings
3. Configure options across multiple tabs

Settings Tabs

Tab	What it controls
Protection (default)	Sensitivity, block threshold, rate limits, trusted-proxy settings
Good Bots	Search engine / AI crawler / monitoring allowances
Blocking	Local IP block list and block behavior
Forms	Honeypot fields for comments, login, registration
Scanner	Client-side detection script options
WooCommerce	Checkout protection (shown when WooCommerce is active)
WebDecoy Cloud	Optional API key for dashboard sync

Behind Cloudflare or a proxy? Read this first

By default the plugin uses the direct connection IP and ignores forwarding headers like X-Forwarded-For and CF-Connecting-IP — spoofable headers are not trusted unless you say so. If your site is behind Cloudflare or another reverse proxy, every visitor will otherwise appear to come from the proxy’s IP:

1. Go to Settings → Protection
2. Enable “This site is behind Cloudflare” (or add your proxy’s CIDR ranges to Trusted proxies)
3. Save — visitor IPs now resolve from the forwarding header only when the connection actually comes from a trusted proxy

WebDecoy Cloud Tab (optional)

Everything works without this. Connecting adds dashboard sync:

Setting	Description
API Key	Your WebDecoy API key (sk_live_...) from the dashboard’s API Keys page

Click Test Connection; status shows Active, Inactive, Connection Error, or “Not checked yet”. If cloud sync is off, the plugin keeps protecting your site locally — only the dashboard sync is affected.

---

Detection Settings

Configure how the plugin detects and responds to threats.

Detection Tab Settings

Setting	Default	Description
Enable Protection	Yes	Master on/off switch
Sensitivity	Medium	Detection strictness
Minimum Score to Block	75	Score threshold for blocking
Rate Limit Enabled	Yes	Enable request rate limiting
Requests Per Minute	60	Max requests before rate limit

Sensitivity Levels

Level	Behavior
Low	Minimal detection, very few false positives
Medium	Balanced detection and accuracy (recommended)
High	Maximum detection, may have false positives

Blocking Actions

Action	Behavior
Block	Return 403 Forbidden
Challenge	Show CAPTCHA (if available)
Log Only	Record but don’t block

---

Good Bot Handling

Configure which bots are allowed through without detection.

Good Bots Tab Settings

Setting	Default	Description
Allow Search Engines	Yes	Googlebot, Bingbot, Yahoo, etc.
Allow Social Media Bots	Yes	Facebook, Twitter, LinkedIn, Pinterest
Block AI Crawlers	No	GPTBot, ClaudeBot, etc.
Custom Allowlist	Empty	Your own bot user agents

Search Engine Bots Recognized

• Googlebot
• Bingbot
• Yahoo! Slurp
• DuckDuckBot
• Baiduspider
• YandexBot

Social Media Bots Recognized

• Facebook External Hit
• Twitterbot
• LinkedInBot
• Pinterest
• WhatsApp
• Slackbot

AI Crawlers (Optional Block)

• GPTBot (OpenAI)
• ClaudeBot (Anthropic)
• Google-Extended
• PerplexityBot
• CCBot

Custom Allowlist

Add your own bots (one per line):

MyInternalBot
PartnerCrawler
UptimeRobot

---

Form Protection

Protect WordPress forms from spam and automated submissions.

Forms Tab Settings

Setting	Default	Description
Protect Comments	Yes	Add honeypot to comment forms
Protect Login	Yes	Detect brute force on login
Protect Registration	Yes	Catch fake registrations
Inject Honeypot Fields	Yes	Add invisible trap fields

How Form Honeypots Work

<!-- Automatically injected hidden field -->
<input type="text"
       name="website_url"
       style="position:absolute;left:-9999px;height:0;width:0;overflow:hidden"
       tabindex="-1"
       autocomplete="off">

Scenario	Result
Human submits (field empty)	Submission allowed
Bot fills field	Detected as bot, blocked

Login Protection

• Tracks failed login attempts per IP
• Temporary blocks after threshold
• Detects credential stuffing patterns

Registration Protection

• Analyzes registration timing
• Honeypot field validation
• Email domain verification

---

WooCommerce Protection

If WooCommerce is installed, additional protection options appear.

WooCommerce Tab Settings

Setting	Default	Description
Checkout Protection	Yes	Enable checkout monitoring
Max Checkouts Per Hour	5	Velocity limit per IP
Card Testing Detection	Yes	Detect rapid card attempts
Decline Tracking	Yes	Track payment failures

Card Testing Detection

Detects patterns indicating card testing attacks:

Pattern	Detection
Multiple cards, same IP	Card testing
Rapid checkout attempts	Velocity abuse
Many declines, one session	Card stuffing
Small amounts, high volume	Testing pattern

Checkout Velocity Limiting

IP: 192.168.1.100
Checkouts this hour: 5
Next checkout → BLOCKED (rate limit)

What Gets Blocked

• IPs exceeding checkout velocity
• Sessions with suspicious patterns
• Known fraudulent payment patterns

---

Client-Side Scanner

The plugin includes a JavaScript scanner that runs in visitors’ browsers.

Scanner Tab Settings

Setting	Default	Description
Enable Scanner	Yes	Load JavaScript scanner
Run on All Pages	Yes	Scanner on every page
Minimum Score to Report	20	Only report scores above this
Exclude Logged-In Users	No	Skip scanning for logged-in users

What the Scanner Detects

Detection	Description
WebDriver	Selenium, Puppeteer automation
Headless Browser	Chrome Headless, PhantomJS
Browser Anomalies	Inconsistent navigator properties
AI Bots	GPTBot, ClaudeBot user agents

Scanner Placement

The scanner is enqueued automatically (public/js/webdecoy-scanner.js) with its configuration passed via a localized webdecoyScanner JavaScript object — there’s nothing to paste into your theme.

Excluding Visitors

Use the Scanner tab’s options — e.g. Exclude logged-in users and the minimum-score-to-report threshold — to control what the scanner reports.

---

Viewing Detections in WordPress

Dashboard Widget

The WebDecoy dashboard widget shows:

• Total detections (last 7 days)
• Blocked IPs count
• Recent high-risk detections
• Quick links to settings

Detections Page

Navigate to WebDecoy → Detections to view:

Column	Description
Date/Time	When detection occurred
IP Address	Visitor’s IP
Score	Threat score (0-100)
Level	MINIMAL, LOW, MEDIUM, HIGH, CRITICAL
Source	Server, Scanner, Form
Action	What action was taken

Filtering:

• By date range
• By threat level
• By source type
• By IP address

Blocked IPs Page

Navigate to WebDecoy → Blocked IPs to view:

Column	Description
IP Address	Blocked IP
Reason	Why it was blocked
Blocked At	When block started
Expires At	When block ends
Actions	Unblock button

Managing Blocks:

• Click Unblock to remove a block immediately
• Expired blocks are automatically cleaned up
• Manual blocks don’t expire unless configured

Local vs. Cloud Detections

Storage	Data
Local (WordPress DB)	All detections, for admin viewing
Cloud (WebDecoy)	Synced for dashboard analytics

---

Troubleshooting the WordPress Plugin

Common Issues

API Status Shows “Inactive”

Causes:

• Invalid API key
• Network connectivity issues
• API key expired or revoked

Solutions:

1. Verify API key is correct
2. Check for typos (no extra spaces)
3. Generate a new API key if needed
4. Check server can reach ingest.webdecoy.com

Scanner Not Running

Causes:

• JavaScript errors on page
• Caching plugin conflict
• Theme blocking scripts

Solutions:

1. Check browser console for errors
2. Clear all caches (page, browser, CDN)
3. Exclude scanner from optimization plugins
4. Verify scanner is enabled in settings

Too Many False Positives

Causes:

• Sensitivity too high
• Score threshold too low
• Blocking legitimate bots

Solutions:

1. Lower sensitivity to “Medium” or “Low”
2. Increase minimum score to block (try 80)
3. Add legitimate bots to allowlist
4. Enable “Log Only” mode temporarily

WooCommerce Conflicts

Causes:

• Checkout velocity too strict
• Interfering with payment plugins

Solutions:

1. Increase max checkouts per hour
2. Disable checkout protection temporarily
3. Check for plugin conflicts
4. Add payment gateway IPs to allowlist

Plugin Updates Not Showing

Causes:

• CDN cache
• WordPress update check timing

Solutions:

1. Go to Plugins → WebDecoy
2. Click Check for updates
3. Or wait for automatic check (every 12 hours)

Debug Mode

Enable debug logging:

1. Add to wp-config.php:

   define('WEBDECOY_DEBUG', true);

2. Logs are written to:

   /wp-content/debug.log

3. Look for entries starting with [WebDecoy]

Getting Help

If issues persist:

1. Check plugin version is latest
2. Gather debug logs
3. Contact [email protected]

---