Caddy MIB (Middleware IP Ban) is a custom Caddy HTTP middleware designed to track client IPs generating repetitive errors (such as 404 or 500) and temporarily ban them after exceeding a specified threshold. This middleware helps mitigate brute force attacks, excessive requests for non-existent resources, or other abusive behavior by blocking IPs that breach the configured error limits.
- Track Specific HTTP Error Codes: Configure which HTTP error codes (e.g.,
404,500) to track. - Set Error Thresholds: Define the maximum number of errors allowed per IP before banning.
- Custom Ban Duration: Specify how long an IP should be banned (e.g.,
10m,1h). - Dynamic Ban Duration: Increase ban duration exponentially with repeated offenses.
- Whitelist Trusted IPs: Exempt specific IPs from banning, even if they trigger errors.
- Dynamic Configuration: Easily configure the middleware using the Caddyfile.
- Debug Logging: Detailed logs to track IP bans, error counts, and request statuses.
- Automatic Unbanning: Banned IPs are automatically unbanned after the ban duration expires.
- Go 1.20 or later
- Caddy v2.9.0 or later
- Overview: Learn about the purpose and functionality of Caddy MIB.
- Features: Explore the key features of the middleware.
- Installation: Step-by-step guide to install and build the middleware.
- Configuration: Configure the middleware using the Caddyfile.
- Usage: Example scenario and testing instructions.
- Debugging: Understand how to debug and interpret logs.
- License: View the project's license.
- Contributions: Contribute to the project.
- Support: Get help and report issues.
git clone https://github.com/fabriziosalmi/caddy-mib.git
cd caddy-mibxcaddy build --with github.com/fabriziosalmi/caddy-mib=././caddy versionEnsure the caddy-mib module is included by checking the version output.
:8080 {
route {
caddy_mib {
error_codes 404 # Error codes to track (e.g., 404, 500)
max_error_count 5 # Number of errors allowed before banning
ban_duration 10m # Base duration to ban IPs (e.g., 10m, 1h)
ban_duration_multiplier 2 # Increase ban duration exponentially (e.g., 2x)
output stdout # Log output (stdout or stderr)
whitelist 192.168.1.1 # Whitelist specific IPs (comma-separated)
}
file_server {
root /var/www/html # Serve files from this directory
}
}
log {
output stdout
format json # Log in JSON format
}
}error_codes: List of space-separated HTTP error codes to track (e.g.,404 500).max_error_count: Maximum number of errors allowed before banning an IP.ban_duration: Base duration to ban IPs (supports values like1m,5m,1h).ban_duration_multiplier: Multiplier to increase ban duration exponentially with repeated offenses (e.g.,2for 2x increase).output: Log output stream (stdoutorstderr).whitelist: List of IPs to exempt from banning (e.g.,192.168.1.1).
- A client repeatedly requests a non-existent resource (
/nonexistent-file), resulting in404 Not Founderrors. - After 5 such errors, the client's IP is banned for 10 minutes.
- If the client continues to generate errors, the ban duration increases exponentially (e.g., 20m, 40m, etc.).
- Whitelisted IPs are never banned, even if they trigger errors.
- Subsequent requests from the banned IP return
403 Forbiddenuntil the ban expires.
Run the following command to test the middleware:
for i in {1..7}; do curl -I http://localhost:8080/nonexistent-file; sleep 1; done- The first 5 requests return
404 Not Found. - The 6th and 7th requests return
403 Forbidden(IP banned).
Check the Caddy logs for detailed information about IP bans and request statuses:
tail -f /var/log/caddy/access.logINFO http.handlers.caddy_mib IP banned {"ip": "::1", "error_code": 404, "error_count": 5, "max_error_count": 5, "ban_duration": "10m0s", "ban_expires_at": "2025-01-09T16:21:45.435Z", "path": "/nonexistent-file"}
INFO http.handlers.caddy_mib IP is currently banned {"ip": "::1", "path": "/nonexistent-file", "ban_expires_at": "2025-01-09T16:21:45.435Z"}
INFO http.handlers.caddy_mib IP is whitelisted, skipping middleware {"ip": "192.168.1.1", "path": "/nonexistent-file"}Did you know you can combine caddy-waf, caddy-mib, and caddy-mlf to create a robust multi-layered security solution for your web applications? By chaining these modules, you can leverage their unique features to provide comprehensive protection against web attacks, abusive behavior, and suspicious traffic patterns.
By chaining these modules, you can set up a flow where each layer contributes to filtering, banning, and analyzing traffic for maximum security:
| Module | Role in the Chain | Repository Link |
|---|---|---|
| caddy-waf | Acts as the first gate, inspecting and filtering malicious requests based on anomaly scores, rate limits, and blacklists. | GitHub: caddy-waf |
| caddy-mib | Handles IP banning for repeated errors, such as 404 or 500, to prevent brute force or abusive access attempts. | GitHub: caddy-mib |
| caddy-mlf | Provides an additional layer of protection by analyzing request attributes and marking/blocking suspicious traffic based on anomaly thresholds. | GitHub: caddy-mlf |
Here’s an example configuration to chain the modules:
- caddy-waf: Listens on
localhost:8080and forwards requests to caddy-mib. - caddy-mib: Listens on
localhost:8081and forwards requests to caddy-mlf. - caddy-mlf: Listens on
localhost:8082and returns a200 OKresponse for legitimate requests or forwards requests to your origin applications.
This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.
If you encounter any issues or have questions, please open an issue.