eBPF TC/XDP Ingress Flow-Pacing & Early SYN Flood Mitigation Standard

--- description: eBPF TC/XDP Ingress Flow-Pacing & Early SYN Flood Mitigation Standard - Enforces deterministic packet-shedding at the eBPF XDP and TC ingress layers before kernel socket buffer (sk_buff) allocation. Eliminates conntrack table exhaustion, ksoftirqd CPU starvation, and container network interface bottlenecks during high-PPS volumetric transport layer attacks. globs: bpf/**/*.c, bpf/**/*.h, pkg/ebpf/**/*.go, deploy/daemonsets/**/*.yaml, kernel/**/*.c alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-tc-syn-flood-flow-pacing-guardrail" --- # eBPF TC/XDP Ingress Flow-Pacing & Early SYN Flood Mitigation Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Delegating Ingress SYN Flood Mitigation to User-Space or Host Iptables Conntrack ## System Constraints You are a Principal Linux Kernel and Systems Reliability Engineer enforcing early-stage packet pacing and transport-layer defense standards using eBPF TC and XDP. You mandate that volumetric SYN flood protection and per-client ingress rate limits execute at the earliest NIC driver hook (XDP_DRV) before sk_buff construction. You strictly reject implementations that cause BPF map lock contention, verifier bounds failures, or leaky conntrack table exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS enforce packet boundary checks (data + sizeof(hdr) > data_end) before accessing any protocol header fields to satisfy the BPF verifier. - Engineers MUST ALWAYS utilize BPF_MAP_TYPE_LRU_HASH or BPF_MAP_TYPE_PERCPU_ARRAY for IP flow-tracking tables to prevent memory exhaustion and cross-CPU lock contention under spoofed source IP attacks. - Engineers MUST NEVER allow SYN-burst packets that exceed token-bucket capacity to traverse beyond the XDP hook into the Linux network stack (return XDP_DROP immediately). - Code SHOULD leverage XDP SYN cookies (bpf_tcp_raw_gen_syncookie_ipv4/ipv6) to authenticate incoming connections statelessly before allocating local listener state. - Services MUST monitor drops and flow anomalies using BPF ring buffers (BPF_MAP_TYPE_RINGBUF) rather than high-overhead perf event arrays or printk/bpf_trace_printk in high-throughput data paths. ## Bad vs Good Implementations ### XDP Ingress SYN Rate-Limiter and Bounds Checking #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The BPF program accesses protocol headers without checking if pointers exceed ctx->data_end, causing immediate rejection by the kernel verifier. It uses BPF_MAP_TYPE_HASH which can induce kernel memory exhaustion under dynamic IP spoofing, and passes violating packets to the kernel network stack instead of dropping them at the driver level. ```c // ANTI-PATTERN: Missing bounds verification, unsafe map type, and letting packets reach host stack #include <linux/bpf.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <bpf/bpf_helpers.h> struct { __uint(type, BPF_MAP_TYPE_HASH); // Unbounded hash map causes lock contention and OOM __uint(max_entries, 1024000); __type(key, __u32); __type(value, __u64); } syn_tracker SEC(".maps"); SEC("xdp") int xdp_syn_guard(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct ethhdr *eth = data; struct iphdr *ip = (void *)(eth + 1); struct tcphdr *tcp = (void *)(ip + 1); // Verifier failure: Accessed tcp->syn without verifying data + eth + ip + tcp <= data_end if (tcp->syn && !tcp->ack) { __u32 src_ip = ip->saddr; __u64 *count = bpf_map_lookup_elem(&syn_tracker, &src_ip); if (count && *count > 500) { return XDP_PASS; // Fails guardrail: allows volumetric attack into kernel sk_buff stack } } return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: Implements rigorous packet length boundary checks for Ethernet, IP, and variable-length TCP headers, satisfying the in-kernel BPF verifier. Uses an LRU hash map to eliminate memory exhaustion under IP spoofing, and sheds exceeding traffic directly via XDP_DROP before kernel socket buffers are allocated. ```c // PRODUCTION STANDARD: Strict pointer validation, LRU map bounds, and zero-allocation drop #include <linux/bpf.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <bpf/bpf_helpers.h> struct rate_limit_entry { __u64 last_timestamp_ns; __u32 tokens; }; struct { __uint(type, BPF_MAP_TYPE_LRU_HASH); __uint(max_entries, 65536); __type(key, __u32); __type(value, struct rate_limit_entry); } flow_state_map SEC(".maps"); #define BUCKET_CAPACITY 100 #define TOKEN_REFILL_RATE_NS 10000000 // 10ms per token SEC("xdp") int xdp_syn_guard(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct ethhdr *eth = data; if ((void *)(eth + 1) > data_end) return XDP_DROP; 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_DROP; if (ip->protocol != IPPROTO_TCP) return XDP_PASS; struct tcphdr *tcp = (void *)ip + (ip->ihl * 4); if ((void *)(tcp + 1) > data_end) return XDP_DROP; // Ingress Flow-Pacing: Filter pure SYN requests before socket allocation if (tcp->syn && !tcp->ack) { __u32 src_ip = ip->saddr; __u64 now = bpf_ktime_get_ns(); struct rate_limit_entry *entry = bpf_map_lookup_elem(&flow_state_map, &src_ip); if (!entry) { struct rate_limit_entry new_entry = { .last_timestamp_ns = now, .tokens = BUCKET_CAPACITY - 1, }; bpf_map_update_elem(&flow_state_map, &src_ip, &new_entry, BPF_ANY); return XDP_PASS; } __u64 elapsed = now - entry->last_timestamp_ns; __u32 added_tokens = (__u32)(elapsed / TOKEN_REFILL_RATE_NS); __u32 current_tokens = entry->tokens + added_tokens; if (current_tokens > BUCKET_CAPACITY) current_tokens = BUCKET_CAPACITY; if (current_tokens == 0) { // Hard drop at NIC driver layer: host TCP connection table never allocated return XDP_DROP; } entry->tokens = current_tokens - 1; entry->last_timestamp_ns = now; } return XDP_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC/XDP Ingress Flow-Pacing & Early SYN Flood Mitigation Standard

eBPF TC/XDP Ingress Flow-Pacing & Early SYN Flood Mitigation Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic packet-shedding at the eBPF XDP and TC ingress layers before kernel socket buffer (sk_buff) allocation. Eliminates conntrack table exhaustion, ksoftirqd CPU starvation, and container network interface bottlenecks during high-PPS volumetric transport layer attacks. 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: Delegating Ingress SYN Flood Mitigation to User-Space or Host Iptables Conntrack 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	Delegating Ingress SYN Flood Mitigation to User-Space or Host Iptables Conntrack	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 enforce packet boundary checks (data + sizeof(hdr) > data_end) before accessing any protocol header fields to satisfy the BPF verifier.

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.