eBPF XDP Driver-Level TCP SYN-Cookie Verification & Offload Standard

--- description: eBPF XDP Driver-Level TCP SYN-Cookie Verification & Offload Standard - Mandates that edge gateways and edge proxy infrastructure validate and generate cryptographically signed TCP SYN cookies directly at the NIC ingress driver level via eBPF XDP hooks. Prevents kernel socket queue exhaustion, conntrack table saturation, and sk_buff allocation overhead during volumetric TCP SYN flood attacks. Guarantees zero TCP state allocation until the full three-way handshake is verified. globs: **/*.bpf.c, **/*.bpf.h, ebpf/**/*.c, pkg/xdp/**/*.go, src/ebpf/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-l4-syncookie-offload-standard" --- # eBPF XDP Driver-Level TCP SYN-Cookie Verification & Offload Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: SKB Allocation Pass-Through and In-Kernel Connection Backlog Saturation Under L4 SYN Floods ## System Constraints You are a Principal Linux Systems & Network Security Architect enforcing the eBPF XDP Layer-4 SYN-Cookie Offload Standard. Mandate that all incoming TCP SYN and ACK packets targeting protected services are validated or challenged within the native driver eBPF hook (XDP_DRV) before sk_buff allocation. Ensure memory safety via strict verifier boundary checks, enforce kernel-native helper consumption (`bpf_tcp_raw_gen_syncookie_ipv4` and `bpf_tcp_raw_check_syncookie_ipv4`), reject non-standard custom hashing, and enforce strictly stateless operation until cryptographic cookie verification succeeds. ## Strict Guidelines - Engineers MUST ALWAYS verify packet bounds (`(void *)(header + 1) > data_end`) before dereferencing Ethernet, IPv4/IPv6, or TCP headers to satisfy the BPF verifier. - Engineers MUST NEVER fallback to generic SKB-mode XDP (`XDP_GENERIC`) in production environments; programs MUST attach using native driver mode (`XDP_DRV`) or hardware offload (`XDP_HW`). - Code MUST use kernel-provided BPF helpers `bpf_tcp_raw_gen_syncookie_ipv4` / `bpf_tcp_raw_check_syncookie_ipv4` (or IPv6 equivalents) rather than rolling custom non-standard hash algorithms. - Services MUST return `XDP_TX` for reverse SYN-ACK reflections directly out of the incoming NIC, completely bypassing the Linux IP/TCP networking stack during flood conditions. - Components NEVER store connection state in BPF maps upon receiving a SYN packet; state MUST remain strictly stateless via cryptographic timestamp/cookie embedding until the completing ACK packet passes verification. ## Bad vs Good Implementations ### eBPF XDP Native SYN-Cookie Ingress Validation vs. Stateful Pass-Through #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Allocates state per SYN packet inside a bounded BPF hash map, which gets exhausted during volumetric DDoS. Passing the packet via XDP_PASS forces the kernel to allocate an sk_buff and consume socket backlog memory, causing kernel memory starvation and dropping legitimate connections. ```c // ANTI-PATTERN: Tracking incoming SYNs in stateful BPF maps or passing directly to host network 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); __uint(max_entries, 1048576); __type(key, __u32); // client IP __type(value, __u64); // timestamp } syn_state_map SEC(".maps"); SEC("xdp") int xdp_syn_filter(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); // Vulnerable: Insufficient bounds checks trigger verifier rejection or unsafe access if ((void *)(tcp + 1) > data_end) return XDP_PASS; if (tcp->syn && !tcp->ack) { __u32 src_ip = ip->saddr; __u64 ts = bpf_ktime_get_ns(); // Flaw: Map exhaustion under SYN flood triggers DoS before kernel processing bpf_map_update_elem(&syn_state_map, &src_ip, &ts, BPF_ANY); // Flaw: Allocates sk_buff and pushes to host socket queue under volumetric attack return XDP_PASS; } return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: Validates packet boundaries exhaustively to guarantee memory safety. For TCP SYN packets, it computes a cryptographic cookie statelessly using the in-kernel helper `bpf_tcp_raw_gen_syncookie_ipv4`, swaps L2/L3 addresses, and emits a SYN-ACK directly from the NIC via `XDP_TX`. For TCP ACKs, it validates the cookie using `bpf_tcp_raw_check_syncookie_ipv4`, dropping spoofed traffic with `XDP_DROP` and only passing valid handshakes via `XDP_PASS`. ```c // PRODUCTION STANDARD: Driver-Level Stateless SYN-Cookie Offload via Linux BPF Helpers #include <linux/bpf.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <bpf/bpf_helpers.h> #include <bpf/bpf_endian.h> static __always_inline void swap_mac_and_ip(struct ethhdr *eth, struct iphdr *ip) { __u8 tmp_mac[ETH_ALEN]; __builtin_memcpy(tmp_mac, eth->h_source, ETH_ALEN); __builtin_memcpy(eth->h_source, eth->h_dest, ETH_ALEN); __builtin_memcpy(eth->h_dest, tmp_mac, ETH_ALEN); __be32 tmp_ip = ip->saddr; ip->saddr = ip->daddr; ip->daddr = tmp_ip; } SEC("xdp") int xdp_syn_cookie_ingress(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 != bpf_htons(ETH_P_IP)) return XDP_PASS; struct iphdr *ip = (void *)(eth + 1); if ((void *)(ip + 1) > data_end || ip->protocol != IPPROTO_TCP) return XDP_PASS; struct tcphdr *tcp = (void *)((void *)ip + (ip->ihl * 4)); if ((void *)(tcp + 1) > data_end) return XDP_DROP; // Handle SYN packets: Generate cryptographic cookie and reflect SYN-ACK without host stack allocation if (tcp->syn && !tcp->ack) { __s64 cookie = bpf_tcp_raw_gen_syncookie_ipv4(ip, tcp, sizeof(struct tcphdr)); if (cookie < 0) return XDP_DROP; swap_mac_and_ip(eth, ip); tcp->ack_seq = bpf_htonl(bpf_ntohl(tcp->seq) + 1); tcp->seq = bpf_htonl((__u32)cookie); tcp->ack = 1; tcp->syn = 1; return XDP_TX; // Reflect immediately via the NIC driver } // Handle final ACK packets: Verify cookie validity before pushing to host TCP stack if (tcp->ack && !tcp->syn) { __s32 ret = bpf_tcp_raw_check_syncookie_ipv4(ip, tcp); if (ret == 0) { // Verified: Legitimate 3-way handshake completion, pass to kernel socket table return XDP_PASS; } // Spoofed/Invalid ACK under attack return XDP_DROP; } return XDP_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF XDP Driver-Level TCP SYN-Cookie Verification & Offload Standard

eBPF XDP Driver-Level TCP SYN-Cookie Verification & Offload Standard defines an industrial-grade behavioral standard for devops engineering. Mandates that edge gateways and edge proxy infrastructure validate and generate cryptographically signed TCP SYN cookies directly at the NIC ingress driver level via eBPF XDP hooks. Prevents kernel socket queue exhaustion, conntrack table saturation, and sk_buff allocation overhead during volumetric TCP SYN flood attacks. Guarantees zero TCP state allocation until the full three-way handshake is verified. 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: SKB Allocation Pass-Through and In-Kernel Connection Backlog Saturation Under L4 SYN Floods 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	SKB Allocation Pass-Through and In-Kernel Connection Backlog Saturation Under L4 SYN Floods	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 verify packet bounds (`(void *)(header + 1) > data_end`) before dereferencing Ethernet, IPv4/IPv6, or TCP headers 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.