Skip to content

NetDeflect v4.0.0: Rebuilt

Latest
Latest

Choose a tag to compare

View all tags
@0vm 0vm released this 13 Oct 02:25
· 1 commit to main since this release
v4.0.0
eb189fb
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

🚀 Install

git clone https://github.com/0vm/NetDeflect && cd NetDeflect
sudo bash install.sh

The installer sets everything up and asks five quick questions. Check on it any time with sudo systemctl status netdeflect.

Upgrading from v2? v4 is a full rebuild, so remove v2's old firewall rules first (see the Upgrading from v2 section below), then run the two commands above. Your settings.ini still works but make sure to update it.

Already on v4? git pull && sudo bash install.sh updates it and keeps your settings.

💡 New to NetDeflect? Pick watch-only mode during setup. It shows what it would block without blocking anything.

🛡️ NetDeflect v4.0.0

NetDeflect v4 is a ground-up rebuild. v2 captured traffic with tcpdump, turned it into text with tshark, searched that text for hex strings and blocked source addresses one at a time. v4 reads real packet headers, recognises 110 attack types by their actual fields, learns attacks it has never seen, and drops them inside the Linux kernel. It also protects game and VPN ports, scales to 10G/100G networks with sFlow, NetFlow and BGP, and installs with one command.

v3 was never released publicly. It was an internal test build for the new packet capture (dpkt and the AF_PACKET socket filter), and that work is now part of v4.

The program grew from about 1,800 lines to about 7,600, and the signature list from 98 text patterns to 110 field-based signatures that match real packet fields.

✨ Highlights

  • 🔥 Attacks are dropped in the kernel, not just blocked by address. v2 could only block source IPs, so a spoofed flood (most floods) was detected and then left alone. v4 drops the attack pattern itself with nftables, before connection tracking.
  • 🎯 Real packet classification. Signatures match protocol, ports, TCP flags, MSS, window, TTL, DSCP, length, fragments and payload at an exact offset. v2 searched tshark's text output, which caused false matches.
  • 🧠 Unknown attacks are learned and stopped. v4 fingerprints the whole packet (source port, TTL, TCP window, DSCP, flags, length, payload), builds the most specific rule that still covers the attack, and drops it automatically when it's confident.
  • 🕵️ Spoof-safe. Forged source addresses are never blocked, so an attacker can't trick NetDeflect into blocking an innocent address. Real reflectors and botnet machines are blocked, and the blocks expire.
  • 🎮 Game and VPN port protection. Learns your real players, lets them through first during an attack, and caps everyone else.
  • 📡 Big networks. sFlow and NetFlow/IPFIX collector, BGP blackholing and FlowSpec-style upstream mitigation, and an optional XDP fast path.
  • 💬 New Discord alerts. Coloured by result, with a plain-English summary, drop figures, and an "Action needed" field only when you need to do something.
  • 🚀 One-command install. sudo bash install.sh sets up dependencies, a five-question wizard and a systemd service.

🔍 Detection

New

  • Built-in packet sniffer using an AF_PACKET socket with a kernel socket filter. tcpdump and tshark are no longer required (both are still available as capture_method options).
  • sFlow v5, NetFlow v5, NetFlow v9 and IPFIX collector (capture_method = sflow or netflow), using the same classifier as live capture.
  • 110 signatures, rewritten from v2's 98 text patterns: more than 50 reflection and amplification vectors, SYN/ACK/RST/FIN floods, NULL/XMAS/SYN-FIN/SYN-RST/reserved-bit/ECN anomalies, ICMP/ICMPv6/GRE/ESP/AH/IPX floods, botnet payloads (Mirai, Qbot, Legion, Chaos, RyMGang, Condi, Fodcha and more), and game query floods (TeamSpeak, Source, FiveM, Quake 3, SA-MP, Minecraft).
  • Reflection is matched by the shape of an amplified reply (size floor and response markers), never by the port alone, so your own NTP, DNS or game traffic is not mistaken for an attack.
  • Header fingerprinting for unknown attacks. A field only counts when it dominates the attack and is shared by several different sources. Single connections, established-connection flags (ACK, ACK+PSH, ACK+FIN), your learned clients and your normal traffic are never learned.
  • Tool-generated SYN floods (no MSS option, impossible MSS, invalid flag combinations) are recognised and dropped outright.
  • Per-protocol triggers (TCP, UDP, ICMP) for floods that hide inside normal total traffic.
  • Carpet-bombing detection across a range of your addresses.
  • Pulse-wave detection, so protection stays up through the quiet gaps of on/off attacks.
  • Saturation detection from network card and kernel drop counters, so you're told when an attack is bigger than your connection.
  • IPv6 support throughout: capture, classification and blocking.
  • Peacetime baseline, so traffic you normally see is not learned as an attack.

Changed

  • detection_threshold (an absolute match count in v2) is replaced by detection_min_packets and a percentage of the sample, so sensitivity no longer shifts when you change packet_count. An old detection_threshold is read and converted for you.
  • The attacked port is now worked out from the whole sample (top ports), not from the first captured packet.

🧱 Mitigation

New

  • nftables backend at the raw prerouting hook (priority -300, before connection tracking). The whole ruleset is applied in one step, so protection never drops out while rules change.
  • Pattern drops for spoofed floods, per-source rate limits for SYN, ICMP, DNS and query floods, and address blocks for reflectors and botnets. The response is chosen by attack category.
  • Every reflector in a reflection attack is blocked, added in batches, so tens of thousands of reflectors cost one firewall update per round.
  • Blocks expire on their own (block_timeout, default one hour). In v2 a block lasted until reboot or until you removed it by hand.
  • Automatic range blocking when many addresses from one /24 or /64 are attacking.
  • SYN cookies switched on automatically.
  • Always-on clean-up of impossible traffic: port 0, packets claiming to come from your own server, fragment floods, and optionally private-range sources on a public interface.
  • Blocklist files and URLs (for example Spamhaus DROP), loaded into the kernel and refreshed automatically.
  • Optional connection tracking extras: out-of-state ACK/RST floods, unsolicited reflection replies, and per-address connection limits for slowloris-style attacks.
  • Optional XDP fast path (firewall_system = xdp, using xdp-tools): banned addresses are dropped in the network card driver. Falls back to nftables if XDP isn't available.
  • Upstream BGP blackholing (ExaBGP or your own script) when your link is nearly full, with a cap on announced prefixes so your provider's max-prefix limit is never hit.
  • Out-of-band mode (firewall_system = bgp) for routers exporting sFlow or NetFlow: no local rules, mitigation sent upstream.
  • Drop counters are read back from the firewall, so reports show how much is actually being dropped and how much still gets through.

Changed

  • Default firewall is now nftables (was blackhole). ipset, iptables and blackhole still work.
  • ufw is no longer a backend. A ufw setting is switched to ipset, which runs alongside ufw.
  • Firewall commands run without a shell, and many blocks are applied in one call instead of one process per address.

🎮 Game server and VPN protection (all new)

  • Declare your ports once in [services] ports (for example 27015/both, 51820/udp:wireguard).
  • Learns real players and VPN users while things are quiet, and lets them through first during an attack. Learned clients survive restarts.
  • Lockdown during an attack: unknown addresses get a small allowance each and a fixed total, so a flood from thousands of fake addresses can't fill the port and new players can still join.
  • WireGuard and OpenVPN validation: anything that isn't a valid packet for that protocol is dropped.
  • Optional per-port rate limits and packet-size limits, and per-service sections ([service:NAME]) with presets for game, WireGuard, OpenVPN and Minecraft.
  • GRE, IPIP and WireGuard tunnels are detected automatically and their endpoints trusted.
  • Works with Docker game panels such as Pterodactyl and Pelican: rules run before Docker's port forwarding, and Docker's internal networks are left alone.

💬 Alerts and reports

New

  • Discord alerts coloured by result: green mitigated, amber partially mitigated, red not yet mitigated, dark red link saturated.
  • A one-line plain-English summary, for example: "Zero-fill UDP Flood against 203.0.113.10 port 53. Dropping 68,347 pps (62% of incoming) in the kernel."
  • Incoming traffic, dropped and passing traffic, target ports, protocol mix, each attack type marked spoofed or real, learned patterns, unique source count, and what was blocked.
  • An "Action needed" field that appears only when something is wrong, naming the setting to change.
  • An end-of-attack summary with duration, peak, peak dropped, every attack type seen, rounds, start and end time and pulse-wave bursts.
  • discord_mention to ping a role or @here on attack alerts.
  • discord_style = template keeps your own notification_template.json, with new placeholders: {{summary}}, {{action_needed}}, {{dropped_pct}}, {{top_ports}}, {{protocol_mix}}, {{unique_sources}}, {{source_kind}} and {{hostname}}.
  • Slack, Microsoft Teams and Mattermost alerts (text_webhook_url).
  • Alerts on attack start, on a new attack type, and on attack end, rather than every round.
  • notify_script runs your own script with the full report as JSON.
  • Prometheus metrics (node_exporter textfile or a built-in /metrics page) and a JSON event log for SIEM tools.
  • A text and JSON report per attack, a CSV of the addresses involved, and a .pcap capture.
  • Reports, captures and logs are rotated so they never fill the disk.
  • --test-webhook sends a realistic sample alert so you can check the look without an attack.

Kept from v2

  • External firewall API integration ([external_firewall]), with bearer, basic or header authentication and a custom request body.
  • The classic [NetDeflect] terminal look, now as a live status screen showing the current attack and drop rate while mitigating.
  • Update notice when a new release is out.

🛠️ Setup and day-to-day running

New

  • install.sh: installs dependencies on Debian/Ubuntu, Fedora/Rocky/Alma, openSUSE and Arch, runs a five-question setup, runs a self-test, and installs a systemd service. Running it again upgrades in place, keeps your settings, backs up an edited methods.json, and restarts the service on the new version. Options: --service, --here, --with-xdp.
  • Unattended installs (no terminal) start in watch-only mode so nothing is blocked before the settings are checked.
  • --setup guided setup and --selftest system check.
  • Watch-only mode (--dry-run or enable_ban = False).
  • Live management commands that don't disturb the running service: --block, --block-net, --unblock, --list-blocks, --stats.
  • systemctl reload netdeflect re-reads settings and signatures without a restart.
  • Profiles for a VPS, a dedicated server or an enterprise fleet.
  • Network interface detected automatically (network_interface = auto, was eth0).
  • Rules are removed when NetDeflect stops (--teardown cleans up anything left), and put back within 30 seconds if a firewall restart or Docker removes them.
  • Settings are checked on start, with every mistake listed clearly.
  • Your gateway, public IP, DNS resolvers, SSH session and whitelisted addresses are never blocked.

🐛 Fixed from v2

  • Spoofed floods were detected but nothing was dropped. v2 only blocked addresses and correctly refused to block forged ones, which left the flood running. v4 drops the pattern.
  • False matches from text searching. v2 counted hex strings in tshark's text output, so a short pattern such as 41414141 or 2f78 could match inside unrelated packets. A signature like 17\t\t123 matched any UDP packet from port 123, including your own NTP traffic. v4 matches real fields.
  • Blocks never expired and v2 lost track of them on restart. v4 blocks are timed, tracked and cleaned up.
  • Rules were left behind on exit. v4 removes everything it created when it stops.
  • iptables blocks were appended to INPUT, after any accept rules and after connection tracking, so they could be skipped or arrive too late. v4 drops in raw prerouting.
  • One process per blocked address. A reflection attack with thousands of reflectors meant thousands of firewall commands. v4 batches them.
  • The attacked port came from the first captured packet only. v4 uses the whole sample.
  • "Mitigated" was judged by total traffic falling below the threshold, not by what was dropped. v4 reads the firewall's drop counters.
  • IPv6 addresses couldn't go in the ipset backend. v2 created an IPv4-only set. v4 handles IPv6 in every backend.
  • Removed sys.setrecursionlimit(100000000), which could crash the interpreter on deep recursion instead of raising a clean error.

⬆️ Upgrading from v2

  1. Stop v2 if it's running.
  2. Remove v2's old rules, since v4 doesn't manage them: 
    sudo iptables -t raw -D PREROUTING -m set --match-set blocked_ips src -j DROP 2>/dev/null
sudo iptables -t raw -D PREROUTING -m set --match-set trusted_ips src -j ACCEPT 2>/dev/null
sudo ipset destroy blocked_ips 2>/dev/null; sudo ipset destroy trusted_ips 2>/dev/null
    If you used firewall_system = blackhole, list the routes with ip route show type blackhole and remove the ones v2 added with sudo ip route del blackhole <address>. If you used ufw or iptables, remove v2's deny rules the same way you'd remove any other rule.
  3. Get v4 and run sudo bash install.sh.

Settings. Your v2 settings.ini still loads. detection_threshold and block_other_attack_contributors are read and converted, with a warning in the log. Any new setting you don't have uses its default. For the full set of options and explanations, let the installer or --write-default-config write a fresh file and copy your values across.

Signatures. methods.json has a new format. Use the one that ships with v4; the installer copies it for you. Patterns v2 learned in application_data/new_detected_methods.json are carried over and come back as report-only until you approve them.

Behaviour changes to know about

  • Blocks now expire after block_timeout (one hour by default) instead of lasting until reboot.
  • The default firewall is nftables. Set firewall_system if you want something else.
  • ufw is no longer a backend and is switched to ipset.
  • Confident learned patterns are now dropped automatically during the attack (autodetect_enforce = True). Set it to False to only report them.

📋 Requirements

  • Linux with root access.
  • Python 3.7 or newer, with psutil and requests.
  • nftables (recommended) or iptables with ipset, and iproute2.
  • Optional: xdp-tools for the XDP fast path, tcpdump or tshark if you prefer them for capture, ExaBGP for BGP.

🧪 Testing behind this release

  • 90 automated tests covering classification, signature loading, learning, rule generation, alerts and settings.
  • Live attack simulations in isolated network namespaces: SYN flood, zero-fill UDP flood, an unknown header-only flood and NTP reflection, each confirmed dropping from the firewall's own counters.
  • 150,000 random inputs through the packet, sFlow, NetFlow v5 and NetFlow v9/IPFIX decoders with no errors.
  • Every alert type checked against Discord's limits (25 fields, 1,024 characters per field, 6,000 in total).
  • Installer tested for fresh install, upgrade, failed start, missing dependencies and machines without systemd.

⚠️ Known limitations

  • An attack bigger than your internet connection has to be stopped upstream, by your host or with BGP.
  • An attack has to cross your thresholds before NetDeflect acts.
  • An attack that randomises every header field and payload and matches no signature can't be dropped by pattern. On [services] ports, lockdown still caps it.
  • In sFlow/NetFlow mode, mitigation is upstream (BGP or API), not local.
  • Linux only.

Run in watch-only mode for a day on a new server and check application_data/new_detected_methods.json before turning blocking on.

Assets 2
Loading