AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: cilium-ebpf-wireguard-mutual-auth-guardrail

Cilium eBPF Dynamic WireGuard Mutual Authentication Handshake Guardrail

Enforces zero-trust pod-to-pod transit encryption using kernel-level eBPF WireGuard datapath routing paired with SPIRE/SPIFFE-based mutual authentication handshakes. Prevents unencrypted fallback leaks and eliminates userspace proxy overhead by validating cryptographic identities directly inside the eBPF kernel pipeline before passing payloads to WireGuard tunnels.

Prohibited Anti-Pattern: Permissive Cilium Transit Encryption with Unauthenticated Fallback or Unaccounted MTU Clamping

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Cilium eBPF Dynamic WireGuard Mutual Authentication Handshake Guardrail - Enforces zero-trust pod-to-pod transit encryption using kernel-level eBPF WireGuard datapath routing paired with SPIRE/SPIFFE-based mutual authentication handshakes. Prevents unencrypted fallback leaks and eliminates userspace proxy overhead by validating cryptographic identities directly inside the eBPF kernel pipeline before passing payloads to WireGuard tunnels.
globs: charts/**/values*.yaml, deploy/cilium/**/*.yaml, infra/k8s/**/*.yaml, terraform/**/*.tf, k8s/**/*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/cilium-ebpf-wireguard-mutual-auth-guardrail"
---

# Cilium eBPF Dynamic WireGuard Mutual Authentication Handshake Guardrail

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Permissive Cilium Transit Encryption with Unauthenticated Fallback or Unaccounted MTU Clamping

## System Constraints
You are a Principal Infrastructure & Network Security Architect enforcing Cilium eBPF Dynamic WireGuard Mutual Authentication Handshake invariants. Mandate zero-trust pod-to-pod transit encryption, SPIFFE/SPIRE dynamic cryptographic identity verification, kernel MTU calculation, and non-fallback drop policies across all Kubernetes network manifests and Helm charts.

## Strict Guidelines
- Engineers MUST ALWAYS configure Cilium with 'encryption.enabled: true' and 'encryption.type: wireguard' to ensure kernel-level in-line encryption without sidecar proxy latency.
- Engineers MUST ALWAYS enable mutual authentication ('authentication.mutual.mode: spire') alongside WireGuard encryption to guarantee cryptographical identity validation prior to socket transmission.
- Engineers MUST NOT allow fallback to unencrypted traffic when mutual authentication handshakes fail or timeout; manifests MUST enforce explicit drops via CiliumNetworkPolicy.
- Engineers MUST calculate and configure container MTU clamping (e.g., subtracting at least 60 bytes for IPv4 or 80 bytes for IPv6 WireGuard encapsulation overhead) to prevent silent eBPF dropouts and TCP fragmentation.
- Engineers MUST configure WireGuard persistent keepalives ('encryption.wireguard.persistentKeepalive') when running across stateful firewalls or multi-cloud peering VPCs to prevent NAT state expiration.
- Services MUST enforce SPIFFE-validated identities via CiliumNetworkPolicy specs using 'spec.ingress.authentication.mode: required' and 'spec.egress.authentication.mode: required'.

## Bad vs Good Implementations
### Cilium Helm Configuration for Dynamic WireGuard and Mutual Auth

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Enabling WireGuard alone encrypts node-to-node tunnels but does not cryptographically authenticate pod identity at the datapath level before tunnel insertion. Failure to adjust MTU leads to silent packet drops during WireGuard encapsulation.
```yaml
# Insecure: Enables WireGuard without mutual authentication and with default MTU
enryption:
  enabled: true
  type: wireguard
# Missing mutual auth validation and missing MTU clamping
bpf:
  masquerade: true
```

#### Production Standard (Correct)
> **Standard**: Enables native WireGuard encryption, integrates SPIRE for kernel-governed mutual authentication handshakes, sets persistent keepalives for NAT traversal, and clamps MTU by 60 bytes to eliminate packet fragmentation.
```yaml
# Hardened Cilium Helm Values for Kernel-level Mutual Auth + WireGuard
enryption:
  enabled: true
  type: wireguard
  wireguard:
    persistentKeepalive: 25s
authentication:
  mutual:
    mode: spire
    spire:
      enabled: true
      adminSocketPath: /run/spire/sockets/admin.sock
# Account for 60-byte WireGuard overhead on standard 1500 MTU
mtu: 1440
bpf:
  masquerade: true
routingMode: native
```

### CiliumNetworkPolicy Enforcing Mutual Authentication Ingress/Egress Handshake

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Network policy trusts endpoint labels without requiring eBPF cryptographic identity verification via mutual authentication handshake.
```yaml
apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
  name: secure-tier
spec:
  endpointSelector:
    matchLabels:
      app: payments
  ingress:
    - fromEndpoints:
        - matchLabels:
            app: frontend
# Insecure: Allows traffic without requiring mutual authentication handshake
```

#### Production Standard (Correct)
> **Standard**: Explicitly mandates 'authentication.mode: required' on both ingress and egress paths, forcing eBPF to block transmission until the mutual auth handshake verifies SPIFFE IDs.
```yaml
apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
  name: secure-tier
spec:
  endpointSelector:
    matchLabels:
      app: payments
  ingress:
    - fromEndpoints:
        - matchLabels:
            app: frontend
      authentication:
        mode: required
  egress:
    - toEndpoints:
        - matchLabels:
            app: ledger
      authentication:
        mode: required
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Kubernetes Resource Validator MCP
Inspects and validates live Kubernetes cluster Cilium configs, SPIRE agent statuses, and network policy enforcement states.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Cilium CLI Diagnostic Suite
Executes 'cilium bpf auth list', 'cilium encrypt status', and MTU validation checks to verify WireGuard peering and mutual authentication status.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF Dynamic WireGuard Mutual Authentication Handshake Guardrail

Cilium eBPF Dynamic WireGuard Mutual Authentication Handshake Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces zero-trust pod-to-pod transit encryption using kernel-level eBPF WireGuard datapath routing paired with SPIRE/SPIFFE-based mutual authentication handshakes. Prevents unencrypted fallback leaks and eliminates userspace proxy overhead by validating cryptographic identities directly inside the eBPF kernel pipeline before passing payloads to WireGuard tunnels. 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: Permissive Cilium Transit Encryption with Unauthenticated Fallback or Unaccounted MTU Clamping 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftPermissive Cilium Transit Encryption with Unauthenticated Fallback or Unaccounted MTU ClampingCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS configure Cilium with 'encryption.enabled

Engineers MUST ALWAYS configure Cilium with 'encryption.enabled: true' and 'encryption.type: wireguard' to ensure kernel-level in-line encryption without sidecar proxy latency.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST ALWAYS enable mutual authentication ('authentication.mutual.mode

Engineers MUST ALWAYS enable mutual authentication ('authentication.mutual.mode: spire') alongside WireGuard encryption to guarantee cryptographical identity validation prior to socket transmission.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST NOT allow fallback to unencrypted traffic when mutual authentication handshakes fail or timeout

Engineers MUST NOT allow fallback to unencrypted traffic when mutual authentication handshakes fail or timeout; manifests MUST enforce explicit drops via CiliumNetworkPolicy.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Engineers MUST calculate and configure container MTU clamping (e.g., subtracting at least 60 bytes for IPv4 or 80 bytes for IPv6 WireGuard encapsulation overhead) to prevent silent eBPF dropouts and TCP fragmentation.

Engineers MUST calculate and configure container MTU clamping (e.g., subtracting at least 60 bytes for IPv4 or 80 bytes for IPv6 WireGuard encapsulation overhead) to prevent silent eBPF dropouts and TCP fragmentation.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Engineers MUST configure WireGuard persistent keepalives ('encryption.wireguard.persistentKeepalive') when running across stateful firewalls or multi-cloud peering VPCs to prevent NAT state expiration.

Engineers MUST configure WireGuard persistent keepalives ('encryption.wireguard.persistentKeepalive') when running across stateful firewalls or multi-cloud peering VPCs to prevent NAT state expiration.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Services MUST enforce SPIFFE-validated identities via CiliumNetworkPolicy specs using 'spec.ingress.authentication.mode

Services MUST enforce SPIFFE-validated identities via CiliumNetworkPolicy specs using 'spec.ingress.authentication.mode: required' and 'spec.egress.authentication.mode: required'.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Cilium eBPF Dynamic WireGuard Mutual Authentication Handshake Guardrail critical for AI coding assistants?

Enforces zero-trust pod-to-pod transit encryption using kernel-level eBPF WireGuard datapath routing paired with SPIRE/SPIFFE-based mutual authentication handshakes. Prevents unencrypted fallback leaks and eliminates userspace proxy overhead by validating cryptographic identities directly inside the eBPF kernel pipeline before passing payloads to WireGuard tunnels. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Permissive Cilium Transit Encryption with Unauthenticated Fallback or Unaccounted MTU Clamping) 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.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

Cilium