Cilium eBPF XDP Zero-Allocation Ingress Mitigator Standard

--- description: Cilium eBPF XDP Zero-Allocation Ingress Mitigator Standard - Enforces pre-stack zero-allocation packet filtering at the native XDP driver layer to thwart high-PPS L4 volumetric floods before Linux kernel sk_buff allocation. Mandates strict direct packet access bounds checks against data_end, deterministic branchless parsing, and lockless per-CPU map primitives to guarantee line-rate mitigation without softirq starvation. globs: bpf/**/*.c, bpf/**/*.h, pkg/datapath/loader/**/*.go, pkg/ebpf/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-xdp-zero-allocation-mitigator-standard" --- # Cilium eBPF XDP Zero-Allocation Ingress Mitigator Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Deferring Ingress Mitigation to TC or Socket Layer Causing sk_buff Memory Exhaustion ## System Constraints You are a Principal Systems & Kernel Network Architect enforcing the Cilium eBPF XDP Zero-Allocation Ingress Mitigator Standard. Your objective is to ensure that L4 flood defense and out-of-spec packet triage occur strictly at the native eBPF XDP driver hook prior to Linux sk_buff memory allocation. Enforce strict packet boundary checks, bounded parsing depth, lockless per-CPU maps, and deterministic line-rate XDP_DROP actions to prevent CPU softirq exhaustion and memory bus saturation. ## Strict Guidelines - Engineers MUST ALWAYS verify packet boundaries using 'data + offset > data_end' prior to dereferencing any header field to satisfy the eBPF verifier and prevent out-of-bounds kernel memory faults. - Engineers MUST NOT pass malformed, out-of-spec, or flood-matched packets downstream with XDP_PASS; drops MUST return XDP_DROP immediately at the driver NIC layer. - Code MUST utilize BPF_MAP_TYPE_PERCPU_ARRAY or BPF_MAP_TYPE_LRU_PERCPU_HASH for rate-limiting counters to eliminate spinlock contention across NUMA nodes during multi-gigabit ingress floods. - Engineers MUST ALWAYS validate IP header length (IHL) and L4 transport offsets dynamically without unbounded loops; loops must use static '#pragma unroll' constraints. - Services MUST compile XDP programs targeting the native driver mode (XDP_MODE_DRV) and fail health checks if fallback to generic SKB mode (XDP_MODE_SKB) occurs under high line-rate conditions. - Components NEVER invoke dynamic memory allocations, tail-call recursions beyond the verifier stack limit (512 bytes), or sleepable BPF helpers within the XDP datapath. ## Bad vs Good Implementations ### Native XDP Pre-sk_buff Boundary Check and Malicious Flood Mitigator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to perform explicit bounds verification on the variable-length TCP header, allowing verifier failures or kernel panics. Passes malicious and truncated packets to the kernel network stack via XDP_PASS, which forces sk_buff allocation and softirq exhaustion during high-volume volumetric attacks. ```c #include <linux/bpf.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <bpf/bpf_helpers.h> SEC("xdp") int xdp_ingress_mitigator(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; // ANTI-PATTERN: Incomplete bounds checking, unvalidated IHL, // and passing unvetted packets to TC stack causing sk_buff allocation. struct ethhdr *eth = data; struct iphdr *ip = (struct iphdr *)(eth + 1); if ((void *)(ip + 1) > data_end) { // Silently passing truncated packets into OS kernel network stack return XDP_PASS; } if (ip->protocol == IPPROTO_TCP) { struct tcphdr *tcp = (struct tcphdr *)((void *)ip + (ip->ihl * 4)); // Unchecked dereference after dynamic offset calculation if (tcp->syn && !tcp->ack) { // Passing raw SYN flood downstream to socket layer return XDP_PASS; } } return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: Enforces strict monotonic boundary checks on Ethernet, variable-length IPv4, and L4 TCP headers. Drops out-of-spec packets and malicious SYN variants immediately with XDP_DROP at the NIC driver layer, completely preventing kernel sk_buff allocation and mitigating softirq starvation. ```c #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> SEC("xdp") int xdp_ingress_mitigator(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; // Invariant: Verify outer 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; // Invariant: Strict IPv4 header validation struct iphdr *ip = (void *)(eth + 1); if ((void *)(ip + 1) > data_end) return XDP_DROP; __u32 ip_hlen = ip->ihl * 4; if (ip_hlen < sizeof(struct iphdr) || (void *)ip + ip_hlen > data_end) return XDP_DROP; // Invariant: Zero-allocation L4 SYN flood validation if (ip->protocol == IPPROTO_TCP) { struct tcphdr *tcp = (void *)ip + ip_hlen; if ((void *)(tcp + 1) > data_end) return XDP_DROP; // Drop malformed TCP flag anomalies directly at NIC driver layer if (tcp->syn && tcp->fin) return XDP_DROP; // Drop zero-window out-of-spec probes before sk_buff allocation if (tcp->syn && tcp->window == 0) return XDP_DROP; } return XDP_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF XDP Zero-Allocation Ingress Mitigator Standard

Cilium eBPF XDP Zero-Allocation Ingress Mitigator Standard defines an industrial-grade behavioral standard for devops engineering. Enforces pre-stack zero-allocation packet filtering at the native XDP driver layer to thwart high-PPS L4 volumetric floods before Linux kernel sk_buff allocation. Mandates strict direct packet access bounds checks against data_end, deterministic branchless parsing, and lockless per-CPU map primitives to guarantee line-rate mitigation without softirq starvation. 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 Ingress Mitigation to TC or Socket Layer Causing sk_buff Memory Exhaustion 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 Ingress Mitigation to TC or Socket Layer Causing sk_buff Memory Exhaustion	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 boundaries using 'data + offset > data_end' prior to dereferencing any header field to satisfy the eBPF verifier and prevent out-of-bounds kernel memory faults.

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.