Integrating Fail2Ban with Pangolin
USE ONLY AS LAST RESORT AND IF YOU KNOW WHAT YOU ARE DOING. ITS A PAIN TO MANAGE IT
USE GEO-BLOCK and CROWDSEC MORE THAN ENOUGH
Fail2Ban is a powerful security tool that helps protect your Pangolin installation from brute force attacks and other malicious activities. This guide will walk you through integrating Fail2Ban with Pangolin using Traefik’s built-in Fail2Ban plugin.
Installation and Configuration
1. Update Traefik Configuration
First, you’ll need to modify your Traefik configuration to include the Fail2Ban plugin. Open your traefik_config.yml and add the following under the experimental plugins section:
experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.0.0-beta.3"
fail2ban:
moduleName: "github.com/tomMoulard/fail2ban"
version: "v0.8.3"
2. Configure Fail2Ban Middleware
Add the Fail2Ban middleware configuration to your dynamic_config.yml:
You will have to adjust according to your requirements.
This is just a starter file to get you going.
middlewares:
# fail2ban configuration with proper IP forwarding
fail2ban:
plugin:
fail2ban:
rules:
bantime: 3h # Three hours is a good balance
enabled: "true" # Must be string "true"
findtime: 10m # Standard window for attempts
maxretry: "4" # Four failures trigger ban
whitelist:
ip: ::1,127.0.0.1,100.89.137.0/20,172.16.0.0/12,10.0.0.0/8,192.168.0.0/16,your-ip/32
This configuration:
- Whitelists internal network ranges
- Bans IPs for 1 hour after 5 failed attempts within 10 minutes
- Monitors both HTTP and HTTPS ports
- Watches for authentication failures (401/403 status codes)
3. Apply Middleware to traefik file
Update your http configurations in traefik_config.yml to use the Fail2Ban middleware. Add fail2ban to the middlewares list.
http:
middlewares:
- fail2ban@file # CHANGE MADE HERE (BOUNCER ENABLED) !!!
- crowdsec@file
- middlewares-compress@file
- middlewares-secure-headers@file
4. Enable Access Logging
Ensure Traefik’s access logging is properly configured in traefik_config.yml:
accessLog:
filePath: "/var/log/traefik/access.log"
format: json
filters:
statusCodes:
- "200-299" # Success codes
- "400-499" # Client errors
- "500-599" # Server errors
retryAttempts: true
minDuration: "100ms" # Increased to focus on slower requests
bufferingSize: 100 # Add buffering for better performance
fields:
defaultMode: drop # Start with dropping all fields
names:
ClientAddr: keep
ClientHost: keep
RequestMethod: keep
RequestPath: keep
RequestProtocol: keep
DownstreamStatus: keep
DownstreamContentSize: keep
Duration: keep
ServiceName: keep
StartUTC: keep
TLSVersion: keep
TLSCipher: keep
RetryAttempts: keep
headers:
defaultMode: drop
names:
User-Agent: keep
X-Real-Ip: keep
X-Forwarded-For: keep
X-Forwarded-Proto: keep
Content-Type: keep
Authorization: redact # Redact sensitive information
Cookie: redact # Redact sensitive information
Testing the Configuration
Basic Functionality Test
-
Generate Failed Login Attempts
# Replace your-pangolin-domain with your actual domain curl -X POST https://your-pangolin-domain/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"test@test.com","password":"wrong"}'Repeat this 6 times to trigger a ban.
-
Monitor Logs in Real-time
tail -f ./config/traefik/logs/access.logWatch for 401/403 responses and subsequent connection rejections.
Testing Whitelist Configuration
-
Test Internal Network Access
- Attempt login failures from a whitelisted IP
- Verify that the IP doesn’t get banned
-
Test External IP Blocking
- Use a non-whitelisted IP (like a VPN)
- Verify that the IP gets banned after exceeding maxretry
Verify Active Bans
Access Traefik’s API dashboard (if enabled in compose file):
curl http://172.19.0.3:8080/api/http/middlewares/fail2ban@file
Managing IP Blocks
How to Unblock an IP
There are several methods to unblock an IP address:
-
Restart Traefik (Quickest method)
docker restart traefikNote: This will clear ALL current bans
-
Wait for Ban Expiration
- Bans automatically expire after the configured bantime (default: 1 hour)
Best Practices
-
Monitoring
- Regularly check access logs for unusual patterns
- Monitor the number of active bans
- Keep track of frequently banned IPs
-
Configuration Tuning
- Adjust
bantime,findtime, andmaxretrybased on your security needs - Keep whitelist updated with your trusted IP ranges
- Consider increasing ban times for repeat offenders
- Adjust
-
Maintenance
- Regularly review and update whitelist entries
- Monitor log file sizes and implement log rotation
- Keep Traefik and plugin versions updated
Troubleshooting
Common Issues
-
Bans Not Working
- Verify middleware is properly configured in routers
- Check if IP is in whitelist
- Ensure logs are being written correctly
-
Legitimate Users Getting Banned
- Review
maxretryandfindtimesettings - Check whitelist configuration
- Consider implementing rate limiting instead of outright bans
- Review
-
Configuration Not Taking Effect
- Verify Traefik configuration syntax
- Check Traefik logs for configuration errors
- Ensure middleware is properly linked to routers
Debug Mode
To enable more detailed logging, update the log level in traefik_config.yml:
log:
level: "DEBUG"
Remember to return it to “INFO” in production.
Security Considerations
- Don’t set ban times too short (makes the protection ineffective)
- Don’t set retry attempts too high (makes the protection ineffective)
- Keep your whitelist minimal and regularly reviewed
- Monitor logs for signs of evasion attempts
- Consider implementing additional security measures like rate limiting
These configurations and practices will help secure your Pangolin installation against unauthorized access attempts while maintaining usability for legitimate users.
