Open source · Go · IPv4 · CLI

A million IPs.
A handful of ranges.

flokbn is a Go CLI that clusters the IPs in your access logs into CIDR ranges. A binary trie does the heavy lifting - a 2-million-line log takes about a second on an ordinary workstation. Use it for botnet detection, abuse analysis, or building ban lists.

Quick start CLI reference

static for historical logs · live for real-time banning · JSON / plain / TUI output

~4M requests/sec measured parse rate, full parse on the reference dataset

~50ms trie build for ~1.2M unique IPs on the reference dataset

<1ms cluster detection across multiple cluster arg sets

~50B memory per unique IP in the trie - usage scales linearly

Measured on a 2.3M-request real-world dataset on a single Linux workstation - your numbers will vary with hardware and log shape. Full benchmarks →

00 / SEE IT RUN

One command from raw log to clustered ranges

Point flokbn static at an access log and give it one or more cluster arg sets - minSize,minDepth,maxDepth,threshold. Each set is a detection tier: tight ones catch single hot hosts, loose ones catch whole subnets misbehaving together.

Multiple detection tiers in a single pass
Whitelists protect monitoring and partner IPs
Plain or JSON output you can script into iptables, nftables, or a WAF

Static analysis guide →

flokbn static - illustrative output, RFC 5737 ranges

$ flokbn static --logfile /var/log/nginx/access.log \
    --clusterArgSets 1000,24,32,0.1 \
    --clusterArgSets 10000,16,24,0.2 --plain

ANALYSIS OVERVIEW
────────────────────────────────────────────
Total Requests:  2,345,057
Parse Rate:      4,388,769 requests/sec
Duration:        570 ms

CLUSTERING RESULTS (2 sets)
────────────────────────────────────────────
Set 1: min_size=1000, depth=24-32, threshold=0.10
  192.0.2.86/32        1,574 requests  (  0.07%)
  198.51.100.192/26    3,083 requests  (  0.13%)

Set 2: min_size=10000, depth=16-24, threshold=0.20
  203.0.113.0/24      52,868 requests  (  2.25%)
  198.51.100.0/24     28,812 requests  (  1.23%)

01 / HOW IT WORKS

Five stages, one pass

1
Parse
Configurable format strings read Apache, Nginx, or custom logs. An IP-only fast path skips every field the analysis doesn’t need.
Log formats
2
Filter
Time windows, whitelist/blacklist files, and regex filters on User-Agent and endpoint - with a literal prefilter so the regex engine rarely runs.
Filtering
3
Build trie
Every surviving IP is inserted into a binary trie - on the reference dataset, clustering then runs in microseconds per arg set.
Internals
4
Detect clusters
Configurable depth ranges and thresholds walk the trie and emit the CIDR ranges where traffic concentrates.
Clustering
5
Jail
Detected ranges land in a persistent jail - the state your firewall automation reads to ban and unban.
Jail system

02 / TWO MODES

Analyze logs after the fact, or watch them live

flokbn static

Static analysis

Analyze historical log files. Slice by time window, query specific CIDR ranges, and - when the use case calls for it - generate a ban-candidate list from what actually happened.

Multi-tier detection with several cluster arg sets per run
Time-window filtering for forensic slices
JSON, compact JSON, plain text, or interactive TUI

Static analysis guide →

flokbn live

Live protection

Continuous monitoring over the Lumberjack protocol (Filebeat-compatible). Sliding windows watch traffic in real time; detected ranges are banned automatically.

Bounded memory via slidingWindowMaxSize
Persistent jail state with escalating ban stages
HTTP /stats, /bans and Prometheus /metrics endpoints
Docker demo stack - closed-loop firewall with a Grafana dashboard

Live protection guide →

03 / FEATURES

What’s in the box

/01

Automatic clustering

IPs group into CIDR ranges without manual configuration - you tune size, depth, and threshold, the trie does the rest.

/02

Multi-trie detection

Run several detection configurations simultaneously in one pass - one log read, many perspectives.

/03

Flexible filtering

Whitelist and blacklist files, regex on User-Agent and endpoint, and time-based windows - combined freely.

/04

Block list generation

Inspired by fail2ban: the output is a list of CIDR ranges with request counts - a ready-made candidate list for bans or rate limits.

/05

Four output formats

JSON for pipelines, compact JSON for storage, plain text for humans, and an interactive TUI for exploration.

/06

Speed as a feature

Zero-copy chunked I/O, an IP-only parse path, regex literal prefiltering, memory pools - the performance work is documented and benchmarked.

04 / THE DOCS

Scope, stated plainly

IPv4 only. IPv6 is not implemented yet.
Live mode ingests via Lumberjack. HTTP/JSON API support is planned.
One %h field per log format. Multiple IP fields are not supported.
No duplicate field specifiers in a log format string.

Full limitations →

Cluster your first log
in five minutes.

Quick start View on GitHub

Title here

A million IPs.
A handful of ranges.

One command from raw log to clustered ranges

Five stages, one pass

Parse

Filter

Build trie

Detect clusters

Jail

Analyze logs after the fact, or watch them live

Static analysis

Live protection

What’s in the box

Automatic clustering

Multi-trie detection

Flexible filtering

Block list generation

Four output formats

Speed as a feature

Pick your entry point

Getting Started

Guides

Reference

Architecture

Contributing

Scope, stated plainly

Cluster your first log
in five minutes.

A million IPs.A handful of ranges.

One command from raw log to clustered ranges

Five stages, one pass

Parse

Filter

Build trie

Detect clusters

Jail

Analyze logs after the fact, or watch them live

Static analysis

Live protection

What’s in the box

Automatic clustering

Multi-trie detection

Flexible filtering

Block list generation

Four output formats

Speed as a feature

Pick your entry point

Getting Started

Guides

Reference

Architecture

Contributing

Scope, stated plainly

Cluster your first login five minutes.

A million IPs.
A handful of ranges.

Cluster your first log
in five minutes.