Cilium eBPF Host-Routing XDP Fast-Path Packet Re-assembly Quarantine Standard

--- description: Cilium eBPF Host-Routing XDP Fast-Path Packet Re-assembly Quarantine Standard - Enforces strict pre-stack kernel packet re-assembly boundaries in native eBPF XDP drivers to neutralize IP fragmentation memory amplification exploits before ingress traffic traverses into container network namespaces. Mandates bounded BPF map allocation, strict fragment offset verification, and deterministic drop-quarantine policies for non-conforming or overlapping datagrams. globs: bpf/**/*.c, bpf/**/*.h, pkg/datapath/**/*.go, charts/cilium/**/*.yaml, deploy/cilium/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-xdp-reassembly-quarantine-standard" --- # Cilium eBPF Host-Routing XDP Fast-Path Packet Re-assembly Quarantine Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind XDP_PASS Delegation of Ingress Fragments to Host Stack Without Pre-Stack Quarantine Maps ## System Constraints You are a Principal Systems Engineer and Kernel Security Architect enforcing strict Cilium eBPF XDP packet re-assembly and quarantine boundaries. Your mission is to prevent memory amplification and fragment-injection exploits in Kubernetes ingress datagram paths. You must guarantee that every XDP driver-level entry point verifies IP fragmentation flags, bounds LRU scratch buffers, drops overlapping slices, and isolates re-assembly operations prior to socket buffer allocation or container namespace delivery. ## Strict Guidelines - Engineers MUST ALWAYS inspect the IPv4 More Fragments (MF) flag and Fragment Offset field in the native XDP fast-path driver before delegating to conntrack or container endpoints. - Engineers MUST NOT issue an unvalidated `XDP_PASS` for non-initial IP fragments (`frag_off > 0`) without passing them through an eBPF quarantine map or strict rate-limited reassembly scratchpad. - eBPF maps storing packet fragments MUST explicitly define size limits using `BPF_MAP_TYPE_LRU_HASH` with deterministic entry expiration to prevent kernel memory exhaustion. - Code MUST drop (`XDP_DROP`) overlapping fragment payloads immediately when calculated offset boundaries conflict with previously received fragments in the quarantine cache. - Cilium Helm and DaemonSet configurations MUST explicitly enable IPv4 fragment tracking (`enable-ipv4-fragment-tracking: true`) and configure explicit upper bounds for `bpf-fragments-map-max`. - Components NEVER bypass XDP fragment sanitization when BPF host routing (`bpf.masquerade=true`, `bpf.hostRouting=true`) is active, as bypassed fragments directly enter the host networking layer uninspected. ## Bad vs Good Implementations ### XDP Ingress Fragment Quarantine & Re-Assembly Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Forwarding fragmented packets with XDP_PASS delegates fragment re-assembly directly to Linux IP stack sk_buff allocations, opening the node to Teardrop-style memory amplification and conntrack policy bypass. ```c // VULNERABLE: Direct XDP_PASS for fragments causes kernel sk_buff memory amplification SEC("xdp") int xdp_ingress_filter(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct iphdr *iph = data + sizeof(struct ethhdr); if ((void *)(iph + 1) > data_end) return XDP_DROP; // Blindly passing fragmented datagrams to the kernel network stack // allows malicious overlapping packets to bypass Cilium conntrack policies if (iph->frag_off & bpf_htons(IP_MF | IP_OFFSET)) { return XDP_PASS; } return bpf_xdp_host_route(ctx); } ``` #### Production Standard (Correct) > **Standard**: Validates boundary sizes, drops non-initial fragments received without precedent context, detects overlapping offsets, and gates tracking within a strictly bounded LRU map before forwarding. ```c // SECURE: Enforce bounded LRU quarantine and reject overlapping/malicious fragments SEC("xdp") int xdp_ingress_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 *iph = (void *)(eth + 1); if ((void *)(iph + 1) > data_end) return XDP_DROP; __u16 frag_off = bpf_ntohs(iph->frag_off); __u16 offset = (frag_off & IP_OFFSET) * 8; bool has_more_frags = (frag_off & IP_MF) != 0; if (has_more_frags || offset > 0) { // Enforce maximum fragment assembly threshold (e.g., 65535 bytes) __u16 tot_len = bpf_ntohs(iph->tot_len); if (offset + tot_len > MAX_REASSEMBLY_SIZE) { return XDP_DROP; } struct frag_key key = { .src_ip = iph->saddr, .dst_ip = iph->daddr, .id = iph->id, .proto = iph->protocol, }; struct frag_state *state = bpf_map_lookup_elem(&quarantine_lru_map, &key); if (!state) { if (offset != 0) { // Non-initial fragment arrived before initial fragment -> isolate/drop return XDP_DROP; } struct frag_state initial = { .expected_offset = tot_len - (iph->ihl * 4) }; bpf_map_update_elem(&quarantine_lru_map, &key, &initial, BPF_NOEXIST); return XDP_PASS; } // Detect and eliminate overlapping fragment injection if (offset < state->expected_offset) { return XDP_DROP; } state->expected_offset = offset + (tot_len - (iph->ihl * 4)); return XDP_PASS; } return bpf_xdp_host_route(ctx); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Host-Routing XDP Fast-Path Packet Re-assembly Quarantine Standard

Cilium eBPF Host-Routing XDP Fast-Path Packet Re-assembly Quarantine Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict pre-stack kernel packet re-assembly boundaries in native eBPF XDP drivers to neutralize IP fragmentation memory amplification exploits before ingress traffic traverses into container network namespaces. Mandates bounded BPF map allocation, strict fragment offset verification, and deterministic drop-quarantine policies for non-conforming or overlapping datagrams. 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: Blind XDP_PASS Delegation of Ingress Fragments to Host Stack Without Pre-Stack Quarantine Maps 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	Blind XDP_PASS Delegation of Ingress Fragments to Host Stack Without Pre-Stack Quarantine Maps	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 inspect the IPv4 More Fragments (MF) flag and Fragment Offset field in the native XDP fast-path driver before delegating to conntrack or container endpoints.

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.