Sign inSign up

crowdsecurity/spoa-bouncer

By crowdsecurity

•Updated about 2 hours ago

BETA: HAProxy spoe filter for CrowdSec - WAF and IP protection

Image
0

10K+

crowdsecurity/spoa-bouncer repository overview

⁠CrowdSec HAProxy SPOA Bouncer Docker Image

This is a minimal scratch-based Docker image containing only the statically-linked bouncer binary and essential files.

⁠Image Contents

/crowdsec-spoa-bouncer                              # The bouncer binary
/etc/ssl/certs/ca-certificates.crt                  # CA certs for HTTPS to LAPI
/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml   # Default config
/usr/lib/crowdsec-haproxy-spoa-bouncer/lua/         # Lua files for HAProxy
/var/lib/crowdsec-haproxy-spoa-bouncer/html/        # Ban/captcha templates

⁠Quick Start

docker run -d \
  --name crowdsec-spoa-bouncer \
  -e CROWDSEC_KEY=your-api-key \
  -e CROWDSEC_URL=http://crowdsec:8080/ \
  -p 9000:9000 \
  -p 6060:6060 \
  crowdsecurity/spoa-bouncer

⁠Configuration

⁠Custom Configuration File

Mount your own configuration file for full control:

docker run -d \
  --name crowdsec-spoa-bouncer \
  -v /path/to/your/config.yaml:/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml:ro \
  -p 9000:9000 \
  crowdsecurity/spoa-bouncer

Or specify a different config path:

docker run -d \
  --name crowdsec-spoa-bouncer \
  -v /path/to/config.yaml:/config.yaml:ro \
  -p 9000:9000 \
  crowdsecurity/spoa-bouncer -c /config.yaml
⁠Environment Variables

For simple deployments, the default configuration supports environment variables:

VariableDefaultDescription
CROWDSEC_KEYrequiredAPI key for CrowdSec LAPI
CROWDSEC_URLhttp://crowdsec:8080/CrowdSec LAPI URL
LOG_MODEstdoutLog output: stdout or file
LOG_LEVELinfoLog level: trace, debug, info, warn, error
UPDATE_FREQUENCY10sHow often to poll LAPI for decisions
INSECURE_SKIP_VERIFYfalseSkip TLS verification for LAPI
LISTEN_TCP0.0.0.0:9000TCP listener address
PROMETHEUS_ENABLEDtrueEnable Prometheus metrics
PROMETHEUS_ADDR0.0.0.0Prometheus listen address
PROMETHEUS_PORT6060Prometheus listen port

Note: Default values are set in the Docker image. Only CROWDSEC_KEY must be provided.

⁠Unix Socket (Recommended for Same-Host HAProxy)
docker run -d \
  --name crowdsec-spoa-bouncer \
  -v /path/to/config.yaml:/etc/crowdsec/bouncers/crowdsec-spoa-bouncer.yaml:ro \
  -v /run/crowdsec-spoa:/run/crowdsec-spoa \
  crowdsecurity/spoa-bouncer

Ensure the socket directory exists and has appropriate permissions for HAProxy to connect.

⁠Docker Compose Example

services:
  crowdsec-spoa-bouncer:
    image: crowdsecurity/spoa-bouncer
    restart: unless-stopped
    environment:
      - CROWDSEC_KEY=${CROWDSEC_API_KEY}
      - CROWDSEC_URL=http://crowdsec:8080/
      - LOG_LEVEL=info
    ports:
      - "6060:6060"  # Prometheus metrics
    networks:
      - crowdsec
    deploy:
      resources:
        limits:
          memory: 256M

  haproxy:
    image: haproxy:3.1
    volumes:
      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
    ports:
      - "80:80"
      - "443:443"
    networks:
      - crowdsec
    depends_on:
      - crowdsec-spoa-bouncer

networks:
  crowdsec:

⁠Running as Non-Root

The scratch image runs as root by default. To run as a specific user:

docker run -d \
  --user 1000:1000 \
  --name crowdsec-spoa-bouncer \
  -p 9000:9000 \
  crowdsecurity/spoa-bouncer

Note: Ensure mounted volumes have appropriate permissions for the specified user.

⁠Health Checks

Prometheus metrics are enabled by default on port 6060. Since this is a scratch image with no shell, use external health checks:

# Docker Compose with healthcheck via curl sidecar
services:
  crowdsec-spoa-bouncer:
    image: crowdsecurity/spoa-bouncer
    environment:
      - CROWDSEC_KEY=${API_KEY}
    # Use depends_on with service_healthy for dependent services

  healthcheck:
    image: curlimages/curl:8.11.1
    command: ["sh", "-c", "while true; do curl -sf http://crowdsec-spoa-bouncer:6060/metrics > /dev/null && echo healthy || echo unhealthy; sleep 30; done"]
    depends_on:
      - crowdsec-spoa-bouncer

Or check from the host:

curl -sf http://localhost:6060/metrics > /dev/null && echo "healthy" || echo "unhealthy"

⁠Ports

PortDefaultDescription
9000YesSPOA TCP listener
6060YesPrometheus metrics (enabled by default)
6070Nopprof debug endpoint (disabled by default)

⁠Troubleshooting

⁠View Logs
docker logs -f crowdsec-spoa-bouncer
⁠Debug Mode

Set the LOG_LEVEL environment variable:

docker run -e LOG_LEVEL=debug -e CROWDSEC_KEY=... crowdsecurity/spoa-bouncer
⁠Connection Issues
  1. Verify LAPI is reachable from the container
  2. Check API key is correct
  3. Ensure HAProxy can reach the SPOA listener (TCP port or Unix socket)

⁠Building the Image

docker build -t crowdsecurity/spoa-bouncer .
⁠Build Arguments
ArgumentDefaultDescription
GOVERSION1.25Go version for build stage

Tag summary

Content type

Image

Digest

sha256:9d01409b5…

Size

6 MB

Last updated

2 months ago

docker pull crowdsecurity/spoa-bouncer