envoy-proxy-bouncer

README

CrowdSec Envoy Proxy Bouncer

CrowdSec bouncer for Envoy Proxy using the ext_authz filter.

[!WARNING] This project is in active development and has not been tested in production environments. Use at your own risk. Breaking changes may occur between releases. For the most stable experience, use a tagged release rather than the main branch.

Features

• Block malicious IPs streamed via CrowdSec decisions
• Bouncer metrics reporting
• Request inspection via CrowdSec AppSec
• CAPTCHA challenges for suspicious IPs with support for:
  • Google reCAPTCHA v2
  • Cloudflare Turnstile
• Crowdsec AppSec bot challenges

Supported CrowdSec Versions

The following CrowdSec versions have been tested. Other versions may work but have not been validated.

CrowdSec Version	Status
v1.7.0	✅
v1.7.2	✅
v1.7.3	✅
v1.7.4	✅
v1.7.6	✅
v1.7.7	✅
v1.7.8	✅
v1.8.0	✅
v1.8.1	✅

How It Works

Integrates with Envoy as an external authorization service. Each request is evaluated by:

1. Extracting client IP from forwarded headers
2. Checking CrowdSec decision cache for IP-based ban or captcha decisions
3. Inspecting request with CrowdSec AppSec WAF (if enabled)
4. Enforcing decisions:
   • Allow: request proceeds
   • Ban: return 403 with ban page
   • Captcha: redirect to challenge page
   • Challenge: pass AppSec's bot challenge page through to the client

Documentation

• Configuration Reference
• CrowdSec Integration
• CAPTCHA Integration
• Webhooks
• Custom Templates
• Signing Key Generation
• Deployment Guide

Examples

• Kubernetes Deployment
• Real Example
• Custom Templates

Acknowledgments

• Helm schema generated with helm-values-schema-json
• Helm docs generated with helm-docs