diff --git a/doc/DEVELOPER.md b/doc/DEVELOPER.md index f53d5d6..e387c66 100644 --- a/doc/DEVELOPER.md +++ b/doc/DEVELOPER.md @@ -321,7 +321,7 @@ npm install -g doctoc Then, run it in the root folder: ```bash -doctoc README.md --maxlevel 4 && doctoc docs/* --maxlevel 4 +doctoc doc/* --maxlevel 4 ``` ## Release process diff --git a/doc/INSTALLATION_GUIDE.md b/doc/INSTALLATION_GUIDE.md index 1231fb7..f63401e 100644 --- a/doc/INSTALLATION_GUIDE.md +++ b/doc/INSTALLATION_GUIDE.md @@ -4,10 +4,10 @@ ## Installation Guide +**Table of Contents** -**Table of Contents** - [Requirements](#requirements) - [Installation](#installation) @@ -23,7 +23,6 @@ - ## Requirements - Magento >= 2.3 @@ -32,7 +31,7 @@ Use `Composer` by simply adding `crowdsec/magento2-module-engine` as a dependency: - composer require crowdsec/magento2-module-engine + composer require crowdsec/magento2-module-engine ## Post Installation @@ -48,15 +47,12 @@ After enabling the module, the Magento 2 system must be upgraded. If the system mode is set to production, run the compile command first. This is not necessary for the developer mode. - bin/magento setup:di:compile Then run the upgrade command: - bin/magento setup:upgrade - ### Clear Cache The Magento 2 cache should be cleared by running the flush command. @@ -69,7 +65,6 @@ At last, you have to deploy the static content: bin/magento setup:static-content:deploy -f - ## Troubleshooting ### Higher matching error @@ -104,12 +99,15 @@ To avoid this error and install the latest known Packagist release `y.y.y`, you } }, ``` + And then run the same command: + ```bash composer require crowdsec/magento2-module-engine --no-plugins ``` As an alternative, you can also exclude the `crowdsec/magento2-module-engine` from the `repo.magento.com` repository: + ``` "repositories": { "0": { @@ -120,6 +118,5 @@ As an alternative, you can also exclude the `crowdsec/magento2-module-engine` fr }, ``` -Thus, running `composer require crowdsec/magento2-module-engine` will always pick up the latest `y.y.y` Packagist +Thus, running `composer require crowdsec/magento2-module-engine` will always pick up the latest `y.y.y` Packagist release. - diff --git a/doc/TECHNICAL_NOTES.md b/doc/TECHNICAL_NOTES.md index c07deed..2bf0e0a 100644 --- a/doc/TECHNICAL_NOTES.md +++ b/doc/TECHNICAL_NOTES.md @@ -4,9 +4,10 @@ ## Technical notes +**Table of Contents** + -**Table of Contents** - [CrowdSec Remediation Engine](#crowdsec-remediation-engine) - [Why `crowdsec/magento-symfony-cache` dependency?](#why-crowdsecmagento-symfony-cache-dependency) @@ -14,20 +15,17 @@ - ## CrowdSec Remediation Engine -This extension is mainly based on the CrowdSec Remediation Engine PHP SDK library. It is an open source library whose +This extension is mainly based on the CrowdSec Remediation Engine PHP SDK library. It is an open source library whose code you can find [here](https://github.com/crowdsecurity/php-remediation-engine). - ## Why `crowdsec/magento-symfony-cache` dependency? This `CrowdSec_Engine` module depends on the [CrowdSec Remediation Engine library `crowdsec/remediation-engine`](https://github.com/crowdsecurity/php-remediation-engine) that comes with`symfony/cache` as dependency (`v5` or `v6`). Since Magento `2.4.4`, a fresh installation on PHP 8 will lock a `3.0.0` version of `psr/cache`. And it also installs a `v2.2.11` version of `web-token/jwt-framework` that locks a `v4.4.45` version of`symfony/http-kernel`. - As a `v5` version of `symfony/cache` required `^1.0|^2.0` version of `psr/cache`, and a `v6` version of `symfony/cache` conflicts with `symfony/http-kernel` <5.4, it is impossible to require any version of the`symfony/cache` package. That's why we needed to create a fork of `symfony/cache` that we called `crowdsec/magento-symfony-cache`. @@ -37,14 +35,13 @@ The `v1` version of `crowdsec/magento-symfony-cache` only requires some specific For PHP >= `8.0.2`, we provide a compatible `v2` version of `crowdsec/magento-symfony-cache`. This `v2` version replaces the specified `5.x.y` version of `symfony/cache` : we use a copy of `5.x.y` files and allow `psr/cache` `3.0`. We also copy some `6.0.z` files to have compatible PHP 8 method signatures. -_Update_: Since Magento `2.4.6`, it is possible to install `symfony/cache` because the required version of -`web-token/jwt-framework` is `3.1`. But, in order to keep compatibility with `2.4.4` and `2.4.5`, we have to +_Update_: Since Magento `2.4.6`, it is possible to install `symfony/cache` because the required version of +`web-token/jwt-framework` is `3.1`. But, in order to keep compatibility with `2.4.4` and `2.4.5`, we have to keep this `crowdsec/magento-symfony-cache` dependency. - ## The `crowdsec_engine_detected_alert` event -This module listens to a `crowdsec_engine_detected_alert` event whose purpose is to send a ban signal for a given IP +This module listens to a `crowdsec_engine_detected_alert` event whose purpose is to send a ban signal for a given IP and a given scenario. You have to dispatch this event and pass an `alert` array with at least two required indexes: @@ -52,7 +49,7 @@ You have to dispatch this event and pass an `alert` array with at least two requ - `ip`: the IP you want to signal - `scenario`: the name of the scenario that triggered the alert. -Optionally, you can pass a timestamp (integer) as a value of a `last_event_date` key. +Optionally, you can pass a timestamp (integer) as a value of a `last_event_date` key. For example, you can have your own class that will dispatch the `crowdsec_engine_detected_alert` event: @@ -87,4 +84,5 @@ class YourClass } ``` + This way, an event will be stored in the `crowdsec_event` table with an `alert_triggered` status and the following `crowdsec_engine_push_signals` executed cron job will push it as a ban signal. diff --git a/doc/USER_GUIDE.md b/doc/USER_GUIDE.md index 064552b..252269b 100644 --- a/doc/USER_GUIDE.md +++ b/doc/USER_GUIDE.md @@ -1,12 +1,13 @@ ![CrowdSec Logo](images/logo_crowdsec.png) + # CrowdSec Engine extension for Magento 2 ## User Guide +**Table of Contents** -**Table of Contents** - [Description](#description) - [Usage](#usage) @@ -27,29 +28,24 @@ - - ## Description -The `CrowdSec Engine` extension for Magento 2 has been designed to protect Magento 2 websites from all kinds of attacks +The `CrowdSec Engine` extension for Magento 2 has been designed to protect Magento 2 websites from all kinds of attacks by using [CrowdSec](https://www.crowdsec.net/) technology. - ## Usage ### Features - #### Push signals to the CrowdSec community This module can detect "pages scan" and "user admin enumeration" behaviors. Beyond a certain threshold, suspicious behavior triggers an alert and a "ban" signal for the detected IP is sent to the community. Signals can be sent manually or via a cron job. - #### Retrieve CrowdSec banned IPs -CrowdSec decisions can be pulled from the community blocklist. +CrowdSec decisions can be pulled from the community blocklist. Decisions can be retrieved manually or via a cron job. #### Block access to banned IPs @@ -62,67 +58,59 @@ The design and content of this ban wall can be configured in a Magento 2 CMS blo Enrolling your security machine gives you access to more details in your [CrowdSec console](https://app.crowdsec.net). It can be done manually from the back office. - ### Configurations -This module comes with configurations that you will find under `Stores → Configurations → Security → CrowdSec Engine` +This module comes with configurations that you will find under `Stores → Configurations → Security → CrowdSec Engine` admin section. -These configurations are divided in five main parts : `General`, `Scenarios and signals`, `Decisions`, `Crons job` and +These configurations are divided in five main parts : `General`, `Scenarios and signals`, `Decisions`, `Crons job` and `Advanced`. - #### General Settings - In the `General` part, you will set your security engine details. +In the `General` part, you will set your security engine details. ![General](images/screenshots/config-general.jpg) -*** +--- - `General → Environment` (`global` scope) +`General → Environment` (`global` scope) -Environment determines the CrowdSec environment used by the security engine: `Development` for tests, +Environment determines the CrowdSec environment used by the security engine: `Development` for tests, and `Production` for real data. - -*** +--- `General → Enrollment key` (`global` scope) -If you enroll your security engine, you will have access to a wealth of useful information [in your CrowdSec console](https://app.crowdsec.net/). +If you enroll your security engine, you will have access to a wealth of useful information [in your CrowdSec console](https://app.crowdsec.net/). You can obtain your enrollment key in your console. Once all the necessary fields have been completed, you can click on the "enroll" button. +--- -*** - - `General → Security engine name` (`global` scope) - +`General → Security engine name` (`global` scope) The name that will be display in your console. -*** +--- `General → Force enroll` (`global` scope) -If you already have enrolled your machine, you can force re-enrollment with this option. - -*** - +If you already have enrolled your machine, you can force re-enrollment with this option. +--- #### Scenarios and signals - In the `Scenarios and signals` part, you can configure the way suspicious IPs are detected and sent to the - community as a ban signal. +In the `Scenarios and signals` part, you can configure the way suspicious IPs are detected and sent to the +community as a ban signal. ![Scenario and signals](images/screenshots/config-scenario-signals.jpg) - -*** +--- `Scenarios and signals → List of detection scenarios` (`global` scope) @@ -138,7 +126,6 @@ An alert will only be triggered if the bucket overflows. So, for an alert to be triggered, several suspicious events need to be detected in a sufficiently short space of time to cause the bucket to overflow despite the leak. - ##### Black hole concept Once an alert has been detected for a given IP address and scenario, it is likely that the suspect IP address will continue its actions, which will be detected again. @@ -147,62 +134,49 @@ However, to avoid reporting the same alert too often, a certain amount of time m During this time, the IP is said to be in the black hole of the scenario. - - -| Scenario name | Description | Bucket capacity | Bucket leak speed | Black hole duration | -| :---------------------------- | ------------------------------------------------------------ | --------------- | ----------------- | ------------------- | -| Detect pages scan | Detects IPs that reach 403 or 404 pages. | 10 | 10 seconds | 1 hour | +| Scenario name | Description | Bucket capacity | Bucket leak speed | Black hole duration | +| :---------------------------- | --------------------------------------------------------------------------------------- | --------------- | ----------------- | ------------------- | +| Detect pages scan | Detects IPs that reach 403 or 404 pages. | 10 | 10 seconds | 1 hour | | Detect admin user enumeration | Detects IPs attempting to connect to the back office with several incorrect user names. | 10 | 30 seconds | 1 hour | - - In addition, regardless of the time taken, an alert will be triggered for the "Detect admin user enumeration" scenario if the number of bad user names exceeds 20. - - -*** +--- `Scenarios and signals → Ban duration` (`global` scope) When a signal is sent, we use this setting to determine the ban duration (in seconds). -*** - -#### Decisions +--- +#### Decisions - In the `Decisons` part, you can define whether you want to block banned IPs and whether you want to ban IPs - detected by local scenarios. Finally, you can configure the cache system used to store decisions. +In the `Decisons` part, you can define whether you want to block banned IPs and whether you want to ban IPs +detected by local scenarios. Finally, you can configure the cache system used to store decisions. ![Decisions](images/screenshots/config-decisions.jpg) -*** - +--- `Decisions → Ban IP locally` (`global` scope) - If enabled, a "ban" decision will be added to local cache as soon as an alert is triggered for the IP. - -*** - +--- `Decisions → Block banned IP` (`global` scope) -If enabled, a cached "banned" IP will be blocked by a ban wall (403). +If enabled, a cached "banned" IP will be blocked by a ban wall (403). You can edit the content of this ban wall in the "crowdsec-engine-ban-wall" CMS block: ![CMS ban wall](./images/screenshots/admin-cms-block.jpg) -By default, it will have the following design and content: +By default, it will have the following design and content: ![Ban wall](./images/screenshots/front-ban-wall.jpg) - -*** - +--- `Decisions → Cache configuration → Technology` (`global` scope) @@ -212,44 +186,37 @@ The File system cache is faster than calling Local API. Redis or Memcached is fa **N.B** : There are also a clear cache button fo all cache technologies. -*** - +--- `Decisions → Cache configuration → Redis DSN` (`global` scope) Only if you choose Redis cache as technology. Example of DSN: redis://localhost:6379. -*** - +--- `Decisions → Cache configuration → Memcached DSN` (`global` scope) Only if you choose Memcached cache as technology. Example of DSN: memcached://localhost:11211. -*** - +--- #### Crons jobs - In the `Cron jobs` part, you can configure cron jobs to manage signals, cached decisions and events. -Please note that you have to set 0 0 30 2 * as cron expression if you want to disable a cron job. +Please note that you have to set 0 0 30 2 \* as cron expression if you want to disable a cron job. ![Crons](images/screenshots/config-crons.jpg) -*** +--- `Crons jobs → Signals management → Cron expression for pushing signals` (`global` scope) - This task will push signals for which an alert has been triggered. You can also use the "Push signals" button to send signals manually. - -*** - +--- `Crons jobs → Cache Management → Cron expression for refreshing cache` (`global` scope) @@ -257,75 +224,63 @@ This task will pull decisions from community block-list. You can also use the "Refresh cache" button to pull them manually. - -*** - +--- `Crons jobs → Cache Management → Cron expression for file system cache pruning` (`global` scope) If you chose file system as cache technology, you can schedule here an automatic cache pruning cron task. -*** - +--- `Crons jobs → Events Management → Cron expression for cleaning events` (`global` scope) Events are stored in database. You can use this cron job to clean old events. -*** +--- `Crons jobs → Events Management → Event lifetime` (`global` scope) Events last detected more than X days ago will be deleted by the cron task above. - -*** - +--- #### Advanced settings - In the `Advanced` part, you can configure log levels and CrowdSec API call timeout. ![Advanced](images/screenshots/config-advanced.jpg) - -*** +--- `Advanced → Log level` (`global` scope) - Log messages will be written in "var/log/crowdsec-engine.log". -you can choose between: +you can choose between: - Disabled : no logs - Normal (info level) - Verbose (debug level) - -*** +--- `Advanced → Crowdsec API timeout` (`global` scope) - Maximum execution time (in seconds) for a CAPI request (used for pulling decisions or sending signals). Set a negative value (e.g. -1) to allow unlimited request timeout. ### Reports -You will find detected events list and decision metrics in the `Reports → Business Threats → CrowdSec Events and +You will find detected events list and decision metrics in the `Reports → Business Threats → CrowdSec Events and Metrics` admin section. #### Events list - ![Events reporting](./images/screenshots/report-events.jpg) You can filter according to your needs: by IP, by scenario, by date, etc. - #### Metrics ![metrics reporting](./images/screenshots/report-metrics.jpg)