CrowdSec allows you to present a captcha challenge to suspicious web visitors instead of applying a flat ban. This remediation feature is available through compatible bouncers like the PHP Standalone or HAProxy components.
You might struggle with false positives that block legitimate users from your site. This article explains how to configure your profiles and bouncers to implement a smooth captcha flow.
CrowdSec Captcha Setup for Web Apps
CrowdSec captcha remediation requires a compatible bouncer like Traefik or HAProxy and valid keys from providers like Cloudflare Turnstile or hCaptcha. Success depends on stable LAPI communication and correct DNS resolution for verification servers, starting with a rigorous check of your current bouncer capabilities.
Before you start, check your bouncer support. You should look at Traefik, HAProxy, or PHP bouncers first. Not all bouncers handle challenges, so read the official documentation to be sure.
Verify your bouncer support
Focus on Traefik, HAProxy, and PHP bouncers. Not all bouncers handle challenges. Checking the official documentation is the first move.
The bouncer must intercept HTTP requests. It needs to hold the connection while the user solves the puzzle.
The bouncer asks LAPI if a captcha is required. This is the LAPI communication. Confirm the API key is active. Ensure permissions are correct.
Select a challenge provider
Compare reCAPTCHA, hCaptcha, and Turnstile. Each has different privacy trade-offs. Pick the one that fits your user base and privacy policy.
You need site keys and secret keys. Copy them exactly into the CrowdSec configuration file. This prevents authentication errors.
Check these technical requirements for your setup:
- DNS resolution requirements for provider servers
- Outbound firewall rules for port 443
- SSL/TLS certificate verification
- Backend server connectivity
3 Steps to Configure Profiles
Now that the infrastructure is ready, we need to tell CrowdSec exactly when to trigger a challenge instead of a flat ban.
Define filters for IP alerts
Focus on Alert.Remediation and IP scope. You want to target specific bad behaviors. Do not catch innocent bystanders in a massive net.
Use the http tag. This limits the captcha to web traffic only.
Set remediation to captcha. This replaces the default ban decision.
Use the on_success break logic
The « on_success: break » directive is very useful. It stops the engine from looking at other profiles. This happens once the user passes the test.
This prevents a legitimate user from getting banned later. A stricter rule could cause issues. It keeps the decision flow clean and logical for everyone.
Limit challenges with helper functions
GetDecisionsSinceCount is a great tool for bot mitigation. It tracks how many times an IP has been challenged recently. Don’t let them try forever. It is very efficient.
Switch to a ban after three failures. Hard blocking is better for aggressive bot pressure.
How to Manage Grace Periods and TTL?
Security is a balance, so let’s tweak the timing to make sure humans aren’t annoyed by constant puzzles.
Set expiration and grace periods
Define how long a solved captcha stays valid. A standard duration might be 24 hours. Adjust this based on your specific risk level.
Configure grace periods for recurring visitors. You don’t want to challenge a loyal customer every single hour.
Adjust the Time To Live (TTL). High-risk scenarios need shorter TTLs to stay effective against rotating IP addresses.
Test these settings. Watch for user friction.
Customize the HTML template style
Modify the default page for brand consistency. A generic page looks suspicious to many users. Use your own colors and logo.
Make the page yours with these simple steps:
- CSS customization for brand colors
- Custom text for instructions
- Mobile-responsive layout checks
- Multi-language support for international traffic
Verify the mobile experience. Challenges must be easy to solve on small touchscreens.
Troubleshooting Common Bouncer Errors
But what happens when the screen stays blank? Let’s fix the most frequent bugs that break your defense.
Resolve DNS and connectivity bugs
Fix unreachable provider service errors. Usually, this is a DNS issue on the server side. Check your resolver configuration immediately.
Audit your firewall rules. The bouncer needs to reach external verification APIs to confirm the user is human.
Check SSL certificates. Secure communication with providers is mandatory. Expired certs will silently kill your captcha remediation flow.
Look at the logs. They usually point to the exact timeout or connection error.
Sync bouncers with Local API
Debug authentication failures between the bouncer and LAPI. A mismatched API key is the most common culprit here. Double-check the yaml config.
Monitor success rates via the CrowdSec console. If nobody is passing, your challenge might be broken or too hard.
Handle false positives. Sometimes legitimate automated tools get caught. Use these methods to fix it:
- Whitelisting known good bots
- Adjusting scenario sensitivity
- Checking for IP overlaps
- Reviewing community blocklists
Secure your web apps by integrating a compatible bouncer and a challenge provider like Turnstile. Use the on_success break logic to prevent bans for verified humans. Deploy your CrowdSec captcha setup now to stop bots while keeping your real users happy and safe.
