Challenge mitigation

A lightweight IP whitelisting and challenge module for Drupal 10+
Prevent automated abuse while maintaining a smooth UX for real visitors.

Disclaimer: This module is not a WAF

This module is not intended to replace a Web Application Firewall (WAF). A dedicated WAF remains the most robust and efficient solution for mitigating complex threats and high-volume attacks. However, WAFs often involve significant infrastructure or licensing costs, making them inaccessible for some environments.

This module aims to offer a lightweight mitigation layer at the Drupal level — as a pragmatic compromise. While not as fast or powerful as a WAF, it provides reasonable protection for scenarios where a full WAF is not an option.

What It Does

This module enforces a one-time challenge or JavaScript-based check when users visit specific parts of your Drupal site. Once passed, their IP is whitelisted for a configurable duration.

This is ideal for:

• Limiting access to exposed endpoints (e.g. `/user`, `/search`, `/contact`)
• Reducing spam and automated attacks
• Soft gating traffic without forcing login or rate limits

Features

• IP whitelist based on successful challenge
• Configurable list of target URLs (with support for wildcards and query strings)
• Optional full-site protection mode
• Three challenge modes:
  • Automatic JS
  • Hard
  • Adaptive Hard
• Cron-based cleanup of expired IPs
• Admin UI for settings and whitelist management
• CAPTCHA module integration (optional)
• Manual IP Whitelist (IPv4 / IPv6 / CIDR support)
• Manual User-Agents Whitelist

Challenge Modes

• Automatic JS
  • Invisible JS-based form auto-submission. No user interaction required.
• Hard
  • User must manually submit a form. CAPTCHA is required if integration enabled.
• Adaptive Hard
  • Automatically use Hard Challenge for suspicious User-Agents; otherwise use Automatic JS.

Configuration

1. Go to:
   • `Admin > Configuration > Security > Challenge Mitigation`
2. Configure:
   • Enable/disable the system
   • Define challenge URLs (one per line, support for ``, wildcards, and query matching)
   • Choose enforcement mode (`automatic_js` or `hard`)
   • Enable CAPTCHA integration (optional)
   • Set whitelist duration (in minutes)
3. View/manage whitelist entries at:
   • `Admin > Configuration > Security > Challenge Mitigation > Whitelist IPs`

URL Pattern Matching

Patterns are matched against the full request URI, including query parameters.

Examples:

/user
/search?*
/news?*f%5B0%5D=*
/node/*?preview=*

Use `*` as a wildcard. You may include query strings as needed.

Automatic Cleanup

The module uses `hook_cron()` to delete expired whitelist entries.
You can also trigger it manually with:

drush cron

Manual IP Whitelist (IPv4 / IPv6 / CIDR support)

You can define a list of IP addresses or IP ranges that should always bypass the challenge mechanism, regardless of visited paths or access mode.

Simply enter one IP per line in the "Manually whitelisted IPs" field in the module configuration form.

Supported formats include:

• Individual IPv4 addresses: 192.168.0.1
• Individual IPv6 addresses: 2001:db8::1
• CIDR notation (subnets): 10.0.0.0/8, 192.168.0.0/24, 2a01:e0a::/32

Whitelisted User-Agents (Advanced)

In addition to IP whitelisting, the module supports User-Agent-based whitelisting. This is useful for allowing specific bots or services (such as monitoring tools or CDN health checks) to bypass the challenge mechanism.

The manual_user_agent_whitelist configuration field accepts one regular expression per line. Each expression is evaluated against the User-Agent header of incoming requests. If a match is found, the challenge is skipped.

CAPTCHA Integration (Optional)

If the [CAPTCHA module](https://www.drupal.org/project/captcha) is enabled, you may activate it in Hard mode by checking the "Use CAPTCHA module integration" option.

Authenticated User Skip

The module provides an option to skip the challenge for authenticated users.
When enabled, only anonymous (non-logged-in) visitors will be prompted to complete the security challenge.
This setting is useful for sites where logged-in users are trusted and should not experience additional friction while navigating protected pages.

You can enable this option in the module configuration under "Skip authenticated users".

Signed Cookie Bypass

After successfully completing the challenge, users can optionally receive a signed cookie that allows them to bypass future challenges from the same browser.
The cookie contains a securely signed timestamp to prevent tampering.
On subsequent visits, if the cookie is present and valid, the module will automatically skip the challenge for that user, providing a smoother user experience.

You can enable this feature in the module settings under "Enable cookie-based challenge bypass" and configure the lifetime of the cookie according to your needs.

Installation

composer require drupal/challenge_mitigation
drush en challenge_mitigation

Maintainers

Originally developed by Sébastien Libbrecht

This implementation is sponsored by the GAYA web agency.

Feedback and contributions welcome!