fix: preserve X-Forwarded-For from untrusted sources

[shreemaan-abhishek]

Description

When the downstream connection is not listed in apisix.trusted_addresses, handle_x_forwarded_headers() cleared the incoming X-Forwarded-For header outright. For deployments with a multi-tier proxy chain (e.g. client -> front proxy -> APISIX -> upstream) where the front proxy is not added to trusted_addresses, the upstream loses the original client IP and only sees the connection IP rebuilt by $proxy_add_x_forwarded_for. This is a behavior change from older releases and breaks upstreams that read the client IP from X-Forwarded-For.

Unlike X-Forwarded-Proto/Host/Port and the RFC 7239 Forwarded header (which are set wholesale and have no append mechanism, so a forged value would pass straight through), X-Forwarded-For has a safe append model: ngx_tpl appends the trusted connection IP via $proxy_add_x_forwarded_for, so even a client-forged chain always carries the real connection IP as its last hop. Consumers that want the real client IP should anchor on the trusted rightmost hop (this is what the real-ip plugin does).

This PR keeps X-Forwarded-For intact for untrusted sources and continues to overwrite X-Forwarded-Proto/Host/Port and clear Forwarded. This aligns with the default behavior of Kong, Tyk and Envoy edge mode, which preserve the incoming XFF and append the connection IP.

Behavior

For an untrusted source sending X-Forwarded-For: 1.2.3.4:

• Before: upstream receives X-Forwarded-For: <connection-ip>
• After: upstream receives X-Forwarded-For: 1.2.3.4, <connection-ip>

X-Forwarded-Proto/Host/Port and Forwarded handling is unchanged.

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the documentation to reflect this change
• I have verified that this change is backward compatible (if not, please discuss on the APISIX mailing list first)

[Copilot]

Pull request overview

This PR adjusts APISIX’s handling of forwarded headers for downstream connections that are not in apisix.trusted_addresses, preserving the incoming X-Forwarded-For header so upstreams can still receive the original chain (with the downstream connection IP appended by Nginx).

Changes:

• Stop clearing X-Forwarded-For for untrusted sources while continuing to override X-Forwarded-Proto/Host/Port and clear Forwarded.
• Update core tests to assert X-Forwarded-For preservation + append behavior in untrusted scenarios.
• Update the example configuration comments to document the revised behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
apisix/init.lua	Keeps X-Forwarded-For intact for untrusted sources while still sanitizing other forwarded headers.
t/core/trusted-addresses.t	Updates expectations to verify preserved incoming XFF plus appended downstream connection IP.
t/plugin/real-ip.t	Adjusts behavior/expectations so the real-ip plugin can still honor XFF when global trusted addresses don’t trust the downstream source.
conf/config.yaml.example	Documents the updated trusted/untrusted forwarded-header behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.