FAIR

Federated and Independent Repositories

Samurai Honeypot for Forms

Plugin Banner

Samurai Honeypot for Forms

by Team beta version

Download
Description

Note: This plugin requires HTTPS to function (due to Web Crypto API usage).

The Story: The Forging of the Ultimate Defense

This project began with a simple goal: to create a lightweight honeypot trap to catch basic bots. But during development, we faced a harsh reality: Simple traps are obsolete. Modern AI bots and headless browsers can easily step over traditional defenses. A basic trap was no longer enough; we needed a fortress.

So, we forged a completely new architecture. We added Proof of Work, Behavioral Analysis, and Rate Limiting. What started as a simple honeypot evolved into a 15-layer invisible firewall. Like a samurai’s blade, it operates with absolute precision—completely invisible to your real customers, yet ruthlessly executing a “Silent Kill” on spam bots before they ever reach your inbox or database.

Samurai Honeypot protects every Contact Form 7 and WPForms form with fifteen independent defense layers.
Each layer contributes a score, and blocked submissions are handled by a 3-Tier Triage System:

3-Tier Triage System

  • Tier 1 (Pass): Score below the threshold (default 50) — email is sent normally.
  • Tier 2 (Quarantine): Score between the threshold and 99 — email is silently suppressed (Silent Kill) and the submission is saved to the built-in Quarantine Log for admin review.
  • Tier 3 (Drop / Instant Kill): Score of 100 or higher — email is silently suppressed and the submission is permanently dropped without logging. This protects your database from bloat during DDoS or mass bot attacks.

Warning — False Positives: Depending on your environment, legitimate emails may occasionally be flagged as spam. Enterprise proxies, strict corporate firewalls, outdated browsers, VPNs, and unusual network configurations can trigger detection layers. You MUST check the Quarantine Log periodically to identify and recover any false positives. The plugin cannot distinguish all edge cases automatically.

Defense Layers

  1. JS Injection Gate — Blocks bots that cannot execute JavaScript. Tokens are fetched via REST API for full page-cache compatibility.
  2. Polymorphic Honeypot — Decoy field name is cryptographically derived per token (not exposed in the API response), hidden from humans via CSS.
  3. Token Signature — HMAC-SHA256 signed stateless token with IP and Form ID binding.
  4. Time Trap — Detects impossibly fast submissions. Browser autofill is automatically exempt.
  5. Proof of Work — SHA-256 computational challenge via Web Crypto API that forces CPU cost on bots.
  6. Behavioral Entropy — Hash-verified human-like event counters: mouse, keyboard, touch, scroll. Uniqueness tracking detects script reuse.
  7. Headless UA Block — Server-side User-Agent check instantly blocks known headless browsers and automated tools (Headless Chrome, Puppeteer, PhantomJS, Selenium, Playwright, Nightmare, Electron). Toggleable in settings for E2E testing compatibility.
  8. Headless Detection — Detects automated browser environments (navigator.webdriver, plugin count, window.chrome, language count).
  9. UA Age Detection — Scores based on Chrome version age. 2+ years: +10, 3+ years: +20, 4+ years: +30. Bots often use hardcoded old User-Agent strings that never update.
  10. Rate Limiting — Per-IP submission rate limiting with IPv6 /64 normalization.
  11. Replay Protection — Atomic token consumption (INSERT IGNORE) + TTL expiry enforcement.
  12. IP Blacklist — Manually configured IP/CIDR blacklist for known bad actors.
  13. Content: URL Limit — Flags messages containing more URLs than the configured threshold.
  14. Content: BBCode — Detects BBCode link syntax ([url=...]) that never appears in legitimate form submissions.
  15. Content: Denylist — Matches against WordPress Disallowed Comment Keys (Settings > Discussion).

Key Features

  • 3-Tier Triage — Pass, Quarantine (with local log), or Drop. No legitimate message is lost without a trace — quarantined submissions are saved for admin review.
  • Built-in Quarantine Log — Blocked Tier 2 submissions are saved to a local database table (up to 1,000 entries, FIFO). View date, score, trigger reasons, and full form data from the admin panel. No external plugin required.
  • DDoS-Resilient Tier 3 Drop — Submissions scoring 100+ are immediately dropped from memory without any database write. This prevents database exhaustion during mass bot attacks.
  • GDPR Compliant — No cookies, no external service calls, no plugin-specific PII stored. IP addresses are one-way hashed with a site-specific salt before any storage — raw IPs never touch the database. No consent banner required.
  • Stateless Tokens — No database writes for token generation; prevents DoS via DB bloat.
  • Zero Trust Client — All client-submitted data is verified server-side with HMAC signatures and hash integrity checks.
  • Zero Configuration — Activate and all Contact Form 7 / WPForms forms are protected automatically.
  • Cache Compatible — Tokens are fetched via REST API, so page caching works fine.
  • Multiple Forms — Works correctly with multiple forms on the same page.
  • IP Whitelist / Blacklist — Whitelist trusted IPs or CIDR ranges to skip all scoring. Blacklist known bad IPs to add +100 score instantly. Optionally whitelist all logged-in WordPress users.
  • Headless Browser Blocking — Server-side User-Agent check instantly blocks Headless Chrome, Puppeteer, Selenium, and other automated browsers (+100 score). Enabled by default; can be toggled off for E2E testing.
  • Content Rules — Detect spam patterns in form content: excessive URLs, BBCode link syntax, and WordPress Disallowed Comment Keys matching.
  • Trusted Proxy Support — Optional mode for Cloudflare and reverse proxy environments with IP range validation.
  • Lightweight — Three PHP files, no external dependencies, no jQuery.
  1. Upload the plugin files to /wp-content/plugins/samurai-honeypot-for-forms/, or install directly from the WordPress plugin screen.
  2. Activate “Samurai Honeypot for Forms” on the Plugins screen.
  3. Done — all Contact Form 7 and WPForms forms are now protected automatically.

To disable protection on a specific Contact Form 7 form, add the following to its Additional Settings tab:

skip_samhp: on

For WPForms, go to Settings > Samurai Honeypot > Access Control, and enter the form IDs (one per line) in the “WPForms Skip Form IDs” field. You can find each form’s ID in WPForms > All Forms (the number in the Shortcode column).

Does it work with page caching?

Yes. Tokens are fetched dynamically via REST API, so it works correctly with any page cache plugin.

Does Proof of Work slow down the user’s device?

The default difficulty is 4 (the first 4 hex characters of the SHA-256 hash must be zero).
On typical devices this completes in tens to hundreds of milliseconds with no perceptible delay.
You can adjust the difficulty from 2 to 6 in the settings.

Can I disable protection on specific forms?

Yes, for both Contact Form 7 and WPForms:

  • Contact Form 7: Open the form editor, go to the “Additional Settings” tab, and add skip_samhp: on (or skip_samurai_honeypot: on).
  • WPForms: Go to Settings > Samurai Honeypot > Access Control, and enter the form IDs in the “WPForms Skip Form IDs” textarea (one ID per line). You can find the form ID in WPForms > All Forms (the number in the Shortcode column).

Where can I see spam detection logs?

Blocked submissions with scores between your threshold and 99 are automatically saved to the Quarantine Log (Settings > Quarantine Log). You can view the date, score, triggered defense layers, and full form data for each entry. The log retains up to 1,000 entries in a FIFO (first-in, first-out) manner.

Submissions scoring 100 or higher are permanently dropped and never saved anywhere. These are considered absolute bots (e.g., missing JavaScript, invalid tokens) and are dropped to protect your server from database bloat during mass attacks.

How does Samurai Honeypot work with Flamingo?

Samurai Honeypot no longer tags spam for Flamingo’s spam folder. Instead, it prevents Flamingo from saving spam entirely to protect your database, while still allowing legitimate messages (Tier 1 / Pass) to be saved in Flamingo normally. Blocked messages (Tier 2 and Tier 3) are saved in our lightweight built-in Quarantine Log (max 1,000 records, FIFO auto-rotation) instead. This means you can safely use Flamingo as a CRM for real customer messages without worrying about spam bloating your database.

Could legitimate messages be blocked? (False Positives)

Yes, this is possible. While the multi-layer detection system is designed to minimize false positives, certain environments may cause legitimate submissions to be flagged:

  • Users behind enterprise proxies or corporate firewalls
  • Users with outdated browsers (especially Chrome versions 2+ years old)
  • Users with aggressive privacy extensions that block JavaScript features
  • VPN users whose IP addresses may be shared with spammers
  • Users with accessibility tools that suppress mouse/keyboard events

You MUST check the Quarantine Log periodically to identify any false positives. Quarantined messages (Tier 2) are always recoverable from the log. Adjust the spam threshold or whitelist specific IPs if you notice recurring false positives.

What happens during a DDoS or mass bot attack?

Submissions scoring 100 or higher (Tier 3) are immediately dropped from memory without any database write. This is a hardcoded absolute threshold that cannot be changed via settings. Combined with the FIFO cap of 1,000 quarantine entries, this ensures your database remains protected even under extreme attack conditions.

Is it compatible with other anti-spam plugins?

Yes. Samurai Honeypot uses the wpcf7_skip_mail filter, so it works alongside reCAPTCHA, Akismet, and other anti-spam solutions.

Do I need to configure anything for reverse proxies?

By default, the plugin uses REMOTE_ADDR only.
If you are behind Cloudflare or an Nginx reverse proxy, enable “Trusted Proxy Mode” in the plugin settings.
The plugin validates proxy IPs against Cloudflare’s published IP ranges and RFC 1918 private networks before trusting forwarded headers.

How do I whitelist or blacklist IP addresses?

Go to the Samurai Honeypot settings page under Access Control. Enter one IP address or CIDR range per line (e.g. 192.168.1.0/24).
Whitelisted IPs skip all spam scoring entirely. Blacklisted IPs receive an automatic +100 spam score.
You can also enable “Whitelist Logged-in Users” to skip scoring for all authenticated WordPress users.

What are Content Rules?

Content Rules analyze the text submitted through form fields for common spam patterns:

  • URL Limit — Set a maximum number of URLs allowed per submission. Messages exceeding the limit receive +50 score. Set to 0 to disable.
  • BBCode Detection — Detects [url=...] BBCode syntax, which is never used in legitimate contact form messages. Enabled by default (+100 score).
  • WordPress Disallowed Keys — Reuses the keyword list from Settings > Discussion > Disallowed Comment Keys. Disabled by default; enable it to apply the same keyword blocking to form submissions (+100 score).

Can I change the spam score threshold?

Yes. On the Samurai Honeypot settings page you can adjust the spam threshold (10-99, default 50), submission speed threshold, PoW difficulty, and rate limit. The maximum threshold is capped at 99 because scores of 100+ are always handled as Tier 3 (Drop).

My E2E tests (Puppeteer / Selenium / Playwright) are being blocked. How do I fix it?

Go to the Samurai Honeypot settings page and uncheck “Block Headless Browsers (Recommended)”.
This disables the server-side User-Agent check that instantly blocks known headless browsers (+100 score).
Remember to re-enable it after testing is complete.

Does browser autofill cause false positives?

No. The plugin detects browser autofill via CSS animation events and exempts it from the Time Trap (submission speed check).

1.1.5

  • Improved: Conditional script loading — anti-spam JavaScript and CSS are now only output on pages that contain a CF7 or WPForms form (shortcode or Gutenberg block), reducing unnecessary DOM output on all other pages
  • New: samhp_force_enqueue filter — allows themes/plugins to force-load the anti-spam script on pages where forms are rendered outside post content (e.g. widgets, custom templates)

1.1.4

  • Improved: PoW submit guard — disable submit button during Proof of Work computation to prevent premature submission
  • Improved: PoW loading spinner shown only when computation exceeds 500 ms (no visual noise for low difficulty)
  • Improved: PoW abort mechanism — stale PoW computations from previous submissions and token refreshes are immediately cancelled via generation counter, preventing CPU contention
  • Fixed: Race condition where old token refresh could cancel new PoW computation after form re-injection

1.1.3

  • Fixed: Flamingo compatibility — removed incorrect bool type hint on wpcf7_flamingo_submit_if filter callback that caused a fatal TypeError on PHP 8.x when Flamingo is active
  • Fixed: Quarantine Log table now auto-creates on plugin update (previously only on fresh activation, causing empty log on updated sites)

1.1.2

  • Improved: Flamingo protection filter added to prevent database bloat (block Tier 2/3 from being saved to Flamingo)
  • Improved: Quarantine Log now explicitly sets created_at timestamp

1.1.1

  • Improved: Settings page reorganized into three tabs (General, Rules & Access, Documentation)
  • Improved: Quarantine Log explanation expanded with detailed 3-Tier Triage information
  • Improved: Defense Layers Overview and REST API Status moved to dedicated Documentation tab

1.1.0

  • New: 3-Tier Triage System — Pass (Tier 1), Quarantine (Tier 2), Drop (Tier 3)
  • New: Built-in Quarantine Log with WP_List_Table UI (Settings > Quarantine Log)
  • New: Local database table (wp_samhp_logs) with FIFO hard cap of 1,000 rows
  • New: Tier 3 Drop — submissions scoring 100+ are silently dropped without any database write to prevent DB bloat during mass attacks
  • New: “Delete All Logs” action with nonce protection and confirmation dialog
  • New: Quarantine Log link on the main settings page
  • New: Defense Layers Overview table updated with 3-Tier Triage description
  • Improved: Silent Kill hooks for CF7 and WPForms now implement the 3-Tier logic
  • Improved: WPForms Silent Kill now blocks both email and entry save (Pro DB write + Lite Connect)
  • Removed: Flamingo integration completely removed — replaced by the built-in Quarantine Log to prevent database bloat during mass attacks
  • Improved: readme.txt updated with false positive warnings and 3-Tier documentation

1.0.0

  • Initial release
  • 15-layer score-based spam detection with Silent Kill
  • Contact Form 7 & WPForms (Lite & Pro) support with multi-adapter architecture
  • Stateless HMAC-SHA256 signed tokens with IP and Form ID binding
  • Proof of Work with Web Crypto API
  • Hash-verified behavioral entropy analysis with uniqueness tracking
  • Headless browser detection (client-side) and Headless Browser UA Block (server-side)
  • UA Age Detection — Chrome version age scoring (+10/+20/+30) to catch bots with outdated User-Agent strings
  • Atomic replay protection (INSERT IGNORE / wp_cache_add)
  • WPForms AJAX post-submit token refresh (wpformsAjaxSubmitSuccess)
  • IPv6 /64 normalization for rate limiting
  • Trusted proxy validation (Cloudflare + RFC 1918) with X-Forwarded-For rightmost-IP parsing
  • IP Whitelist / Blacklist with CIDR support and Whitelist Logged-in Users option
  • Content Rules: URL limit detection, BBCode detection, WordPress Disallowed Keys matching
  • Per-form skip support (CF7 Additional Settings / WPForms Skip Form IDs)
  • Multiple forms per page support
  • GDPR Compliant (Cookie-less & IP Hashing)
Back to top