fix: only trust `X-Forwarded-*` headers from `trusted_addresses` by SkyeYoung · Pull Request #12551 · apache/apisix

SkyeYoung · 2025-08-27T07:36:21Z

Description

In the past, APISIX trusted the X-Forwarded-* headers from all IPs, which caused many problems. For example:

When using the redirect plugin, even if http_to_https is enabled, as long as the user tries to request curl http://route -H "X-Forwarded-Proto: https" (or uses any value other than http. Allow any value will be fixed in #12561), they can bypass the redirection logic and downgrade to http.

apisix/apisix/plugins/redirect.lua

Lines 192 to 195 in 167b655

    
           local proxy_proto = core.request.header(ctx, "X-Forwarded-Proto") 
        
           local _scheme = proxy_proto or core.request.get_scheme(ctx) 
        
           if conf.http_to_https and _scheme == "http" then 
        
               if ret_port == nil or ret_port == 443 or ret_port <= 0 or ret_port > 65535  then

This PR implements that X-Forwarded-* headers are only trusted if they are sent by IPs or CIDRs configured in apisix.trusted_addresses. Therefore, all plugins or features that use X-Forwarded-* headers require configuration of apisix.trusted_addresses to take effect.

apisix.trusted_addresses supports matching both IPs and CIDRs.

Solve part of #12500

Which issue(s) this PR fixes:

Fixes #

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)

SkyeYoung · 2025-08-29T07:21:47Z

-
-    local proto = api_ctx.var.http_x_forwarded_proto
-    if proto then
-        api_ctx.var.var_x_forwarded_proto = proto
-    end
-
-    local x_forwarded_host = api_ctx.var.http_x_forwarded_host
-    if x_forwarded_host then
-        api_ctx.var.var_x_forwarded_host = x_forwarded_host
-    end
-
-    local port = api_ctx.var.http_x_forwarded_port
-    if port then
-        api_ctx.var.var_x_forwarded_port = port
-    end


apisix/apisix/plugins/ai.lua

Lines 277 to 282 in 09f6e36

apisix.handle_upstream = orig_handle_upstream

apisix.http_balancer_phase = orig_http_balancer_phase

else

-- replace the upstream and balancer module

apisix.handle_upstream = ai_upstream

apisix.http_balancer_phase = ai_http_balancer_phase

Because the code above will replace handle_upstream with ai_upstream below:

apisix/apisix/plugins/ai.lua

Lines 115 to 117 in 09f6e36

local function ai_upstream()

core.log.info("enable sample upstream")

end

This will cause this deleted part of the code to be skipped.

Now that we need to handle X-Forwarded-*, we need to update these var_x_forwarded_*, so we need to extract this part of the code as update_var_x_forwarded_headers.

apisix/apisix/cli/ngx_tpl.lua

Lines 835 to 838 in 3260931

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $var_x_forwarded_proto;

proxy_set_header X-Forwarded-Host $var_x_forwarded_host;

proxy_set_header X-Forwarded-Port $var_x_forwarded_port;

Copilot

Pull Request Overview

This PR implements security hardening by restricting APISIX to only trust X-Forwarded-* headers from configured trusted IP addresses/CIDRs. Previously, APISIX accepted these headers from any source, creating security vulnerabilities where malicious clients could bypass features like HTTP-to-HTTPS redirection.

Adds trusted_addresses configuration to specify which IPs/CIDRs can send trusted X-Forwarded-* headers
Creates utility module to validate and match trusted addresses using IP/CIDR notation
Modifies request processing to override untrusted X-Forwarded-* headers with server-generated values

Reviewed Changes

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

Show a summary per file

File	Description
apisix/utils/trusted-addresses.lua	New utility module for validating and matching trusted IP addresses/CIDRs
apisix/init.lua	Core logic to handle X-Forwarded headers based on client trust status
conf/config.yaml.example	Configuration example for trusted_addresses setting
t/core/trusted-addresses.t	Comprehensive tests for trusted address functionality
docs/en/latest/plugins/*.md	Documentation updates explaining trusted address requirements
docs/zh/latest/plugins/*.md	Chinese documentation updates for trusted address requirements
t/APISIX.pm	Default test configuration with localhost as trusted address
t/plugin/*.t	Test configuration updates to include trusted addresses

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

moonming · 2025-09-02T01:26:13Z

    node_listen: 1984
    enable_admin: false
+    trusted_addresses:
+        - "127.0.0.1"


why change this test case?

Added in batches, removed

moonming · 2025-09-02T01:26:20Z

    my $yaml_config = $block->yaml_config // <<_EOC_;
 apisix:
    node_listen: 1984
+    trusted_addresses:


In order to pass the original tests.

https://github.com/apache/apisix/blob/197ce75259b729717f4a5f7cbca898e4f73bc4fc/t/plugin/proxy-rewrite2.t#L154-L235

moonming · 2025-09-02T01:26:27Z

        enable_encrypt_fields: true
        keyring:
            - edd1c9f0985e76a2
+    trusted_addresses:


Added in batches, removed

moonming · 2025-09-02T01:27:11Z

@@ -0,0 +1,219 @@
+#


Need to test the situation where trusted-addresses contain multiple IP addresses

and need test cases in plugins.

Other than chaitin-waf, the original PR didn't find any tests covering the real_client_ip=true scenario, and after spending time researching, I also couldn't find the actual purpose of this parameter.

moonming · 2025-09-02T01:28:21Z

                                        # When set to true, it overrides all upstream healthcheck configurations and globally disabling healthchecks.
+# trusted_addresses:              # When enabled, APISIX will trust the `X-Forwarded-*` Headers
+#   - 127.0.0.1                   # passed in requests from the IP/CIDR in the list.
+#   - 0.0.0.0/0                   # CAUTION: When not configured, APISIX will remove `X-Forwarded-*` headers


No IP restriction is a bad example

moonming · 2025-09-02T01:29:00Z

                                  # or (standalone mode) the config isn't loaded yet either via file or Admin API.
  # disable_upstream_healthcheck: false # A global switch for healthcheck. Defaults to false.
                                        # When set to true, it overrides all upstream healthcheck configurations and globally disabling healthchecks.
+# trusted_addresses:              # When enabled, APISIX will trust the `X-Forwarded-*` Headers


Suggested change

# trusted_addresses: # When enabled, APISIX will trust the `X-Forwarded-*` Headers

# trusted_addresses: # When enabled, APISIX will trust the `X-Forwarded-*` Headers

how to disabled?

If not configured, it is disabled by default.

This statement references

apisix/conf/config.yaml.example

Line 138 in 1e3950e

# status: # When enabled, APISIX will provide `/status` and `/status/ready` endpoints

write it in this file and docs

moonming · 2025-09-16T05:57:48Z

+--- request
+GET /old_uri
+--- error_log
+invalid IP/CIDR '1.0.0' exists in trusted_addresses


we also need to check the value of trusted_addresses when apisix starts, not only at runtime.

moonming · 2025-09-16T06:04:13Z

+                    type = "array",
+                    minItems = 1,
+                    items = {
+                        type = "string",


"oneOf": [
{"format": "ipv4"},
{"format": "ipv6"}
]

There are a few problems with doing this:

Need CIDR support

As discussed in fix: only trust X-Forwarded-* headers from trusted_addresses #12551 (comment), try to use the existing schema_def. A feasible solution is to copy the corresponding schema again.

Currently, I will try to copy a schema from schema_def to implement this function.

moonming · 2025-09-16T06:08:40Z

+        api_ctx.var.http_x_forwarded_port = port
+        api_ctx.var.http_x_forwarded_for = nil
+
+        -- override the x-forwarded-* headers to the trusted ones


In the if not trusted logic of this code, where the trusted ones come from?

apisix/apisix/cli/ngx_tpl.lua

Lines 830 to 837 in 33b9632

set $var_x_forwarded_proto $scheme;

set $var_x_forwarded_host $host;

set $var_x_forwarded_port $server_port;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $var_x_forwarded_proto;

proxy_set_header X-Forwarded-Host $var_x_forwarded_host;

proxy_set_header X-Forwarded-Port $var_x_forwarded_port;

Referenced the implementation of APISIX.

moonming · 2025-09-16T06:16:09Z

+    local proto = api_ctx.var.http_x_forwarded_proto
+    if proto then
+        api_ctx.var.var_x_forwarded_proto = proto
+    end


why not set X-Forwarded-Proto as http_x_forwarded_proto?

I don't quite understand.

This function is extracted from the following code without any adjustments.

https://github.com/apache/apisix/pull/12551/files/528116c496c9c5ea3ef2b3030e1da6596bac67cb#diff-7439ffe94cc4bcad12066d5d83f6c1004b8e9b3ff5097b645fa7c700eb3b3743L293-L307

X-Forwarded-Proto in the header == http_x_forwarded_proto

moonming · 2025-09-16T06:16:43Z

+local _M = {}
+
+
+local function validate_trusted_addresses(trusted_addresses)


we also need to check this when apisix starts.

moonming · 2025-09-16T07:12:45Z

 end


+local function handle_x_forwarded_headers(api_ctx)


Please add some comments to explain the purpose of each code segment

moonming · 2025-09-16T07:57:13Z

    required = {"prefix", "host"}
 }

+-- copy from apisix/schema_def.lua


please do not copy. we should find the root reason

My suggestion is to extract this schema separately.

This part has been handled by @nic-6443 . Thanks to nic for the assistance.

Signed-off-by: Nic <[email protected]>

…to young/feat/trusted_addresses

…che#12551)

SkyeYoung added 14 commits August 27, 2025 15:34

feat: use trusted_addresses to handle X-Forwarded-* headers

b67dc67

chore

34b5953

fix

5bcc9ff

feat: add to config.yaml.example

a9b3e4c

fix: handle xf headers in untrusted addresses

1ab46cd

fix: logic

b9cf720

chore: format

4f2ed0c

fix: lint

5411324

fix: lint

5e12819

fix: old tests

197ce75

fix: old tests

8a271a5

test: add trusted_accesses cases

cd98ba8

try fix

809b1e9

fix: update vars logic

1a072b2

SkyeYoung commented Aug 29, 2025

View reviewed changes

chore

6614dc0

SkyeYoung changed the title ~~feat: use trusted_addresses to handle X-Forwarded-* headers~~ feat: only trust X-Forwarded-* headers from trusted_addresses Aug 29, 2025

SkyeYoung changed the title ~~feat: only trust X-Forwarded-* headers from trusted_addresses~~ fix: only trust X-Forwarded-* headers from trusted_addresses Aug 29, 2025

SkyeYoung added 2 commits August 29, 2025 16:21

test: add cases

510b2b3

docs: add notes to related docs

16ecd73

SkyeYoung marked this pull request as ready for review August 29, 2025 08:43

dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. bug Something isn't working labels Aug 29, 2025

membphis requested changes Sep 1, 2025

View reviewed changes

Comment thread apisix/init.lua

Comment thread conf/config.yaml.example Outdated

chore: add more explain about the default process way

1e3950e

membphis previously approved these changes Sep 1, 2025

View reviewed changes

moonming requested a review from Copilot September 2, 2025 01:22

Copilot AI reviewed Sep 2, 2025

View reviewed changes

Comment thread apisix/init.lua

Comment thread apisix/utils/trusted-addresses.lua

moonming requested changes Sep 2, 2025

View reviewed changes

chore: adjust config example

1b6e5e6

moonming requested changes Sep 16, 2025

View reviewed changes

moonming reviewed Sep 16, 2025

View reviewed changes

fix: solve comments by @moonming

c06b7c2

SkyeYoung dismissed nic-6443’s stale review via c06b7c2 September 16, 2025 07:40

moonming reviewed Sep 16, 2025

View reviewed changes

nic-6443 and others added 5 commits September 16, 2025 16:56

merge main

c7e372d

Signed-off-by: Nic <[email protected]>

reverse dependecy between schema_def.lua and schema.lua

30ce9c2

Signed-off-by: Nic <[email protected]>

chore: add comments

bb614f2

Merge remote-tracking branch 'origin/young/feat/trusted_addresses' in…

5020eb4

…to young/feat/trusted_addresses

fix: lint

bccb5e6

SkyeYoung requested review from moonming and nic-6443 September 16, 2025 11:14

SkyeYoung added 4 commits September 17, 2025 08:35

Merge branch 'master' into young/feat/trusted_addresses

4a3cb12

chore: rm code which is covered by json schema

37c639b

Merge remote-tracking branch 'origin/young/feat/trusted_addresses' in…

be9a275

…to young/feat/trusted_addresses

fix: lint

fa5a6b6

bzp2010 reviewed Sep 17, 2025

View reviewed changes

Comment thread apisix/core/schema.lua

Comment thread apisix/core.lua

SkyeYoung requested a review from bzp2010 September 18, 2025 01:11

bzp2010 approved these changes Sep 18, 2025

View reviewed changes

moonming approved these changes Sep 18, 2025

View reviewed changes

nic-6443 approved these changes Sep 18, 2025

View reviewed changes

SkyeYoung merged commit 5f0ff46 into apache:master Sep 19, 2025
93 of 102 checks passed

SkyeYoung deleted the young/feat/trusted_addresses branch September 19, 2025 01:30

jizhuozhi pushed a commit to jizhuozhi/apisix that referenced this pull request Oct 18, 2025

fix: only trust X-Forwarded-* headers from trusted_addresses (apa…

0f82d9f

…che#12551)

deekshith-hadil mentioned this pull request Nov 3, 2025

help request: How to Set X-Forwarded-Host and X-Forwarded-Port in APISIX When Using a Second Proxy? #12721

Closed

ngclinflows mentioned this pull request Nov 20, 2025

Upper level reverse proxy X-Forwarded-* headers cleared by APISIX apache/apisix-helm-chart#906

Closed

shreemaan-abhishek mentioned this pull request Mar 12, 2026

fix(openidc): include request port in redirect_uri #13081

Merged

5 tasks

This was referenced May 12, 2026

docs: CHANGELOG audit findings for v3.x — completeness, wording, and process gaps #13359

Open

docs(changelog): apply v3.x audit revisions across all 21 release sections #13362

Open

mhofer117 mentioned this pull request Jun 3, 2026

allow proxy-rewrite plugin to rewrite x-forwarded-port request header #4942

Closed

	local proxy_proto = core.request.header(ctx, "X-Forwarded-Proto")
	local _scheme = proxy_proto or core.request.get_scheme(ctx)
	if conf.http_to_https and _scheme == "http" then
	if ret_port == nil or ret_port == 443 or ret_port <= 0 or ret_port > 65535 then

	apisix.handle_upstream = orig_handle_upstream
	apisix.http_balancer_phase = orig_http_balancer_phase
	else
	-- replace the upstream and balancer module
	apisix.handle_upstream = ai_upstream
	apisix.http_balancer_phase = ai_http_balancer_phase

	local function ai_upstream()
	core.log.info("enable sample upstream")
	end

	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	proxy_set_header X-Forwarded-Proto $var_x_forwarded_proto;
	proxy_set_header X-Forwarded-Host $var_x_forwarded_host;
	proxy_set_header X-Forwarded-Port $var_x_forwarded_port;

	# trusted_addresses: # When enabled, APISIX will trust the `X-Forwarded-*` Headers
	# trusted_addresses: # When enabled, APISIX will trust the `X-Forwarded-*` Headers

	set $var_x_forwarded_proto $scheme;
	set $var_x_forwarded_host $host;
	set $var_x_forwarded_port $server_port;

	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	proxy_set_header X-Forwarded-Proto $var_x_forwarded_proto;
	proxy_set_header X-Forwarded-Host $var_x_forwarded_host;
	proxy_set_header X-Forwarded-Port $var_x_forwarded_port;

		local _M = {}


		local function validate_trusted_addresses(trusted_addresses)

Uh oh!

Conversation

SkyeYoung commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Which issue(s) this PR fixes:

Checklist

Uh oh!

SkyeYoung Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SkyeYoung Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SkyeYoung Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SkyeYoung Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SkyeYoung Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

SkyeYoung commented Aug 27, 2025 •

edited

Loading

SkyeYoung Aug 29, 2025 •

edited

Loading

SkyeYoung Sep 2, 2025 •

edited

Loading

SkyeYoung Sep 2, 2025 •

edited

Loading

SkyeYoung Sep 16, 2025 •

edited

Loading

SkyeYoung Sep 16, 2025 •

edited

Loading

SkyeYoung Sep 16, 2025 •

edited

Loading