What is flokbn?#

flokbn is an IP clustering tool that analyzes HTTP logs and groups IP addresses into CIDR ranges for blacklist generation. Inspired by fail2ban.

Key Features#

• Static Mode: Analyze historical log files
• Live Mode: Real-time protection with automated banning
• Automatic IP Clustering: Groups IPs into CIDR ranges without manual configuration
• Multi-Trie Detection: Run multiple detection configurations simultaneously
• Flexible Filtering: Whitelist/blacklist support with regex-based User-Agent and endpoint filtering
• Multiple Output Formats: JSON, compact JSON, plain text, and interactive TUI

How It Works#

1. Log Parsing: Parses HTTP logs using configurable format strings
2. Filtering: Applies time-based, pattern-based, and list-based filters
3. Trie Building: Constructs IP address tries for efficient clustering
4. Cluster Detection: Identifies CIDR ranges using configurable parameters
5. Jail Management: Maintains persistent state of detected ranges

Use Cases#

• Emergency Response: Quickly identify and block high-volume networks
• Real-Time Protection: Continuous monitoring with automatic banning
• Forensic Analysis: Investigate specific time periods

Limitations#

• IPv4 Only: Currently only IPv4 addresses are supported. IPv6 is not implemented yet.
• Lumberjack Protocol: Live mode uses the Lumberjack protocol for log ingestion. HTTP/JSON API support is planned for future releases.
• Fixed Live Log Layout: Live mode expects the standard combined log format with the client IP as the first field. Configurable format strings apply to static mode only.
• Single IP Field: Log format must contain exactly one %h (IP address) field. Multiple IP fields are not supported.
• No Duplicate Fields: Log format cannot contain duplicate field specifiers (e.g., two %t timestamp fields or two %s status fields).

Next Steps#

Ready to get started? Check out the Installation Guide to install flokbn, or jump straight to the Quick Start to see it in action.