Driver-Level XDP SYN Flood Mitigation and Lockless Ring Buffer Telemetry

--- description: Driver-Level XDP SYN Flood Mitigation and Lockless Ring Buffer Telemetry - Mandates dropping malicious volumetric L4 SYN floods at the native NIC driver layer via eBPF XDP before kernel sk_buff and socket allocation occur. Enforces memory-safe packet parsing with strict verifier bounds checks and zero-copy metric streaming via BPF_MAP_TYPE_RINGBUF to eliminate context switches and userspace polling overhead. globs: **/*.bpf.c, **/*.bpf.h, **/*.c, **/*.h, src/ebpf/**/*.{c,go,rs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-syn-flood-ringbuf-mitigation" --- # Driver-Level XDP SYN Flood Mitigation and Lockless Ring Buffer Telemetry > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Processing High-PPS SYN Floods in Socket Layer and Using Blocking or Deprecated BPF Telemetry ## System Constraints You are a Principal Systems Architect specializing in Linux kernel networking and eBPF. Enforce strict standards for XDP-based volumetric DDoS mitigation. Prohibit any design that permits unauthenticated TCP SYN packets into the host networking stack (sk_buff creation). Mandate exact bounds checking for the BPF verifier and require lockless, zero-copy telemetry streaming via BPF_MAP_TYPE_RINGBUF with mandatory NULL checks on reservation. ## Strict Guidelines - Engineers MUST ALWAYS evaluate TCP SYN packet authenticity at the XDP layer (native driver mode or offloaded mode) and return XDP_DROP immediately for invalid or rate-exceeded flows before any net_device allocates an sk_buff. - Engineers MUST ALWAYS perform explicit packet bounds checking against (void *)(long)ctx->data_end for every protocol header layer (Ethernet, IPv4/IPv6, TCP) before dereferencing fields to satisfy the BPF verifier. - Engineers MUST use BPF_MAP_TYPE_RINGBUF instead of legacy BPF_MAP_TYPE_PERF_EVENT_ARRAY to prevent per-CPU buffer fragmentation, reduce memory footprint, and allow lockless multi-producer submissions. - Engineers MUST ALWAYS check the return pointer of bpf_ringbuf_reserve() for NULL before writing telemetry payloads, and MUST finalize reservations with either bpf_ringbuf_submit() or bpf_ringbuf_discard(). - Engineers MUST NOT invoke heavy helpers or unmetered ring buffer events per dropped packet during multi-million PPS line-rate attacks; mitigation telemetry MUST implement token-bucket or sampling mechanisms directly in eBPF to prevent ring buffer exhaustion. - Components NEVER fall back to tc (traffic control) or iptables/nftables conntrack for volumetric L4 SYN mitigation, as connection tracking table allocations incur catastrophic CPU cache thrashing during floods. ## Bad vs Good Implementations ### Line-Rate SYN Flood Drop with Safe BPF Ring Buffer Telemetry #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing packet pointers without validating against ctx->data_end will be rejected by the BPF verifier. Returning XDP_PASS forwards the packet to Linux TCP stack, which allocates an sk_buff and exhausts memory. Calling bpf_printk on high-rate traffic causes kernel log locking and drops line rate. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> // Anti-pattern: No bounds verification against data_end, passes to netfilter, // and uses slow printk or unchecked tracing on every packet. SEC("xdp") int xdp_syn_mitigate(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; struct ethhdr *eth = data; struct iphdr *ip = (void *)(eth + 1); struct tcphdr *tcp = (void *)(ip + 1); // Verifier failure / crash: dereferencing unchecked pointers if (ip->protocol == IPPROTO_TCP && tcp->syn && !tcp->ack) { bpf_printk("SYN packet detected from %x\n", ip->saddr); // High overhead context switch // Passing packet to standard networking stack; sk_buff will be allocated! return XDP_PASS; } return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: Implements strict bounds checking on Ethernet, IP, and variable-length TCP headers satisfying the BPF verifier. Drops malicious SYN floods at the driver hook with XDP_DROP, completely bypassing sk_buff and socket layer allocation. Telemetry is streamed without locking via BPF_MAP_TYPE_RINGBUF with a mandatory NULL check. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> struct drop_event { __be32 src_ip; __be32 dst_ip; __be16 src_port; __be16 dst_port; __u32 action; }; struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 1 << 24); // 16MB ring buffer } telemetry_ringbuf SEC(".maps"); SEC("xdp") int xdp_syn_mitigate(struct xdp_md *ctx) { void *data_end = (void *)(long)ctx->data_end; void *data = (void *)(long)ctx->data; struct ethhdr *eth = data; if ((void *)(eth + 1) > data_end) return XDP_PASS; if (eth->h_proto != __builtin_bswap16(ETH_P_IP)) return XDP_PASS; struct iphdr *ip = (void *)(eth + 1); if ((void *)(ip + 1) > data_end) return XDP_PASS; if (ip->protocol != IPPROTO_TCP) return XDP_PASS; struct tcphdr *tcp = (void *)((__u32 *)ip + ip->ihl); if ((void *)(tcp + 1) > data_end) return XDP_PASS; // Detect pure SYN packet and mitigate volumetric flood at driver hook if (tcp->syn && !tcp->ack) { // Zero-copy event reservation on the BPF ring buffer struct drop_event *evt = bpf_ringbuf_reserve(&telemetry_ringbuf, sizeof(*evt), 0); if (evt) { evt->src_ip = ip->saddr; evt->dst_ip = ip->daddr; evt->src_port = tcp->source; evt->dst_port = tcp->dest; evt->action = XDP_DROP; bpf_ringbuf_submit(evt, 0); } return XDP_DROP; // Drop packet immediately; zero sk_buff or socket allocation } return XDP_PASS; } char _license[] SEC("license") = "GPL"; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Driver-Level XDP SYN Flood Mitigation and Lockless Ring Buffer Telemetry

Driver-Level XDP SYN Flood Mitigation and Lockless Ring Buffer Telemetry defines an industrial-grade behavioral standard for devops engineering. Mandates dropping malicious volumetric L4 SYN floods at the native NIC driver layer via eBPF XDP before kernel sk_buff and socket allocation occur. Enforces memory-safe packet parsing with strict verifier bounds checks and zero-copy metric streaming via BPF_MAP_TYPE_RINGBUF to eliminate context switches and userspace polling overhead. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Processing High-PPS SYN Floods in Socket Layer and Using Blocking or Deprecated BPF Telemetry Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Processing High-PPS SYN Floods in Socket Layer and Using Blocking or Deprecated BPF Telemetry	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS evaluate TCP SYN packet authenticity at the XDP layer (native driver mode or offloaded mode) and return XDP_DROP immediately for invalid or rate-exceeded flows before any net_device allocates an sk_buff.

Engineers MUST ALWAYS evaluate TCP SYN packet authenticity at the XDP layer (native driver mode or offloaded mode) and return XDP_DROP immediately for invalid or rate-exceeded flows before any net_device allocates an sk_buff.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.