Home

FLOD System

First Line Of Defense

An adaptive two stage Layer 4 volumetric DDoS mitigation gateway.

What It Does

Most DDoS mitigation uses fixed thresholds: block anything sending more than some hard coded number of packets per second. That fails in both directions. Your legitimate traffic spikes during a busy period and real users get blocked; an attacker stays just under the line and gets through.

FLOD learns what your normal traffic looks like and moves its own detection boundaries to match. It distinguishes a DDoS flood from a flash crowd, a legitimate surge, without anyone adjusting a threshold by hand.

It sits inline on a gateway between the traffic source and the hosts you are protecting, and it drops or throttles offending sources in the kernel.

How It Is Built

Two stages, connected by a Unix domain socket.

Stage 1 is a Rust sensor. It captures every packet headed for a protected host, computes rate and source diversity over short windows, and compares them against a running baseline it maintains itself. When a window looks wrong, it sends a feature vector to Stage 2. When nothing looks wrong, it still reports periodically so the dashboard stays current.

Stage 2 is a Python service. It receives those feature vectors, runs a Random Forest classifier to decide whether the window is normal traffic, a flash crowd, or an attack, and issues kernel level enforcement through ipset and iptables. A second model, an Isolation Forest, runs alongside it on every window, flagging traffic unlike anything either model has learned as a separate Anomalous state rather than driving enforcement itself. It also serves the web dashboard.

The split matters: Stage 1 is on the packet path and must stay fast, so it does only arithmetic. Stage 2 does the expensive work and is never in the way of a packet.

What It Detects

FLOD works on Layer 4 volumetric floods that are visible from packet headers alone: rate, source IP entropy, protocol mix, and how concentrated traffic is on its busiest source. In practice that means floods which are both high volume and concentrated, arriving from a bounded set of real addresses. SYN, UDP, and ICMP floods qualify, as does reflected and amplified traffic returning from a finite set of reflectors.

One thing is explicitly out of scope, one is partially addressed:

Application layer attacks. No request content is parsed, so low and slow request floods, connection exhaustion such as Slowloris, and anything that looks ordinary per packet but is malicious per request are outside what a header only feature set can see.

Randomized source spoofing. Forging a new source address for every packet raises entropy instead of lowering it, inverting the signal the address based features look for. Source port entropy, TTL variance, and TCP SYN fingerprint diversity (1.2.0 and later) are invariant under address forgery and close this detection blind spot, but detecting a spoofed flood is a narrower problem than stopping one: blocking a forged address still punishes whoever really owns it. Safe enforcement against this class remains open.

Which Version Are You Running?

ddos_stage1 --help | head -1
systemctl status ddos-stage1

Or check the release you installed from. The two lines differ enough that following the wrong pages will waste your time.

1.x adds a second capture backend that runs in the kernel using XDP and TC, selected with --capture-mode, along with tuning flags for the detection boundaries. Everything from 0.x still works and remains the default. From 1.2.0, also adds source port entropy, TTL variance, and TCP SYN fingerprint diversity to the feature set and a second model, an Isolation Forest, for the new Anomalous state described in the Dashboard Guide. From 1.3.0, passively captured traffic gets labeled and folded into training data automatically once two independently trained models agree on it confidently, covered in Configuration. 1.4.0 added a dashboard page for reviewing what was labeled. 1.5.0 gave DDoS windows their own capture file, so the loop grows Normal, Flash Crowd, and DDoS.

0.x captures in user space with libpcap only. Ended at 0.5.5.

Page	1.x	0.x
Requirements, install, first login	Installation	Installation 0.x
Sensor flags, enforcement tuning, alerts	Configuration	Configuration 0.x
When something is not working	Troubleshooting	Troubleshooting 0.x
Every page in the web console	Dashboard Guide	Dashboard Guide

The dashboard is the same in both lines, so there is one page for it.

The README covers the detection theory: Welford's algorithm, Shannon entropy, the EWMA rate, and how the classifier is trained and evaluated.

Reporting Problems

Bugs and feature requests go in the issue tracker.

Security vulnerabilities do not. Read SECURITY.md first and report privately.

A Note on Scope

This is a personal, open source project built as a learning exercise in network security, statistical detection, and systems programming. It is a working system, and it does what this wiki describes, but it has not been through the kind of adversarial testing a production security product needs. Deploy it on a lab network or somewhere you can afford to have it be wrong.