Antibot
Lightweight anti-spam module that prevents robotic form submissions by requiring JavaScript and human interaction.
antibot
Install
composer require 'drupal/antibot:^2.0'
Overview
Antibot is an extremely lightweight module designed to eliminate robotic form submissions on your website in an innovative fashion. The module works completely behind the scenes and doesn't require any interaction from end-users.
The protection mechanism works by modifying the form action to a dead-end path and injecting a hidden key field. JavaScript listens for human-like behavior (mouse movement, touch events, or Tab/Enter key presses) and only then restores the original form action and sets the correct key value. Without JavaScript enabled or without demonstrating human behavior, the form submission will fail.
The only requirement for end users is that they must have JavaScript enabled. If they do not, protected forms will display a message telling the user that JavaScript is required to use the form.
Features
- Invisible anti-spam protection that requires no user interaction (no CAPTCHAs)
- Detects human behavior through mouse movement, touch gestures, or keyboard navigation (Tab/Enter)
- Protects forms by redirecting bot submissions to a dead-end page (/antibot)
- Supports wildcard patterns for form ID matching (e.g., comment_* protects all comment forms)
- Ability to exclude specific forms from protection even when matched by wildcards
- Debug mode to display form IDs and their protection status on pages
- Permission-based bypass allowing trusted users to skip antibot protection
- Proper cache invalidation when protection settings change
- Integration with Webform module for individual webform protection settings
- Hooks for other modules to modify protection status or respond to rejected submissions
Use Cases
Protecting Comment Forms from Spam Bots
By default, Antibot protects all comment forms using the pattern 'comment_*'. Spam bots that don't execute JavaScript or simulate human interaction will be blocked from posting comments. This reduces comment spam without requiring users to solve CAPTCHAs.
Securing User Registration Against Automated Signups
The user_register_form is protected by default, preventing automated account creation by bots. This is especially useful for sites that allow open registration but want to prevent mass fake account creation.
Protecting Contact Forms Without Annoying Users
Contact forms (contact_message_*) are protected by default. Unlike CAPTCHA solutions, users don't need to prove they're human - they just need to interact naturally with the page (moving their mouse or using keyboard navigation).
Protecting Custom Forms
Enable the 'Display form IDs' option temporarily to see the form ID of any custom form on your site. Then add that form ID (or a wildcard pattern) to the protected forms list. Custom webform submissions can be protected using patterns like 'webform_submission_*'.
Allowing Trusted Users to Bypass Protection
Assign the 'Skip antibot' permission to trusted roles (like administrators or content editors) so they can submit forms without antibot validation. This is useful for automated testing or for users who may have accessibility tools that don't trigger mouse/keyboard events.
Fine-Grained Form Protection Control
Use the excluded_form_ids setting to exempt specific forms from protection even when they match a wildcard pattern. For example, protect all contact forms with 'contact_message_*' but exclude a specific one with 'contact_message_newsletter' in the excluded list.
Integration with Webform Module
When the Webform module is installed, individual webforms can have Antibot protection enabled through the webform's third-party settings. The module automatically manages the form_ids configuration when webform settings are saved.
Tips
- Use wildcard patterns (e.g., 'comment_*') to protect multiple related forms with a single entry rather than listing each form individually
- Enable 'Display form IDs' only temporarily when setting up protection - leaving it enabled on production may expose internal form IDs
- The 'Skip antibot' permission is useful for automated testing environments where JavaScript interaction cannot be simulated
- Antibot works well in combination with other anti-spam modules like Honeypot for layered protection
- Views exposed forms have special handling - they can be protected but will work on initial page load before user interaction
- Protected forms get the 'antibot' CSS class added, which you can use for custom styling if needed
Technical Details
Admin Pages 1
/admin/config/user-interface/antibot
Configure which forms are protected by Antibot and enable debug mode to identify form IDs. This page allows administrators to specify form ID patterns using wildcards to protect multiple forms at once, exclude specific forms from protection, and enable a debug mode that displays form IDs on pages.
Permissions 2
Hooks 3
hook_antibot_form_status_alter
Allows modules to modify whether a specific form should be protected by Antibot. Called after the form ID is matched against the configured patterns.
hook_antibot_reject
React to the rejection of a form submission. Called when Antibot blocks a form submission due to missing or invalid antibot key (bot behavior detected).
hook_antibot_generate_key_alter
Alter the encrypted key generated for form validation. Allows modules to customize the key generation process.
Troubleshooting 5
Ensure the user has JavaScript enabled in their browser. If using accessibility tools or automation, consider granting the 'Skip antibot' permission to affected users.
Add the antibot fields to your custom form template: {{ element.antibot_no_js }} and {% if element.antibot_key %}{{ element.antibot_key }}{% endif %}. The conditional check for antibot_key prevents duplicate field rendering.
Some sophisticated bots can execute JavaScript and simulate mouse events. Consider combining Antibot with other spam protection measures like Honeypot or reCAPTCHA for high-value forms.
Enable the 'Display form IDs' checkbox in Antibot settings. Then visit the page containing the form - the form ID and its protection status will be displayed as a message. Remember to disable this option after identifying the form ID.
The module includes proper cache tag handling. If you experience caching issues, try clearing all caches via Drush (drush cr) or the Performance settings page.
Security Notes 5
- The antibot key is generated using Drupal's cryptographic HMAC function with the site's hash salt, making it secure against prediction attacks
- The key is shuffled before being sent to the browser and unshuffled by JavaScript, adding an additional layer of obfuscation
- Forms without JavaScript fall back to the /antibot endpoint which displays an error, not exposing any sensitive information
- Programmatically submitted forms (using FormState::setProgrammed()) bypass Antibot validation, allowing legitimate automated form submissions
- The module does not store any user data or tracking information - it only validates form submissions at the time of submission