Skip to content
Myra EU CAPTCHA Online Help Updated · 25 Aug 2026

CrowdSec

The bouncer for CrowdSec is a standalone upstream server that connects the decisions of CrowdSec with the Myra EU CAPTCHA. IP addresses with the captcha decision get a challenge, IP addresses with the ban decision get the 403 status code. The other traffic goes to your application unchanged.

Sequence

  1. The bouncer queries the decision stream of CrowdSec at /v1/decisions/stream and keeps the decisions in the memory.
  2. For each request, it looks up the IP address of the visitor:
Decision Behaviour
ban The bouncer answers the request with the 403 Forbidden status code.
captcha The bouncer redirects to /__captcha__, shows the widget, verifies the token on the server, sets a signed cookie, and redirects back.
no decision The bouncer sends the request to your application.

Requirements

The following requirements must be met:

Requirement Value
CrowdSec Agent in operation with an available local API
Go From version 1.22 to build from the sources
Credentials Public sitekey and secret from the Details view

Install the bouncer

Download the built program for your platform from the releases page:

# Linux amd64
curl -L https://github.com/Myra-Security-GmbH/eu-captcha-crowdsec/releases/latest/download/cs-eucaptcha-bouncer-linux-amd64 \
  -o cs-eucaptcha-bouncer
chmod +x cs-eucaptcha-bouncer

Programs are available for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64).

Build from the sources as follows:

git clone https://github.com/Myra-Security-GmbH/eu-captcha-crowdsec.git
cd eu-captcha-crowdsec
make build
# produces ./cs-eucaptcha-bouncer

Set up the bouncer

Proceed as follows to set up the bouncer:

  • ► Register the bouncer with CrowdSec:
cscli bouncers add eu-captcha-bouncer
# Note the printed API key — you'll need it in the next step
  • ↳ CrowdSec shows an API key.
  • ► Make the configuration file:
cp config.yaml.example config.yaml
  • ► Enter the necessary values:
listen_addr: "0.0.0.0:8080"
upstream_url: "http://localhost:3000"   # your application

crowdsec:
  lapi_url: "http://localhost:8080"
  api_key: "<API key from cscli bouncers add>"
  update_interval: "10s"

eu_captcha:
  sitekey: "EUCAPTCHA_SITE_KEY"    # from app.eu-captcha.eu
  secret:  "EUCAPTCHA_SECRET_KEY"  # from app.eu-captcha.eu

session:
  secret: "<random hex string>"  # openssl rand -hex 32
  ttl: "1h"
  • ► Start the bouncer:
./cs-eucaptcha-bouncer -config config.yaml
  • ➔ The bouncer writes its log as structured JSON to the standard output.

Then point your load balancer or your DNS to the address from listen_addr.

Settings

These settings are available:

Setting Default Effect
listen_addr 0.0.0.0:8080 Address at which the bouncer accepts requests.
upstream_url necessary Address of your application.
crowdsec.lapi_url http://localhost:8080 Address of the local API of CrowdSec.
crowdsec.api_key necessary API key from cscli bouncers add.
crowdsec.update_interval 10s Interval between two queries of the decision stream.
eu_captcha.sitekey necessary Public sitekey.
eu_captcha.secret necessary Secret key.
eu_captcha.verify_url https://api.eu-captcha.eu/v1/verify Address of the endpoint for the verification.
session.secret necessary Key for the HMAC signature. Make it with openssl rand -hex 32.
session.cookie_name __eucaptcha_pass Name of the session cookie.
session.ttl 1h Validity period of a passed challenge.
trusted_proxies empty CIDR ranges whose X-Forwarded-For header the bouncer reads.

Operation with systemd

[Unit]
Description=EU Captcha CrowdSec Bouncer
After=network.target crowdsec.service

[Service]
ExecStart=/usr/local/bin/cs-eucaptcha-bouncer -config /etc/eu-captcha-bouncer/config.yaml
Restart=on-failure
User=www-data

[Install]
WantedBy=multi-user.target

Operation in a container

FROM golang:1.22-alpine AS builder
WORKDIR /src
COPY . .
RUN go build -o cs-eucaptcha-bouncer ./cmd/cs-eucaptcha-bouncer

FROM alpine:3.19
COPY --from=builder /src/cs-eucaptcha-bouncer /usr/local/bin/
ENTRYPOINT ["cs-eucaptcha-bouncer", "-config", "/etc/bouncer/config.yaml"]

Reserved paths

The bouncer reserves two paths of the protected domain. Do not use these paths in your application:

Path Use
/__captcha__ Shows the challenge page.
/__captcha__/verify Accepts the solved token.