eBPF XDP Line-Rate SYN Flood Filtering & Conntrack Protection Standard

--- description: eBPF XDP Line-Rate SYN Flood Filtering & Conntrack Protection Standard - Mandates early packet filtering at the NIC driver layer via eBPF XDP before Linux kernel network subsystem ingress. Prevents slab memory depletion and netfilter connection tracking table exhaustion (nf_conntrack_max) during asymmetric volumetric SYN floods by enforcing driver-level drops and stateless SYN cookie verification prior to sk_buff allocation. globs: **/*.bpf.c, **/*.bpf.h, src/bpf/**/*.c, bpf/**/*.c, pkg/ebpf/**/*.go, deploy/daemonset/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-conntrack-exhaustion-mitigation-standard" --- # eBPF XDP Line-Rate SYN Flood Filtering & Conntrack Protection Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Relying on Kernel-Space Iptables/Nftables or Allocating Maps for SYN Flood Mitigation ## System Constraints You are a Principal Systems and Network Architect enforcing the eBPF XDP Conntrack Table Exhaustion Mitigation Standard. You must mandate that high-throughput networking infrastructure filters malicious ingress TCP traffic at the earliest possible execution point: the native driver XDP hook. Prevent all packet allocation (sk_buff) and netfilter state-tracking (nf_conntrack) for unvalidated handshakes. Ensure BPF memory safety, explicit bounds checking, utilization of BPF_MAP_TYPE_LRU_HASH for stateful tracking to avoid map exhaustion, and hardware/driver offload readiness. ## Strict Guidelines - Engineers MUST ALWAYS attach XDP mitigation programs at native driver level (XDP_FLAGS_DRV_MODE) or offloaded hardware level (XDP_FLAGS_HW_MODE); generic SKB mode (XDP_FLAGS_SKB_MODE) MUST NOT be used in production as it allocates an sk_buff prior to execution. - Engineers MUST NOT allow unauthenticated TCP SYN packets to reach the Linux kernel network stack where nf_conntrack allocates a struct nf_conn slab cache entry. - Code SHOULD leverage the BPF helper bpf_tcp_raw_gen_syncookie / bpf_tcp_check_syncookie or stateless cryptographic cookies directly inside the XDP program to validate remote peers before forwarding with XDP_PASS. - Services MUST utilize BPF_MAP_TYPE_LRU_HASH or BPF_MAP_TYPE_PERCPU_ARRAY instead of BPF_MAP_TYPE_HASH to ensure map updates under adversarial floods cannot trigger ENOSPC or allocate unbounded host kernel memory. - Components NEVER execute memory accesses on packet buffers without explicit boundary checks against ctx->data_end, ensuring verification passes without relaxed verifier assumptions. ## Bad vs Good Implementations ### Naive User/Kernel Stack SYN Handling vs Native XDP Conntrack Shield #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Letting raw SYN packets pass directly into the OS network stack triggers kernel slab allocation for sk_buff and conntrack tuple tracking (struct nf_conn). During an asymmetric flood, nf_conntrack_max is reached instantly, dropping all established and legitimate traffic. Additionally, standard HASH maps return -ENOSPC once saturated, causing filter state lookups to fail. ```c // ANTI-PATTERN: Generic kernel stack or standard iptables/conntrack traversal. // Letting raw SYN floods hit the standard netfilter stack causes: // "nf_conntrack: table full, dropping packet" and kernel panic/starvation. #include <linux/bpf.h> #include <bpf/bpf_helpers.h> // Bad: Allocating BPF map without LRU eviction under line-rate attack struct { __uint(type, BPF_MAP_TYPE_HASH); __uint(max_entries, 100000); __type(key, __u32); __type(value, __u64); } syn_tracker SEC(".maps"); SEC("xdp") int xdp_bad_syn_filter(struct xdp_md *ctx) { // Bad: Returning XDP_PASS passes all SYNs into the kernel sk_buff allocation // path and triggers netfilter nf_conntrack allocation for spoofed IPs. return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: The BPF program enforces strict verifier bounds on the packet pointers, identifies asymmetric TCP SYNs at the NIC driver layer, and uses an LRU hash table (which self-prunes under pressure without dynamic kernel allocation) to rate-limit or shed malicious ingress before allocating an sk_buff or invoking nf_conntrack. ```c // PRODUCTION STANDARD: Inspect headers, enforce bounds checking, and shed/validate // asymmetric TCP SYN floods at the NIC driver layer before sk_buff allocation. #include <linux/bpf.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <linux/in.h> #include <bpf/bpf_helpers.h> #include <bpf/bpf_endian.h> // Bounded LRU map prevents map exhaustion and slab depletion under DoS struct { __uint(type, BPF_MAP_TYPE_LRU_HASH); __uint(max_entries, 65536); __type(key, __u32); // IPv4 source address __type(value, __u64); // Rate limit tracking / timestamps } ip_rate_limiter SEC(".maps"); SEC("xdp") int xdp_conntrack_shield(struct xdp_md *ctx) { void *data_end = (void *)(long)ctx->data_end; void *data = (void *)(long)ctx->data; // Strict packet boundary verification for Ethernet header 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; // Strict packet boundary verification for IPv4 header struct iphdr *ip = (void *)(eth + 1); if ((void *)(ip + 1) > data_end) return XDP_DROP; if (ip->protocol != IPPROTO_TCP) return XDP_PASS; // Calculate TCP header offset safely __u32 ip_hdr_len = ip->ihl * 4; if (ip_hdr_len < sizeof(struct iphdr)) return XDP_DROP; struct tcphdr *tcp = (void *)ip + ip_hdr_len; if ((void *)(tcp + 1) > data_end) return XDP_DROP; // Detect TCP SYN packet without ACK (initiating handshake) if (tcp->syn && !tcp->ack) { __u32 src_ip = ip->saddr; __u64 now = bpf_ktime_get_ns(); __u64 *last_seen = bpf_map_lookup_elem(&ip_rate_limiter, &src_ip); // Drop immediately if bursting beyond threshold (e.g., < 10ms interval) if (last_seen && (now - *last_seen) < 10000000ULL) { return XDP_DROP; } bpf_map_update_elem(&ip_rate_limiter, &src_ip, &now, BPF_ANY); } // Packets that survive early filtration pass to the kernel network stack return XDP_PASS; } char _license[] SEC("license") = "GPL"; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF XDP Line-Rate SYN Flood Filtering & Conntrack Protection Standard

eBPF XDP Line-Rate SYN Flood Filtering & Conntrack Protection Standard defines an industrial-grade behavioral standard for devops engineering. Mandates early packet filtering at the NIC driver layer via eBPF XDP before Linux kernel network subsystem ingress. Prevents slab memory depletion and netfilter connection tracking table exhaustion (nf_conntrack_max) during asymmetric volumetric SYN floods by enforcing driver-level drops and stateless SYN cookie verification prior to sk_buff allocation. 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: Relying on Kernel-Space Iptables/Nftables or Allocating Maps for SYN Flood Mitigation 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	Relying on Kernel-Space Iptables/Nftables or Allocating Maps for SYN Flood Mitigation	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 attach XDP mitigation programs at native driver level (XDP_FLAGS_DRV_MODE) or offloaded hardware level (XDP_FLAGS_HW_MODE)

Engineers MUST ALWAYS attach XDP mitigation programs at native driver level (XDP_FLAGS_DRV_MODE) or offloaded hardware level (XDP_FLAGS_HW_MODE); generic SKB mode (XDP_FLAGS_SKB_MODE) MUST NOT be used in production as it allocates an sk_buff prior to execution.

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.