Deterministic W3C TraceContext eBPF Socket Buffer Injection Standard

--- description: Deterministic W3C TraceContext eBPF Socket Buffer Injection Standard - Mandates protocol-aware boundary verification, safe socket buffer expansion, and L4 checksum reconciliation when injecting W3C TraceContext headers into uninstrumented egress traffic via eBPF programs. Prevents TCP sequence desynchronization, kernel memory faults, and payload corruption across legacy egress streams bridging to OpenTelemetry fabrics. globs: ebpf/**/*.c, bpf/**/*.bpf.c, pkg/ebpf/**/*.go, src/network/**/*.c alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-ebpf-tracecontext-injection-guardrail" --- # Deterministic W3C TraceContext eBPF Socket Buffer Injection Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind TCP Payload Splicing Without L4 Checksum Recalculation or Stream Boundary Verification ## System Constraints You are a Principal Engineer enforcing OpenTelemetry eBPF Network Profiling TraceContext Propagation Guardrails. Mandate invariants that govern kernel-level socket manipulation: never perform blind buffer expansion without protocol identification, always recompute L4 checksums, strictly maintain TCP sequence integrity via sockmsg or sk_msg helpers, and adhere strictly to W3C TraceContext specifications. ## Strict Guidelines - Engineers MUST ALWAYS verify L7 protocol boundaries (e.g., verifying ASCII HTTP/1.1 verbs and CRLF delimiters) before injecting synthetic trace headers. - Engineers MUST NOT invoke raw socket buffer rewriting or `bpf_skb_adjust_room` without updating TCP sequence offsets and executing `bpf_l4_csum_replace`. - Code SHOULD utilize `BPF_PROG_TYPE_SK_MSG` programs with `bpf_msg_push_data` in conjunction with sockmap redirection rather than unconstrained `kprobe:tcp_sendmsg` hooks to let the TCP engine preserve payload framing naturally. - Services MUST generate W3C-compliant `traceparent` headers strictly formatted as `00-${trace_id}-${span_id}-${trace_flags}` with valid 32-character hex trace IDs and 16-character hex span IDs. - Components NEVER inject trace headers into existing TLS/SSL sockets directly from L4 hooks without terminating or intercepting before userland encryption. ## Bad vs Good Implementations ### eBPF Socket Message TraceContext Injection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly overwriting userland pointers via bpf_probe_write_user inside tcp_sendmsg corrupts application memory, disregards socket encryption state (destroying TLS records), and breaks TCP stream byte accounting. ```c // Flawed: Modifying TCP payload directly in raw kprobe without protocol verification // or sequence management, corrupting TLS connections and desyncing TCP streams. SEC("kprobe/tcp_sendmsg") int BPF_KPROBE(trace_tcp_sendmsg, struct sock *sk, struct msghdr *msg, size_t size) { char trace_header[] = "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01\r\n"; void *iov_base; bpf_probe_read_kernel(&iov_base, sizeof(iov_base), &msg->msg_iter.iov->iov_base); // DANGEROUS: Direct user-space pointer overwrite without payload size boundary checks bpf_probe_write_user(iov_base, trace_header, sizeof(trace_header) - 1); return 0; } ``` #### Production Standard (Correct) > **Standard**: Leverages sk_msg programs with bpf_msg_push_data to deterministically expand the TCP stream buffer at the socket layer. It verifies HTTP protocol verbs, dynamically refetches buffer boundaries after mutation, and delegates TCP sequence/checksum recalculation to the kernel TCP stack. ```c // Production: Use BPF_PROG_TYPE_SK_MSG with protocol validation and bpf_msg_push_data SEC("sk_msg") int inject_w3c_traceparent(struct sk_msg_md *msg) { void *data = (void *)(long)msg->data; void *data_end = (void *)(long)msg->data_end; // Verify sufficient headroom for HTTP method inspection if (data + 4 > data_end) return SK_PASS; // Restrict injection to plain-text HTTP/1.x egress streams if (__builtin_memcmp(data, "GET ", 4) != 0 && __builtin_memcmp(data, "POST", 4) != 0) return SK_PASS; // TraceContext header: 55 bytes payload + CRLF const char hdr[] = "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01\r\n"; __u32 len = sizeof(hdr) - 1; // Safely insert data at byte offset without corrupting existing socket frames if (bpf_msg_push_data(msg, 0, len, 0) != 0) return SK_PASS; // Refresh packet boundary pointers after buffer reallocation data = (void *)(long)msg->data; data_end = (void *)(long)msg->data_end; if (data + len > data_end) return SK_DROP; __builtin_memcpy(data, hdr, len); return SK_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic W3C TraceContext eBPF Socket Buffer Injection Standard

Deterministic W3C TraceContext eBPF Socket Buffer Injection Standard defines an industrial-grade behavioral standard for devops engineering. Mandates protocol-aware boundary verification, safe socket buffer expansion, and L4 checksum reconciliation when injecting W3C TraceContext headers into uninstrumented egress traffic via eBPF programs. Prevents TCP sequence desynchronization, kernel memory faults, and payload corruption across legacy egress streams bridging to OpenTelemetry fabrics. 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 TCP Payload Splicing Without L4 Checksum Recalculation or Stream Boundary Verification 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 TCP Payload Splicing Without L4 Checksum Recalculation or Stream Boundary Verification	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 L7 protocol boundaries (e.g., verifying ASCII HTTP/1.1 verbs and CRLF delimiters) before injecting synthetic trace headers.

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.