eBPF kTLS Socket Splicing Non-Blocking and Session State Verification Guardrail

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Synchronous Socket Splicing with Silent eBPF Redirect Drops and Unmonitored kTLS Sequence Overflows) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

eBPF kTLS Socket Splicing Non-Blocking and Session State Verification Guardrail

--- description: eBPF kTLS Socket Splicing Non-Blocking and Session State Verification Guardrail - Mandates non-blocking zero-copy in-kernel socket splicing across eBPF sockmap redirects and kTLS offload pipelines. Prevents TCP window collapse, write buffer deadlocks, and silent stream desynchronization by strictly validating cryptographic session boundaries and enforcing explicit userspace backpressure fallback loops. globs: src/**/*.c, src/**/*.rs, src/**/*.go, bpf/**/*.bpf.c, bpf/**/*.bpf.h alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-ktls-socket-splicing-nonblocking-standard" --- # eBPF kTLS Socket Splicing Non-Blocking and Session State Verification Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Synchronous Socket Splicing with Silent eBPF Redirect Drops and Unmonitored kTLS Sequence Overflows ## System Constraints You are a Principal Systems and Infrastructure Architect enforcing industrial standards for eBPF-enforced kTLS socket splicing and zero-copy proxying. You must reject any design that combines blocking socket descriptors with BPF sockmaps, permits unhandled eBPF redirect drops (SK_DROP) without backpressure signaling, or fails to synchronously verify TLS 1.3 cryptographic record sequence counters and control alert frames before in-kernel splicing. ## Strict Guidelines - Engineers MUST ALWAYS configure socket file descriptors with O_NONBLOCK prior to attaching them to any BPF sockmap (BPF_MAP_TYPE_SOCKMAP or BPF_MAP_TYPE_SOCKHASH). - Engineers MUST NOT allow eBPF sk_msg verdict programs to return SK_DROP without incrementing atomic drop counters and propagating backpressure (EAGAIN/EWOULDBLOCK) to userspace via epoll event flags. - Code SHOULD verify kTLS cryptographic session continuity by polling MSG_ERRQUEUE for TLS alert records, connection teardowns, and sequence number wrap warnings prior to splicing operations. - Services MUST implement a dual-ring fallback mechanism that evicts stalling sockets from the BPF sockmap back to userspace asynchronous I/O (io_uring or epoll) when write buffers exceed SO_SNDBUF low-water marks. - Components NEVER execute blocking splice(2), vmsplice(2), or sendfile(2) system calls on sockets actively governed by an eBPF BPF_PROG_TYPE_SK_MSG or BPF_PROG_TYPE_SK_SKB verdict program. ## Bad vs Good Implementations ### eBPF Sockmap In-Kernel Redirection and Non-Blocking Socket Setup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Sockets are added to the BPF sockmap without O_NONBLOCK verification or kTLS crypto-state negotiation checks. If the egress buffer fills, bpf_msg_redirect_map will either silently drop packets or stall the kernel socket lock, causing cascading connection hangs across worker threads. ```c int attach_to_proxy(int ingress_fd, int egress_fd, int sock_map_fd) { // ANTI-PATTERN: Blocking socket configuration paired with blind sockmap update. // No verification of kTLS ULP status or non-blocking flags, risking kernel deadlocks // if the egress TCP write buffer saturates during sk_msg redirection. int key = 0; bpf_map_update_elem(sock_map_fd, &key, &egress_fd, BPF_ANY); key = 1; bpf_map_update_elem(sock_map_fd, &key, &ingress_fd, BPF_ANY); return 0; } ``` #### Production Standard (Correct) > **Standard**: Validates that descriptors enforce O_NONBLOCK and confirms kTLS is active via TCP_ULP inspection. Updates the sockmap atomically with rollback logic on failure, ensuring the kernel verdict program operates solely on verified non-blocking crypto pipelines. ```c int attach_to_proxy(int ingress_fd, int egress_fd, int sock_map_fd) { int flags; char ulp_name[16]; socklen_t len = sizeof(ulp_name); // Verify non-blocking invariant on both endpoints flags = fcntl(ingress_fd, F_GETFL, 0); if (flags < 0 || !(flags & O_NONBLOCK)) return -1; flags = fcntl(egress_fd, F_GETFL, 0); if (flags < 0 || !(flags & O_NONBLOCK)) return -1; // Verify kTLS active session-state before kernel fast-path transition if (getsockopt(ingress_fd, SOL_TCP, TCP_ULP, ulp_name, &len) != 0 || strncmp(ulp_name, "tls", 3) != 0) { return -ENOPROTOOPT; } // Populate sockmap keys safely with verified non-blocking descriptors int key_egress = 0, key_ingress = 1; if (bpf_map_update_elem(sock_map_fd, &key_egress, &egress_fd, BPF_NOEXIST) != 0) { return -errno; } if (bpf_map_update_elem(sock_map_fd, &key_ingress, &ingress_fd, BPF_NOEXIST) != 0) { bpf_map_delete_elem(sock_map_fd, &key_egress); return -errno; } return 0; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF kTLS Socket Splicing Non-Blocking and Session State Verification Guardrail

eBPF kTLS Socket Splicing Non-Blocking and Session State Verification Guardrail defines an industrial-grade behavioral standard for devops engineering. Mandates non-blocking zero-copy in-kernel socket splicing across eBPF sockmap redirects and kTLS offload pipelines. Prevents TCP window collapse, write buffer deadlocks, and silent stream desynchronization by strictly validating cryptographic session boundaries and enforcing explicit userspace backpressure fallback loops. 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: Synchronous Socket Splicing with Silent eBPF Redirect Drops and Unmonitored kTLS Sequence Overflows 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	Synchronous Socket Splicing with Silent eBPF Redirect Drops and Unmonitored kTLS Sequence Overflows	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 configure socket file descriptors with O_NONBLOCK prior to attaching them to any BPF sockmap (BPF_MAP_TYPE_SOCKMAP or BPF_MAP_TYPE_SOCKHASH).

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.