fix: only trust `X-Forwarded-*` headers from `trusted_addresses` #12551

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

apisix/init.lua

-
-    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;

apisix/init.lua

conf/config.yaml.example

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.}

apisix/init.lua

apisix/utils/trusted-addresses.lua

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

t/plugin/dubbo-proxy/upstream.t

    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

t/plugin/proxy-rewrite2.t

    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

t/plugin/sls-logger.t

        enable_encrypt_fields: true
        keyring:
            - edd1c9f0985e76a2
+    trusted_addresses:


Added in batches, removed

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

t/core/trusted-addresses.t

@@ -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

conf/config.yaml.example

                                        # 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

conf/config.yaml.example

                                  # 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

nic-6443 · 2025-09-15T02:22:37Z

apisix/cli/schema.lua

                    default = false,
                    description = "a global switch to disable upstream health checks",
                },
+                trusted_addresses = {


ref:

apisix/apisix/plugins/real-ip.lua

Lines 32 to 36 in bb71dfc

trusted_addresses = {

type = "array",

items = {anyOf = core.schema.ip_def},

minItems = 1

},

we can add more restrction to schema like this.

Adding core.schema.ip_def doesn't seem to work.

https://github.com/apache/apisix/blob/8bb6802bd2b2ccd4dabe78e90beb8f87ec046035/apisix/schema_def.lua depends on https://github.com/apache/apisix/blob/0fd582bc299a9d90893d3843cd3ec21f217cb40e/apisix/core/schema.lua

Using it will cause an error /usr/local/openresty//luajit/bin/luajit: ./apisix/core/lrucache.lua:22: module '\''resty.lrucache'\'' not found:

Using it will cause an error /usr/local/openresty//luajit/bin/luajit: ./apisix/core/lrucache.lua:22: module '''resty.lrucache''' not found:

What is the reason for this error？

The reason for this error is that there is no openresty environment in the apisix cli, which makes it impossible to use the resty.lru library.
I have considered the dependency relationship between schema_def.lua and schema.lua, and I think their dependency relationship is reversed. It should be that schema.lua depends on schema_def.lua, allowing schema_def.lua to retain only the definition of schema, in line with the naming of this file.
Added a new commit to this PR to fix this dependency issue: 30ce9c2

apisix/init.lua

…warded_headers`

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

t/core/trusted-addresses.t

+--- 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

apisix/cli/schema.lua

+                    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

apisix/init.lua

+        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

apisix/init.lua

+    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

apisix/utils/trusted-addresses.lua

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


we also need to check this when apisix starts.

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

apisix/init.lua

 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

apisix/cli/schema.lua

    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

apisix/core/schema.lua

apisix/core.lua

…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

apisix/init.lua Show resolved Hide resolved

conf/config.yaml.example Outdated Show resolved Hide resolved

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

apisix/init.lua Show resolved Hide resolved

apisix/utils/trusted-addresses.lua Show resolved Hide resolved

moonming requested changes Sep 2, 2025

View reviewed changes

chore: adjust config example

1b6e5e6

nic-6443 reviewed Sep 15, 2025

View reviewed changes

apisix/init.lua Outdated Show resolved Hide resolved

nic-6443 previously approved these changes Sep 15, 2025

View reviewed changes

chore: rename update_var_x_forwarded_headers to `set_upstream_x_for…

528116c

…warded_headers`

SkyeYoung dismissed nic-6443’s stale review via 528116c September 15, 2025 05:44

nic-6443 previously approved these changes Sep 15, 2025

View reviewed changes

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

apisix/core/schema.lua Show resolved Hide resolved

apisix/core.lua Show resolved Hide resolved

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)

	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

	trusted_addresses = {
	type = "array",
	items = {anyOf = core.schema.ip_def},
	minItems = 1
	},

	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)

fix: only trust X-Forwarded-* headers from trusted_addresses #12551

fix: only trust X-Forwarded-* headers from trusted_addresses #12551

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!

nic-6443 Sep 15, 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!

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!

fix: only trust `X-Forwarded-*` headers from `trusted_addresses` #12551

fix: only trust `X-Forwarded-*` headers from `trusted_addresses` #12551

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

nic-6443 Sep 15, 2025 •

edited

Loading

SkyeYoung Sep 16, 2025 •

edited

Loading

SkyeYoung Sep 16, 2025 •

edited

Loading

SkyeYoung Sep 16, 2025 •

edited

Loading