Kernel Socket-Layer BPF Acceleration with Cryptographic Handshake and L7 Telemetry Retention

--- description: Kernel Socket-Layer BPF Acceleration with Cryptographic Handshake and L7 Telemetry Retention - Enforces deterministic eBPF socket-layer redirection (sockops/sockmap) invariants across service mesh proxies. Kernel-level TCP stream short-circuiting must never bypass mutual TLS authentication, cgroup identity attribution, or L7 telemetry ring-buffer dispatch. globs: bpf/**/*.c, bpf/**/*.h, pkg/ebpf/**/*.go, pkg/mesh/**/*.go, deploy/mesh/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-sockops-service-mesh-mtls-standard" --- # Kernel Socket-Layer BPF Acceleration with Cryptographic Handshake and L7 Telemetry Retention > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Kernel Socket Splicing That Bypasses Userspace Proxy Authentication and Evades L7 Telemetry ## System Constraints You are a Principal Systems & Kernel Architect enforcing invariants for eBPF-accelerated service mesh deployments. You must prevent premature socket splicing that circumvents mTLS validation, ensure kTLS or post-handshake synchronization, and guarantee that L7 observability probes (traceparent, metrics, access logs) remain fully functional when bypassing the host TCP/IP stack. ## Strict Guidelines - Engineers MUST ALWAYS require userspace proxies to complete the mTLS handshake and validate peer SPIFFE IDs before registering socket file descriptors into acceleration maps (SOCKHASH/SOCKMAP). - Engineers MUST NOT redirect encrypted payload streams via bpf_msg_redirect_hash or bpf_sk_redirect_hash without kernel-level kTLS (ULP TLS) enablement or proxy-assisted crypto termination. - Code SHOULD extract and emit W3C trace contexts and L7 metrics to a BPF perf/ring buffer prior to executing kernel socket redirection in BPF_PROG_TYPE_SK_MSG programs. - Services MUST implement immediate fallback to userspace proxy data paths when socket map insertion fails, connection renegotiation occurs, or socket state drift is detected. - Components NEVER bridge cross-namespace sockets without strictly verifying cgroup v2 ingress/egress security labels and egress network policies inside the sock_ops hook. ## Bad vs Good Implementations ### eBPF Socket Map Ingress Handling: Pre-Handshake Bypass vs Post-mTLS kTLS Registration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Redirecting sockets immediately upon TCP 3-way handshake completion breaks mTLS. The userspace sidecar proxy never completes the cryptographic handshake, application identity cannot be cryptographically proven via SPIFFE, and L7 metrics/traces are lost entirely. ```c // ANTI-PATTERN: Prematurely splicing TCP streams on socket establishment // completely bypasses envoy/proxy mTLS negotiation and L7 observability. SEC("sockops") int bpf_sockmap_intercept(struct bpf_sock_ops *skops) { if (skops->family != AF_INET) return 0; switch (skops->op) { case BPF_SOCK_OPS_PASSIVE_ESTABLISHED_CB: case BPF_SOCK_OPS_ACTIVE_ESTABLISHED_CB: // Blindly inserts established socket directly into redirection map // The TLS handshake has not completed, sending unencrypted keys or raw frames bpf_sock_hash_update(skops, &sock_map, &skops->sk, BPF_ANY); break; } return 0; } ``` #### Production Standard (Correct) > **Standard**: Validates that the session has successfully passed the userspace proxy's mutual TLS handshake and identity verification check before registering the socket in the SOCKHASH map. If not verified or if kTLS is pending, traffic safely falls back to standard user-space proxy routing. ```c // PRODUCTION STANDARD: Defer acceleration until proxy signals post-mTLS & kTLS activation SEC("sockops") int bpf_sockmap_intercept(struct bpf_sock_ops *skops) { if (skops->family != AF_INET) return 0; // Only inspect established sockets if (skops->op != BPF_SOCK_OPS_PASSIVE_ESTABLISHED_CB && skops->op != BPF_SOCK_OPS_ACTIVE_ESTABLISHED_CB) { return 0; } // Verify proxy has registered this connection with verified mTLS identity struct connection_key key = { .src_ip = skops->local_ip4, .dst_ip = skops->remote_ip4, .src_port = skops->local_port, .dst_port = bpf_ntohl(skops->remote_port) }; struct session_state *state = bpf_map_lookup_elem(&verified_mtls_sessions, &key); if (!state || state->handshake_status != MTLS_HANDSHAKE_VERIFIED) { // Fall through to traditional userspace proxy data path for handshake return 0; } // Ensure ULP/kTLS is initialized or socket is authorized for raw acceleration if (state->ktls_enabled) { bpf_sock_hash_update(skops, &sock_map, &key, BPF_NOEXIST); } return 0; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kernel Socket-Layer BPF Acceleration with Cryptographic Handshake and L7 Telemetry Retention

Kernel Socket-Layer BPF Acceleration with Cryptographic Handshake and L7 Telemetry Retention defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic eBPF socket-layer redirection (sockops/sockmap) invariants across service mesh proxies. Kernel-level TCP stream short-circuiting must never bypass mutual TLS authentication, cgroup identity attribution, or L7 telemetry ring-buffer dispatch. 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 Kernel Socket Splicing That Bypasses Userspace Proxy Authentication and Evades L7 Telemetry 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 Kernel Socket Splicing That Bypasses Userspace Proxy Authentication and Evades L7 Telemetry	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 require userspace proxies to complete the mTLS handshake and validate peer SPIFFE IDs before registering socket file descriptors into acceleration maps (SOCKHASH/SOCKMAP).

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.