Honeypot
A spam prevention module that uses honeypot fields and time-based restrictions to deter automated form submissions without using CAPTCHAs.
honeypot
Install
composer require 'drupal/honeypot:^2.2'
composer require 'drupal/honeypot:^2.1'
Overview
The Honeypot module provides an effective and non-intrusive method to prevent spam bots from completing forms on your Drupal site. Unlike CAPTCHAs which require user interaction, Honeypot works invisibly in the background using two complementary techniques.
The first technique adds a hidden honeypot field to forms. Since spam bots typically fill in all available fields, they will complete this hidden field, which real users cannot see. When a submission includes data in the honeypot field, it is rejected as spam.
The second technique implements time-based protection. A timestamp is stored when the form is loaded, and if the form is submitted faster than humanly possible (configurable time limit), the submission is rejected. This is effective because spam bots typically submit forms almost instantaneously.
Honeypot includes an exponential time penalty for repeat offenders - each failed submission increases the required wait time exponentially, making it increasingly difficult for persistent bots to successfully submit forms.
Features
- Honeypot field protection - adds a hidden field that triggers rejection if filled out by bots
- Time-based form protection - requires a minimum time before form submission is accepted
- Exponential time penalty for repeat offenders based on failed submission history
- Protect all forms site-wide or select specific forms individually
- Bypass protection for users with specific permissions (e.g., administrators)
- Logging of blocked form submissions for monitoring and analysis
- Integration with Rules module via events for custom reactions to spam rejections
- Interactive tour for configuration guidance
- Automatic cleanup of old failed submission records via cron
- Page cache handling with automatic cache disabling when time protection is active
- Programmatic API for adding protection to custom forms
Use Cases
Protecting User Registration from Spam Bots
Enable Honeypot on the user registration form to prevent automated account creation. Navigate to /admin/config/content/honeypot and check 'User Registration form' under Honeypot Enabled Forms. Set a time limit of 5-10 seconds to catch bots that submit instantly.
Site-wide Form Protection
For sites under heavy spam attack, enable 'Protect all forms with Honeypot' to add protection to every form. Be aware this disables page caching on pages with forms when time limit is enabled. System forms, search forms, and views exposed forms are automatically excluded.
Adding Honeypot to Custom Forms
Use the honeypot service to add protection to custom module forms. In your form builder or hook_form_alter: \Drupal::service('honeypot')->addFormProtection($form, $form_state, ['honeypot', 'time_restriction']); You can include just 'honeypot' or just 'time_restriction' if needed.
Monitoring Spam Attempts
Enable 'Log blocked form submissions' to track spam attempts in Drupal's log. Review logs at /admin/reports/dblog filtered by 'honeypot' to understand spam patterns and verify protection is working.
Custom Reaction to Spam with Rules
Install the Rules module and create a rule that reacts to the 'After rejecting a form submission' event. Use this to send email notifications, add IPs to a blocklist, or trigger other automated responses to spam attempts.
Allowing Administrators to Bypass Protection
By default, users with the 'bypass honeypot protection' permission are not subject to honeypot checks. Assign this permission to trusted roles like Administrator to prevent false positives when testing or during legitimate rapid form submissions.
Tips
- Use a tempting element name like 'url', 'homepage', or 'link' to encourage bots to fill it out
- Start with time_limit of 5 seconds and adjust based on form complexity and user feedback
- For commerce or checkout forms, consider disabling time protection to avoid false positives during quick purchases
- The exponential time penalty means repeat offenders face increasingly long wait times automatically
- Use hook_honeypot_form_protections_alter to add protection to forms from other modules
- Monitor the log regularly after enabling to ensure legitimate users aren't being blocked
- Combine Honeypot with other spam prevention methods for defense in depth
Technical Details
Admin Pages 1
/admin/config/content/honeypot
Configure Honeypot spam prevention settings including protection methods, time limits, and select which forms to protect. This page allows administrators to fine-tune the anti-spam behavior for their site.
Permissions 2
Hooks 4
hook_honeypot_form_protections_alter
Alter the honeypot protections applied to a particular form. Use this to add or remove protection types for specific forms.
hook_honeypot_add_form_protection
React after honeypot protection has been added to a form. Useful for tracking when protected forms are displayed.
hook_honeypot_reject
React when a form submission is rejected by Honeypot. Allows custom handling of spam attempts.
hook_honeypot_time_limit
Add additional time to the Honeypot time limit. Return an integer of seconds to add to the limit.
Troubleshooting 5
The time limit may be too high for simple forms. Reduce the time_limit setting at /admin/config/content/honeypot, or set it to 0 to disable time-based protection while keeping the honeypot field active.
Time-based protection requires disabling page cache for anonymous users. Set time_limit to 0 if caching is critical, or use the honeypot field protection only by removing 'time_restriction' from form protection options.
Change the element_name setting to something that doesn't conflict with your form's existing fields. Common alternatives: homepage, link, website_url, contact_url.
Increase the time_limit to a higher value (10-15 seconds). Consider enabling protection on all forms. Check that the honeypot element name isn't being recognized by sophisticated bots.
Ensure you're not logged in as a user with 'bypass honeypot protection' permission. Administrative users bypass protection by default.
Security Notes 5
- Honeypot is not a complete spam solution - determined attackers with JavaScript-capable bots may bypass protection
- Always use Honeypot in combination with other security measures for sensitive forms
- The bypass permission should only be granted to highly trusted roles
- Failed submission logs may contain information about attackers - review and clear periodically
- Consider rate limiting at the server level in addition to Honeypot protection