mirror of
https://github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin.git
synced 2026-07-21 03:28:59 +02:00
f5d580578c
The sequence diagrams used the keyword `Destroy` (capital D). Mermaid keywords are case-sensitive, so the invalid token aborted parsing and every diagram failed to render on GitHub. Lowercase all `Destroy` -> `destroy` in README.md and the captcha example README. The `create` keyword was already correct, and each create/destroy is properly paired with an adjacent message. Fixes #270 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
162 lines
5.1 KiB
Markdown
162 lines
5.1 KiB
Markdown
# 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 grace 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:v3.0.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/local_api/profiles/captcha_profile/).
|
|
|
|
```yaml
|
|
...
|
|
crowdsec:
|
|
image: crowdsecurity/crowdsec:v1.6.1-2
|
|
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
|
|
```
|
|
|
|
|
|
|
|
We will see in the browser the captcha validation page:
|
|
|
|
|
|
|
|
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
|
|
```
|
|
|
|
## Captcha Configuration:
|
|
|
|
- Recaptcha
|
|
|
|
Choose v2 (challenge) and configure the domain to protect:
|
|
|
|
|
|
- Turnstile
|
|
|
|
TODO
|
|
|
|
- Hcatpcha
|
|
|
|
TODO
|