✨ add custom selfhosted captcha (#259)

* ✨ Add wicketkeeper captcha * ✨ Anom config * 🍱 fix readme * 🍱 fix lint * 🍱 fix lint * 🍱 normalize * 🍱 fix lint * 🍱 fix lint * ✨ Add env for RemediationStatusCode (#250) * ✨ Add env for defaultStatusCode * 📝 doc * ✨change name of the parameter * 🔧 Add config check * fix lint * 📈 Report traffic dropped metrics to LAPI (#223) * Initial implementation * fix * fixes * Fixes * xx * progress * xx * xx * xx * fix linter * Progress * Fixes * xx * xx * Remove trace logger * Last fix * fix lint * fix lint * fix lint --------- Co-authored-by: Max Lerebourg <maxlerebourg@gmail.com> * ✨ Anom config * 🍱 fix readme * 🍱 fix lint * 🍱 normalize * 🍱 fix lint * 📝 Add documentation * 📝 Fix example and makefile and doc for wicketkeeper * 🍱 fix last things * 🍱 add disclaimer to use maxlerebourg docker image * 🍱 Use official wicketpeeker image * 🍱 revert unnecessary code * 🍱 fix --------- Co-authored-by: David <deivid.garcia.garcia@gmail.com> Co-authored-by: max.lerebourg <max.lerebourg@monisnap.com> Co-authored-by: mhx <mathieu@hanotaux.fr>
2026-07-21 11:38:59 +02:00 · 2025-09-01 19:41:45 +02:00
parent 734975c206
commit 7c4f5163e9
13 changed files with 649 additions and 46 deletions
@@ -0,0 +1,76 @@
+# Example
+
+Read the example captcha before this, to better understand what is done here.
+
+### Traefik configuration
+
+The minimal configuration is defined below to implement custom captcha.  
+This documentation use https://github.com/a-ve/wicketpeeker, a self-hosted captcha provider that have a similar API than big providers.
+
+Minimal API requirement:
+
+- the JS file URL to load the captcha on the served `captcha.html`
+- the HTML className to tell to the JS where to display the challenge
+- the verify URL endpoint to send the field `response` from the captcha with `content-type: application/x-www-form-urlencoded`
+- the name of the field when you POST the resolved captcha to Traefik
+
+- the JS file need to respect the `data-callback` on the div that contains the captcha if you use our template, but you can customize it by your side
+
+```yaml
+  traefik:
+    ...
+    labels:
+      # Choose captcha provider
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaProvider=custom"
+      # Define captcha grace period seconds
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaGracePeriodSeconds=1800"
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaCustomJsURL=http://captcha.localhost:8000/fast.js"
+      # Inside Traefik container the plugin must be able to reach wicketkeeper service so we can go through a Traefik localhost
+      # domain which would resolve traefik itself and the port for the dashboard
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.CaptchaCustomValidateURL=http://wicketkeeper:8080/v0/siteverify"
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.CaptchaCustomKey=wicketkeeper"
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.CaptchaCustomResponse=wicketkeeper_solution"
+      # Define captcha HTML file path
+      - "traefik.http.middlewares.crowdsec.plugin.bouncer.captchaHTMLFilePath=/captcha.html"
+```
+
+```yaml
+wicketkeeper:
+  image: ghcr.io/a-ve/wicketkeeper:latest
+  user: root
+  ports:
+    - "8080:8080"
+  environment:
+    - ROOT_URL=http://localhost:8080
+    - LISTEN_PORT=8080
+    - REDIS_ADDR=redis:6379
+    - DIFFICULTY=4
+    - ALLOWED_ORIGINS=*
+    - PRIVATE_KEY_PATH=/data/wicketkeeper.key
+  volumes:
+    - ./data:/data
+  depends_on:
+    - redis
+redis:
+  image: redis/redis-stack-server:latest
+```
+
+## Exemple navigation
+
+We can try to query normally the whoami server:
+
+```bash
+curl http://localhost:8000/foo
+```
+
+We can try to ban ourself and retry.
+
+```bash
+docker exec crowdsec cscli decisions add --ip 10.0.0.20 -d 10m --type captcha
+```
+
+To play the demo environment run:
+
+```bash
+make run_custom_captcha
+```