eBPF TC Socket-to-Socket Redirection Netfilter Conntrack State Synchronization

--- description: eBPF TC Socket-to-Socket Redirection Netfilter Conntrack State Synchronization - Enforces mandatory bidirectional Netfilter connection tracking (conntrack) synchronization whenever using eBPF TC (clsact) or sockops helpers for socket-to-socket fast-path redirection. Bypassing the host TCP/IP stack without atomically seeding and updating kernel conntrack tuples leads to catastrophic, silent packet drops via `INVALID` ctstate matches upon fallback, asymmetric routing, or connection termination. globs: bpf/**/*.c, bpf/**/*.h, pkg/ebpf/**/*.go, deploy/daemonsets/*.yaml, manifests/cilium/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tc-sockmesh-conntrack-sync-production-standard" --- # eBPF TC Socket-to-Socket Redirection Netfilter Conntrack State Synchronization > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Bypassing Host TCP Stack via BPF Sockmesh Without Bidirectional Conntrack State Seeding ## System Constraints You are a Principal Systems and Kernel Networking Engineer enforcing strict Netfilter conntrack synchronization invariants in eBPF socket-mesh and TC redirection architectures. Any BPF-level socket fast-path redirection (e.g., bpf_redirect_peer, bpf_sk_redirect_hash, or bpf_msg_redirect_hash) must unconditionally synchronize conntrack tuples in both directions or provide explicit deterministic fallback handlers that prevent ctstate INVALID packet drops. ## Strict Guidelines - Engineers MUST ALWAYS invoke Netfilter conntrack synchronization kfuncs (bpf_ct_alloc, bpf_ct_insert_entry, bpf_ct_set_status) or mirror state to Netfilter tables before executing bpf_sk_redirect_hash or bpf_redirect_peer. - Engineers MUST NOT bypass the host network stack without accounting for TCP FIN/RST lifecycle transitions, ensuring teardown packets clear conntrack state machine entries cleanly. - Programs SHOULD verify socket family, protocol, and connection state (TCP_ESTABLISHED) prior to injecting packets into sockmap redirection maps. - Services MUST configure fallback iptables/nftables rules with explicit telemetry logging whenever un-tracked packets exit TC bypass paths rather than defaulting to silent drops. - eBPF hook implementations NEVER rely on implicit kernel conntrack population when skb bypasses IP layer traversal via veth peer redirection. ## Bad vs Good Implementations ### TC Ingress Redirection Conntrack Sync Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly redirecting via bpf_sk_redirect_hash or bpf_redirect_peer bypasses Netfilter entirely without registering conntrack tuples. Any fallback, RST, or asymmetric return path results in conntrack marking packets as INVALID, leading to silent drops in iptables/nftables pipelines. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> struct { __uint(type, BPF_MAP_TYPE_SOCKHASH); __uint(max_entries, 65535); __type(key, struct sock_key); __type(value, __u64); } sock_ops_map SEC(".maps"); SEC("tc") int tc_ingress_redirect(struct __sk_buff *skb) { struct sock_key key = {}; // ANTI-PATTERN: Direct socket redirection without updating conntrack. // If packets experience TCP retransmits, out-of-order delivery, or // sidecar proxy restarts, packets fall back to host stack where Netfilter // flags them as INVALID state and silently drops them. long ret = bpf_sk_redirect_hash(skb, &sock_ops_map, &key, BPF_F_INGRESS); if (ret == BPF_REDIRECT) return TC_ACT_REDIRECT; return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: Synchronizes connection tracking into Netfilter via BPF kfuncs (bpf_ct_alloc, bpf_ct_set_status, bpf_ct_insert_entry) prior to packet redirection. This ensures that any subsequent host stack traversals or connection termination events encounter a valid, confirmed conntrack state. ```c #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include <bpf/bpf_endian.h> struct bpf_ct_opts { __u16 netns_id; __s32 error; __u8 l4proto; __u8 dir; __u8 reserved[2]; }; extern struct nf_conn *bpf_ct_alloc(struct __sk_buff *, struct bpf_sock_tuple *, __u32, struct bpf_ct_opts *, __u32) __ksym; extern struct nf_conn *bpf_ct_insert_entry(struct nf_conn *) __ksym; extern void bpf_ct_release(struct nf_conn *) __ksym; extern void bpf_ct_set_status(struct nf_conn *, __u32) __ksym; #define IPS_CONFIRMED (1 << 3) #define IPS_SEEN_REPLY (1 << 1) SEC("tc") int tc_ingress_redirect(struct __sk_buff *skb) { struct bpf_sock_tuple tuple = {}; struct bpf_ct_opts ct_opts = { .l4proto = IPPROTO_TCP, .netns_id = BPF_F_CURRENT_NETNS, }; // PROD INVARIANT: Seed and confirm conntrack state before bypass redirection struct nf_conn *ct = bpf_ct_alloc(skb, &tuple, sizeof(tuple.ipv4), &ct_opts, sizeof(ct_opts)); if (ct) { bpf_ct_set_status(ct, IPS_CONFIRMED | IPS_SEEN_REPLY); struct nf_conn *inserted = bpf_ct_insert_entry(ct); if (inserted) { bpf_ct_release(inserted); } else { bpf_ct_release(ct); } } // Safely redirect to local peer after Netfilter state is guaranteed synchronized return bpf_redirect_peer(skb->ifindex, 0); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Socket-to-Socket Redirection Netfilter Conntrack State Synchronization

eBPF TC Socket-to-Socket Redirection Netfilter Conntrack State Synchronization defines an industrial-grade behavioral standard for devops engineering. Enforces mandatory bidirectional Netfilter connection tracking (conntrack) synchronization whenever using eBPF TC (clsact) or sockops helpers for socket-to-socket fast-path redirection. Bypassing the host TCP/IP stack without atomically seeding and updating kernel conntrack tuples leads to catastrophic, silent packet drops via `INVALID` ctstate matches upon fallback, asymmetric routing, or connection termination. 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: Bypassing Host TCP Stack via BPF Sockmesh Without Bidirectional Conntrack State Seeding 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	Bypassing Host TCP Stack via BPF Sockmesh Without Bidirectional Conntrack State Seeding	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 invoke Netfilter conntrack synchronization kfuncs (bpf_ct_alloc, bpf_ct_insert_entry, bpf_ct_set_status) or mirror state to Netfilter tables before executing bpf_sk_redirect_hash or bpf_redirect_peer.

Engineers MUST ALWAYS invoke Netfilter conntrack synchronization kfuncs (bpf_ct_alloc, bpf_ct_insert_entry, bpf_ct_set_status) or mirror state to Netfilter tables before executing bpf_sk_redirect_hash or bpf_redirect_peer.

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.