CrowdSec

Integrates your Drupal site with CrowdSec to keep suspicious users and cybercriminals away. No account with CrowdSec required, and no other agent software to be installed. This module brings everything required with it. Download with composer, enable the module and rest assured, that a lot of malicious traffic and many attack vectors will just be gone!

It's that simple.

How does it work?

This module combines three separate CrowdSec-related features:

1. Ban plugins detect bad behavior on your Drupal site and ban IP addresses locally.
2. Signal scenarios decide which local bans should also be reported upstream to CrowdSec.
3. Subscribe scenarios decide which CrowdSec blocklists your site should download and enforce locally.

Only the third part is the actual CrowdSec remediation feed: CrowdSec collects malicious IP addresses globally from participating sites and publishes supported scenarios as upstream blocklists. This module downloads the selected scenarios, caches them locally, and rejects matching requests with a 403 response.

The first two parts control how your Drupal site contributes to that network. Local ban plugins detect bad behavior on this site. If their matching signal scenarios are enabled, those local detections are also sent upstream so CrowdSec can learn from them.

Important note about caching

This module automatically detects and uses Redis for caching when your Drupal site has $settings['redis.connection'] configured in settings.php. No additional configuration is required -- if your site already uses Redis, the CrowdSec cache will use it too.

As a fallback, it uses the file system and stores the cache in temporary://crowdsec.

How does your Drupal site contribute to CrowdSec?

Your site contributes through enabled ban plugins. Each plugin uses its own logic to detect bad behavior locally, for example flood control events, administrator-created bans, or repeated 4xx responses.

Reporting those events upstream is a separate choice. In the module settings, you can decide which signal scenarios should be sent to CrowdSec and which upstream subscribe scenarios should be enforced on your site.

A note about privacy and compliance

This question has been asked before: is it a potential compliance issue and a breach of the user's privacy, when this module signals malicious behavior upstream to CrowdSec?

We certainly don't think so, especially because the sole reason for the potential signal is to protect the website from some strange behavior. This is technically not only necessary but therefor an exempt from the data protection regulations. Of course, we're no lawyers, and you shouldn't take this as legal advise in any context. But we can provide you with a list of links that seem to confirm our understanding:

• Issue about this question
• Discussion on Discourse
• Article 49 of EU GDPR

Available ban plugins

This module provides three built-in ban plugins:

Flood control bans: Uses Drupal core flood control events, for example after repeated failed login attempts.

Administrator bans: Uses the core Ban module or the Advanced Ban module to collect IP addresses that were manually banned by an administrator.

4xx response bans: Automatically bans an IP address for a period of time when it causes too many 4xx responses within a configured time window.

These plugins always control local bans on your site. Whether a local ban is also reported upstream depends on the selected signal scenarios.

Extending this module with custom signal types

This module uses a plugin system that makes it straightforward to add new signal types. You can contribute new scenarios directly to this module by opening a feature request in the issue queue, or you can provide them in separate modules or custom code.

What you get

• A standard way to define a scenario (ID, CrowdSec scenario name, label, description).
• A one-liner to push a signal (IP + response code + optional target user).
• Automatic buffering by default, so your module can emit signals freely while CrowdSec handles batching and upstream sending.
• An option to disable buffering if your module already bans IPs and you want upstream signalling immediately.

Step 1 -- Create a Scenario plugin in your module

Create a file at my_module/src/Plugin/CrowdsecScenario/Something.php:

Key fields in the #[Scenario] attribute:

• id: Your local plugin ID (what you pass to the plugin manager).
• scenario: The CrowdSec scenario string (e.g. drupal/captcha-ban, drupal/spam).
• label / description: What site owners will see.
• buffer: Whether to use the leaky bucket buffering mechanism. Defaults to TRUE. Set to FALSE if your module already bans IPs and you want signals pushed upstream immediately.

Step 2 -- Emit a signal from your module

When your module detects something worthy of signalling, call:

ScenarioPluginManager::getPlugin('something')
  ->addSignal('1.2.3.4', 403, $targetUser);

Parameters:

• The source IP address.
• The HTTP response code you returned (or an equivalent code representing the block/deny action).
• $targetUser(optional): The user ID if the event is tied to a specific user on that IP; otherwise NULL.

Buffering vs immediate upstream signalling

By default, CrowdSec buffers signals automatically using a leaky bucket algorithm (recommended for most modules). Signals only get pushed upstream when a configurable threshold is exceeded within a time window.

If your module already bans IPs itself and you don't want buffering, set the plugin attribute buffer: FALSE. In that mode, signals are pushed upstream directly.

Best practices

• Throttle your detections: only signal when a meaningful threshold is reached (e.g. 5 failures in 2 minutes).
• Choose scenario names consistently: prefer drupal/-ban patterns so they are self-explanatory.
• Keep the "signal moment" clear: emit the signal when you would actually block / deny / ban, not on every minor suspicious event.