CrowdSec v1.6 includes a feature to replace standard IP bans with interactive challenges. Are you looking for a way to verify human users without blocking legitimate traffic entirely? Managing false positives remains a major hurdle for web administrators who want to maintain a smooth user experience.
This article explains how to configure the CrowdSec Captcha remediation to secure your infrastructure. You will learn to modify your profiles and link your bouncers to a provider to manage suspicious HTTP traffic effectively.
CrowdSec Captcha Remediation Basics
CrowdSec captcha remediation requires LAPI 1.5+, compatible bouncers like HAProxy or Traefik, and valid Site/Secret keys from providers like Cloudflare Turnstile or hCaptcha to replace standard IP bans with interactive user challenges.
The technical requirements for specific software versions are the first step in this process.
Identifying Compatible Bouncers
Verify if your current bouncer supports the captcha remediation type. Not all legacy versions include this feature. Check the binary version using the command line tool.
HAProxy and Traefik bouncers are the primary candidates for this setup. Ensure your middleware configuration allows for challenge redirection.
Consult official documentation for versioning. Some community bouncers lack support.
Selecting A Captcha Provider
Compare options between reCAPTCHA, hCaptcha, and Cloudflare Turnstile. Each service has different privacy levels. Google is standard but hCaptcha offers better data protection. Turnstile is gaining popularity for its frictionless approach. Choose based on your specific user experience goals.
Evaluate the privacy implications for each external service. Some require heavy script loading. This affects your site speed and compliance.
Configure Your Profiles.yaml File
Once the provider is chosen, the logic must be defined within the CrowdSec security engine configuration.
Defining Filters For HTTP Scenarios
Write expressions to target only HTTP-related alerts in your profiles.yaml. Using the CrowdSec expression language allows for precise triggers. You can isolate specific subdomains or sensitive paths. This prevents applying challenges to non-web traffic like SSH or SMTP.
Filter decisions based on the alert type. Only web-based attacks should trigger a visual challenge. Use the « Alert.Remediation == true » logic here.
Applying The Break Logic
Set the on_success directive to stop further evaluation. This ensures the engine doesn’t process lower-priority profiles immediately.
Prevent users from being banned after solving the challenge. A successful validation must clear the current decision. This maintains a smooth flow for legitimate traffic.
- on_success: break directive
- duration settings
- profile priority
Scaling From Captcha To Ban
Use helper functions to count previous decisions per IP address. This tracks how many times a user failed the challenge. It is a vital security layer for automated bots.
Define a threshold for repeated captcha failures. Automate the transition to a hard ban after three failed attempts. This escalation policy protects your backend from persistent attackers. It balances user accessibility with strict infrastructure protection.
Link Your Bouncers To The API
With the engine logic ready, the final step involves bridging the bouncer to your chosen captcha provider’s API.
Setting Up Keys And Templates
Input the Site Key and Secret Key in the bouncer configuration file. These credentials authenticate your requests to the provider. Double-check for trailing spaces in the YAML strings.
Specify the path to the HTML template for customization. You can modify the look to match your brand. Adjust grace periods to avoid frequent re-validation for the same user. This improves the overall browsing experience significantly for human visitors.
- Site Key
- Secret Key
- Captcha Template Path
- Grace Period duration
Managing Stick Tables And SSL
Configure stick tables in HAProxy for caching validation results. This prevents the bouncer from asking the LAPI for every single request. It saves significant CPU resources on high-traffic sites.
Handle SSL requirements for communication with the verification backend. Ensure your system certificates are up to date. The bouncer needs to trust the provider’s HTTPS endpoint. Optimize performance by reducing redundant API calls through efficient local caching mechanisms.
SSL verification is mandatory for security. Use valid CA bundles to avoid backend connection errors during the challenge phase.
Solve Your Captcha Display Problems
Even a perfect configuration can fail, so you need a reliable method to debug the integration.
Using Cscli For Manual Testing
Create a manual captcha decision for a specific IP using the cscli tool. This is the fastest way to trigger the challenge. Use your own IP for the test.
Check the bouncer logs to confirm the challenge trigger. Look for 401 or 403 status codes in the access logs. Clear existing decisions to reset the test environment frequently. This ensures a clean state for each troubleshooting attempt you perform.
- Step 1: Run cscli decisions add
- Step 2: Access site from test IP
- Step 3: Verify bouncer logs
Fixing Connectivity And Mode Issues
Identify differences in behavior between stream and live modes. Stream mode relies on local cache updates. Live mode queries the LAPI in real-time for every new connection.
Debug API connectivity issues preventing challenge delivery. Check if your firewall blocks outgoing traffic to the captcha provider. Resolve issues with unreachable verification backends. A broken backend connection will often result in a default « allow » or « deny » behavior.
Verify your network DNS settings. If the bouncer cannot resolve the captcha API hostname, the validation will fail every time.
Secure your web traffic by integrating CrowdSec captcha remediation with compatible bouncers like HAProxy or Traefik. Simply configure your profiles.yaml with the break logic and link your provider keys to start challenging suspicious users. Act now to protect your infrastructure while ensuring a smooth experience for human visitors.
