Deterministic Microsecond-Level Conntrack Eviction & Capacity Invariants for XDP

--- description: Deterministic Microsecond-Level Conntrack Eviction & Capacity Invariants for XDP - Guarantees deterministic microsecond-level map eviction and strict memory headroom for eBPF XDP connection tracking tables. Enforces inline bounded expiration, proactive watermark-triggered evictions, and SYN-proxy fallback mechanisms to eliminate packet drops under volumetric state-exhaustion DDoS attacks. globs: **/*.bpf.c, **/*.bpf.h, **/*.c, pkg/ebpf/**/*.go, src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-dynamic-conntrack-eviction-guardrail" --- # Deterministic Microsecond-Level Conntrack Eviction & Capacity Invariants for XDP > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded Hash Map Saturation with Userspace-Dependent Eviction and Unchecked BPF Map Insert Failures ## System Constraints You are a Principal Systems Engineer and Kernel Security Architect enforcing deterministic eBPF XDP connection tracking (conntrack) memory invariants. Under volumetric DDoS attacks (e.g., SYN floods, UDP amplification), standard BPF maps face state exhaustion, lock contention, and allocation latency. You must enforce zero-allocation inline eviction, lockless watermark monitoring, bounded microsecond-level lookup/replacement, and fail-safe packet bypass/SYN-cookie offload before maps reach 100% capacity. ## Strict Guidelines - Engineers MUST ALWAYS implement bounded fast-path inline eviction or dynamic dual-table rotation directly in XDP rather than relying on userspace garbage collection. - Engineers MUST NOT use unconstrained BPF_MAP_TYPE_HASH for conntrack without atomic capacity tracking, pre-allocated memory pools (BPF_F_NO_PREALLOC omitted), or bounded eviction fallbacks. - Code MUST inspect the return value of map lookups and updates, explicitly implementing a SYN-cookie verification or XDP_PASS degradation path when map capacity exceeds the critical high-watermark threshold (e.g., 90%). - Services MUST monitor conntrack map occupancy via per-CPU atomic counters or BPF ring buffers, preventing synchronous userspace map traversals during traffic spikes. - Components NEVER drop legitimate in-flight connections when tables fill; stale connections (FIN/RST state, or inactive TCP handshake timers) MUST be evicted deterministically using constant-time (O(1)) sampling. ## Bad vs Good Implementations ### Naive Map Insertion vs. Bounded Watermark Eviction with SYN-Cookie Offload #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an attacker generates random 5-tuple SYN floods, the static hash map rapidly exhausts all entries. `bpf_map_update_elem` fails, returning -EEXIST or -ENOMEM. The code blindly returns `XDP_DROP`, which takes down legitimate service traffic and leaves cleanup to high-latency userspace sweeps. ```c // BAD: Naive static hash map insertion under XDP fast path // Fails abruptly when table is full, causing indiscriminate packet drops under SYN flood struct { __uint(type, BPF_MAP_TYPE_HASH); __uint(max_entries, 1048576); __type(key, struct ct_key); __type(value, struct ct_entry); } ct_table SEC(".maps"); SEC("xdp") int xdp_conntrack(struct xdp_md *ctx) { struct ct_key key = {}; struct ct_entry entry = {}; // ... packet parsing populates key and entry ... struct ct_entry *existing = bpf_map_lookup_elem(&ct_table, &key); if (!existing) { // Unbounded insertion: when table is full (-EEXIST / -ENOMEM), // packet is blindly dropped, causing full DoS for legitimate traffic. long err = bpf_map_update_elem(&ct_table, &key, &entry, BPF_NOEXIST); if (err) { return XDP_DROP; } } return XDP_PASS; } ``` #### Production Standard (Correct) > **Standard**: Employs `BPF_MAP_TYPE_LRU_HASH` to guarantee constant-time node eviction without lock contention or allocation stall. Actively monitors table pressure using a per-CPU counter; when occupancy exceeds the high watermark (90%), it drops into stateless SYN-cookie verification instead of filling the conntrack table, effectively defeating state-exhaustion DDoS attacks. ```c // GOOD: Dynamic capacity reservation, bounded inline stale-entry eviction, and SYN-cookie fallback #define MAX_ENTRIES 1048576 #define WATERMARK_HIGH (MAX_ENTRIES * 9 / 10) // 90% capacity struct { __uint(type, BPF_MAP_TYPE_LRU_HASH); __uint(max_entries, MAX_ENTRIES); __type(key, struct ct_key); __type(value, struct ct_entry); } ct_table SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __uint(max_entries, 1); __type(key, __u32); __type(value, __u64); } ct_counter SEC(".maps"); SEC("xdp") int xdp_conntrack(struct xdp_md *ctx) { struct ct_key key = {}; struct ct_entry entry = {}; __u32 ckey = 0; // ... parse packet header, extract TCP flags, compute key ... struct ct_entry *existing = bpf_map_lookup_elem(&ct_table, &key); if (existing) { existing->last_seen = bpf_ktime_get_ns(); return XDP_PASS; } __u64 *count = bpf_map_lookup_elem(&ct_counter, &ckey); // If conntrack is pressurized (>90%), defer state creation and engage stateless SYN cookies if (count && *count > WATERMARK_HIGH) { if (is_tcp_syn(ctx)) { return generate_and_send_syn_cookie(ctx); } } entry.last_seen = bpf_ktime_get_ns(); entry.state = CT_STATE_SYN_SENT; // LRU map guarantees non-blocking bounded eviction without map allocation freeze bpf_map_update_elem(&ct_table, &key, &entry, BPF_ANY); if (count) { __sync_fetch_and_add(count, 1); } return XDP_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Microsecond-Level Conntrack Eviction & Capacity Invariants for XDP

Deterministic Microsecond-Level Conntrack Eviction & Capacity Invariants for XDP defines an industrial-grade behavioral standard for devops engineering. Guarantees deterministic microsecond-level map eviction and strict memory headroom for eBPF XDP connection tracking tables. Enforces inline bounded expiration, proactive watermark-triggered evictions, and SYN-proxy fallback mechanisms to eliminate packet drops under volumetric state-exhaustion DDoS 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: Unbounded Hash Map Saturation with Userspace-Dependent Eviction and Unchecked BPF Map Insert Failures 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	Unbounded Hash Map Saturation with Userspace-Dependent Eviction and Unchecked BPF Map Insert Failures	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 implement bounded fast-path inline eviction or dynamic dual-table rotation directly in XDP rather than relying on userspace garbage collection.

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.