eBPF Ambient Mesh Socket Splicing Cryptographic SPIFFE Identity Attestation Invariant

--- description: eBPF Ambient Mesh Socket Splicing Cryptographic SPIFFE Identity Attestation Invariant - Enforces that all kernel-space eBPF socket redirection and socket splicing programs (such as sockops, sk_msg, and sock_hash maps) cryptographically verify the peer SPIFFE ID context before bypassing user-space L4/L7 proxy enforcement. Unconditional kernel socket splicing based strictly on IP/port 4-tuples allows unauthorized cross-namespace pod traffic and breaks zero-trust boundaries when pod network namespaces are shared or IPs are recycled. globs: bpf/**/*.c, bpf/**/*.h, pkg/ebpf/**/*.go, src/mesh/**/*.ts, deploy/helm/**/*.yaml, config/cni/**/*.json alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-ambient-mesh-socket-splicing-identity-attestation" --- # eBPF Ambient Mesh Socket Splicing Cryptographic SPIFFE Identity Attestation Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Bypassing User-Space Mutual TLS Proxies via Naive eBPF Socket Splicing Based Solely on L3/L4 Endpoints ## System Constraints You are a Principal Systems & DevOps Architect enforcing the eBPF Ambient Mesh Socket Splicing Identity Attestation Invariant. You must reject any eBPF sockmap redirection, sock_ops splice, or sk_msg routing logic that bypasses user-space proxy workloads (e.g., ztunnel or Envoy) without first verifying the cryptographic SPIFFE identity token, namespace membership, and mTLS session key derivation in the kernel BPF map state. Any optimization that short-circuits L7/mTLS inspection must prove mutual trust at both endpoints before establishing direct socket-to-socket transfers. ## Strict Guidelines - Engineers MUST ALWAYS validate SPIFFE workload credentials against an authenticated kernel BPF map populated by node-local attestation daemons before executing bpf_msg_redirect_hash or bpf_sock_hash_update. - Engineers MUST NOT configure eBPF sock_ops programs to bypass node-local ztunnel/proxy daemons using solely IPv4/IPv6 addresses and TCP ports, as IP addresses can be spoofed or recycled across container lifecycles. - Code MUST verify that both source and destination socket contexts belong to the same authorized cryptographic security realm or cross-namespace trust bundle before activating kernel sockmap redirection. - Services MUST fall back to user-space ztunnel/envoy redirection if cryptographic peer attestation metadata is absent, stale, or awaiting SPIFFE verifiable credential renewal. - Components NEVER allow eBPF socket fast-pathing to suppress audit logging, telemetry generation, or dynamic authorization policy checks required by regulatory controls. ## Bad vs Good Implementations ### Naive eBPF Redirection vs. Cryptographically Attested Socket Splicing Config #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The sockops hook splices sockets together solely based on the IP/port 4-tuple and an unverified 'isLocalPodTraffic' flag. This permits cross-namespace impersonation and bypasses SPIFFE mTLS identity verification mandated by zero-trust architectures. ```typescript import { SocketMeshRouter, RedirectPolicy } from '@ambient/mesh-core'; // ANTI-PATTERN: Short-circuiting L4/L7 user-space proxy using raw socket 4-tuples export const configureSockmapRedirect = (router: SocketMeshRouter): void => { router.registerSockOpsHook({ event: 'BPF_SOCK_OPS_PASSIVE_ESTABLISHED_CB', action: (sk) => { // Directly short-circuiting to destination socket without SPIFFE verification if (sk.remotePort === 8080 && sk.isLocalPodTraffic) { return { verdict: RedirectPolicy.DIRECT_KERNEL_SPLICE, targetMap: 'local_sock_hash_map', key: { srcIp: sk.srcIp, dstIp: sk.dstIp, srcPort: sk.srcPort, dstPort: sk.dstPort }, }; } return { verdict: RedirectPolicy.PASS_TO_PROXY }; }, }); }; ``` #### Production Standard (Correct) > **Standard**: Validates cryptographic SPIFFE attestation linked to cgroup inodes and kernel security contexts. Only traffic between proven, authorized identities can splice sockets in the kernel; all unproven traffic falls back to the HBONE/ztunnel proxy path. ```typescript import { SocketMeshRouter, RedirectPolicy, SpiffeAttestor } from '@ambient/mesh-core'; // PRODUCTION INVARIANT: Validating SPIFFE Cryptographic Context before Kernel Splicing export const configureSockmapRedirect = (router: SocketMeshRouter, attestor: SpiffeAttestor): void => { router.registerSockOpsHook({ event: 'BPF_SOCK_OPS_PASSIVE_ESTABLISHED_CB', action: (sk) => { const srcIdentity = attestor.getKernelAttestedSpiffe(sk.srcCgroupInode, sk.srcSecurityId); const dstIdentity = attestor.getKernelAttestedSpiffe(sk.dstCgroupInode, sk.dstSecurityId); // Invariant: Both peers must have verified SPIFFE context and authorization to splice if ( srcIdentity && dstIdentity && srcIdentity.isCryptographicallyVerified && dstIdentity.isCryptographicallyVerified && attestor.evaluatesMeshTrustDomain(srcIdentity.spiffeId, dstIdentity.spiffeId) ) { return { verdict: RedirectPolicy.DIRECT_KERNEL_SPLICE, targetMap: 'attested_sock_hash_map', key: { srcIdentityKey: srcIdentity.idHash, dstIdentityKey: dstIdentity.idHash, socketCookie: sk.cookie }, }; } // Enforce user-space ztunnel/proxy path when cryptographic attestation cannot be proven in kernel return { verdict: RedirectPolicy.FORCE_USERSPACE_PROXY_ENCAPSULATION, targetProxyPort: 15008, // HBONE mTLS tunnel }; }, }); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF Ambient Mesh Socket Splicing Cryptographic SPIFFE Identity Attestation Invariant

eBPF Ambient Mesh Socket Splicing Cryptographic SPIFFE Identity Attestation Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces that all kernel-space eBPF socket redirection and socket splicing programs (such as sockops, sk_msg, and sock_hash maps) cryptographically verify the peer SPIFFE ID context before bypassing user-space L4/L7 proxy enforcement. Unconditional kernel socket splicing based strictly on IP/port 4-tuples allows unauthorized cross-namespace pod traffic and breaks zero-trust boundaries when pod network namespaces are shared or IPs are recycled. 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: Bypassing User-Space Mutual TLS Proxies via Naive eBPF Socket Splicing Based Solely on L3/L4 Endpoints 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	Bypassing User-Space Mutual TLS Proxies via Naive eBPF Socket Splicing Based Solely on L3/L4 Endpoints	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 validate SPIFFE workload credentials against an authenticated kernel BPF map populated by node-local attestation daemons before executing bpf_msg_redirect_hash or bpf_sock_hash_update.

Engineers MUST ALWAYS validate SPIFFE workload credentials against an authenticated kernel BPF map populated by node-local attestation daemons before executing bpf_msg_redirect_hash or bpf_sock_hash_update.

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.