Merge pull request #6 from crowdsecurity/feature/cap-remediations

Cap remediation to a capped value. Useful for sensitive websites (as e-commerce).

Author: mobula9

.github/workflows/tests.yml

@@ -1,8 +1,7 @@
 name: Tests
 
 on:
-    pull_request:
-    push: #TODO P3 No tests on push because it causes an unresolved bug (no space left on device). This Smell a race condition.
+    push:
 
 jobs:
 

docs/configuration.rst

@@ -20,7 +20,7 @@ Full configuration reference
        'live_mode'=> true,
        
        // Optional. Cap the remediation to the selected one. Select from 'bypass' (minimum remediation), 'captcha' or 'ban' (maximum remediation). Defaults to 'ban'.
-       'max_remediation'=> 'ban',
+       'max_remediation_level'=> 'ban',
 
        // Optional. Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 600 (10 minutes).
        'cache_expiration_for_clean_ip'=> '600',

docs/getting-started.rst

@@ -29,7 +29,7 @@ Use the bouncer library (live mode)
    $bouncer = new Bouncer();
    $bouncer->configure(['api_token'=> $apiToken], $cacheAdapter);
 
-   $remediation = $bouncer->getRemediationForIp($blockedIp);// Return "ban", "catpcha" or "bypass"
+   $remediation = $bouncer->getRemediationForIp($blockedIp);// Return "ban", "captcha" or "bypass"
 
 Use the bouncer library (stream mode)
 ------------------------------------

src/ApiCache.php

@@ -69,12 +69,9 @@ private function addRemediationToCacheItem(string $ip, string $type, int $expira
         $remediations = $item->get();
         $remediations = $remediations ?: [];
 
-
-        // TODO P3 use constant for clean, ban or captcha single word
-        // TODO P3 wording replace "clean" by "bypass"
-        $index = array_search('clean', array_column($remediations, 0));
+        $index = array_search(Constants::REMEDIATION_BYPASS, array_column($remediations, 0));
         if (false !== $index) {
-            $this->logger->debug("cache#$ip: Previously clean IP but now bad, remove the \"clean\" remediation immediately");
+            $this->logger->debug("cache#$ip: Previously clean IP but now bad, remove the ".Constants::REMEDIATION_BYPASS." remediation immediately");
             unset($remediations[$index]);   
         }
 
@@ -190,7 +187,7 @@ private static function parseDurationToSeconds(string $duration): int
     private function formatRemediationFromDecision(?array $decision): array
     {
         if (!$decision) {
-            return ['clean', time() + $this->cacheExpirationForCleanIp, 0];
+            return [Constants::REMEDIATION_BYPASS, time() + $this->cacheExpirationForCleanIp, 0];
         }
 
         return [
@@ -347,7 +344,7 @@ private function hit(string $ip): string
      *
      * @return string the computed remediation string, or null if no decision was found
      */
-    public function get(string $ip): ?string
+    public function get(string $ip): string
     {
         $this->logger->debug('IP to check: '.$ip);
         if (!$this->liveMode && !$this->warmedUp) {

src/Bouncer.php

@@ -29,6 +29,9 @@ class Bouncer
     /** @var ApiCache */
     private $apiCache;
 
+    /** @var int */
+    private $maxRemediationLevelIndex;
+
     public function __construct(ApiCache $apiCache = null, LoggerInterface $logger = null)
     {
         if (!$logger) {
@@ -49,6 +52,8 @@ public function configure(array $config, AbstractAdapter $cacheAdapter): void
         $processor = new Processor();
         $this->config = $processor->processConfiguration($configuration, [$config]);
 
+        $this->maxRemediationLevelIndex = array_search($this->config['max_remediation_level'], Constants::ORDERED_REMEDIATIONS);
+
         // Configure Api Cache.
         $this->apiCache->configure(
             $cacheAdapter,
@@ -61,23 +66,37 @@ public function configure(array $config, AbstractAdapter $cacheAdapter): void
         );
     }
 
+    /**
+     * Cap the remediation to a fixed value given in configuration
+    */
+    private function capRemediationLevel($remediation): string
+    {
+        $currentIndex = array_search($remediation, Constants::ORDERED_REMEDIATIONS);
+        if ($currentIndex < $this->maxRemediationLevelIndex) {
+            return Constants::ORDERED_REMEDIATIONS[$this->maxRemediationLevelIndex];
+        }
+        return $remediation;
+    }
+
     /**
      * Get the remediation for the specified IP. This method use the cache layer.
      * In live mode, when no remediation was found in cache, the cache system will call the API to check if there is a decision.
      *
      * @return string the remediation to apply (ex: 'ban', 'captcha', 'bypass')
      */
-    public function getRemediationForIp(string $ip): ?string
+    public function getRemediationForIp(string $ip): string
     {
         $intIp = ip2long($ip);
         if (false === $intIp) {
             throw new BouncerException("IP $ip should looks like x.x.x.x, with x in 0-255. Ex: 1.2.3.4");
         }
-        return $this->apiCache->get(long2ip($intIp));
+        $remediation = $this->apiCache->get(long2ip($intIp));
+        $remediation = $this->capRemediationLevel($remediation);
+        return $remediation;
     }
 
     /**
-     * Returns a default "CrowdSec 403" HTML template to display to a web browser using a ban IP.
+     * Returns a default "CrowdSec 403" HTML template to display to a web browser using a banned IP.
      */
     public function getDefault403Template(): string
     {

src/Configuration.php

@@ -32,7 +32,7 @@ public function getConfigTreeBuilder()
             ->scalarNode('api_user_agent')->defaultValue(Constants::BASE_USER_AGENT)->end()
             ->integerNode('api_timeout')->defaultValue(Constants::API_TIMEOUT)->end()
             ->booleanNode('live_mode')->defaultValue(true)->end()
-            ->enumNode('max_remediation')->values(['bypass', 'captcha', 'ban'])->defaultValue('ban')->end()
+            ->enumNode('max_remediation_level')->values(Constants::ORDERED_REMEDIATIONS)->defaultValue(Constants::REMEDIATION_BAN)->end()
             ->integerNode('cache_expiration_for_clean_ip')->defaultValue(Constants::CACHE_EXPIRATION_FOR_CLEAN_IP)->end()
             ->end();
 

src/Constants.php

@@ -26,6 +26,16 @@ class Constants
     /** @var int The duration we keep a clean IP in cache 600s = 10m */
     const CACHE_EXPIRATION_FOR_CLEAN_IP = 600; // TODO P2 get the correct one
 
-    /** @var array The list of each known remediation, sorted by priority */
-    const ORDERED_REMEDIATIONS = ['ban', 'captcha', 'clean']; // TODO P2 get the correct one
+    /** @var string The ban remediation */
+    const REMEDIATION_BAN = 'ban';
+
+    /** @var string The captcha remediation */
+    const REMEDIATION_CAPTCHA = 'captcha';
+
+    /** @var string The bypass remediation */
+    const REMEDIATION_BYPASS = 'bypass';
+
+    // TODO P2 get the correct list
+    /** @var array<string> The list of each known remediation, sorted by priority */
+    const ORDERED_REMEDIATIONS = [self::REMEDIATION_BAN, self::REMEDIATION_CAPTCHA, self::REMEDIATION_BYPASS];
 }

tests/IpVerificationTest.php

@@ -107,14 +107,14 @@ public function testCanVerifyIpInLiveModeWithCacheSystem(AbstractAdapter $cacheA
 
         $cleanRemediation1stCall = $bouncer->getRemediationForIp($cleanIp);
         $this->assertEquals(
-            'clean',
+            'bypass',
             $cleanRemediation1stCall,
             'Get decisions for a clean IP for the first time (it should be a cache miss)'
         );
 
         // Call the same thing for the second time (now it should be a cache hit)
         $cleanRemediation2ndCall = $bouncer->getRemediationForIp($cleanIp);
-        $this->assertEquals('clean', $cleanRemediation2ndCall);
+        $this->assertEquals('bypass', $cleanRemediation2ndCall);
 
         // Clear cache
         $cacheAdapter->clear();
@@ -123,6 +123,14 @@ public function testCanVerifyIpInLiveModeWithCacheSystem(AbstractAdapter $cacheA
 
         $remediation3rdCall = $bouncer->getRemediationForIp($badIp);
         $this->assertEquals('ban', $remediation3rdCall);
+
+        // Reconfigure the bouncer to set maximum remediation level to "captcha"
+        $config['max_remediation_level'] = 'captcha';
+        $bouncer->configure($config, $cacheAdapter);
+        $cappedRemediation = $bouncer->getRemediationForIp($badIp);
+        $this->assertEquals('captcha', $cappedRemediation, 'The remediation for the banned IP should now be "captcha"');
+        $config['max_remediation_level'] = 'ban';
+        $bouncer->configure($config, $cacheAdapter);
     }
 
     /**
@@ -170,22 +178,30 @@ public function testCanVerifyIpInStreamModeWithCacheSystem(AbstractAdapter $cach
             'Get decisions for a bad IP for the first time (as the cache has been warmed up should be a cache hit)'
         );
 
+        // Reconfigure the bouncer to set maximum remediation level to "captcha"
+        $config['max_remediation_level'] = 'captcha';
+        $bouncer->configure($config, $cacheAdapter);
+        $cappedRemediation = $bouncer->getRemediationForIp($badIp);
+        $this->assertEquals('captcha', $cappedRemediation, 'The remediation for the banned IP should now be "captcha"');
+        $config['max_remediation_level'] = 'ban';
+        $bouncer->configure($config, $cacheAdapter);
+
         $this->assertEquals(
-            'clean',
+            'bypass',
             $bouncer->getRemediationForIp($cleanIp),
             'Get decisions for a clean IP for the first time (as the cache has been warmed up should be a cache hit)'
         );
 
         // Preload the remediation to prepare the next tests.
         $this->assertEquals(
-            'clean',
+            'bypass',
             $bouncer->getRemediationForIp($newlyBadIp),
-            'Preload the clean remediation to prepare the next tests'
+            'Preload the bypass remediation to prepare the next tests'
         );
-        
+
         // Add and remove decision
         $this->watcherClient->setSecondState();
-        
+
         // Pull updates
         $bouncer->refreshBlocklistCache();
 
@@ -213,7 +229,7 @@ public function testCanVerifyIpInStreamModeWithCacheSystem(AbstractAdapter $cach
         );
 
         $this->assertEquals(
-            'clean',
+            'bypass',
             $bouncer->getRemediationForIp($badIp),
             'The old decisions should now be removed, so the previously bad IP should now be clean'
         );