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:

• Low-effort virtual patching capabilities.
• Support for your legacy ModSecurity rules.
• Combining classic WAF benefits with advanced CrowdSec features for otherwise difficult advanced behavior detection.

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:

• hcaptcha
• recaptcha
• turnstile
• custom/wicketkeeper

There are 5 operating modes (CrowdsecMode) for this plugin:

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:

sequenceDiagram
    participant User
    participant TraefikPlugin
    User->>TraefikPlugin: Can I access that webpage
    create participant CrowdsecLAPI
    TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a Crowdsec Decision ?
    Destroy CrowdsecLAPI
    CrowdsecLAPI-->>TraefikPlugin: Yes a ban Decision
    TraefikPlugin->>User: No, HTTP 403

sequenceDiagram
    participant User
    participant TraefikPlugin
    User->>TraefikPlugin: Can I access that webpage
    create participant CrowdsecLAPI
    TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a crowdsec decision ?
    Destroy CrowdsecLAPI
    CrowdsecLAPI-->>TraefikPlugin: Nothing, all good!
    Destroy TraefikPlugin
    TraefikPlugin->>Webserver: Forwarding this HTTP Request from User
    Webserver->>User: HTTP Response

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: Nothing, all good!
    create participant CrowdsecLAPI
    TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a crowdsec decision ?
    Destroy CrowdsecLAPI
    CrowdsecLAPI-->>TraefikPlugin: Yes a ban Decision
    TraefikPlugin-->>PluginCache: Store the information for this IP for DefaultDecisionSeconds
    Destroy PluginCache
    PluginCache-->>TraefikPlugin: Done
    TraefikPlugin->>User: No, HTTP 403

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: Nothing, all good!
    create participant CrowdsecLAPI
    TraefikPlugin-->>CrowdsecLAPI: Does the User IP has a crowdsec decision ?
    Destroy CrowdsecLAPI
    CrowdsecLAPI-->>TraefikPlugin: Nothing, all good!
    TraefikPlugin-->>PluginCache: Store the information for this IP for DefaultDecisionSeconds
    Destroy PluginCache
    PluginCache-->>TraefikPlugin: Done
    TraefikPlugin->>Webserver: Forwarding this HTTP Request from User
    Webserver->>User: HTTP Response

sequenceDiagram
    participant TraefikPlugin
    participant CrowdsecLAPI
    TraefikPlugin->>CrowdsecLAPI: What are the current decisions
    Destroy CrowdsecLAPI
    CrowdsecLAPI->>TraefikPlugin: Here is the list
    create participant PluginCache
    TraefikPlugin-->>PluginCache: Store this list
    Destroy PluginCache
    PluginCache-->>TraefikPlugin: Done

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
    Destroy TraefikPlugin
    TraefikPlugin->>User: No, HTTP 403

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

sequenceDiagram
    participant TraefikPlugin
    participant CrowdsecCAPI
    TraefikPlugin->>CrowdsecCAPI: What are the current decisions from CAPI
    Destroy CrowdsecCAPI
    CrowdsecCAPI->>TraefikPlugin: Here is the list
    create participant PluginCache
    TraefikPlugin-->>PluginCache: Store this list
    Destroy PluginCache
    PluginCache-->>TraefikPlugin: Done

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
    Destroy TraefikPlugin
    TraefikPlugin->>User: No, HTTP 403

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

sequenceDiagram
    participant User
    participant TraefikPlugin
    User->>TraefikPlugin: Can I access that webpage
    create participant CrowdsecAppSec
    TraefikPlugin-->>CrowdsecAppSec: Is this request malicious ?
    Destroy CrowdsecAppSec
    CrowdsecAppSec-->>TraefikPlugin: Yes I think so
    Destroy TraefikPlugin
    TraefikPlugin->>User: No, HTTP 403

sequenceDiagram
    participant User
    participant TraefikPlugin
    User->>TraefikPlugin: Can I access that webpage
    create participant CrowdsecAppSec
    TraefikPlugin-->>CrowdsecAppSec: Is this request malicious ?
    Destroy CrowdsecAppSec
    CrowdsecAppSec-->>TraefikPlugin: No I don't think so
    Destroy TraefikPlugin
    TraefikPlugin->>Webserver: Forwarding this HTTP Request from User
    Webserver->>User: HTTP Response

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

To get started, use the docker-compose.yml file.

You can run it with:

make 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

• Enabled
  • bool
  • default: false
  • Enable the plugin
• LogLevel
  • string
  • default: INFO, expected values are: INFO, DEBUG, ERROR
  • Log are written to stdout / stderr or file if LogFilePath is provided
• LogFilePath
  • string
  • default: ""
  • File Path to write logs, must be writable by Traefik, Log rotation may require a restart of traefik
• MetricsUpdateIntervalSeconds
  • int64
  • default: 600
  • Interval in seconds between metrics updates to Crowdsec
  • If set to zero or less, metrics collection is disabled
• CrowdsecMode
  • string
  • default: live, expected values are: none, live, stream, alone, appsec
• CrowdsecAppsecEnabled
  • bool
  • default: false
  • Enable Crowdsec Appsec Server (WAF).
• CrowdsecAppsecHost
  • string
  • default: "crowdsec:7422"
  • Crowdsec Appsec Server available on which host and port. The scheme will be handled by the CrowdsecLapiScheme var.
• CrowdsecAppsecPath
  • string
  • default: "/"
  • Crowdsec Appsec Server available on this path. Will be appended to CrowdsecAppsecHost. Need to finish with "/".
• CrowdsecAppsecFailureBlock
  • bool
  • default: true
  • Block request when Crowdsec Appsec Server have a status 500.
• CrowdsecAppsecUnreachableBlock
  • bool
  • default: true
  • Block request when Crowdsec Appsec Server is unreachable.
• CrowdsecAppsecBodyLimit
  • int64
  • default: 10485760 (= 10MB)
  • Transmit only the first number of bytes to Crowdsec Appsec Server.
• CrowdsecLapiScheme
  • string
  • default: http, expected values are: http, https
• CrowdsecLapiHost
  • string
  • default: "crowdsec:8080"
  • Crowdsec LAPI available on which host and port.
• CrowdsecLapiPath
  • string
  • default: "/"
  • Crowdsec LAPI Server available on this path. Will be appended to CrowdsecLapiHost. Need to finish with "/".
• CrowdsecLapiKey
  • string
  • default: ""
  • Crowdsec LAPI key for the bouncer.
• CrowdsecLapiTlsInsecureVerify
  • bool
  • default: false
  • Disable verification of certificate presented by Crowdsec LAPI
• CrowdsecLapiTlsCertificateAuthority
  • string
  • default: ""
  • PEM-encoded Certificate Authority of the Crowdsec LAPI
• CrowdsecLapiTlsCertificateBouncer
  • string
  • default: ""
  • PEM-encoded client Certificate of the Bouncer
• CrowdsecLapiTlsCertificateBouncerKey
  • string
  • default: ""
  • PEM-encoded client private key of the Bouncer
• ClientTrustedIPs
  • string
  • default: []
  • List of client IPs to trust, they will bypass any check from the bouncer or cache (useful for LAN or VPN IP)
• RemediationHeadersCustomName
  • string
  • default: ""
  • Name of the header you want in response when request are cancelled (possible value of the header ban or captcha)
• ForwardedHeadersCustomName
  • string
  • default: "X-Forwarded-For"
  • Name of the header where the real IP of the client should be retrieved
• ForwardedHeadersTrustedIPs
  • []string
  • default: []
  • List of IPs of trusted Proxies that are in front of traefik (ex: Cloudflare)
• RedisCacheEnabled
  • bool
  • default: false
  • enable Redis cache instead of in-memory cache
• RedisCacheHost
  • string
  • default: "redis:6379"
  • hostname and port for the Redis service
• RedisCachePassword
  • string
  • default: ""
  • Password for the Redis service
• RedisCacheDatabase
  • string
  • default: ""
  • Database selection for the Redis service
• RedisCacheUnreachableBlock
  • bool
  • default: true
  • Block request when Redis is unreachable (if Redis is unreachable, 1-second delay is added to each request)
• HTTPTimeoutSeconds
  • int64
  • default: 10
  • Default timeout in seconds for contacting Crowdsec LAPI
• UpdateIntervalSeconds
  • int64
  • default: 60
  • Used only in stream mode, the interval between requests to fetch blacklisted IPs from LAPI
• UpdateMaxFailure
  • int64
  • default: 0
  • Used only in stream and alone mode, the maximum number of time we can not reach Crowdsec before blocking traffic (set -1 to never block)
• DefaultDecisionSeconds
  • int64
  • default: 60
  • Used only in live mode, maximum decision duration
• RemediationStatusCode
  • int
  • default: 403
  • HTTP status code for banned user (not captcha)
• CrowdsecCapiMachineId
  • string
  • Used only in alone mode, login for Crowdsec CAPI
• CrowdsecCapiPassword
  • string
  • Used only in alone mode, password for Crowdsec CAPI
• CrowdsecCapiScenarios
  • []string
  • Used only in alone mode, scenarios for Crowdsec CAPI
• CaptchaProvider
  • string
  • Provider to validate the captcha, expected values are: hcaptcha, recaptcha, turnstile or custom
• CaptchaCustomJsURL
  • string
  • If CaptchaProvider is custom, URL used to load the challenge in the HTML (in case of hcaptcha: https://hcaptcha.com/1/api.js)
• CaptchaCustomValidateURL
  • string
  • If CaptchaProvider is custom, URL used to validate the challenge (in case of hcaptcha: https://api.hcaptcha.com/siteverify)
• CaptchaCustomKey
  • string
  • If CaptchaProvider is custom, used to set class name of the div used by captcha provider (in case of hcaptcha: h-captcha)
• CaptchaCustomResponse
  • string
  • If CaptchaProvider is custom, used to set the field in the POST body from the captcha.html to Traefik (in case of hcaptcha: h-captcha-response)
• CaptchaSiteKey
  • string
  • Site key for the captcha provider
• CaptchaSecretKey
  • string
  • Site secret key for the captcha provider
• CaptchaGracePeriodSeconds
  • int64
  • default: 1800 (= 30 minutes)
  • Period after validation of a captcha before a new validation is required if Crowdsec decision is still valid
• CaptchaHTMLFilePath
  • string
  • default: /captcha.html
  • Path where the captcha template is stored
• BanHTMLFilePath
  • string
  • default: ""
  • Path where the ban html file is stored (default empty ""=disabled)

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.

# Static configuration

experimental:
  plugins:
    bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
      version: vX.Y.Z # To update

# Dynamic configuration

http:
  routers:
    my-router:
      rule: host(`whoami.localhost`)
      service: service-foo
      entryPoints:
        - web
      middlewares:
        - crowdsec

  services:
    service-foo:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:5000

  middlewares:
    crowdsec:
      plugin:
        bouncer:
          enabled: false
          logLevel: DEBUG
          LogFilePath: ""
          updateIntervalSeconds: 60
          updateMaxFailure: 0
          defaultDecisionSeconds: 60
          remediationStatusCode: 403
          httpTimeoutSeconds: 10
          crowdsecMode: live
          crowdsecAppsecEnabled: false
          crowdsecAppsecHost: crowdsec:7422
          crowdsecAppsecPath: "/"
          crowdsecAppsecFailureBlock: true
          crowdsecAppsecUnreachableBlock: true
          crowdsecAppsecBodyLimit: 10485760
          crowdsecLapiKey: privateKey-foo
          crowdsecLapiScheme: http
          crowdsecLapiHost: crowdsec:8080
          crowdsecLapiPath: "/"
          crowdsecLapiTLSInsecureVerify: false
          crowdsecCapiMachineId: login
          crowdsecCapiPassword: password
          crowdsecCapiScenarios:
            - crowdsecurity/http-path-traversal-probing
            - crowdsecurity/http-xss-probing
            - crowdsecurity/http-generic-bf
          forwardedHeadersTrustedIPs:
            - 10.0.10.23/32
            - 10.0.20.0/24
          clientTrustedIPs:
            - 192.168.1.0/24
          forwardedHeadersCustomName: X-Custom-Header
          remediationHeadersCustomName: cs-remediation
          redisCacheEnabled: false
          redisCacheHost: "redis:6379"
          redisCachePassword: password
          redisCacheDatabase: "5"
          redisCacheUnreachableBlock: true
          crowdsecLapiTLSCertificateAuthority: |-
            -----BEGIN CERTIFICATE-----
            MIIEBzCCAu+gAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwgZQxCzAJBgNVBAYTAlVT
            ...
            Q0veeNzBQXg1f/JxfeA39IDIX1kiCf71tGlT
            -----END CERTIFICATE-----
          crowdsecLapiTLSCertificateBouncer: |-
            -----BEGIN CERTIFICATE-----
            MIIEHjCCAwagAwIBAgIUOBTs1eqkaAUcPplztUr2xRapvNAwDQYJKoZIhvcNAQEL
            ...
            RaXAnYYUVRblS1jmePemh388hFxbmrpG2pITx8B5FMULqHoj11o2Rl0gSV6tHIHz
            N2U=
            -----END CERTIFICATE-----
          crowdsecLapiTLSCertificateBouncerKey: |-
            -----BEGIN RSA PRIVATE KEY-----
            MIIEogIBAAKCAQEAtYQnbJqifH+ZymePylDxGGLIuxzcAUU4/ajNj+qRAdI/Ux3d
            ...
            ic5cDRo6/VD3CS3MYzyBcibaGaV34nr0G/pI+KEqkYChzk/PZRA=
            -----END RSA PRIVATE KEY-----
          captchaProvider: hcaptcha
          captchaSiteKey: FIXME
          captchaSecretKey: FIXME
          captchaGracePeriodSeconds: 1800
          captchaHTMLFilePath: /captcha.html
          banHTMLFilePath: /ban.html
          metricsUpdateIntervalSeconds: 600

CrowdsecLapiTlsCertificateBouncerKey, CrowdsecLapiTlsCertificateBouncer, CrowdsecLapiTlsCertificateAuthority, CrowdsecCapiMachineId, CrowdsecCapiPassword, CrowdsecLapiKey, 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:

• Content: VariableName: XXX
• File : VariableNameFile: /path

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

docker compose -f docker-compose-local.yml up -d crowdsec
docker exec crowdsec cscli bouncers add crowdsecBouncer

This LAPI key must be set where is noted FIXME-LAPI-KEY in the docker-compose.yml

..
whoami:
  labels:
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapikey=FIXME-LAPI-KEY"
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapischeme=http"
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapihost=crowdsec:8080"
..
crowdsec:
  environment:
    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:

docker 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/

docker compose up -d crowdsec
docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m # this will be effective 10min
docker exec crowdsec cscli decisions remove --ip 10.0.0.10
docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m -t captcha # this will return a captcha challenge
docker 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:

./plugins-local/
    └── src
        └── github.com
            └── maxlerebourg
                └── crowdsec-bouncer-traefik-plugin
                    ├── bouncer.go
                    ├── bouncer_test.go
                    ├── go.mod
                    ├── LICENSE
                    ├── Makefile
                    ├── readme.md
                    └── 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.

docker compose -f docker-compose.local.yml up -d

Equivalent to

make 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.