Zero-Instrumentation Socket-Level W3C TraceContext eBPF Injection Standard

--- description: Zero-Instrumentation Socket-Level W3C TraceContext eBPF Injection Standard - Enforces safe, deterministic W3C TraceContext injection at the kernel socket layer across heterogeneous polyglot services without application-level agent overhead. Mandates protocol-aware stream parsing, strict TLS boundary preservation via kTLS or uprobe co-processing, and non-destructive TCP byte-stream manipulation using sk_msg and sock_ops helpers. globs: bpf/**/*.{c,h}, src/bpf/**/*.{c,h}, pkg/ebpf/**/*.{go,rs,c}, deploy/daemonsets/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tracecontext-sockops-injection-standard" --- # Zero-Instrumentation Socket-Level W3C TraceContext eBPF Injection Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Corrupting In-Flight L7 Payloads or Breaking TCP Sequence Spaces via Blind eBPF Byte Injection ## System Constraints You are a Principal Systems Engineer and Kernel Observability Architect enforcing eBPF-Driven Zero-Instrumentation TraceContext Injection. You must eliminate application runtime overhead while guaranteeing that socket-level context injection never corrupts TCP sequence spaces, violates TLS boundaries, or truncates HTTP/1.1 and HTTP/2 framing. Enforce strict verification bounds, bounded loops, and safe helper usage. ## Strict Guidelines - Engineers MUST ALWAYS verify protocol stream framing before injection; blind injection via bpf_msg_push_data without parsing HTTP header boundaries or frame delimiters is strictly prohibited. - Engineers MUST NOT attempt raw socket buffer (sk_buff/sk_msg) injection on encrypted TLS traffic; tracing must coordinate with kTLS or attach uprobes to userspace crypto primitives (e.g., OpenSSL SSL_write) before ciphertext generation. - eBPF programs MUST recalculate or mutate downstream protocol state (e.g., Content-Length headers or HTTP/2 DATA frame lengths) synchronously when inserting W3C 'traceparent' and 'tracestate' byte buffers. - Services MUST maintain deterministic fallback telemetry: if an eBPF map lookup fails or the sockmap ring buffer is congested, packets must pass unmodified rather than dropping or corrupting the stream (fail-open invariant). - Engineers MUST ALWAYS bound all kernel-side parsers using #pragma unroll or verifier-guaranteed bounded loops (< 32 iterations) to satisfy the BPF verifier across all target kernel versions (>= 5.15 LTS). ## Bad vs Good Implementations ### eBPF sk_msg Program: Safe HTTP/1.1 TraceContext Header Injection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This anti-pattern injects headers indiscriminately at offset 0 of any socket message. It corrupts TLS records, breaks HTTP chunked encoding/Content-Length synchronization, fails to check if the payload is an HTTP request, and will crash or desynchronize TCP state for non-HTTP L7 protocols. ```c // Blindly injects traceparent at offset 0 without protocol checks or Content-Length updates #include <linux/bpf.h> #include <bpf/bpf_helpers.h> SEC("sk_msg") int traceparent_injector_bad(struct sk_msg_md *msg) { char trace_hdr[] = "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01\r\n"; // ANTI-PATTERN: Injects blind bytes regardless of protocol or payload state // Corrupts non-HTTP traffic, destroys TLS handshake streams, and breaks TCP offsets bpf_msg_push_data(msg, 0, sizeof(trace_hdr) - 1, 0); return SK_PASS; } ``` #### Production Standard (Correct) > **Standard**: The production-grade code safely parses the initial stream buffer, verifies valid HTTP request tokens (GET/POST), searches within bounded loop limits for the end of the HTTP request line, and injects the W3C header strictly at valid header boundaries. If validation fails or buffer allocation limits are hit, it safely falls open with SK_PASS, preventing TCP connection resets. ```c // Verifies HTTP method line, validates kTLS state, and safely injects W3C traceparent header #include <linux/bpf.h> #include <bpf/bpf_helpers.h> #include <bpf/bpf_endian.h> #define TRACEPARENT_LEN 55 static const char trace_hdr[] = "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01\r\n"; SEC("sk_msg") int traceparent_injector_good(struct sk_msg_md *msg) { void *data = (void *)(long)msg->data; void *data_end = (void *)(long)msg->data_end; // 1. Boundary check for minimal HTTP verb inspection if (data + 4 > data_end) return SK_PASS; // 2. Protocol sanity: ensure outbound stream is unencrypted plaintext HTTP request char *buf = (char *)data; if (!(buf[0] == 'G' && buf[1] == 'E' && buf[2] == 'T' && buf[3] == ' ') && !(buf[0] == 'P' && buf[1] == 'O' && buf[2] == 'S' && buf[3] == 'T')) { return SK_PASS; } // 3. Scan for end of request line (CRLF) within bounded window __u32 injection_offset = 0; #pragma unroll for (__u32 i = 0; i < 64; i++) { if ((void *)(buf + i + 2) > data_end) break; if (buf[i] == '\r' && buf[i + 1] == '\n') { injection_offset = i + 2; break; } } if (injection_offset == 0) return SK_PASS; // Fail-open if request line delimiter is not resolved // 4. Inject traceparent cleanly after request line without breaking TLS or framing long ret = bpf_msg_push_data(msg, injection_offset, sizeof(trace_hdr) - 1, 0); if (ret < 0) return SK_PASS; return SK_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Zero-Instrumentation Socket-Level W3C TraceContext eBPF Injection Standard

Zero-Instrumentation Socket-Level W3C TraceContext eBPF Injection Standard defines an industrial-grade behavioral standard for devops engineering. Enforces safe, deterministic W3C TraceContext injection at the kernel socket layer across heterogeneous polyglot services without application-level agent overhead. Mandates protocol-aware stream parsing, strict TLS boundary preservation via kTLS or uprobe co-processing, and non-destructive TCP byte-stream manipulation using sk_msg and sock_ops helpers. 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: Corrupting In-Flight L7 Payloads or Breaking TCP Sequence Spaces via Blind eBPF Byte Injection 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	Corrupting In-Flight L7 Payloads or Breaking TCP Sequence Spaces via Blind eBPF Byte Injection	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 verify protocol stream framing before injection

Engineers MUST ALWAYS verify protocol stream framing before injection; blind injection via bpf_msg_push_data without parsing HTTP header boundaries or frame delimiters is strictly prohibited.

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.