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

apisix/cli/schema.lua

@@ -259,6 +259,14 @@ local config_schema = {
                     default = false,
                     description = "a global switch to disable upstream health checks",
                 },
+                trusted_addresses = {
+                    type = "array",
+                    minItems = 1,
+                    items = {
+                        type = "string",
+                    },
+                    uniqueItems = true
+                },
             }
         },
         nginx_config = {

apisix/init.lua

@@ -45,6 +45,7 @@ local xrpc            = require("apisix.stream.xrpc")
 local ctxdump         = require("resty.ctxdump")
 local debug           = require("apisix.debug")
 local pubsub_kafka    = require("apisix.pubsub.kafka")
+local trusted_addresses_util = require("apisix.utils.trusted-addresses")
 local ngx             = ngx
 local get_method      = ngx.req.get_method
 local ngx_exit        = ngx.exit
@@ -159,6 +160,8 @@ function _M.http_init_worker()
     -- To ensure that all workers related to Prometheus metrics are initialized,
     -- we need to put the initialization of the Prometheus plugin here.
     plugin.init_prometheus()
+
+    trusted_addresses_util.init_worker()
 end
 
 
@@ -290,21 +293,6 @@ end
 
 local function set_upstream_headers(api_ctx, picked_server)
     set_upstream_host(api_ctx, picked_server)
-
-    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
 end
 
 
@@ -599,6 +587,54 @@ function _M.handle_upstream(api_ctx, route, enable_websocket)
 end
 
 
+local function handle_x_forwarded_headers(api_ctx)
+    local addr_is_trusted = trusted_addresses_util.is_trusted(api_ctx.var.realip_remote_addr)
+
+    if not addr_is_trusted then
+        -- store the original x-forwarded-* headers
+        -- to allow future use by other plugins or processes
+        api_ctx.var.original_x_forwarded_proto = api_ctx.var.http_x_forwarded_proto
+        api_ctx.var.original_x_forwarded_host = api_ctx.var.http_x_forwarded_host
+        api_ctx.var.original_x_forwarded_port = api_ctx.var.http_x_forwarded_port
+        api_ctx.var.original_x_forwarded_for = api_ctx.var.http_x_forwarded_for
+
+        local proto = api_ctx.var.scheme
+        local host = api_ctx.var.host
+        local port = api_ctx.var.server_port
+
+        api_ctx.var.http_x_forwarded_proto = proto
+        api_ctx.var.http_x_forwarded_host = host
+        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
+        core.request.set_header(api_ctx, "X-Forwarded-Proto", proto)
+        core.request.set_header(api_ctx, "X-Forwarded-Host", host)
+        core.request.set_header(api_ctx, "X-Forwarded-Port", port)
+        -- later processed in ngx_tpl by `$proxy_add_x_forwarded_for`
+        core.request.set_header(api_ctx, "X-Forwarded-For", nil)
+    end
+end
+
+
+local function set_upstream_x_forwarded_headers(api_ctx)
+    local proto = api_ctx.var.http_x_forwarded_proto
+    if proto then
+        api_ctx.var.var_x_forwarded_proto = proto
+    end
+
+    local port = api_ctx.var.http_x_forwarded_port
+    if port then
+        api_ctx.var.var_x_forwarded_port = port
+    end
+
+    local host = api_ctx.var.http_x_forwarded_host
+    if host then
+        api_ctx.var.var_x_forwarded_host = host
+    end
+end
+
+
 function _M.http_access_phase()
     -- from HTTP/3 to HTTP/1.1 we need to convert :authority pesudo-header
     -- to Host header, so we set upstream_host variable here.
@@ -648,6 +684,8 @@ function _M.http_access_phase()
     api_ctx.var.real_request_uri = api_ctx.var.request_uri
     api_ctx.var.request_uri = api_ctx.var.uri .. api_ctx.var.is_args .. (api_ctx.var.args or "")
 
+    handle_x_forwarded_headers(api_ctx)
+
     router.router_http.match(api_ctx)
 
     local route = api_ctx.matched_route
@@ -754,6 +792,8 @@ function _M.http_access_phase()
     end
 
     _M.handle_upstream(api_ctx, route, enable_websocket)
+
+    set_upstream_x_forwarded_headers(api_ctx)
 end
 
 

apisix/utils/trusted-addresses.lua

@@ -0,0 +1,67 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements.  See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License.  You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local require       = require
+local core          = require("apisix.core")
+local ipairs        = ipairs
+
+local trusted_addresses_matcher
+
+local _M = {}
+
+
+local function validate_trusted_addresses(trusted_addresses)
+    for _, cidr in ipairs(trusted_addresses) do
+        if not core.ip.validate_cidr_or_ip(cidr) then
+            core.log.error("invalid IP/CIDR '", cidr, "' exists in trusted_addresses")
+            return false
+        end
+    end
+    return true
+end
+
+function _M.init_worker()
+    local local_conf = core.config.local_conf()
+    local trusted_addresses = core.table.try_read_attr(local_conf, "apisix", "trusted_addresses")
+
+    if not trusted_addresses then
+        core.log.info("trusted_addresses is not configured")
+        return
+    end
+
+    if not validate_trusted_addresses(trusted_addresses) then
+        return
+    end
+
+    local matcher, err = core.ip.create_ip_matcher(trusted_addresses)
+    if not matcher then
+        core.log.error("failed to create ip matcher for trusted_addresses: ", err)
+        return
+    end
+
+    trusted_addresses_matcher = matcher
+end
+
+
+function _M.is_trusted(address)
+    if not trusted_addresses_matcher then
+        core.log.info("trusted_addresses_matcher is not initialized")
+        return false
+    end
+    return trusted_addresses_matcher:match(address)
+end
+
+return _M

conf/config.yaml.example

@@ -141,6 +141,10 @@ apisix:
                                   # 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 configured, APISIX will trust the `X-Forwarded-*` Headers
+#   - 127.0.0.1                   # passed in requests from the IP/CIDR in the list.
+#   - 172.18.0.0/16               # CAUTION: When not configured or the request from an untrusted address,
+                                  # APISIX will override `X-Forwarded-*` headers with trusted values.
 nginx_config:                     # Config for render the template to generate nginx.conf
   # user: root                    # Set the execution user of the worker process. This is only
                                   # effective if the master process runs with super-user privileges.

docs/en/latest/plugins/chaitin-waf.md

@@ -90,7 +90,10 @@ The examples below demonstrate how you can configure chaitin-waf Plugin for diff
 Before proceeding, make sure you have installed [Chaitin WAF (SafeLine)](https://docs.waf.chaitin.com/en/GetStarted/Deploy).
 
 :::note
+Only `X-Forwarded-*` headers sent from addresses in the `apisix.trusted_addresses` configuration (supports IP and CIDR) will be trusted and passed to plugins or upstream. If `apisix.trusted_addresses` is not configured or the IP is not within the configured address range, all `X-Forwarded-*` headers will be overridden with trusted values.
+:::
 
+:::note
 You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
 
 ```bash

docs/en/latest/plugins/real-ip.md

@@ -45,6 +45,10 @@ The Plugin is functionally similar to NGINX's [ngx_http_realip_module](https://n
 | trusted_addresses | array[string] | False |     | array of IPv4 or IPv6 addresses (CIDR notation acceptable)  | Trusted addresses that are known to send correct replacement addresses. This configuration sets the [`set_real_ip_from`](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. |
 | recursive  | boolean | False |  False   |    | If false, replace the original client address that matches one of the trusted addresses by the last address sent in the configured `source`.<br />If true, replace the original client address that matches one of the trusted addresses by the last non-trusted address sent in the configured `source`. |
 
+:::note
+Only `X-Forwarded-*` headers sent from addresses in the `apisix.trusted_addresses` configuration (supports IP and CIDR) will be trusted and passed to plugins or upstream. If `apisix.trusted_addresses` is not configured or the IP is not within the configured address range, all `X-Forwarded-*` headers will be overridden with trusted values.
+:::
+
 :::note
 If the address specified in `source` is missing or invalid, the Plugin would not change the client address.
 :::

docs/zh/latest/plugins/chaitin-waf.md

@@ -89,6 +89,10 @@ description: chaitin-waf 插件与长亭雷池 WAF 集成，以检测和阻止
 
 继续操作之前，请确保您已安装 [长亭雷池 WAF](https://docs.waf.chaitin.com/en/GetStarted/Deploy)。
 
+:::note
+只有发送自 `apisix.trusted_addresses` 配置（支持 IP 和 CIDR）地址的 `X-Forwarded-*` 头才会被信任，并传递给插件或上游。如果未配置 `apisix.trusted_addresses` 或 ip 不在配置地址范围内的，`X-Forwarded-*` 头将全部被可信值覆盖。
+:::
+
 :::note
 
 您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：

docs/zh/latest/plugins/real-ip.md

@@ -45,6 +45,10 @@ description: real-ip 插件允许 Apache APISIX 通过 HTTP 请求头或 HTTP 
 | trusted_addresses | array[string] | 否       |        | IPv4 或 IPv6 地址数组（接受 CIDR 表示法） | 已知会发送正确替代地址的可信地址。此配置设置 [`set_real_ip_from`](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) 指令。 |
 | recursive         | boolean       | 否       | false  |                            | 如果为 false，则将匹配可信地址之一的原始客户端地址替换为配置的 `source` 中发送的最后一个地址。<br />如果为 true，则将匹配可信地址之一的原始客户端地址替换为配置的 `source` 中发送的最后一个非可信地址。 |
 
+:::note
+只有发送自 `apisix.trusted_addresses` 配置（支持 IP 和 CIDR）地址的 `X-Forwarded-*` 头才会被信任，并传递给插件或上游。如果未配置 `apisix.trusted_addresses` 或 ip 不在配置地址范围内的，`X-Forwarded-*` 头将全部被可信值覆盖。
+:::
+
 :::note
 如果 `source` 属性中设置的地址丢失或者无效，该插件将不会更改客户端地址。
 :::

t/APISIX.pm

@@ -105,6 +105,8 @@ apisix:
     tcp:
       - 9100
   enable_resolv_search_opt: false
+  trusted_addresses:
+    - "127.0.0.1"
 _EOC_
 
 my $etcd_enable_auth = $ENV{"ETCD_ENABLE_AUTH"} || "false";

t/cli/test_validate_config.sh

@@ -204,3 +204,96 @@ if ! echo "$out" | grep 'property "host" validation failed'; then
 fi
 
 echo "passed: check etcd schema during init"
+
+# Test trusted_addresses with non-array value (string instead of array)
+echo '
+apisix:
+  trusted_addresses: "127.0.0.1"
+deployment:
+  role: traditional
+  role_traditional:
+    config_provider: etcd
+etcd:
+  host:
+    - "http://127.0.0.1:2379"
+  prefix: "/apisix"
+' > conf/config.yaml
+
+out=$(make init 2>&1 || true)
+if ! echo "$out" | grep 'property "trusted_addresses" validation failed: wrong type: expected array, got string'; then
+    echo "failed: trusted_addresses should reject string value"
+    exit 1
+fi
+
+echo "passed: trusted_addresses rejects non-array value"
+
+# Test trusted_addresses with empty array (should be rejected)
+echo '
+apisix:
+  trusted_addresses: []
+deployment:
+  role: traditional
+  role_traditional:
+    config_provider: etcd
+etcd:
+  host:
+    - "http://127.0.0.1:2379"
+  prefix: "/apisix"
+' > conf/config.yaml
+
+out=$(make init 2>&1 || true)
+if ! echo "$out" | grep 'property "trusted_addresses" validation failed: expect array to have at least 1 items'; then
+    echo "failed: trusted_addresses should reject empty array"
+    exit 1
+fi
+
+echo "passed: trusted_addresses rejects empty array"
+
+# Test trusted_addresses with non-string items in array
+echo '
+apisix:
+  trusted_addresses:
+    - "127.0.0.1"
+    - 123
+deployment:
+  role: traditional
+  role_traditional:
+    config_provider: etcd
+etcd:
+  host:
+    - "http://127.0.0.1:2379"
+  prefix: "/apisix"
+' > conf/config.yaml
+
+out=$(make init 2>&1 || true)
+if ! echo "$out" | grep 'property "trusted_addresses" validation failed: failed to validate item 2: wrong type: expected string, got number'; then
+    echo "failed: trusted_addresses should reject non-string items"
+    exit 1
+fi
+
+echo "passed: trusted_addresses rejects non-string array items"
+
+# Test trusted_addresses with duplicate items (should be rejected)
+echo '
+apisix:
+  trusted_addresses:
+    - "127.0.0.1"
+    - "192.168.1.1"
+    - "127.0.0.1"
+deployment:
+  role: traditional
+  role_traditional:
+    config_provider: etcd
+etcd:
+  host:
+    - "http://127.0.0.1:2379"
+  prefix: "/apisix"
+' > conf/config.yaml
+
+out=$(make init 2>&1 || true)
+if ! echo "$out" | grep 'property "trusted_addresses" validation failed.*equal'; then
+    echo "failed: trusted_addresses should reject duplicate items"
+    exit 1
+fi
+
+echo "passed: trusted_addresses rejects duplicate items"