>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3568807. --> Reported by: [rr404](https://www.drupal.org/user/3739954) Related to !18 >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The plugin system doesn't have a doc</p> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>we could add something like this (or shorter) at the end of the readme:</p> <p>### **What you get**</p> <p>* **A standard way to define a scenario** (ID, CrowdSec scenario name, label, description).</p> <p>* **A one-liner to push a signal** (IP \+ response code \+ optional target user).</p> <p>* **Automatic buffering by default**, so your module can emit signals freely while CrowdSec handles batching / upstream sending.</p> <p>* An option to **disable buffering** if your module already bans IPs and you want upstream signalling immediately.</p> <p>---</p> <p>## **Where the CrowdSec scenarios live**</p> <p>Built-in (and your custom) scenario plugins are in:</p> <p>* `src/Plugin/CrowdsecScenario`</p> <p>Your module will add its own plugin under its namespace, in the same subpath.</p> <p>---</p> <p>## **Step 1 &mdash; Create a Scenario plugin in your module**</p> <p>Create a file like:</p> <p>`my_module/src/Plugin/CrowdsecScenario/Something.php`</p> <p>`<?php `</p> </p><p>`declare(strict_types=1);`</p> <p>`namespace Drupal\my_module\Plugin\CrowdsecScenario;`</p> <p>`use Drupal\Core\StringTranslation\TranslatableMarkup;`<br> `use Drupal\crowdsec\Attribute\Scenario;`<br> `use Drupal\crowdsec\ScenarioPluginBase;`</p> <p>`/**`<br> `* Plugin implementation of the SOMETHING scenario.`<br> `*/`<br> `#[Scenario(`<br> `id: 'something',`<br> `scenario: 'drupal/something',`<br> `label: new TranslatableMarkup('Bans from something'),`<br> `description: new TranslatableMarkup('Describe the purpose of this plugin.'),`<br> `)]`<br> `final class Something extends ScenarioPluginBase {}`</p> <p>Key fields:</p> <p>* `id`: your local plugin ID (what you&rsquo;ll pass to the plugin manager).</p> <p>* `scenario`: the CrowdSec scenario string (e.g. `drupal/captcha-ban`, `drupal/spam`, etc.).</p> <p>* `label` / `description`: what site owners will see.</p> <p>---</p> <p>## **Step 2 &mdash; Emit a signal from your module**</p> <p>When your module detects something worthy of signalling (e.g. N failed CAPTCHAs in M minutes), call:</p> <p>`ScenarioPluginManager::getPlugin('something')`<br> `-&gt;addSignal('1.2.3.4', 403, $targetUser);`</p> <p>Parameters:</p> <p>* `1.2.3.4`: the source IP address</p> <p>* `403`: the HTTP response code you returned (or an equivalent code representing the block/deny)</p> <p>* `$targetUser` *(optional)*: the user ID if the event is tied to a specific user on that IP; otherwise `NULL`.</p> <p>---</p> <p>## **Buffering vs immediate upstream signalling**</p> <p>By default, **CrowdSec buffers signals automatically** (recommended for most modules).</p> <p>If your module *already bans IPs itself* and you don&rsquo;t want buffering, set the plugin attribute:</p> <p>* `buffer: FALSE`</p> <p>In that mode, signals are pushed upstream **directly** (no buffering).</p> <p>*(Exact placement is inside the `#[Scenario(...)]` attribute for your plugin.)*</p> <p>---</p> <p>## **Best practices (practical guidance)**</p> <p>* **Throttle your detections**: only signal when a meaningful threshold is reached (e.g., 5 failures in 2 minutes).</p> <p>* **Choose scenario names consistently**: prefer `drupal/<feature>-ban` patterns so they&rsquo;re self-explanatory.</feature></p> <p>* **Keep the &ldquo;signal moment&rdquo; clear**: emit the signal when you would *actually block / deny / ban*, not on every minor suspicious event.</p>