Envoy xff_num_trusted_hops needs a topology proof
Envoy's original IP detection can derive a trusted client address from X-Forwarded-For. The xff_num_trusted_hops setting tells Envoy how many proxy hops on the right side of the header it should trust. The documentation gives the key ordering rule: when use_remote_address is false and xff_num_trusted_hops is set to a value N greater than zero, the trusted client address is the (N+1)th address from the right end of the header.
That rule is precise, and it is easy to misapply. An engineer may count addresses from the left, assume every value is trustworthy, or copy a hop count from another environment. The result can be an access rule, rate-limit key, or audit field that identifies an address selected from attacker-controlled data.
The count describes a path, not a header
xff_num_trusted_hops is useful when an edge Envoy sits behind a known number of proxies. If the topology changes, the count must change with it. A new global load balancer, a second ingress layer, a service mesh sidecar, or a direct-to-Envoy route can alter the number of trusted hops.
The setting interacts with use_remote_address. When use_remote_address is true, Envoy treats the immediate downstream address as the trusted client address and sets related external-address information. When it is false, the XFF logic can use the trusted-hop count. Mixing those modes across internal and external listeners without documenting the intended path makes the resulting address difficult to defend.
Do not translate a hop count into a trust decision until you know which proxies actually write or append X-Forwarded-For. A proxy that preserves an existing header without sanitizing it can create a longer chain than the diagram suggests. A client that sends a forged left-most value should not be able to win the right-to-left selection when the currently connected peers are untrusted.
Build a request-path test
Draw the path from the public listener to the Envoy listener. Mark every component that can read, append, replace, or delete X-Forwarded-For. Record the immediate peer addresses and whether a direct connection to Envoy is possible. Include IPv4 and IPv6, internal health checks, and administrative routes.
Use a test instance to send a header with several distinct addresses. Observe which address Envoy reports to the upstream. Repeat with the intended proxy chain and with a direct request. Confirm that the selected value changes only when the topology changes. Test the application's IP allowlist and rate-limit behavior with the same requests.
If the application cannot tolerate forged header values, enforce a single trusted ingress path and configure that path to overwrite the header rather than append untrusted input. Network policy, listener binding, and firewall rules should prevent clients from bypassing the edge. A header setting is not a substitute for making the bypass path unreachable.
Keep observability honest
Log the listener, the immediate peer, the original header chain, and the selected client address during controlled tests. Do not log cookies, authorization headers, or request bodies. Compare the observed values with the topology document and update the document when a proxy is added.
Review changes to use_remote_address, xff_num_trusted_hops, and any original-IP detection extension as routing and security changes. A review that only checks the listener port misses the header transformation that determines what the backend believes about the caller.
Envoy can give a service a consistent way to reason about the client address when the path is known. The configuration must be tied to that path. A hop count copied without a topology proof is just an assumption about the left side of a header.