🦀 CrabShield

A high-performance, hybrid L3/L4/L7 anti-DDoS firewall powered by eBPF/XDP and Rust.

CrabShield protects your Linux servers from massive Application-Layer (L7) floods and volumetric attacks by combining user-space log analysis with kernel-space XDP_DROP mitigation. Instead of overwhelming your CPU tracking network packets via iptables/nftables when an attack strikes, CrabShield drops malformed traffic at the Network Interface Card (NIC) driver level, achieving virtually zero CPU overhead during massive Botnet attacks.

🚀 Features

• XDP (eXpress Data Path) Mitigation: Packets from attacking IPs are dropped in the kernel before reaching the TCP/IP stack (skb), saving massive amounts of compute resources.
• L7 Tailing Engine: Instantly parses nginx or traefik access logs to detect 404 floods, Brute-force attacks, bad User-Agents, and Instant-Ban paths.
• Auto-Expiry: Bans are dynamically placed and reaped via shared eBPF RingBuf / Hash Maps.
• Zero-Dependency Daemon: The User-space control plane compiles down to a single, static musl binary.
• Cross-Architecture Support: Works natively on both legacy Intel/AMD (x86_64) servers as well as modern ARM64 (aarch64) cloud instances (e.g., Oracle Ampere, Hetzner ARM).

🛠️ Architecture

CrabShield consists of two primary components communicating via BPF Maps:

1. The Kernel-Space Driver (crab_shield_xdp): A high-performance eBPF program compiled into an .elf object. It hooks onto your network interface and performs lightning-fast hash map lookups.
2. The User-Space Daemon (crab-shield-daemon): A Tokio asynchronous application that trails logs, calculates request velocity, loads the XDP driver into the kernel, and manages IP blocklists.

📚 Documentation & Guides

To keep the repository clean, detailed instructions for deployment, configuration, and compilation have been split into standalone guides. Please read them carefully before trying to run the firewall:

• 🏁 DEPLOYMENT.md - A step-by-step guide for foreground testing and configuring CrabShield as a permanent systemd background service.
• ⚙️ CONFIGURATION.md - Explains config.toml, how to find your correct network interface, and why whitelisting your IP is critical.
• 🛠️ COMPILING.md - Instructions for setting up Rust nightly, bpf-linker, and cross-compiling the daemon for Intel/ARM servers (with macOS compatibility).

📖 The "Mind-Blowing" Paradigm Shift: eBPF vs Traditional Firewalls

How do 99% of System Administrators attempt to block attacks today? They use tools like Fail2ban or UFW, which rely on the Linux kernel's iptables or nftables.

The Traditional Flaw (L7 -> iptables): When a massive volumetric DDoS attack hits a traditional server:

1. The Network Card (NIC) receives the packet and triggers a hardware CPU interrupt.
2. The Linux OS halts what it's doing, allocates a kernel memory structure (sk_buff), and copies the packet into memory.
3. The packet travels up the heavy Linux network stack (IP -> TCP layer).
4. iptables finally inspects the packet rules and decides to DROP it. The Result: Even if your web server (Nginx) never sees the packet, your server's CPU is completely crushed just by the sheer overhead of allocating memory and processing headers for 500,000 packets per second. This is known as an Interrupt Storm. Your server crashes, your SSH connection drops, and the attackers win. To survive, businesses are typically forced to pay thousands for external CDNs (like Cloudflare Enterprise).

The CrabShield Way (eBPF / XDP at L3/L4): CrabShield utilizes the eXpress Data Path (XDP). We attach a compiled eBPF Rust program directly into the driver of the Network Interface Card.

1. The NIC receives the incoming packet.
2. CrabShield's XDP driver inspects the packet's Source IP natively, instantly.
3. If the IP is on our blocklist, it issues an XDP_DROP instruction. The Result: The packet is annihilated across the hardware/driver boundary. No sk_buff memory is allocated. The heavy Linux network stack is 100% bypassed. A standard $5/month VPS can casually drop millions of packets per second while utilizing less than 5% of a single CPU core, leaving your databases and APIs completely untouched.

The Hybrid Magic: CrabShield achieves the best of both worlds. It uses standard Application-Layer (L7) logs from Nginx to smartly identify "sneaky" attackers (like brute-forcers or scrapers), but it executes the penalty at the Network-Layer (L3/L4) via XDP.

☎️ Contact & Installation Support

Interested in deploying CrabShield on your infrastructure but need help setting it up?

If you are a business looking for a done-for-you installation, tuning, and configuration of CrabShield on your Linux servers to mitigate DDoS attacks, feel free to reach out.

Email: alexgrimdev@gmail.com

📄 License

This project is licensed under the MIT License.