XDP-ban

See it. Ban it.

Governed XDP banning — in a single binary.

---

XDP-ban is a governed ban tool: submit a ban, get it approved by someone else, and it executes in XDP, at the earliest point in the kernel, with escalating durations for attackers who keep knocking. Ships as a single static binary you can copy and run.

Features

• Governed — approvals, four-eyes principle, role-based access, immutable audit log, one-time email approval links.
• Escalating bans — repeat offenders get progressively longer bans, up to permanent.
• Scoped bans — pick source ranges by country / ASN, protect a single target host. Impact is previewed and quota-checked before submission.
• Pure XDP enforcement — no nftables, no iptables. The agent writes eBPF maps directly, in generic (SKB) mode so it works on any NIC driver, not just the ones with native XDP support.
• Single binary — pure Go, CGO_ENABLED=0, no external DB, no HTTP API surface. Copy and run.

Architecture

One binary, control plane and enforcement together:

web UI / approvals ──▶ SQLite ──▶ (in-process) ──▶ xdp_filter.o ──eBPF map──▶ [eth0] production NIC

xdp-ban used to be split into a control plane and a separate xdp-agent executor that polled the control plane's own HTTP API for orders. They've been merged: xdp-ban now loads and attaches the XDP filter program itself and executes approved bans directly against the database, no local HTTP round-trip. Pass -iface <ifname> so it knows where to attach.

Quick start

Download the binary and run it. No dependencies, no build step — the eBPF objects are already inside.

# x86_64
curl -L -o xdp-ban https://github.com/githubflyideas/xdp-ban/releases/download/v0.28/xdp-ban-linux-amd64
# arm64: replace amd64 with arm64 in the URL above

chmod +x xdp-ban
sudo ./xdp-ban -iface eth0    # http://localhost:8080 — root needed to attach XDP

Default accounts

Four accounts are seeded on first run, one per role. Change these passwords immediately — they are printed in this README and therefore public.

Username	Password	Role	Can do
admin	admin12345	admin	everything, incl. user management and system config
approver	approver12345	approver	approve / reject / revoke bans, view audit
operator	operator12345	operator	submit ban requests, view audit
viewer	viewer12345	viewer	read-only

Why four and not one: the four-eyes principle requires the submitter and the approver to be different people. A single account cannot approve its own request, so you need at least two usable logins to complete a ban.

Change passwords under Users (admin only). You can also add, disable and delete users there — every change is written to the audit log.

Data lives in a single xdpban.db file. Back up = copy the file.

All releases: https://github.com/githubflyideas/xdp-ban/releases

Scoped bans (country / ASN)

curl -O https://iptoasn.com/data/ip2asn-v4.tsv.gz
XDPBAN_PREFIX_DB=./ip2asn-v4.tsv.gz ./xdp-ban

Without it, everything else works and the UI tells you the feature is unavailable.

Configuration

xdp-ban flags:

Flag	Default	Purpose
-iface	— (required)	Production NIC to attach the XDP ban program to. No default — silently skipping this would mean bans stay in the approval log without ever blocking traffic.
-poll-interval	5s	How often to scan for newly-approved dispatches to execute

xdp-ban environment variables:

Variable	Default	Purpose
XDPBAN_DB	xdpban.db	SQLite file path
XDPBAN_ADDR	:8080	Listen address
XDPBAN_BASE_URL	http://localhost:8080	Prefix for email approval links
XDPBAN_IFACE	—	Alternative to -iface
XDPBAN_PREFIX_DB	—	Path to ip2asn-v4.tsv[.gz]; enables scoped bans
XDPBAN_COOKIE_SECURE	—	Set to any value when behind TLS
XDPBAN_PPROF	—	Set to any value to expose /debug/pprof (bind to a private interface only)

Build from source

Only needed if you're hacking on it — released binaries already bundle the eBPF objects. Requires clang and libbpf-dev.

make bpf      # clang → cmd/xdpban/obj/xdp_filter.o (embedded via go:embed)
make build    # xdp-ban; refuses to run if the .o file is missing
make check    # go vet + go test -race
make release  # bpf + check + cross-compile linux/{amd64,arm64}

The .o files are build artifacts, not tracked in git. make build asserts they are non-empty, so a binary with empty bytecode can't be shipped by accident.

License

Apache-2.0. See LICENSE.