Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(api): stop trusting X-Forwarded-For from every peer in the agent webhook IP whitelist (#19550)

coderdailyoneaf02d0a6e81e
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.go
index e3fdd6a81d..57ece4f2a6 100644
--- a/cmd/ragflow_server.go
+++ b/cmd/ragflow_server.go
@@ -684,6 +684,11 @@ func runAdmin(ctx context.Context, args *serverArgs) error {
ginEngine := gin.New()
// Mirror Quart's merge_slashes: collapse duplicate slashes before routing.
ginEngine.RemoveExtraSlash = true
+ // Only honour X-Forwarded-For / X-Real-IP from the configured proxies
+ // (default: the loopback nginx bundled in the image), never from every peer.
+ if err := common.ConfigureTrustedProxies(ginEngine, globalConfig.GetAPIServerConfig().TrustedProxies); err != nil {
+ common.Fatal("Failed to configure trusted proxies", zap.Error(err))
+ }
// Middleware
ginEngine.Use(common.GinLogger())
@@ -1360,6 +1365,14 @@ func startServer(ctx context.Context) {
ginEngine := gin.New()
// Mirror Quart's merge_slashes: collapse duplicate slashes before routing.
ginEngine.RemoveExtraSlash = true
+ // Only honour X-Forwarded-For / X-Real-IP from the configured proxies
+ // (default: the loopback nginx bundled in the image), never from every
+ // peer. c.ClientIP() feeds the agent webhook ip_whitelist gate and the
+ // login audit records, so gin's trust-everything default would let any
+ // caller pick its own address.
+ if err := common.ConfigureTrustedProxies(ginEngine, globalConfig.GetAPIServerConfig().TrustedProxies); err != nil {
+ common.Fatal("Failed to configure trusted proxies", zap.Error(err))
+ }
// Middleware
// Note: common.GinLogger() is registered inside router.Setup so the
diff --git a/conf/service_conf.yaml b/conf/service_conf.yaml
index 73d3b7243b..6c34076f1a 100644
--- a/conf/service_conf.yaml
+++ b/conf/service_conf.yaml
@@ -3,6 +3,12 @@ general:
ragflow:
host: 0.0.0.0
http_port: 9380
+ # Proxies whose X-Forwarded-For / X-Real-IP headers the Go API server trusts
+ # when resolving the client address (agent webhook ip_whitelist, login audit).
+ # Defaults to loopback, i.e. the nginx bundled in this image. An explicit list
+ # replaces that default, so keep the loopback entries when adding the address
+ # or CIDR of a further proxy in front of nginx; an empty list trusts none.
+ # trusted_proxies: ['127.0.0.0/8', '::1/128']
admin:
host: 0.0.0.0
http_port: 9381
diff --git a/docker/service_conf.yaml.template b/docker/service_conf.yaml.template
index 37f2c8b6e8..8d66bfd9ad 100644
--- a/docker/service_conf.yaml.template
+++ b/docker/service_conf.yaml.template
@@ -3,6 +3,12 @@ general:
ragflow:
host: ${RAGFLOW_HOST:-0.0.0.0}
http_port: 9380
+ # Proxies whose X-Forwarded-For / X-Real-IP headers the Go API server trusts
+ # when resolving the client address (agent webhook ip_whitelist, login audit).
+ # Defaults to loopback, i.e. the nginx bundled in this image. An explicit list
+ # replaces that default, so keep the loopback entries when adding the address
+ # or CIDR of a further proxy in front of nginx; an empty list trusts none.
+ # trusted_proxies: ['127.0.0.0/8', '::1/128']
admin:
host: ${RAGFLOW_HOST:-0.0.0.0}
http_port: 9381
diff --git a/docs/administrator/configurations/configurations.md b/docs/administrator/configurations/configurations.md
index a1910c4b96..f1d5d75973 100644
--- a/docs/administrator/configurations/configurations.md
+++ b/docs/administrator/configurations/configurations.md
@@ -154,6 +154,7 @@ If you cannot download the RAGFlow Docker image, try the following mirrors.
- `host`: The API server's IP address inside the Docker container. Defaults to `0.0.0.0`.
- `http_port`: The API server's serving port inside the Docker container. Defaults to `9380`.
+- `trusted_proxies`: The proxy IPs or CIDRs whose `X-Forwarded-For` / `X-Real-IP` headers the Go API server trusts when resolving the client address (used by the agent webhook `ip_whitelist` and login audit records). Defaults to loopback (`['127.0.0.0/8', '::1/128']`), i.e. the nginx bundled in the Docker image. An explicit list *replaces* the default rather than extending it, so keep the loopback entries when adding a further proxy placed in front of nginx, for example `['127.0.0.0/8', '::1/128', '10.0.0.0/8']`; an empty list trusts no proxy headers at all.
### `mysql`
diff --git a/internal/common/trusted_proxies.go b/internal/common/trusted_proxies.go
new file mode 100644
index 0000000000..c0744aa0f2
--- /dev/null
+++ b/internal/common/trusted_proxies.go
@@ -0,0 +1,55 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed 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.
+//
+
+package common
+
+import (
+ "fmt"
+
+ "github.com/gin-gonic/gin"
+)
+
+// DefaultTrustedProxies is the proxy set whose X-Forwarded-For / X-Real-IP
+// headers gin honours when no `ragflow.trusted_proxies` list is configured.
+// It covers the nginx that docker/entrypoint.sh starts inside the same
+// container as this server: docker/nginx/ragflow.conf.golang proxies /v1 and
+// /api to 127.0.0.1:9384 and proxy.conf appends the caller to
+// X-Forwarded-For. Nothing else is trusted, so a request that reaches the
+// server from any other peer is attributed to that peer regardless of the
+// headers it carries.
+var DefaultTrustedProxies = []string{"127.0.0.0/8", "::1/128"}
+
+// ConfigureTrustedProxies replaces gin's default trust-everything proxy list
+// (0.0.0.0/0, ::/0) with proxies, falling back to DefaultTrustedProxies when
+// proxies is nil. An explicitly empty list disables header-based client IP
+// resolution entirely, making c.ClientIP() the socket peer for every request.
+// Every c.ClientIP() consumer (the agent webhook ip_whitelist gate, login
+// audit records, access logs) depends on this being applied to the engine.
+func ConfigureTrustedProxies(engine *gin.Engine, proxies []string) error {
+ if proxies == nil {
+ proxies = DefaultTrustedProxies
+ }
+ if err := engine.SetTrustedProxies(proxies); err != nil {
+ return fmt.Errorf("invalid trusted_proxies %v: %w", proxies, err)
+ }
+ // gin also consults X-Real-IP by default. The bundled nginx
+ // (docker/nginx/proxy.conf) only rewrites X-Forwarded-For, so X-Real-IP
+ // would reach the server exactly as the caller wrote it and a trusted peer
+ // that forwards no X-Forwarded-For would let it name the client. Only the
+ // header the proxy owns is honoured.
+ engine.RemoteIPHeaders = []string{"X-Forwarded-For"}
+ return nil
+}
diff --git a/internal/common/trusted_proxies_test.go b/internal/common/trusted_proxies_test.go
new file mode 100644
index 0000000000..10cd05d448
--- /dev/null
+++ b/internal/common/trusted_proxies_test.go
@@ -0,0 +1,91 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed 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.
+//
+
+package common
+
+import (
+ "net/http/httptest"
+ "testing"
+
+ "github.com/gin-gonic/gin"
+)
+
+func clientIPWith(t *testing.T, proxies []string, remoteAddr, forwardedFor string) string {
+ t.Helper()
+ gin.SetMode(gin.TestMode)
+ c, engine := gin.CreateTestContext(httptest.NewRecorder())
+ if err := ConfigureTrustedProxies(engine, proxies); err != nil {
+ t.Fatalf("ConfigureTrustedProxies(%v): %v", proxies, err)
+ }
+ c.Request = httptest.NewRequest("GET", "/", nil)
+ c.Request.RemoteAddr = remoteAddr
+ if forwardedFor != "" {
+ c.Request.Header.Set("X-Forwarded-For", forwardedFor)
+ }
+ return c.ClientIP()
+}
+
+func TestConfigureTrustedProxies(t *testing.T) {
+ for _, test := range []struct {
+ name string
+ proxies []string
+ remoteAddr string
+ forwardedFor string
+ want string
+ }{
+ {name: "default trusts loopback nginx", proxies: nil, remoteAddr: "127.0.0.1:0", forwardedFor: "203.0.113.7", want: "203.0.113.7"},
+ {name: "default ignores headers from other peers", proxies: nil, remoteAddr: "192.168.1.5:0", forwardedFor: "203.0.113.7", want: "192.168.1.5"},
+ {name: "default stops at first undeclared hop", proxies: nil, remoteAddr: "127.0.0.1:0", forwardedFor: "203.0.113.7, 198.51.100.9", want: "198.51.100.9"},
+ {name: "configured proxy honoured", proxies: []string{"10.0.0.0/8"}, remoteAddr: "10.1.2.3:0", forwardedFor: "203.0.113.7", want: "203.0.113.7"},
+ {name: "configured list replaces loopback", proxies: []string{"10.0.0.0/8"}, remoteAddr: "127.0.0.1:0", forwardedFor: "203.0.113.7", want: "127.0.0.1"},
+ {name: "empty list trusts nobody", proxies: []string{}, remoteAddr: "127.0.0.1:0", forwardedFor: "203.0.113.7", want: "127.0.0.1"},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ if got := clientIPWith(t, test.proxies, test.remoteAddr, test.forwardedFor); got != test.want {
+ t.Fatalf("ClientIP = %q, want %q", got, test.want)
+ }
+ })
+ }
+}
+
+func TestConfigureTrustedProxiesRejectsInvalidEntry(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ if err := ConfigureTrustedProxies(gin.New(), []string{"not-an-ip"}); err == nil {
+ t.Fatal("expected an error for an unparsable trusted proxy entry")
+ }
+}
+
+// The bundled nginx never sets X-Real-IP, so a trusted loopback peer that
+// forwards no X-Forwarded-For must not let a caller-supplied X-Real-IP name
+// the client.
+func TestConfigureTrustedProxiesIgnoresXRealIP(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ c, engine := gin.CreateTestContext(httptest.NewRecorder())
+ if err := ConfigureTrustedProxies(engine, nil); err != nil {
+ t.Fatalf("ConfigureTrustedProxies(nil): %v", err)
+ }
+ c.Request = httptest.NewRequest("GET", "/", nil)
+ c.Request.RemoteAddr = "127.0.0.1:41000"
+ c.Request.Header.Set("X-Real-IP", "203.0.113.7")
+ if got := c.ClientIP(); got != "127.0.0.1" {
+ t.Fatalf("ClientIP() = %q, want the loopback peer; X-Real-IP must not be trusted", got)
+ }
+
+ c.Request.Header.Set("X-Forwarded-For", "198.51.100.9")
+ if got := c.ClientIP(); got != "198.51.100.9" {
+ t.Fatalf("ClientIP() = %q, want the X-Forwarded-For client from the trusted proxy", got)
+ }
+}
diff --git a/internal/handler/agent_webhook_security.go b/internal/handler/agent_webhook_security.go
index fbb4fada1d..09302f8ed6 100644
--- a/internal/handler/agent_webhook_security.go
+++ b/internal/handler/agent_webhook_security.go
@@ -202,8 +202,16 @@ func parseMaxBodySize(cfg map[string]any) (int64, error) {
// validateIPWhitelist mirrors python agent_api.py:1660-1679. Empty
// list → allow. Supports CIDR ("10.0.0.0/8") and exact ("1.2.3.4").
-// The client IP comes from gin's c.ClientIP() which honours
-// X-Forwarded-For when trusted proxies are configured.
+//
+// This is a security gate, so the address it checks must be one the
+// caller cannot choose. c.ClientIP() takes X-Forwarded-For / X-Real-IP
+// only when the direct peer is in the engine's trusted proxy list and
+// falls back to the socket peer otherwise; the engine is configured via
+// common.ConfigureTrustedProxies (default: loopback, the nginx bundled
+// in the image) instead of gin's trust-everything default, which let any
+// caller send "X-Forwarded-For: <an-allowed-ip>" and pass. The socket
+// peer alone (c.RemoteIP()) is not usable here because behind that
+// bundled nginx it is 127.0.0.1 for every request.
func validateIPWhitelist(c *gin.Context, cfg map[string]any) error {
whitelist, _ := cfg["ip_whitelist"].([]any)
if len(whitelist) == 0 {
diff --git a/internal/handler/agent_webhook_security_test.go b/internal/handler/agent_webhook_security_test.go
index 2baf3f0ddc..feb8c612c3 100644
--- a/internal/handler/agent_webhook_security_test.go
+++ b/internal/handler/agent_webhook_security_test.go
@@ -30,13 +30,19 @@ import (
"github.com/gin-gonic/gin"
"github.com/golang-jwt/jwt/v5"
+
+ "ragflow/internal/common"
)
func securityCtx(t *testing.T, remoteAddr string, headers map[string]string) *gin.Context {
t.Helper()
gin.SetMode(gin.TestMode)
w := httptest.NewRecorder()
- c, _ := gin.CreateTestContext(w)
+ c, engine := gin.CreateTestContext(w)
+ // Same trust boundary as the production engine in cmd/ragflow_server.go.
+ if err := common.ConfigureTrustedProxies(engine, nil); err != nil {
+ t.Fatalf("ConfigureTrustedProxies: %v", err)
+ }
c.Request = httptest.NewRequest("POST", "/api/v1/agents/c1/webhook", strings.NewReader("{}"))
c.Request.Header.Set("Content-Type", "application/json")
c.Request.RemoteAddr = remoteAddr
@@ -477,3 +483,72 @@ func newSecurityCtx(canvasID string) *gin.Context {
c.Request = httptest.NewRequest(http.MethodPost, "/api/v1/agents/"+canvasID+"/webhook", nil)
return c
}
+
+// TestValidateIPWhitelist_IgnoresForwardedForSpoof asserts that a peer
+// outside the trusted proxy list is judged by its socket address, not by
+// the X-Forwarded-For / X-Real-IP headers it sends. Under gin's
+// trust-everything default the spoofed header value would have satisfied
+// the allowlist.
+func TestValidateIPWhitelist_IgnoresForwardedForSpoof(t *testing.T) {
+ // Real peer 192.168.1.5 is not on the list; the headers claim 10.0.0.5.
+ c := securityCtx(t, "192.168.1.5:0", map[string]string{
+ "X-Forwarded-For": "10.0.0.5",
+ "X-Real-IP": "10.0.0.5",
+ })
+ cfg := map[string]any{"ip_whitelist": []any{"10.0.0.5", "10.0.0.0/8"}}
+ err := validateIPWhitelist(c, cfg)
+ if err == nil || !strings.Contains(err.Error(), "not allowed by whitelist") {
+ t.Fatalf("spoofed X-Forwarded-For must not satisfy the whitelist: err = %v", err)
+ }
+ if strings.Contains(err.Error(), "10.0.0.5") {
+ t.Fatalf("rejection should report the real peer, not the spoofed header: %v", err)
+ }
+}
+
+// TestValidateIPWhitelist_AllowsRealPeerDespiteSpoof confirms a peer that is
+// genuinely on the list still passes even when the headers claim otherwise.
+func TestValidateIPWhitelist_AllowsRealPeerDespiteSpoof(t *testing.T) {
+ c := securityCtx(t, "10.0.0.5:0", map[string]string{
+ "X-Forwarded-For": "8.8.8.8",
+ })
+ cfg := map[string]any{"ip_whitelist": []any{"10.0.0.0/8"}}
+ if err := validateIPWhitelist(c, cfg); err != nil {
+ t.Fatalf("real peer on the list must pass: err = %v", err)
+ }
+}
+
+// TestValidateIPWhitelist_BehindBundledProxy covers the shipped deployment:
+// docker/entrypoint.sh runs nginx in the same container and
+// docker/nginx/ragflow.conf.golang proxies the webhook route to
+// 127.0.0.1:9384 with X-Forwarded-For set by proxy.conf. The socket peer is
+// therefore always loopback and the whitelist has to be evaluated against
+// the forwarded address, which the loopback default in
+// common.DefaultTrustedProxies makes gin.ClientIP() return.
+func TestValidateIPWhitelist_BehindBundledProxy(t *testing.T) {
+ cfg := map[string]any{"ip_whitelist": []any{"203.0.113.7"}}
+
+ allowed := securityCtx(t, "127.0.0.1:0", map[string]string{
+ "X-Forwarded-For": "203.0.113.7",
+ })
+ if err := validateIPWhitelist(allowed, cfg); err != nil {
+ t.Fatalf("listed caller forwarded by the bundled nginx must pass: err = %v", err)
+ }
+
+ denied := securityCtx(t, "127.0.0.1:0", map[string]string{
+ "X-Forwarded-For": "198.51.100.9",
+ })
+ err := validateIPWhitelist(denied, cfg)
+ if err == nil || !strings.Contains(err.Error(), "198.51.100.9") {
+ t.Fatalf("unlisted caller forwarded by the bundled nginx must be rejected by its own address: err = %v", err)
+ }
+
+ // A caller that reaches nginx through a further, undeclared hop is
+ // attributed to that hop, never to the leftmost value it chose itself.
+ chained := securityCtx(t, "127.0.0.1:0", map[string]string{
+ "X-Forwarded-For": "203.0.113.7, 198.51.100.9",
+ })
+ err = validateIPWhitelist(chained, cfg)
+ if err == nil || !strings.Contains(err.Error(), "198.51.100.9") {
+ t.Fatalf("spoofed leftmost X-Forwarded-For entry must not pass: err = %v", err)
+ }
+}
diff --git a/internal/server/config/api_server_config.go b/internal/server/config/api_server_config.go
index 7184a71732..2d212de8a3 100644
--- a/internal/server/config/api_server_config.go
+++ b/internal/server/config/api_server_config.go
@@ -26,6 +26,13 @@ type AuthenticationConfig struct {
type APIServerConfig struct {
Host string `mapstructure:"host"`
HTTPPort int `mapstructure:"http_port"`
+ // TrustedProxies lists the IPs / CIDRs whose X-Forwarded-For and
+ // X-Real-IP headers are trusted when resolving the client address.
+ // nil means "not configured" and resolves to common.DefaultTrustedProxies
+ // (loopback, i.e. the nginx bundled in the ragflow image). An explicit
+ // list replaces that default rather than extending it, and an empty
+ // list trusts no proxy at all.
+ TrustedProxies []string `mapstructure:"trusted_proxies"`
Authentication AuthenticationConfig `mapstructure:"authentication"`
}
@@ -55,6 +62,14 @@ func (c *Config) ParseAPIServerConfig(v *viper.Viper) error {
c.apiServer.HTTPPort = 9384
}
+ if sub.IsSet("trusted_proxies") {
+ proxies := sub.GetStringSlice("trusted_proxies")
+ if proxies == nil {
+ proxies = []string{}
+ }
+ c.apiServer.TrustedProxies = proxies
+ }
+
c.parseAuthenticationConfig(v)
return nil
diff --git a/internal/server/config/api_server_config_test.go b/internal/server/config/api_server_config_test.go
new file mode 100644
index 0000000000..842951ac8f
--- /dev/null
+++ b/internal/server/config/api_server_config_test.go
@@ -0,0 +1,50 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed 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.
+//
+
+package config
+
+import (
+ "reflect"
+ "testing"
+
+ "github.com/spf13/viper"
+)
+
+func TestParseAPIServerConfigTrustedProxies(t *testing.T) {
+ for _, test := range []struct {
+ name string
+ values map[string]interface{}
+ want []string
+ }{
+ // nil means "not configured": the engine falls back to the loopback default.
+ {name: "unset", values: map[string]interface{}{"http_port": 9380}, want: nil},
+ {name: "explicit list", values: map[string]interface{}{"trusted_proxies": []string{"10.0.0.0/8", "192.168.1.5"}}, want: []string{"10.0.0.0/8", "192.168.1.5"}},
+ // An explicit empty list must survive as empty (trust nobody), not collapse to nil.
+ {name: "explicit empty", values: map[string]interface{}{"trusted_proxies": []string{}}, want: []string{}},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ v := viper.New()
+ v.Set("ragflow", test.values)
+ cfg := &Config{}
+ if err := cfg.ParseAPIServerConfig(v); err != nil {
+ t.Fatalf("ParseAPIServerConfig: %v", err)
+ }
+ if got := cfg.GetAPIServerConfig().TrustedProxies; !reflect.DeepEqual(got, test.want) {
+ t.Fatalf("TrustedProxies = %#v, want %#v", got, test.want)
+ }
+ })
+ }
+}