New! This plugin now supports AppSec feature including virtual patching and capabilities support for your legacy ModSecurity rules.
This plugin aims to implement a Crowdsec Bouncer in a Traefik plugin.
CrowdSec is an open-source and collaborative IPS (Intrusion Prevention System) and a security suite. We leverage local behavior analysis and crowd power to build the largest CTI network in the world.
The purpose is to enable Traefik to authorize or block requests from IPs based on their reputation and behavior.
The Crowdsec utility will provide the community blocklist which contains highly reported and validated IPs banned from the Crowdsec network.
When used with Crowdsec it will leverage the local API which will analyze Traefik logs and take decisions on the requests made by users/bots. Malicious actors will be banned based on patterns used against your website.
Appsec feature is supported from plugin version 1.2.0 and Crowdsec 1.6.0.
The AppSec Component offers:
More information on appsec in the Crowdsec Documentation.
Remediation offered by Crowdsec and supported by the plugin can be either ban or captcha.
For the ban remediation the user will be blocked in Traefik (HTTP 403).
For the captcha remediation, the user will be redirected to a page to complete a captcha challenge.
On successfull completion, he will be cleaned for a specified period of time before a new resolution challenge is expected if Crowdsec still has a decision to verify the user behavior. See the example captcha for more informations and configuration intructions.
The following captcha providers are supported now:
There are 5 operating modes (CrowdsecMode) for this plugin:
| Mode | Description |
|---|---|
| none | If the client IP is on ban list, it will get a http code 403 response. Otherwise, request will continue as usual. All request call the Crowdsec LAPI |
| live | If the client IP is on ban list, it will get a http code 403 response. Otherwise, request will continue as usual. The bouncer can leverage use of a local cache in order to reduce the number of requests made to the Crowdsec LAPI. It will keep in cache the status for each IP that makes queries. |
| stream | Stream Streaming mode allows you to keep in the local cache only the Banned IPs, every requests that does not hit the cache is authorized. Every minute, the cache is updated with news from the Crowdsec LAPI. |
| alone | Standalone mode, similar to the streaming mode but the blacklisted IPs are fetched on the CAPI. Every 2 hours, the cache is updated with news from the Crowdsec CAPI. It does not include any locally banned IP, but can work without a crowdsec service. |
| appsec | Disable Crowdsec IP checking but apply Crowdsec Appsec checking. This mode is intended to be used when Crowdsec IP checking is applied at the Firewall Level. |
The streaming mode is recommended for performance, decisions are updated every 60 sec by default and that's the only communication between Traefik and Crowdsec. Every request that happens hits the cache for quick decisions.
The cache can be local to Traefik in memory or using a separate Redis instance.
Below are Mermaid diagrams detailling how each mode work:
A Ban decision exists in CrowdsecLAPI
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant CrowdsecLAPI6 TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a Crowdsec Decision ?7 Destroy CrowdsecLAPI8 CrowdsecLAPI-->>TraefikPlugin: Yes a ban Decision9 TraefikPlugin->>User: No, HTTP 403
No decision in CrowdsecLAPI
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant CrowdsecLAPI6 TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a crowdsec decision ?7 Destroy CrowdsecLAPI8 CrowdsecLAPI-->>TraefikPlugin: Nothing, all good!9 Destroy TraefikPlugin10 TraefikPlugin->>Webserver: Forwarding this HTTP Request from User11 Webserver->>User: HTTP Response
A Ban decision exists in CrowdsecLAPI but not in cache
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant PluginCache6 TraefikPlugin-->>PluginCache: Does the User IP has a crowdsec decision ?7 PluginCache-->>TraefikPlugin: Nothing, all good!8 create participant CrowdsecLAPI9 TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a crowdsec decision ?10 Destroy CrowdsecLAPI11 CrowdsecLAPI-->>TraefikPlugin: Yes a ban Decision12 TraefikPlugin-->>PluginCache: Store the information for this IP for DefaultDecisionSeconds13 Destroy PluginCache14 PluginCache-->>TraefikPlugin: Done15 TraefikPlugin->>User: No, HTTP 403
No decision in cache
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant PluginCache6 TraefikPlugin-->>PluginCache: Does the User IP has a crowdsec decision ?7 PluginCache-->>TraefikPlugin: Nothing, all good!8 create participant CrowdsecLAPI9 TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a crowdsec decision ?10 Destroy CrowdsecLAPI11 CrowdsecLAPI-->>TraefikPlugin: Nothing, all good!12 TraefikPlugin-->>PluginCache: Store the information for this IP for DefaultDecisionSeconds13 Destroy PluginCache14 PluginCache-->>TraefikPlugin: Done15 TraefikPlugin->>Webserver: Forwarding this HTTP Request from User16 Webserver->>User: HTTP Response
Cache Synchronization every UpdateIntervalSeconds
1sequenceDiagram2 participant TraefikPlugin3 participant CrowdsecLAPI4 TraefikPlugin->>CrowdsecLAPI: What are the current decisions5 Destroy CrowdsecLAPI6 CrowdsecLAPI->>TraefikPlugin: Here is the list7 create participant PluginCache8 TraefikPlugin-->>PluginCache: Store this list9 Destroy PluginCache10 PluginCache-->>TraefikPlugin: Done
A Ban decision exists in cache
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant PluginCache6 TraefikPlugin-->>PluginCache: Does the User IP has a crowdsec decision ?7 Destroy PluginCache8 PluginCache-->>TraefikPlugin: Yes a ban decision9 Destroy TraefikPlugin10 TraefikPlugin->>User: No, HTTP 403
No decision in cache
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant PluginCache6 TraefikPlugin-->>PluginCache: Does the User IP has a crowdsec decision ?7 Destroy PluginCache8 PluginCache-->>TraefikPlugin: Nothing, all good!9 Destroy TraefikPlugin10 TraefikPlugin->>Webserver: Forwarding this HTTP Request from User11 Webserver->>User: HTTP Response
Cache Synchronization every 2 hours to the Crowdsec Central API
1sequenceDiagram2 participant TraefikPlugin3 participant CrowdsecCAPI4 TraefikPlugin->>CrowdsecCAPI: What are the current decisions from CAPI5 Destroy CrowdsecCAPI6 CrowdsecCAPI->>TraefikPlugin: Here is the list7 create participant PluginCache8 TraefikPlugin-->>PluginCache: Store this list9 Destroy PluginCache10 PluginCache-->>TraefikPlugin: Done
A Ban decision exists in cache
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant PluginCache6 TraefikPlugin-->>PluginCache: Does the User IP has a crowdsec decision ?7 Destroy PluginCache8 PluginCache-->>TraefikPlugin: Yes a ban decision9 Destroy TraefikPlugin10 TraefikPlugin->>User: No, HTTP 403
No decision in cache
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant PluginCache6 TraefikPlugin-->>PluginCache: Does the User IP has a crowdsec decision ?7 Destroy PluginCache8 PluginCache-->>TraefikPlugin: Nothing, all good!9 Destroy TraefikPlugin10 TraefikPlugin->>Webserver: Forwarding this HTTP Request from User11 Webserver->>User: HTTP Response
The request is detected as malicious
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant CrowdsecAppSec6 TraefikPlugin-->>CrowdsecAppSec: Is this request malicious ?7 Destroy CrowdsecAppSec8 CrowdsecAppSec-->>TraefikPlugin: Yes I think so9 Destroy TraefikPlugin10 TraefikPlugin->>User: No, HTTP 403
The request is not detected as malicious
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant CrowdsecAppSec6 TraefikPlugin-->>CrowdsecAppSec: Is this request malicious ?7 Destroy CrowdsecAppSec8 CrowdsecAppSec-->>TraefikPlugin: No I don't think so9 Destroy TraefikPlugin10 TraefikPlugin->>Webserver: Forwarding this HTTP Request from User11 Webserver->>User: HTTP Response
1sequenceDiagram2 participant User3 participant TraefikPlugin4 User->>TraefikPlugin: Can I access that webpage5 create participant PluginCache6 TraefikPlugin-->>PluginCache: Does the User IP has a Crowdsec Decision ?7 PluginCache-->>TraefikPlugin: Yes a Catpcha Decision8 TraefikPlugin->>User: Please complete this captcha9 User->>TraefikPlugin: Fine, done!10 create participant ProviderCaptcha11 TraefikPlugin-->>ProviderCaptcha: Is the validation OK ?12 Destroy ProviderCaptcha13 ProviderCaptcha-->>TraefikPlugin: Yes14 TraefikPlugin-->>PluginCache: Set the User IP Clean for captchaGracePeriodSeconds15 Destroy PluginCache16 PluginCache-->>TraefikPlugin: Done17 Destroy TraefikPlugin18 TraefikPlugin->>Webserver: Forwarding this HTTP Request from User19 Webserver->>User: HTTP Response
To get started, use the docker-compose.yml file.
You can run it with:
1make run
[!IMPORTANT]
Some of the behaviours and configuration parameters are shared globally across all crowdsec middlewares even if you declare different middlewares with different settings.Cache is shared by all services: This means if an IP is banned, all services which are protected by an instance of the plugin will deny requests from that IP
If you define different caches for different middlewares, only the first one to be instantiated will be bound to the crowdsec stream.
Overall, this middleware is designed in such a way that only one instance of the plugin is possible. You can have multiple crowdsec middlewares in the same cluster, the key parameters must be aligned (MetricsUpdateIntervalSeconds, CrowdsecMode, CrowdsecAppsecEnabled, etc.)
[!WARNING]
Appsec maximum body limit is defaulted to 10MB > Be careful when you upgrade to >1.4.x
INFO, expected values are: INFO, DEBUG, ERRORstdout / stderr or file if LogFilePath is providedlive, expected values are: none, live, stream, alone, appsecCrowdsecLapiScheme, expected values are: http, httpsCrowdsecLapiKeyhttp, expected values are: http, httpsban or captcha)stream mode, the interval between requests to fetch blacklisted IPs from LAPIstream and alone mode, the maximum number of time we can not reach Crowdsec before blocking traffic (set -1 to never block)live mode, maximum decision durationalone mode, login for Crowdsec CAPIalone mode, password for Crowdsec CAPIalone mode, scenarios for Crowdsec CAPIhcaptcha, recaptcha, turnstile or customcustom, URL used to load the challenge in the HTML (in case of hcaptcha: https://hcaptcha.com/1/api.js)custom, URL used to validate the challenge (in case of hcaptcha: https://api.hcaptcha.com/siteverify)custom, used to set class name of the div used by captcha provider (in case of hcaptcha: h-captcha)custom, used to set the field in the POST body from the captcha.html to Traefik (in case of hcaptcha: h-captcha-response)For each plugin, the Traefik static configuration must define the module name (as is usual for Go packages).
The following declaration (given here in YAML) defines a plugin:
Note that you don't need to copy all thoses settings but only the ones you want to use.
See the examples for advanced usage.
1# Static configuration23experimental:4 plugins:5 bouncer:6 moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin7 version: vX.Y.Z # To update
1# Dynamic configuration23http:4 routers:5 my-router:6 rule: host(`whoami.localhost`)7 service: service-foo8 entryPoints:9 - web10 middlewares:11 - crowdsec1213 services:14 service-foo:15 loadBalancer:16 servers:17 - url: http://127.0.0.1:50001819 middlewares:20 crowdsec:21 plugin:22 bouncer:23 enabled: false24 logLevel: DEBUG25 LogFilePath: ""26 updateIntervalSeconds: 6027 updateMaxFailure: 028 defaultDecisionSeconds: 6029 remediationStatusCode: 40330 httpTimeoutSeconds: 1031 crowdsecMode: live32 crowdsecAppsecEnabled: false33 crowdsecAppsecScheme: ""34 crowdsecAppsecHost: crowdsec:742235 crowdsecAppsecPath: "/"36 crowdsecAppsecFailureBlock: true37 crowdsecAppsecUnreachableBlock: true38 crowdsecAppsecBodyLimit: 1048576039 crowdsecLapiKey: privateKey-foo40 crowdsecLapiScheme: http41 crowdsecLapiHost: crowdsec:808042 crowdsecLapiPath: "/"43 crowdsecLapiTLSInsecureVerify: false44 crowdsecCapiMachineId: login45 crowdsecCapiPassword: password46 crowdsecCapiScenarios:47 - crowdsecurity/http-path-traversal-probing48 - crowdsecurity/http-xss-probing49 - crowdsecurity/http-generic-bf50 forwardedHeadersTrustedIPs:51 - 10.0.10.23/3252 - 10.0.20.0/2453 clientTrustedIPs:54 - 192.168.1.0/2455 forwardedHeadersCustomName: X-Custom-Header56 remediationHeadersCustomName: cs-remediation57 redisCacheEnabled: false58 redisCacheHost: "redis:6379"59 redisCachePassword: password60 redisCacheDatabase: "5"61 redisCacheUnreachableBlock: true62 crowdsecLapiTLSCertificateAuthority: |-63 -----BEGIN CERTIFICATE-----64 MIIEBzCCAu+gAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwgZQxCzAJBgNVBAYTAlVT65 ...66 Q0veeNzBQXg1f/JxfeA39IDIX1kiCf71tGlT67 -----END CERTIFICATE-----68 crowdsecLapiTLSCertificateBouncer: |-69 -----BEGIN CERTIFICATE-----70 MIIEHjCCAwagAwIBAgIUOBTs1eqkaAUcPplztUr2xRapvNAwDQYJKoZIhvcNAQEL71 ...72 RaXAnYYUVRblS1jmePemh388hFxbmrpG2pITx8B5FMULqHoj11o2Rl0gSV6tHIHz73 N2U=74 -----END CERTIFICATE-----75 crowdsecLapiTLSCertificateBouncerKey: |-76 -----BEGIN RSA PRIVATE KEY-----77 MIIEogIBAAKCAQEAtYQnbJqifH+ZymePylDxGGLIuxzcAUU4/ajNj+qRAdI/Ux3d78 ...79 ic5cDRo6/VD3CS3MYzyBcibaGaV34nr0G/pI+KEqkYChzk/PZRA=80 -----END RSA PRIVATE KEY-----81 captchaProvider: hcaptcha82 captchaSiteKey: FIXME83 captchaSecretKey: FIXME84 captchaGracePeriodSeconds: 180085 captchaHTMLFilePath: /captcha.html86 banHTMLFilePath: /ban.html87 traceHeadersCustomName: X-Request-ID88 metricsUpdateIntervalSeconds: 600
CrowdsecLapiTlsCertificateBouncerKey, CrowdsecLapiTlsCertificateBouncer, CrowdsecLapiTlsCertificateAuthority, CrowdsecAppsecTlsCertificateAuthority, CrowdsecCapiMachineId, CrowdsecCapiPassword, CrowdsecLapiKey, CrowdsecAppsecKey, CaptchaSiteKey, CaptchaSecretKey and RedisCachePassword can be provided with the content as raw or through a file path that Traefik can read.
The file variable will be used as preference if both content and file are provided for the same variable.
Format is:
You can authenticate to the LAPI either with LAPIKEY or by using client certificates.
Please see below for more details on each option.
You can generate a crowdsec API key for the LAPI.
You can follow the documentation here: docs.crowdsec.net/docs/user_guides/lapi_mgmt
1docker compose -f docker-compose-local.yml up -d crowdsec2docker exec crowdsec cscli bouncers add crowdsecBouncer
This LAPI key must be set where is noted FIXME-LAPI-KEY in the docker-compose.yml
1..2whoami:3 labels:4 - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapikey=FIXME-LAPI-KEY"5 - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapischeme=http"6 - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapihost=crowdsec:8080"7..8crowdsec:9 environment:10 BOUNCER_KEY_TRAEFIK: FIXME-LAPI-KEY
Note:
Crowdsec does not require a specific format for la LAPI-key, you may use something like FIXME-LAPI-KEY but that is not recommanded for obvious reasons
You can then run all the containers:
1docker compose up -d
You can follow the example in examples/tls-auth to view how to authenticate with client certificates with the LAPI.
In that case, communications with the LAPI must go through HTTPS.
A script is available to generate certificates in examples/tls-auth/gencerts.sh and must be in the same directory as the inputs for the PKI creation.
To communicate with the LAPI in HTTPS you need to either accept any certificates by setting the crowdsecLapiTLSInsecureVerify to true or add the CA used by the server certificate of Crowdsec using crowdsecLapiTLSCertificateAuthority or crowdsecLapiTLSCertificateAuthorityFile.
Set the crowdsecLapiScheme to https.
Crowdsec must be listening in HTTPS for this to work. Please see the tls-auth example or the official documentation: docs.crowdsec.net/docs/local_api/tls_auth/
To communicate with the Appsec in HTTPS you need to either accept any certificates by setting the crowdsecAppsecTLSInsecureVerify to true or add the CA used by the server certificate of Crowdsec using crowdsecAppsecTLSCertificateAuthority or crowdsecAppsecTLSCertificateAuthorityFile.
Set the crowdsecAppsecScheme to https.
Currently AppSec does not support mTLS authentication for the AppSec Component.
1docker compose up -d crowdsec2docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m # this will be effective 10min3docker exec crowdsec cscli decisions remove --ip 10.0.0.104docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m -t captcha # this will return a captcha challenge5docker exec crowdsec cscli decisions remove --ip 10.0.0.10 -t captcha
Traefik also offers a developer mode that can be used for temporary testing of plugins not hosted on GitHub. To use a plugin in local mode, the Traefik static configuration must define the module name (as is usual for Go packages) and a path to a Go workspace, which can be the local GOPATH or any directory.
The plugins must be placed in the ./plugins-local directory,
which should be in the working directory of the process running the Traefik binary.
The source code of the plugin should be organized as follows:
1./plugins-local/2 └── src3 └── github.com4 └── maxlerebourg5 └── crowdsec-bouncer-traefik-plugin6 ├── bouncer.go7 ├── bouncer_test.go8 ├── go.mod9 ├── LICENSE10 ├── Makefile11 ├── readme.md12 └── vendor/*
For local development, a docker-compose.local.yml is provided which reproduces the directory layout needed by Traefik.
This works once you have generated and filled your LAPI-KEY (crowdsecLapiKey), if not read above for informations.
1docker compose -f docker-compose.local.yml up -d
Equivalent to
1make run_local
mathieuHa and I have been using Traefik since 2020 at Primadviz. We come from a web development and security engineer background and wanted to add the power of a very promising technology (Crowdsec) to the edge router we love.
We initially ran into this project: github.com/fbonalair/traefik-crowdsec-bouncer
It was using traefik and forward auth middleware to verify every request.
They had to go through a webserver which then contacts another webservice (the crowdsec LAPI) to make a decision based on the source IP.
We initially proposed some improvements by implementing a streaming mode and a local cache.
With the Traefik hackathon we decided to implement our solution directly as a Traefik plugin which could be found by everyone on plugins.traefik.io and be more performant.