CrowdSec Manager for Pangolin: Complete User Guide
With traefik logs Update and Back Integrated Version.02
Tested on Debian, Alma, and Ubuntu 24.04(Prefered)
Run this command if you are using Debian or Ubuntu before script execution
sudo apt install grep gawk sed tar
CrowdSec Manager is an all-in-one tool designed to simplify the management of your CrowdSec installation within a Docker environment tailored for Pangolin. This comprehensive guide walks you through utilizing the script to oversee various facets of your CrowdSec setup, from basic health diagnostics to advanced configurations such as captcha protection, custom security scenarios, and IP management.
Prerequisites
Before diving into the script, ensure the following requirements are met:
- Docker Compose Stack of Pangolin: Installed and operational.
- Working Setup: Includes CrowdSec, Traefik, Gerbil, and Pangolin components.
- Bash Shell Environment: Available on your system.
- Basic Terminal Knowledge: Familiarity with command-line operations.
Getting Started
1. Installing the Script
To begin using the CrowdSec Manager script:
-
Download the Script:
curl -o setup_crowdsec_manager.sh https://gist.githubusercontent.com/hhftechnology/aadadf48ac906fc38cfd0d7088980475/raw/0a384d518e74c9963a51fcfb60d5ef5bccf9f645/setup_crowdsec_manager.sh
-
Make it Executable:
chmod +x setup_crowdsec_manager.sh
-
Run the Script:
Execute the script in the directory containing yourdocker-compose.yml
file for Pangolin:./setup_crowdsec_manager.sh
Note: If you encounter Docker permission issues, prepend
sudo
:sudo ./setup_crowdsec_manager.sh
2. Initial Health Check
Upon launching, the script automatically verifies the status of essential containers (CrowdSec, Traefik, Pangolin, Gerbil):
- Success: Displays the main menu if all containers are running.
- Failure: Alerts you if any container is missing or stopped, potentially exiting to prompt corrective action.
Main Features
The scriptâs main menu organizes functionalities into four categories: System Health & Diagnostics, IP Management, Advanced Configuration, and Logs & Monitoring.
System Health & Diagnostics
1. Check System Health (Option 1)
Quickly assess the health of your CrowdSec stack:
- Select
1
from the main menu. - The script checks the status of CrowdSec, Traefik, Pangolin, and Gerbil containers.
- Output:
- Green
[+]
indicates a running container. - Red
[-]
signals a non-running container.
- Green
- Press Enter to return to the main menu.
2. Run Complete Diagnostic Check (Option 2)
Perform an in-depth diagnostic of your CrowdSec setup:
- Choose
2
from the main menu. - The script executes a series of checks:
- Container health
- Bouncer registration
- Active decisions
- Metrics availability
- Traefik integration
- Key configuration settings
- Review detailed outputs for each check.
- A summary verdict confirms if CrowdSec is functioning correctly.
- Press Enter to return to the main menu.
3. Check CrowdSec Bouncers (Option 3)
Verify registered bouncers enforcing CrowdSec decisions:
- Select
3
from the main menu. - Lists all registered bouncers.
- Confirms Traefik bouncer registration specifically.
- Press Enter to return to the main menu.
4. Check CrowdSec Metrics (Option 4)
Examine CrowdSecâs performance metrics:
- Choose
4
from the main menu. - Displays:
- Prometheus metrics (first 10 CrowdSec-related lines)
- AppSec-specific metrics
- Internal CrowdSec metrics
- Ensures data collection is active.
- Press Enter to return to the main menu.
5. Check Traefik CrowdSec Integration (Option 5)
Validate Traefikâs integration with CrowdSec:
- Select
5
from the main menu. - Searches for CrowdSec middleware in various Traefik config files.
- Reports middleware presence.
- Press Enter to return to the main menu.
IP Management
6. Check CrowdSec Decisions (List Blocked IPs) (Option 6)
View active security decisions:
- Choose
6
from the main menu. - Lists blocked IPs and reasons.
- Note: An empty list indicates no detected malicious activity yet.
- Press Enter to return to the main menu.
7. IP Whitelisting Management (Option 7)
Manage IP whitelists to exempt trusted sources:
- Select
7
from the main menu. - Access a submenu:
1. Whitelist current public IP
2. Whitelist a specific IP
3. Set up comprehensive whitelist with standard private networks
4. View currently whitelisted IPs
0. Return to main menu
- Options:
- 1: Detects and whitelists your public IP in CrowdSec and/or Traefik.
- 2: Prompts for an IP to whitelist in CrowdSec and/or Traefik.
- 3: Configures a whitelist with defaults:
Allows additional IPs via prompt (one per line, Ctrl+D to finish).- "192.168.0.0/16" # Common internal network - "10.0.0.0/8" # Private range - "172.16.0.0/12" # Docker network range - "100.89.137.0/20" # From Pangolin configuration
- 4: Displays whitelisted IPs in CrowdSec and Traefik configs.
- Follow prompts; CrowdSec restarts if changes are made.
- Press Enter to return to the main menu.
8. Unban an IP (Option 8)
Remove bans from specific IPs:
- Choose
8
from the main menu. - Enter the IP to unban.
- If banned, the script removes the decision; if not, it notifies you.
- Press Enter to return to the main menu.
9. Check IP Security Status (Option 9)
Analyze an IPâs security status:
- Select
9
from the main menu. - Enter the IP to check.
- Reports:
- Block status in CrowdSec
- Whitelist status in CrowdSec (including subnets)
- Whitelist status in Traefik (including subnets)
- Press Enter to return to the main menu.
Advanced Configuration
10. Enroll with CrowdSec Console (Option 10)
Link your CrowdSec instance to the Console:
- Visit CrowdSec Console, log in, and get your enrollment key.
- Choose
10
from the main menu. - Paste the enrollment key.
- The script enrolls and restarts CrowdSec.
- Accept the âpangolin-crowdsecâ instance in the Console.
- Important: After enrollment, go back to the CrowdSec Console and accept the instance named âpangolin-crowdsecâ
- Press Enter to enable additional features and check status.
- Press Enter again to return to the main menu.
11. Set Up Custom Scenarios (Option 11)
Define custom security rules:
- Select
11
from the main menu. - Confirm installation.
- Installs scenarios for:
- Authentication brute force
- API abuse
- Resource scanning
- HTTP flooding
- CrowdSec restarts; verify scenario loading.
- Caution: Monitor decisions to avoid false positives.
- Press Enter to return to the main menu.
12. Set Up Captcha Protection (Option 12)
Implement Cloudflare Turnstile captcha:
- Create a Non-Interactive Turnstile site at Cloudflare Dashboard.
- Choose
12
from the main menu. - If configured, decide to overwrite.
âvery imp Select Non-Interactive only.
4. Enter Site Key and Secret Key.
5. The script:
- Sets up a captcha profile
- Creates an HTML template
- Updates Traefik middleware
- Restarts Traefik and CrowdSec.
- Test with:
docker exec crowdsec cscli decisions add --ip <test-ip> --type captcha -d 1h
- Press Enter to return to the main menu.
Logs & Monitoring
13. View Recent CrowdSec Logs (Option 13)
Examine recent CrowdSec logs:
- Select
13
from the main menu. - Displays the last 50 lines.
- Press Enter to return to the main menu.
14. View Recent Traefik Logs (Option 14)
Check recent Traefik logs:
- Choose
14
from the main menu. - Shows the last 50 lines.
- Press Enter to return to the main menu.
15. Follow CrowdSec Logs (Live) (Option 15)
Monitor CrowdSec logs in real-time:
- Select
15
from the main menu. - View live logs.
- Press Ctrl+C to exit and return to the main menu.
Common Issues and Troubleshooting
CrowdSec Container Wonât Start
- Check: Use Option
13
for logs. - Fix: Look for config errors in scenarios/profiles; ensure whitelist formatting.
Captcha Not Working
- Verify: Correct Turnstile keys, template at
./config/traefik/conf/captcha.html
, middleware (Option5
). - Test: Apply a manual captcha decision.
Traefik Not Blocking Attacks
- Check: Bouncer registration (Option
3
), API key match, middleware config (Option5
).
False Positives in Decisions
- Steps:
- Check decisions (Option
6
). - Unban IP (Option
8
) if needed. - Add to whitelist (Option
7
). - Adjust custom scenarios.
- Check decisions (Option
Best Practices
- Regular Monitoring: Use Option
6
to track decisions. - Testing Changes: Run Option
2
post-configuration. - Whitelist Management: Update via Option
7
to avoid false positives. - Console Integration: Enroll with Option
10
for enhanced oversight. - Backup Configurations: Save configs before changes; note script backups.
- Update Regularly: Keep CrowdSec and bouncers current.
- Log Review: Use Options
13-15
to monitor events and health.
Conclusion
The CrowdSec Manager script streamlines the administration of your CrowdSec security stack, enabling robust protection for your Pangolin environment. This guide equips you to leverage its full feature set, ensuring your infrastructure remains secure against cyber threats. Security is an ongoing effortâconsistently review settings, monitor logs, and stay updated on threats for optimal defense.