XDrop

Distributed XDP/eBPF firewall with wire-speed packet filtering and a central management controller.

中文文档

XDrop is a distributed, high-performance packet filtering system built on Linux XDP (eXpress Data Path). It attaches BPF programs directly to network interface drivers — bypassing the kernel network stack entirely — to drop, pass, or rate-limit traffic at the earliest possible point in the receive path.

The system has two components:

• Node Agent — runs on each filtering host, manages the BPF data plane, and exposes a REST API
• Controller — central management plane with a Web UI, stores rules in SQLite, and pushes them to all registered nodes

Classic Theme	Amber Theme

┌──────────────────────────────────────────────────────────────────────┐
│                            Controller                                │
│                                                                      │
│   ┌──────────────┐   ┌─────────────┐   ┌────────────┐   ┌────────┐  │
│   │  Web UI      │   │  REST API   │   │  Sync      │   │SQLite  │  │
│   │  (Vue 3 +    │   │  (Gin)      │   │  Scheduler │   │  DB    │  │
│   │  ECharts)    │   │             │   │            │   │        │  │
│   └──────────────┘   └─────────────┘   └────────────┘   └────────┘  │
└─────────────────────────────────┬────────────────────────────────────┘
                                  │  HTTP (rule push / health poll)
              ┌───────────────────┼───────────────────┐
              ▼                   ▼                   ▼
       ┌────────────┐      ┌────────────┐      ┌────────────┐
       │  Node 1    │      │  Node 2    │      │  Node N    │
       │  Agent     │      │  Agent     │      │  Agent     │
       │ ┌────────┐ │      │ ┌────────┐ │      │ ┌────────┐ │
       │ │XDP/BPF │ │      │ │XDP/BPF │ │      │ │XDP/BPF │ │
       │ └────────┘ │      │ └────────┘ │      │ └────────┘ │
       └────────────┘      └────────────┘      └────────────┘
        Wire-speed ↑        Wire-speed ↑        Wire-speed ↑

• Wire-speed filtering — XDP programs run before sk_buff allocation; near line-rate even on commodity hardware
• Five-tuple matching — src/dst IP, src/dst port, protocol
• IPv4 and IPv6 — unified rule format; IPv4 stored as IPv4-mapped IPv6 internally
• CIDR rules — per-direction LPM trie (src or dst prefix); supports /0–/128
• Whitelist (v2.7.0+) — 31-combo bitmap-gated matching with double-buffer atomic sync; hash map bypass checked before any blacklist rule
• Actions — drop, rate_limit (token bucket, configurable PPS), pass
• Packet length filter — pkt_len_min / pkt_len_max (L3 total length)
• TCP flags matching — tcp_flags post-match filter (e.g. SYN, SYN,ACK, RST); mismatch continues wildcard fallback
• Decoder sugar (v2.6+) — decoder=tcp_ack|tcp_rst|tcp_fin expands to protocol=tcp + matching TCP flags mask at rule creation; lets upstream detectors name attack patterns instead of bit-manipulating flags
• Anomaly data plane (v2.6.1+) — decoder=bad_fragment|invalid attaches anomaly bits to rules; a tail-called xdp_anomaly_verify program detects Ping-of-Death (offset*8+payload>65535), tiny-first-fragment (TCP <20B / UDP <8B), malformed IHL<5, truncated total_length, and TCP doff<5 — drops packets only when the rule's match_anomaly bits intersect with the packet's actual anomaly signature. Anomaly detection logic ported byte-for-byte from xSight v1.3 for cross-repo parity. IPv6 invalid supported; IPv6 bad_fragment rejected at the Controller (deferred)
• Bitmap optimization — 64-bit bitmap encodes which of 34 field combinations have active rules (blacklist) or 31 combos (whitelist); BPF skips combinations with no rules, keeping the hot path O(1)
• Per-rule statistics — per-CPU match_count and drop_count aggregated by the agent

Rule updates follow an RCU-style double-buffer protocol to eliminate race conditions between writing rules and updating the lookup bitmap:

Blacklist (v2.0+):

1. Write rule to the shadow BPF hash map (blacklist_b or cidr_blist_b)
2. Build updated config (bitmap, counts) in the shadow config map
3. Single atomic write flips the active_config selector — BPF switches atomically

Whitelist (v2.7.0+, Phase 8):

1. Write whitelist entries to the shadow BPF map (whitelist_b)
2. Update CONFIG_WL_BITMAP and CONFIG_WL_MAP_SELECTOR in config
3. Single atomic flip — whitelist switches with zero gap

This guarantees the BPF data path never sees an inconsistent bitmap/rule state.

• Central rule storage in SQLite with full CRUD and batch APIs
• Configurable sync interval with forced-sync endpoint (POST /api/v1/nodes/:id/sync)
• Node health monitoring with automatic online/offline status
• Web UI: real-time traffic dashboard (ECharts), node overview, rule management, whitelist editor
• Optional API key authentication on both controller and node

xdrop/
├── node/
│   ├── bpf/          # XDP program in C (xdrop_gate.c + xdrop_main.c / xdrop.h)
│   └── agent/        # Go agent — BPF loader, API server, AtomicSync engine
├── controller/
│   ├── cmd/          # Binary entry point
│   ├── internal/     # API, service, repository, scheduler, client
│   └── web/          # Vue 3 + Element Plus + ECharts frontend
└── scripts/          # Build and service management scripts

• Node Agent → — XDP data plane, BPF maps, AtomicSync, API
• Controller → — Management plane, Web UI, sync engine

The node agent must run on Linux (XDP is a Linux kernel feature). The controller can be deployed anywhere.

Kernel floor note (v2.5+): the node agent uses BPF_LINK_TYPE_XDP for XDP attach, which landed in Linux 5.9 (October 2020). On older kernels (5.8 and below) startup fails with a clear error message pointing to this requirement. Modern distros are covered: Debian 11+ (5.10), RHEL/Rocky/Alma 9+ (5.14), Ubuntu 20.04 HWE / 22.04+ (5.15+). Operators on legacy kernels should hold on xdrop v2.4.2 (the last release using the netlink attach path) until they can upgrade.

BPF pinning (v2.5+): by default the node agent pins its BPF objects under /sys/fs/bpf/xdrop/ so state survives across systemctl restart xdrop-agent:

• 16 map files (Phase 3) — blacklist, whitelist, cidr_blacklist, the four LPM tries, config_a / config_b, etc. Keeps map IDs stable for bpftool map dump pinned /sys/fs/bpf/xdrop/<name> and for any external BPF tooling pointed at those objects.
• 1 XDP link file per interface (Phase 4) — link_<ifname> (e.g. link_ens38). Agent restart does LoadPinnedLink + Link.Update(newProg) instead of detach/reattach, so the XDP program swap is atomic in the kernel — zero-gap attachment. Without link pinning, a restart would leave a ~1.5–3 s window with no filter.

Requires /sys/fs/bpf to be mounted as a bpf filesystem — most modern distros do this automatically via systemd. If pinning fails (unmounted, EPERM, etc.) the agent silently falls back to non-pinned mode by default; set bpf.pinning: require in config.yaml for strict mode, or disable to opt out entirely.

For a step-by-step environment setup guide, see Getting Started.

# Build controller (frontend + Go binary)
./scripts/build-controller.sh

# Build node agent (BPF program + Go binary) — run on a Linux host
./scripts/build-node.sh

# Controller
cp controller/config.example.yaml controller/config.yaml
# Edit: set jwt_secret, external_api_key, and add nodes under the nodes: section

# Node agent
cp node/config.example.yaml node/config.yaml
# Edit: set interface name, node_api_key, sync_key

# Controller (no root required)
./scripts/controller.sh start

# Node agent (requires root — XDP needs CAP_NET_ADMIN)
sudo ./scripts/node.sh start

# Check status
./scripts/controller.sh status
sudo ./scripts/node.sh status

The Web UI is available at http://<controller-host>:8000 by default.

Both the controller and the node expose a versioned REST API at /api/v1/.

Node API requires X-API-Key header. Controller API key is optional (configurable).

MIT — see LICENSE.

BPF/C kernel programs (node/bpf/) are licensed under GPL-2.0 as required by the Linux kernel BPF subsystem.

_{Built entirely with Claude Code — including the XDP/BPF kernel program, Go concurrency, and Vue frontend.}