Istio Ambient ztunnel eBPF L4-to-L7 Waypoint Cryptographic Identity Transition Standard

--- description: Istio Ambient ztunnel eBPF L4-to-L7 Waypoint Cryptographic Identity Transition Standard - Enforces strict peer identity preservation and cryptographic attestation during transparent Layer-4 ztunnel eBPF redirections to Layer-7 Envoy Waypoint proxies. Prevents identity spoofing, dropped HBONE context, and TCP RST connection resets during cross-node mTLS renegotiation. Ensures authorization policies evaluate downstream SPIFFE SAN identities rather than intermediate node-level ztunnel proxy credentials. globs: k8s/**/*.yaml, deploy/**/*.yaml, mesh/**/*.yaml, src/mesh/**/*.go, src/controllers/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/istio-ambient-ztunnel-ebpf-mtls-identity-transition-invariant" --- # Istio Ambient ztunnel eBPF L4-to-L7 Waypoint Cryptographic Identity Transition Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unvalidated Waypoint Forwarding and Intermediate Identity Stripping via Plaintext HBONE Unpacking ## System Constraints You are a Principal Security Architect specializing in Istio Ambient Mesh, eBPF networking, and SPIFFE/SPIRE cryptographic validation. You mandate absolute immutability of client peer identities during transparent Layer-4 (ztunnel HBONE) to Layer-7 (Waypoint Envoy) transitions. You forbid authorization rules that trust intermediate node-proxy identities and demand strict verification of encapsulated SPIFFE credentials without connection reset (TCP RST) leakage. ## Strict Guidelines - Engineers MUST ALWAYS enforce HBONE (HTTP-Based Overlay Network Environment) mTLS encapsulation between ztunnel and Waypoint proxies using ALPN protocol negotiation strings `hbone` and `istio-peer-exchange`. - Engineers MUST configure Waypoint Envoy proxies to enforce downstream client identity through SPIFFE Trust Domain SAN validation, preventing intermediate ztunnel node identities from being treated as request origins. - Engineers MUST NOT disable STRICT mTLS (PeerAuthentication) on workloads bound to Waypoints, nor allow PERMISSIVE fallback for mesh-internal waypoint routes. - Configurations MUST ensure eBPF redirection maps (via Istio CNI / sockops) maintain connection state persistence across namespace boundaries to eliminate socket hang-ups and TCP RST leakage on waypoint handoffs. - AuthorizationPolicy definitions on Waypoint proxies MUST explicitly match on `source.principals` corresponding to end-client workloads, NEVER relying on raw IP transport-layer assertions. ## Bad vs Good Implementations ### Waypoint Envoy Inbound Filter Identity Propagation & Policy Enforcement #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Matching on raw IP blocks or allowing unvalidated ztunnel node identities breaks the Ambient zero-trust model. In Ambient mesh, ztunnel multiplexes traffic over HBONE; if L7 policies inspect raw source IPs or accept intermediate node ztunnel credentials, any compromised pod on the node can spoof requests to the Waypoint. ```yaml # Flawed: Relies on default L4 identity without cryptographic peer attestation at L7 apiVersion: security.istio.io/v1beta1 kind: AuthorizationPolicy metadata: name: secure-billing-policy namespace: payments spec: selector: matchLabels: istio.io/use-waypoint: billing-waypoint action: ALLOW rules: - from: - source: # VULNERABILITY: Permissive IP matches or relying on ztunnel node identity ipBlocks: ["10.244.0.0/16"] to: - operation: paths: ["/checkout"] methods: ["POST"] ``` #### Production Standard (Correct) > **Standard**: Explicitly binds the AuthorizationPolicy to the Waypoint Gateway via targetRefs and enforces STRICT mTLS. The Waypoint cryptographically unwraps the HBONE tunnel, validates the ALPN `hbone` token, and verifies that the client SPIFFE principal matches the expected identity rather than the intermediate ztunnel proxy. ```yaml # Secure: Enforces downstream SPIFFE identity validation across the HBONE L4/L7 transition apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: name: default namespace: payments spec: mtls: mode: STRICT --- apiVersion: security.istio.io/v1beta1 kind: AuthorizationPolicy metadata: name: secure-billing-policy namespace: payments spec: targetRefs: - kind: Gateway group: gateway.networking.k8s.io name: billing-waypoint action: ALLOW rules: - from: - source: principals: ["cluster.local/ns/frontend/sa/frontend-service-account"] to: - operation: paths: ["/checkout"] methods: ["POST"] ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Istio Ambient ztunnel eBPF L4-to-L7 Waypoint Cryptographic Identity Transition Standard

Istio Ambient ztunnel eBPF L4-to-L7 Waypoint Cryptographic Identity Transition Standard defines an industrial-grade behavioral standard for security engineering. Enforces strict peer identity preservation and cryptographic attestation during transparent Layer-4 ztunnel eBPF redirections to Layer-7 Envoy Waypoint proxies. Prevents identity spoofing, dropped HBONE context, and TCP RST connection resets during cross-node mTLS renegotiation. Ensures authorization policies evaluate downstream SPIFFE SAN identities rather than intermediate node-level ztunnel proxy credentials. 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: Unvalidated Waypoint Forwarding and Intermediate Identity Stripping via Plaintext HBONE Unpacking 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	Unvalidated Waypoint Forwarding and Intermediate Identity Stripping via Plaintext HBONE Unpacking	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 HBONE (HTTP-Based Overlay Network Environment) mTLS encapsulation between ztunnel and Waypoint proxies using ALPN protocol negotiation strings `hbone` and `istio-peer-exchange`.

Engineers MUST ALWAYS enforce HBONE (HTTP-Based Overlay Network Environment) mTLS encapsulation between ztunnel and Waypoint proxies using ALPN protocol negotiation strings `hbone` and `istio-peer-exchange`.

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.