RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
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.goindex 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))+ }// MiddlewareginEngine.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 thediff --git a/conf/service_conf.yaml b/conf/service_conf.yamlindex 73d3b7243b..6c34076f1a 100644--- a/conf/service_conf.yaml+++ b/conf/service_conf.yaml@@ -3,6 +3,12 @@ general:ragflow:host: 0.0.0.0http_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.0http_port: 9381diff --git a/docker/service_conf.yaml.template b/docker/service_conf.yaml.templateindex 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: 9381diff --git a/docs/administrator/configurations/configurations.md b/docs/administrator/configurations/configurations.mdindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.goindex 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.goindex 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 nildiff --git a/internal/server/config/api_server_config_test.go b/internal/server/config/api_server_config_test.gonew file mode 100644index 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)+ }+ })+ }+}