eBPF XDP Kernel-Level SPIFFE/mTLS Handshake Validation Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded TLS Record Parsing and Unsynchronized Session Admittance in Kernel XDP Hooks) 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 XDP Kernel-Level SPIFFE/mTLS Handshake Validation Standard

--- description: eBPF XDP Kernel-Level SPIFFE/mTLS Handshake Validation Standard - Enforces strict bounds checking, bounded state machine parsing, and pinned kernel map lookups when offloading zero-trust SPIFFE/mTLS connection admission to eBPF XDP hooks. Precludes unbounded packet parsing, non-atomic map lookups, and unvalidated identity assertions that compromise the kernel network driver layer. globs: bpf/**/*.c, bpf/**/*.h, src/**/*.bpf.c, pkg/ebpf/**/*.go, src/ebpf/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-xdp-spiffe-mtls-validation-standard" --- # eBPF XDP Kernel-Level SPIFFE/mTLS Handshake Validation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unbounded TLS Record Parsing and Unsynchronized Session Admittance in Kernel XDP Hooks ## System Constraints You are a Principal Systems & Kernel Security Engineer enforcing eBPF XDP standards for SPIFFE/mTLS zero-trust admission. You must guarantee that all XDP programs conform to strict BPF verifier bounds, execute strictly bounded TLS record parsing, perform cryptographically validated session key/ticket lookups using pinned BPF LRU maps populated by authenticated userspace SPIFFE agents, and default to XDP_DROP on any anomalous packet structure. ## Strict Guidelines - Engineers MUST ALWAYS enforce strict bounds checking (`pointer + size > data_end`) before accessing every network, transport, and TLS record header inside XDP programs. - Engineers MUST NOT attempt full asymmetric cryptographic handshake validation (e.g., RSA/ECDSA signature verification) inside the XDP execution context; asymmetric handshakes MUST be offloaded to userspace or kTLS. - XDP hooks MUST validate SPIFFE identities on the fast path by looking up cryptographic session tokens or connection 5-tuples in a pinned `BPF_MAP_TYPE_LRU_HASH` or `BPF_MAP_TYPE_SOCKHASH` managed by a privileged SPIFFE control plane. - Packet parsing loops for variable-length TLS extensions or SNI records MUST use a fixed maximum loop iteration bound (`#pragma unroll` with `i < MAX_ITERATIONS`) to satisfy the BPF verifier and prevent CPU exhaustion attacks. - Services MUST emit deterministic telemetry via `bpf_perf_event_output` or ring buffers for every dropped frame (`XDP_DROP`) due to unauthenticated identity or malformed TLS framing. - Control plane agents MUST atomic-update identity-to-token map entries and verify SPIFFE SVID validity before inserting session tickets into kernel space. ## Bad vs Good Implementations ### Kernel XDP Ingress SPIFFE Handshake Fast-Path Admission #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails BPF verifier bounds checking on ethernet, IP, TCP, and TLS headers. Assumes arbitrary payload offsets without checking ctx->data_end, and unconditionally admits traffic with arbitrary session IDs without cross-referencing a verified SPIFFE identity map. ```c // Insecure: Unchecked TLS record access and unbounded parsing causing verifier rejects or RCE SEC("xdp") int xdp_spiffe_validator(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct ethhdr *eth = data; struct iphdr *iph = (void *)(eth + 1); struct tcphdr *tcp = (void *)(iph + 1); // Blindly accessing TLS payload without data_end bounds check unsigned char *tls_data = (unsigned char *)(tcp + 1); if (tls_data[0] == 0x16) { // TLS Handshake // Unchecked variable length lookup; causes BPF verifier failure or memory leak uint32_t session_id = *(uint32_t *)(tls_data + 44); if (session_id != 0) { return XDP_PASS; // Insecure admission without cryptographic mapping } } return XDP_DROP; } ``` #### Production Standard (Correct) > **Standard**: Implements rigorous pointer bounds validation at each layer of the packet hierarchy (Ethernet, IPv4, TCP, TLS). Extracts the 5-tuple session context and securely validates it against a kernel LRU map synchronized by an authenticated userspace SPIFFE agent with expiration tracking. ```c // Secure: Fully bounded TLS framing check with pinned SPIFFE session map lookup #include <linux/bpf.h> #include <linux/if_ether.h> #include <linux/ip.h> #include <linux/tcp.h> #include <bpf/bpf_helpers.h> #define TLS_HANDSHAKE 0x16 #define TLS_HEADER_LEN 5 struct session_key { __u32 src_ip; __u32 dst_ip; __u16 src_port; __u16 dst_port; }; struct spiffe_identity { __u32 spiffe_id_hash; __u64 expiry_ts; __u8 flags; }; struct { __uint(type, BPF_MAP_TYPE_LRU_HASH); __uint(max_entries, 65536); __type(key, struct session_key); __type(value, struct spiffe_identity); } spiffe_sessions SEC(".maps"); SEC("xdp") int xdp_spiffe_validator(struct xdp_md *ctx) { void *data = (void *)(long)ctx->data; void *data_end = (void *)(long)ctx->data_end; struct ethhdr *eth = data; if ((void *)(eth + 1) > data_end) return XDP_DROP; if (eth->h_proto != __builtin_bswap16(ETH_P_IP)) return XDP_PASS; struct iphdr *iph = (void *)(eth + 1); if ((void *)(iph + 1) > data_end) return XDP_DROP; if (iph->protocol != IPPROTO_TCP) return XDP_PASS; struct tcphdr *tcp = (void *)iph + (iph->ihl * 4); if ((void *)(tcp + 1) > data_end) return XDP_DROP; void *payload = (void *)tcp + (tcp->doff * 4); if (payload + TLS_HEADER_LEN > data_end) return XDP_DROP; __u8 *tls = payload; if (tls[0] != TLS_HANDSHAKE) return XDP_DROP; struct session_key key = { .src_ip = iph->saddr, .dst_ip = iph->daddr, .src_port = tcp->source, .dst_port = tcp->dest }; struct spiffe_identity *id = bpf_map_lookup_elem(&spiffe_sessions, &key); if (!id) return XDP_DROP; __u64 now = bpf_ktime_get_ns(); if (now > id->expiry_ts) return XDP_DROP; return XDP_PASS; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF XDP Kernel-Level SPIFFE/mTLS Handshake Validation Standard

eBPF XDP Kernel-Level SPIFFE/mTLS Handshake Validation Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict bounds checking, bounded state machine parsing, and pinned kernel map lookups when offloading zero-trust SPIFFE/mTLS connection admission to eBPF XDP hooks. Precludes unbounded packet parsing, non-atomic map lookups, and unvalidated identity assertions that compromise the kernel network driver layer. 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: Unbounded TLS Record Parsing and Unsynchronized Session Admittance in Kernel XDP Hooks 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	Unbounded TLS Record Parsing and Unsynchronized Session Admittance in Kernel XDP Hooks	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 enforce strict bounds checking (`pointer + size > data_end`) before accessing every network, transport, and TLS record header inside XDP programs.

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.