Levee is a teaching-grade DDoS-mitigation demo. It is not intended for production use and should not be exposed to untrusted networks without significant additional hardening.
Levee is designed to:
- Detect sustained per-IP TCP connection floods at small scale
- Mitigate them by dropping connections from offending sources at the edge of a single host
- Report packet-level statistics for inspection
Levee is not designed to defend against:
- Volumetric DDoS (anything saturating the network link itself — that must be handled upstream)
- Distributed attacks with rotating source IPs at high cardinality
- L7 application attacks (slowloris, request smuggling, payload-based exploits)
- TLS termination, bot detection, fingerprinting
- Pure SYN floods that never complete handshake (Levee enforces at
TCP
accept, so SYNs that never reachacceptare observed by the sniffer but not rate-limited)
| Limitation | Why it matters | Mitigation |
|---|---|---|
| Bloom filter has no eviction | A false positive blocks an IP forever | Restart container; for production, use a counting Bloom or periodic rebuild |
| Bucket dict is LRU-bounded at 10k | A spoofed-source flood with >10k unique IPs evicts legitimate buckets | Use a count-min sketch in production |
| Enforcement at L4 (TCP accept) | Half-open SYN floods bypass the rate limiter | Layer in SYN cookies / NFQUEUE for real protection |
| Single-process Python | GIL caps throughput | Pre-fork or rewrite in Go/Rust for production |
| In-memory state | All blocks lost on restart | Add persistence + state replication for HA |
If you believe you've found a security issue:
- Do not open a public GitHub issue.
- Email the maintainer directly via the address on the GitHub profile, or open a private security advisory: https://github.com/aakri0/Levee/security/advisories/new
- Include:
- A description of the issue
- Steps to reproduce
- Affected version (commit SHA)
- Your assessment of impact
We aim to respond within 7 days. Because this project is not actively
deployed, fixes will land as ordinary commits to main rather than via a
formal release/CVE process.
Only main is supported. There are no released versions.