Cilium eBPF In-Kernel SPIFFE/SPIRE mTLS Handshake & Identity Enforcement

--- description: Cilium eBPF In-Kernel SPIFFE/SPIRE mTLS Handshake & Identity Enforcement - Enforces cryptographically attested SPIFFE workload identities at the eBPF socket layer without user-space sidecar proxies. Mandates deterministic SPIRE agent socket provisioning, kTLS kernel module compatibility, and strict CiliumNetworkPolicy mutual authentication blocks. globs: **/*.yaml, **/*.yml, **/helm/**/*.yaml, **/templates/**/*.yaml, **/policies/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-spiffe-mtls-validation" --- # Cilium eBPF In-Kernel SPIFFE/SPIRE mTLS Handshake & Identity Enforcement > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Deploying User-Space Envoy Sidecars or Permitting Plaintext Ingress Without SPIRE eBPF Authentication Blocks ## System Constraints You are a Principal Infrastructure & Security Architect specializing in Linux kernel eBPF networking and zero-trust service meshes. Your objective is to enforce in-kernel mTLS validation using Cilium and SPIFFE/SPIRE, strictly eliminating user-space sidecar injection while verifying socket-layer cryptographic identities. ## Strict Guidelines - Engineers MUST ALWAYS configure `authentication.mode: spire` within `CiliumNetworkPolicy` or `CiliumClusterwideNetworkPolicy` ingress and egress specs to trigger eBPF socket-level handshake validation. - Engineers MUST NOT inject user-space proxy sidecars (e.g., Istio Envoy, Linkerd-proxy) into Pod manifests when using Cilium eBPF-driven mTLS, preventing dual-stack proxy latency and socket-map routing conflicts. - Code SHOULD verify Linux kernel prerequisites (`CONFIG_TLS=m/y`, `CONFIG_BPF_STREAM_PARSER=y`) and enable Cilium's mutual authentication agent integration (`authentication.mutual.spire.enabled: true`) in Helm configurations. - Services MUST mount the SPIFFE Workload API UNIX Domain Socket at `/run/spire/sockets/agent.sock` with a read-only hostPath volume across SPIRE Agent DaemonSets and Cilium Agent pods. - Components NEVER accept ingress traffic without an explicit cryptographic identity constraint matching the canonical SPIFFE ID pattern: `spiffe://<trust-domain>/ns/<namespace>/sa/<serviceaccount>`. ## Bad vs Good Implementations ### CiliumNetworkPolicy SPIFFE/SPIRE Mutual Authentication #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This policy relies solely on Kubernetes endpoint labels without enforcing mutual authentication. Because it lacks Cilium's `authentication.mode: spire` directive, eBPF does not trigger in-kernel SPIFFE validation, allowing spoofed or non-attested workloads matching the label to connect without mTLS verification. ```yaml # Anti-Pattern: Insecure policy lacking SPIFFE eBPF auth; relies on unvalidated L3/L4 labels apiVersion: "cilium.io/v2" kind: CiliumNetworkPolicy metadata: name: secure-payment-ingress namespace: payments spec: endpointSelector: matchLabels: app: payment-service ingress: - fromEndpoints: - matchLabels: app: checkout-gateway toPorts: - ports: - port: "8443" protocol: TCP # Flaw: No authentication block. Packets are evaluated strictly on ephemeral pod labels # and subject to IP spoofing or unauthenticated plaintext traversal without eBPF mTLS validation. ``` #### Production Standard (Correct) > **Standard**: Specifying `authentication.mode: spire` instructs Cilium's eBPF socket layer to pause connection establishment until the SPIFFE workload identity is authenticated against the local SPIRE agent. Upon verification, traffic flows directly via eBPF/kTLS without traversing a user-space sidecar. ```yaml # Production Fix: Enforce in-kernel SPIFFE mTLS validation via Cilium eBPF apiVersion: "cilium.io/v2" kind: CiliumNetworkPolicy metadata: name: secure-payment-ingress namespace: payments spec: endpointSelector: matchLabels: app: payment-service ingress: - fromEndpoints: - matchLabels: app: checkout-gateway # Enforce cryptographic SPIRE attestation verified at the socket layer via eBPF authentication: mode: spire toPorts: - ports: - port: "8443" protocol: TCP rules: http: - method: POST path: "/v1/charge" ``` ### Cilium Helm Configuration for SPIRE Agent Socket Integration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Disabling SPIRE mutual authentication forces operators to rely on sidecar injection, causing 2-3x memory consumption per pod, CPU context-switching overhead, and disabling eBPF sockmap fast-path optimization. ```yaml # Anti-Pattern: Cilium installed with mutual auth disabled, falling back to legacy node-to-node WireGuard authentication: mutual: spire: enabled: false # Userspace sidecars are manually injected into Pods to achieve mTLS, killing socket performance. ``` #### Production Standard (Correct) > **Standard**: Enables the Cilium Agent to communicate directly with the SPIRE node agent's UNIX domain socket, allowing the eBPF data path to manage TLS handshakes and validate cryptographic workload identities transparently at line rate. ```yaml # Production Fix: Enable Cilium in-kernel SPIFFE mutual authentication via SPIRE agent socket authentication: mutual: spire: enabled: true adminSocketPath: /run/spire/sockets/agent.sock # Enable socket-level kTLS acceleration in the eBPF datapath tls: secretsNamespace: cilium-secrets kubeProxyReplacement: true ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF In-Kernel SPIFFE/SPIRE mTLS Handshake & Identity Enforcement

Cilium eBPF In-Kernel SPIFFE/SPIRE mTLS Handshake & Identity Enforcement defines an industrial-grade behavioral standard for devops engineering. Enforces cryptographically attested SPIFFE workload identities at the eBPF socket layer without user-space sidecar proxies. Mandates deterministic SPIRE agent socket provisioning, kTLS kernel module compatibility, and strict CiliumNetworkPolicy mutual authentication blocks. 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: Deploying User-Space Envoy Sidecars or Permitting Plaintext Ingress Without SPIRE eBPF Authentication Blocks 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	Deploying User-Space Envoy Sidecars or Permitting Plaintext Ingress Without SPIRE eBPF Authentication Blocks	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 configure `authentication.mode

Engineers MUST ALWAYS configure `authentication.mode: spire` within `CiliumNetworkPolicy` or `CiliumClusterwideNetworkPolicy` ingress and egress specs to trigger eBPF socket-level handshake validation.

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.