![GitHub](https://img.shields.io/github/license/maxlerebourg/crowdsec-bouncer-traefik-plugin)
![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/maxlerebourg/crowdsec-bouncer-traefik-plugin)
![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/maxlerebourg/crowdsec-bouncer-traefik-plugin)
[![Build Status](https://github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/actions/workflows/go-cross.yml/badge.svg)](https://github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/actions)
[![Go Report Card](https://goreportcard.com/badge/github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin)](https://goreportcard.com/badge/github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin)

# Crowdsec Bouncer Traefik plugin

This plugins aims to implement a Crowdsec Bouncer into a traefik plugin.
> [CrowdSec](https://www.crowdsec.net/) 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 treafik to authorize or block requests from IP based and their reputation and behavior.

The crowdsec utility will provide the community blocklist which contains highly reported and validated IP 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 against your website.

There are 4 operating modes (CrowdsecMode) for this plugin:
- 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 -> Streaming mode but the blacklisted IPs are fetched on the CAPI.
    Every 2 hours, the cache is updated with news from the Crowdsec CAPI.

The recommanded mode for performance is the streaming mode, decisions are updated every 60 sec by default and that's the only communication between traefik and crowdsec. Every requests that happens hits the cache for quick decisions.

## Usage

### Variables
- Enabled
  - bool
  - enable the plugin
- CrowdsecMode
  - string
  - default: `stream`, expected value are: `none`, `live`, `stream`, `alone`
- CrowdsecLapiScheme
  - string
  - default: `http`, expected value are: `http`, `https`
- CrowdsecLapiHost
  - string
  - default: "crowdsec:8080"
  - Crowdsec LAPI available on which host.
- CrowdsecLapiKey
  - string
  - Crowdsec LAPI generated key for the bouncer. 
- CrowdsecCapiLogin
  - string
  - Used only in `alone` mode, login for Crowdsec CAPI
- CrowdsecCapiPwd
  - string
  - Used only in `alone` mode, password for Crowdsec CAPI
- CrowdsecCapiScenarios
  - []string
  - Used only in `alone` mode, scenarios for Crowdsec CAPI
- UpdateIntervalSeconds
  - int64
  - default: 60
  - User only in `stream` mode, interval between fetching blacklisted IPs from LAPI
- DefaultDecisionSeconds
  - int64
  - default: 60
  - User only in `live` mode, decision duration of accepted IPs

### Configuration

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:

```yaml
# Static configuration

experimental:
  plugins:
    bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
```

```yaml
# Dynamic configuration

http:
  routers:
    my-router:
      rule: host(`woami.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
          updateIntervalSeconds: 60
          defaultDecisionSeconds: 60
          crowdsecMode: stream
          crowdsecLapiKey: privateKey
          crowdsecLapiHost: crowdsec:8080
          crowdsecLapiScheme: http
          crowdsecCapiLogin: login
          crowdsecCapiPwd: password
          crowdsecCapiScenarios:
            - scenario1
            - scenario2
            ...

```
Except for the crowdsecLapiKey, crowdsecCapiLogin, crowdsecCapiPwd, crowdsecCapiScenarios, these are the default value of the plugin.

#### Generate LAPI KEY (exept for `alone` mode)
You need to generate a crowdsec API key for the LAPI.
You can follow the documentation here: https://docs.crowdsec.net/docs/user_guides/lapi_mgmt/

```bash
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-test.yml
```yaml
...
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
...
```

You can then run all the containers:
```bash
docker-compose up -d
```

#### Generate CAPI credentials (only for `alone` mode)
You need to create a crowdsec API credentials for the CAPI.
You can follow the documentation here: https://docs.crowdsec.net/docs/central_api/intro

```bash
curl -X POST "https://api.crowdsec.net/v2/watchers" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{ \"password\": \"PASSWORD\",  \"machine_id\": \"LOGIN\"}"
```

These CAPI credentials must be set in your docker-compose.yml or in your config files
```yaml
...
traefik:
  command:
    ...
    - "--experimental.plugins.bouncer.modulename=github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin"
    - "--experimental.plugins.bouncer.version=v1.0.0"
    ...
whoami:
  labels:
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseccapilogin=LOGIN"
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseccapipwd=PASSWORD"
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseccapiscenarios=scenario1, scenario2, ..."
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.enabled=true"
```

You can then run all the containers:
```bash
docker-compose up -d
```

#### Add manually an IP to the blocklist (testing purpose)

```bash
docker-compose up -d crowdsec
docker exec crowdsec cscli decisions add --ip 10.0.0.10 # this will be effective 4h
docker exec crowdsec cscli decisions remove --ip 10.0.0.10
```

### Local Mode

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](https://golang.org/doc/gopath_code.html#Workspaces), which can be the local GOPATH or any directory.

The plugins must be placed in `./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 developpement a docker-compose.local.yml is provided and reproduce the directory layout needed by traefik. This works once you have generated and filled your LAPI-KEY (crowdsecLapiKey), if not look below for informations

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

### About

Me and [mathieuHa](https://github.com/mathieuHa) have been using traefik since 2020 at [Primadviz](https://primadviz.com).
We come from web developper and security engineer background and wanted to add the power of a very promesing technology (Crowdsec) into the edge router we love.

We initially run into this project: https://github.com/fbonalair/traefik-crowdsec-bouncer
It was using traefik and forward auth middleware to verify every requests.
They had to go through a webserver which then contacts of another webservice (the crowdsec LAPI) to make a decision based on the source IP.
We initially proposed some improvement by implementing a streaming mode and a local cache.
With the Traefik hackathon we deciced to implement our solution directly as a traefik plugin which could be found by every one on plugins.traefik.io and be more performant.