WordPress Plugin

Plugin Overview

The WebDecoy WordPress plugin provides comprehensive bot protection for WordPress sites without writing any code. It combines server-side detection, client-side JavaScript scanning, and form protection.

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
Cloud Sync	Sync detections to WebDecoy dashboard

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

API Configuration Tab

Connect the plugin to your WebDecoy account:

Setting	Description
API Key	Your WebDecoy API key (sk_live_...)
Organization ID	Optional - auto-detected from API key
Scanner ID	Optional - for cloud scanner sync

Steps:

1. Get your API key from WebDecoy Dashboard → Settings → API Keys
2. Paste the API key in the field
3. Click Test Connection
4. Verify “API Status: Active” appears

API Status Indicators

Status	Meaning
🟢 Active	Connected and working
🟡 Checking	Verifying connection
🔴 Inactive	Not connected or invalid key
⚠️ Error	Connection failed

---

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 automatically added to the page footer:

// Automatically added to wp_footer
<script src="/wp-content/plugins/webdecoy/assets/js/scanner.js"
        data-scanner-id="your-scanner-id">
</script>

Excluding Pages

To exclude specific pages from scanning:

1. Use the page filter setting
2. Or add to your theme:

add_filter('webdecoy_exclude_scanner', function($exclude, $post_id) {
    if ($post_id == 123) return true; // Exclude page ID 123
    return $exclude;
}, 10, 2);

---

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 api.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 support@webdecoy.com

---

WordPress Plugin Hooks

Actions

// After detection is logged
do_action('webdecoy_detection_logged', $detection_id, $ip, $score, $flags);

// After IP is blocked
do_action('webdecoy_ip_blocked', $ip, $reason, $duration);

// After IP is unblocked
do_action('webdecoy_ip_unblocked', $ip);

Filters

// Modify detection score
$score = apply_filters('webdecoy_detection_score', $score, $signals);

// Customize block message
$message = apply_filters('webdecoy_block_message', $message, $ip);

// Add custom good bots
$bots = apply_filters('webdecoy_good_bots', $bots);

// Modify rate limit
$limit = apply_filters('webdecoy_rate_limit', $limit, $ip);