✨ Implement captcha protection (#139)

* ✨ Implement captcha protection * 🍱 fix lint * 🍱 fix lint * 🍱 fix lint * 📝 Update exemple doc Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Add doc for the captcha and update some exemples Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Update doc readme with some arguments Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Update doc Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 generic documentation in readme on catpcha feature Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Update exemple captcha Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Fix rendering and typos Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 🍱 fix readme * 📝 update doc ongoing Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Add doc on crowdsec config Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Add sequence diagram for captcha exemple Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * Fix rendering and typos Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 add mermaid basics graphs Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Update first diagram Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Update first seq diagram Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 🐛 Fix bug in diagram syntax Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 rework all diagrams Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 📝 Update a bit diagrams Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> * 🌐 Fix lang fr * 🚸 change advice on uniq lapi confusing for users * ✅ Fix test du to rework on cache interface * 🚨 Fix lint --------- Signed-off-by: Mathieu Hanotaux <mathieu@hanotaux.fr> Co-authored-by: max.lerebourg <max.lerebourg@monisnap.com> Co-authored-by: Mathieu Hanotaux <mathieu@hanotaux.fr>
2026-07-21 11:38:59 +02:00 · 2024-04-01 11:41:28 +02:00
parent c3e0c2d4c3
commit 497d1a2928
24 changed files with 1413 additions and 184 deletions
@@ -0,0 +1,146 @@
+# Example
+## Enabling catpcha response from crowdsec
+
+Crowdsec support 3 remediations solutions `ban`, `captcha`, and `throttle`.  
+This plugins support the `ban` and `captcha` remediation.  
+
+### Traefik configuration
+
+The minimal configuration is defined below.  
+For now 3 captcha providers are supported:  
+ - [hcaptcha](https://www.hcaptcha.com/)
+ - [recaptcha](https://www.google.com/recaptcha/about/)
+ - [turnstile](https://www.cloudflare.com/fr-fr/products/turnstile/)
+
+```yaml
+  labels:
+      # Choose captcha provider
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaProvider=hcaptcha"
+      # Define captcha site key
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaSiteKey=FIXME"
+      # Define captcha secret key
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaSecretKey=FIXME"
+      # Define captcha grade period seconds
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaGracePeriodSeconds=1800"
+      # Define captcha HTML file path
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaHTMLFilePath=/captcha.html"
+```
+
+The captcha HTML file must be present in the Traefik container (bind mounted or added during a custom build).  
+It is not directly accessible from Traefik even when importing the plugin, so [download](https://raw.githubusercontent.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/master/captcha.html) it locally to expose it to Traefik.
+
+```yaml 
+  ...
+  traefik:
+    image: "traefik:v2.11.0"
+    volumes:
+      - './captcha.html:/captcha.html'
+  ...
+```
+### Crowdsec configuration
+
+Crowdsec by default will take the ban action on suspicious activity detected in logs.  
+To instruct Crowdsec to use captcha remediation, change the `/etc/crowdsec/profiles.yaml`.   
+
+2 modes are supported:
+- Always return a captcha decision
+- Return a captcha decision the first X times and then a ban decision.
+
+The second mode could be used to prevent repeated malicious activity.
+More information is available on configuring Crowdsec in the [official documentation](https://docs.crowdsec.net/docs/next/profiles/captcha_profile/).
+
+```yaml
+  ...
+  crowdsec:
+    image: crowdsecurity/crowdsec:v1.6.0
+    volumes:
+      # For captcha and ban mixed decision
+      - './profiles.yaml:/etc/crowdsec/profiles.yaml:ro' 
+      # For captcha only remediation
+      # - './profiles_captcha_only.yaml:/etc/crowdsec/profiles.yaml:ro'
+  ...
+```
+## Exemple navigation
+We can try to query normally the whoami server:
+```bash
+curl http://localhost:8000/foo
+```
+
+We can try to ban ourself
+
+```bash
+docker exec crowdsec cscli decisions add --ip 10.0.0.20 -d 4h --type captcha
+```
+
+![image decision captcha](image_decision_captcha.png)
+
+We will see in the browser the captcha validation page:
+
+![image captcha validation](image_captcha_validation.png)
+
+To play the demo environment run:
+```bash
+make run_captcha
+```
+
+> Note, if we are banned with a "ban" decision from crowdsec a captcha will not be asked and you will have to wait for the decision to expire or remove it manually.  
+
+```bash
+docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m --type ban
+```
+
+## Captcha Workflow
+
+> Context: The user has no decision attached to his IP
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant TraefikPlugin
+    User->>TraefikPlugin: Can I access that webpage
+    create participant PluginCache
+    TraefikPlugin-->>PluginCache: Does the user IP has a crowdsec decision ?
+    Destroy PluginCache
+    PluginCache-->>TraefikPlugin: Nothing, all good!
+    Destroy TraefikPlugin
+    TraefikPlugin->>Webserver: Forwarding this HTTP Request from User
+    Webserver->>User: HTTP Response
+```
+
+> Context: The user has a captcha decision attached to his IP
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant TraefikPlugin
+    User->>TraefikPlugin: Can I access that webpage
+    create participant PluginCache
+    TraefikPlugin-->>PluginCache: Does the User IP has a Crowdsec Decision ?
+    PluginCache-->>TraefikPlugin: Yes a Catpcha Decision
+    TraefikPlugin->>User: Please complete this captcha
+    User->>TraefikPlugin: Fine, done!
+    create participant ProviderCaptcha
+    TraefikPlugin-->>ProviderCaptcha: Is the validation OK ?
+    Destroy ProviderCaptcha    
+    ProviderCaptcha-->>TraefikPlugin: Yes
+    TraefikPlugin-->>PluginCache: Set the User IP Clean for captchaGracePeriodSeconds
+    Destroy PluginCache
+    PluginCache-->>TraefikPlugin: Done
+    Destroy TraefikPlugin
+    TraefikPlugin->>Webserver: Forwarding this HTTP Request from User
+    Webserver->>User: HTTP Response
+```
+
+> Context: The user has a ban decision attached to his IP
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant TraefikPlugin
+    User->>TraefikPlugin: Can I access that webpage
+    create participant PluginCache
+    TraefikPlugin-->>PluginCache: Does the User IP has a Crowdsec Decision ?
+    Destroy PluginCache
+    PluginCache-->>TraefikPlugin: Yes a ban Decision
+    TraefikPlugin->>User: No, HTTP 403
+```