Cilium eBPF Mutual Authentication and WireGuard Transparent Encryption Invariants

--- description: Cilium eBPF Mutual Authentication and WireGuard Transparent Encryption Invariants - Enforces strict node-to-node transparent WireGuard encryption decoupled from control-plane mutual authentication (mTLS) handshakes using Cilium eBPF host routing. Prevents unauthenticated pod-to-pod egress fallback, eliminates sidecar proxy latency, and ensures periodic session key rotation with zero packet loss across overlay and direct routing meshes. globs: deploy/**/*.yaml, k8s/**/*.yaml, helm/**/*.yaml, infra/**/*.tf, src/network/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-mutual-auth-wireguard-invariants" --- # Cilium eBPF Mutual Authentication and WireGuard Transparent Encryption Invariants > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unencrypted Pod Egress Fallback via Broken eBPF Tail-Calls or Missing Mutual Auth Handshake Verification ## System Constraints You are a Principal Infrastructure & Network Security Architect enforcing Cilium eBPF Mutual Authentication and WireGuard Session Key Invariants. You must ensure that all pod traffic is cryptographically validated and encrypted at the kernel level via eBPF without relying on userspace proxy sidecars. Intercept any misconfiguration that allows plaintext fallback, unrotated WireGuard keys, or missing CiliumNetworkPolicy mutual authentication requirements. ## Strict Guidelines - Engineers MUST ALWAYS enforce Cilium WireGuard transparent encryption at the agent configuration level (`encryption.type: wireguard`) alongside strict eBPF host routing (`bpf.masquerade: true`). - Engineers MUST configure Mutual Authentication with SPIRE/SPIFFE or Cilium internal mutual authentication (`authentication.mutual.mode: spire` or `authentication.mutual.mode: test-ticker`) inside `CiliumNetworkPolicy` to cryptographically bind pod identities before allowing data-plane forwarding. - Engineers MUST NOT disable WireGuard strict mode (`encryption.wireguard.persistentKeepalive` and session rotation) or permit unencrypted fallback when the mutual authentication handshake fails or times out. - Cilium DaemonSet configuration MUST define `encryption.wireguard.strictMode: true` to prevent any node from routing traffic in plaintext when remote WireGuard endpoints are uninitialized or resolving. - Network policies MUST explicitly reject unauthenticated egress and ingress with explicit deny defaults (`default-deny-all`) before matching authenticated peer identities. ## Bad vs Good Implementations ### Cilium Helm Values & Policy: Insecure Plaintext Fallback vs Strict Mutual Auth WireGuard Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Without `encryption.wireguard.strictMode: true`, packets drop out of the WireGuard routing table during handshake re-keying or agent restarts, leaking plaintext across the physical network. Omitting mutual authentication allows any compromised pod spoofing the target label to pass Cilium identity checks. ```yaml # INSECURE: Encryption enabled without strict mode, missing mutual auth enforcement cilium: encryption: enabled: true type: wireguard # Flaw: strictMode is omitted (defaults to false), allowing plaintext fallback during key-rotation tunnelProtocol: vxlan --- apiVersion: "cilium.io/v2" kind: CiliumNetworkPolicy metadata: name: secure-service-access spec: endpointSelector: matchLabels: app: payment-processor ingress: - fromEndpoints: - matchLabels: app: checkout-gateway # Flaw: No authentication block. Relies solely on IP/label spoofable kernel context without cryptographic identity validation ``` #### Production Standard (Correct) > **Standard**: Enforces `strictMode: true` to drop all unencrypted packets unconditionally during key rotation. Combines eBPF host routing with an explicit `authentication.mode: required` block, verifying pod cryptographic identity via SPIRE before the eBPF datapath allows WireGuard encapsulation. ```yaml # SECURE: WireGuard transparent encryption with strict mode and eBPF mutual authentication cilium: encryption: enabled: true type: wireguard wireguard: strictMode: true persistentKeepalive: 25s routingMode: native bpf: masquerade: true hostRouting: true authentication: mutual: mode: spire --- apiVersion: "cilium.io/v2" kind: CiliumNetworkPolicy metadata: name: secure-service-access spec: endpointSelector: matchLabels: app: payment-processor ingress: - fromEndpoints: - matchLabels: app: checkout-gateway authentication: mode: required toPorts: - ports: - port: "8443" protocol: TCP ``` ### Kubernetes WireGuard Key Rotation Automated Verifier #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This naive check simply verifies WireGuard presence in the tunnel list but fails to assert key rotation age, active handshakes, or incrementing dropped-packet counters indicative of broken strict-mode encryption. ```typescript import { execSync } from 'child_process'; // ANTI-PATTERN: Ad-hoc manual check that ignores rotation timestamps and fails to check dropped packet counters export function checkWireguardStatus(): boolean { const output = execSync('cilium-dbg bpf tunnel list').toString(); return output.includes('wireguard'); } ``` #### Production Standard (Correct) > **Standard**: Programmatically enforces zero-trust invariants: verifies that strict mode is actively engaged, asserts dropped-leak metric thresholds, and guarantees that WireGuard cryptographic session keys are actively refreshed within permissible time windows. ```typescript import { execSync } from 'child_process'; interface WireguardPeerStatus { publicKey: string; lastHandshakeAgeSeconds: number; strictModeEnforced: boolean; } // PRODUCTION INVARIANT: Validates cryptographic identity freshness and strict encryption drop metrics export function verifyCiliumWireguardInvariants(maxHandshakeAgeSeconds: number = 180): WireguardPeerStatus[] { const rawMetrics = execSync('cilium-dbg metrics list -o json').toString(); const metrics = JSON.parse(rawMetrics); const unencryptedDrops = metrics.find( (m: { name: string }) => m.name === 'cilium_wireguard_strict_mode_dropped_packets_total' )?.value ?? 0; if (unencryptedDrops > 0) { throw new Error(`CRITICAL: Detected ${unencryptedDrops} unencrypted packet leaks dropped by WireGuard strict mode.`); } const wgRaw = execSync('cilium-dbg encrypt status -o json').toString(); const wgStatus = JSON.parse(wgRaw); if (!wgStatus.wireguard || wgStatus.wireguard.strictMode !== true) { throw new Error('CRITICAL INVARIANT VIOLATION: Cilium WireGuard strictMode is disabled.'); } return (wgStatus.wireguard.peers || []).map((peer: { publicKey: string; lastHandshake: string }) => { const handshakeAge = (Date.now() - new Date(peer.lastHandshake).getTime()) / 1000; if (handshakeAge > maxHandshakeAgeSeconds) { throw new Error(`WireGuard peer ${peer.publicKey} handshake expired: ${handshakeAge}s stale.`); } return { publicKey: peer.publicKey, lastHandshakeAgeSeconds: handshakeAge, strictModeEnforced: true }; }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Mutual Authentication and WireGuard Transparent Encryption Invariants

Cilium eBPF Mutual Authentication and WireGuard Transparent Encryption Invariants defines an industrial-grade behavioral standard for devops engineering. Enforces strict node-to-node transparent WireGuard encryption decoupled from control-plane mutual authentication (mTLS) handshakes using Cilium eBPF host routing. Prevents unauthenticated pod-to-pod egress fallback, eliminates sidecar proxy latency, and ensures periodic session key rotation with zero packet loss across overlay and direct routing meshes. 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: Unencrypted Pod Egress Fallback via Broken eBPF Tail-Calls or Missing Mutual Auth Handshake 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	Unencrypted Pod Egress Fallback via Broken eBPF Tail-Calls or Missing Mutual Auth Handshake 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 enforce Cilium WireGuard transparent encryption at the agent configuration level (`encryption.type

Engineers MUST ALWAYS enforce Cilium WireGuard transparent encryption at the agent configuration level (`encryption.type: wireguard`) alongside strict eBPF host routing (`bpf.masquerade: true`).

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.