eBPF XDP Line-Rate Stateful DDoS Quarantine and Pre-SKB Shedding

--- description: eBPF XDP Line-Rate Stateful DDoS Quarantine and Pre-SKB Shedding - Enforces pre-allocation packet filtering directly in the network driver RX ring buffer via eBPF XDP (eXpress Data Path). Eliminates Linux kernel socket buffer (sk_buff) allocation overhead and ksoftirqd CPU starvation under high-throughput Layer-4 amplification floods by tracking state inside LRU per-CPU maps and shedding malicious flows with XDP_DROP before kernel stack ingress. globs: bpf/**/*.c, src/bpf/**/*.c, **/*.bpf.c, **/*.bpf.h alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-stateful-ddos-quarantine-pipe" --- # eBPF XDP Line-Rate Stateful DDoS Quarantine and Pre-SKB Shedding > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Deferring Volumetric Mitigation to Netfilter or Using Unbounded BPF Maps In Ingress Pipeline ## System Constraints You are a Principal Systems & Kernel Security Engineer enforcing eBPF XDP Line-Rate Stateful DDoS Quarantine rules. Mandate early packet filtering before kernel sk_buff allocation, strict verifier-compliant pointer bounds checks, and lockless per-CPU memory structures. ## Strict Guidelines - Engineers MUST ALWAYS execute volumetric packet dropping within native driver-mode XDP (XDP_DRV) before memory allocation for struct sk_buff occurs. - Engineers MUST verify packet boundaries (data + offset > data_end) before dereferencing any byte in Ethernet, IPv4, IPv6, UDP, or TCP headers to satisfy the BPF verifier. - Engineers MUST NOT use BPF_MAP_TYPE_HASH with standard spinlocks on line-rate hot paths; per-CPU hash maps (BPF_MAP_TYPE_PERCPU_HASH) or LRU maps (BPF_MAP_TYPE_LRU_HASH) MUST be utilized to prevent inter-core cache line bouncing. - Code MUST strictly validate L4 header length fields against total IP payload sizes to prevent malformed fragmentation bypasses. - Services MUST implement sliding-window rate limiters using hardware timestamping or bpf_ktime_get_ns() directly within the quarantine map entry. - Components NEVER fall back to XDP_PASS when a flow exceeds stateful burst thresholds; packets meeting quarantine criteria MUST yield XDP_DROP. ## Bad vs Good Implementations ### eBPF XDP Stateful UDP Amplification Quarantine Filter #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code fails to validate packet boundaries against data_end before dereferencing headers, which violates the BPF verifier guarantees. It uses a non-concurrency-safe global Hash map causing cacheline bouncing across cores, and passes unverified traffic to the OS network stack, exhausting kernel memory buffers under multi-gigabit reflection floods. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/udp.h> // ANTI-PATTERN: Generic global hash map creates lock contention; // Incomplete bounds checks trigger verifier faults or kernel panic; // Returns XDP_PASS on unhandled conditions, flooding kernel sk_buff allocations. struct { __uint(type, BPF_MAP_TYPE_HASH); __uint(max_entries, 100000); __type(key, __u32); __type(value, __u64); } tracking_map SEC(".maps"); SEC("xdp") int ddos_filter(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct ethhdr *eth = data; // Missing bounds check for ethhdr struct iphdr *ip = (void *)(eth + 1); // Missing bounds check for iphdr if (ip->protocol == IPPROTO_UDP) { struct udphdr *udp = (void *)(ip + 1); __u32 src_ip = ip->saddr; __u64 *hits = bpf_map_lookup_elem(&tracking_map, &src_ip); if (hits) { *hits += 1; // Thread safety hazard across CPUs if (*hits > 10000) return XDP_DROP; } } return XDP_PASS; } char _license[] SEC("license") = "GPL"; ``` #### Production Standard (Correct) > **Standard**: Adheres to all kernel verifier safety bounds, calculates IP header variable length dynamically, uses a lockless BPF_MAP_TYPE_LRU_PERCPU_HASH to eradicate core contention, and drops volumetric floods via XDP_DROP before packet allocation in the Linux socket buffer layer. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include <bpf/bpf_endian.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/udp.h> #define RATE_LIMIT_NS 1000000000ULL // 1 second window #define MAX_PPS_THRESHOLD 50000 struct rate_state { __u64 last_seen; __u64 packet_count; }; struct { __uint(type, BPF_MAP_TYPE_LRU_PERCPU_HASH); __uint(max_entries, 262144); __type(key, __u32); __type(value, struct rate_state); } quarantine_map SEC(".maps"); SEC("xdp") int xdp_quarantine_pipe(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; // Invariant 1: Rigorous Ethernet boundary check struct ethhdr *eth = data; if ((void *)(eth + 1) > data_end) return XDP_DROP; if (eth->h_proto != bpf_htons(ETH_P_IP)) return XDP_PASS; // Invariant 2: Rigorous IPv4 boundary check struct iphdr *ip = (void *)(eth + 1); if ((void *)(ip + 1) > data_end) return XDP_DROP; // Prevent variable IHL overflow bounds violation if (ip->ihl < 5) return XDP_DROP; if ((void *)ip + (ip->ihl * 4) > data_end) return XDP_DROP; // Focus on L4 Amplification vectors (e.g., DNS, NTP, CLDAP over UDP) if (ip->protocol == IPPROTO_UDP) { struct udphdr *udp = (void *)ip + (ip->ihl * 4); if ((void *)(udp + 1) > data_end) return XDP_DROP; __u32 src_ip = ip->saddr; __u64 now = bpf_ktime_get_ns(); struct rate_state *state = bpf_map_lookup_elem(&quarantine_map, &src_ip); if (state) { if (now - state->last_seen < RATE_LIMIT_NS) { state->packet_count++; if (state->packet_count > MAX_PPS_THRESHOLD) { return XDP_DROP; // Shed directly in NIC ring buffer } } else { state->last_seen = now; state->packet_count = 1; } } else { struct rate_state new_state = { .last_seen = now, .packet_count = 1 }; bpf_map_update_elem(&quarantine_map, &src_ip, &new_state, BPF_NOEXIST); } } return XDP_PASS; } char _license[] SEC("license") = "Dual BSD/GPL"; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF XDP Line-Rate Stateful DDoS Quarantine and Pre-SKB Shedding

eBPF XDP Line-Rate Stateful DDoS Quarantine and Pre-SKB Shedding defines an industrial-grade behavioral standard for security engineering. Enforces pre-allocation packet filtering directly in the network driver RX ring buffer via eBPF XDP (eXpress Data Path). Eliminates Linux kernel socket buffer (sk_buff) allocation overhead and ksoftirqd CPU starvation under high-throughput Layer-4 amplification floods by tracking state inside LRU per-CPU maps and shedding malicious flows with XDP_DROP before kernel stack ingress. 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: Deferring Volumetric Mitigation to Netfilter or Using Unbounded BPF Maps In Ingress Pipeline 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	Deferring Volumetric Mitigation to Netfilter or Using Unbounded BPF Maps In Ingress Pipeline	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 execute volumetric packet dropping within native driver-mode XDP (XDP_DRV) before memory allocation for struct sk_buff occurs.

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.