Skip to content

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

fix(syncer): honor ALLOW_ANY_HOST for private database hosts (#20574)

Öndery6ea926239d7d
diff --git a/docker/.env b/docker/.env
index 4e8f90d193..b3a566a3bb 100644
--- a/docker/.env
+++ b/docker/.env
@@ -303,8 +303,10 @@ SVR_MCP_PORT=9382
# first login.
ADMIN_DEFAULT_PASSWORD=admin
-# Development-only: set to 1 to bypass host safety checks for test_db_connection and allow private/local database hosts.
-# Do not enable in production.
+# Development-only: set to 1 to allow private database and connector hosts
+# (MySQL, PostgreSQL, IMAP, test_db_connection, ExeSQL), including
+# host.docker.internal. The dial stays pinned to the resolved address.
+# Agent URL and Invoke checks stay in force. Do not enable in production.
ALLOW_ANY_HOST=0
# The RAGFlow Docker image to download. v0.22+ doesn't include embedding models.
diff --git a/internal/agent/tool/ssrf.go b/internal/agent/tool/ssrf.go
index ca996249dd..12c03aaadc 100644
--- a/internal/agent/tool/ssrf.go
+++ b/internal/agent/tool/ssrf.go
@@ -153,6 +153,8 @@ func isNonGlobalIP(ip net.IP) bool {
return err != nil
}
+// allowAnyHost reports the in-memory test override. ValidateDBHost also
+// honors ALLOW_ANY_HOST; ResolveAndValidate does not.
func allowAnyHost() bool {
return common.AllowAnyHostForTest
}
@@ -177,19 +179,14 @@ func ValidateDBHost(host string) (string, error) {
return "", fmt.Errorf("%w: empty host", ErrSSRFBlocked)
}
- // Mirror ResolveAndValidate's test-only bypass.
+ // Operator opt-in. ResolveAndValidate does not use this path, so
+ // user-controlled URLs stay strict.
+ if pinned, enabled, err := common.PinConfiguredPrivateHost(host); enabled {
+ return pinned, err
+ }
+ // In-memory test hook. Still resolve so the SQL dial stays pinned.
if allowAnyHost() {
- if ip := net.ParseIP(host); ip != nil {
- return ip.String(), nil
- }
- addrs, lerr := common.LookupHost(host)
- if lerr != nil {
- return "", fmt.Errorf("ssrf: resolve %s: %w", host, lerr)
- }
- if len(addrs) == 0 {
- return "", fmt.Errorf("ssrf: %s has no A/AAAA records", host)
- }
- return addrs[0], nil
+ return common.ResolveHostPin(host)
}
// Short-circuit the well-known host aliases DNS lookups may also
diff --git a/internal/agent/tool/ssrf_test.go b/internal/agent/tool/ssrf_test.go
index b0f6eeca52..2f279181b6 100644
--- a/internal/agent/tool/ssrf_test.go
+++ b/internal/agent/tool/ssrf_test.go
@@ -202,14 +202,47 @@ func TestResolveAndValidate(t *testing.T) {
})
}
-func TestResolveAndValidateProductionEnvCannotDisableGuard(t *testing.T) {
+// TestResolveAndValidateProductionEnvCannotDisableURLGuard checks that
+// ALLOW_ANY_HOST does not relax user-controlled URL checks, while a
+// database host dial still accepts the resolved address.
+func TestResolveAndValidateProductionEnvCannotDisableURLGuard(t *testing.T) {
t.Setenv(common.EnvAllowAnyHost, "true")
if _, _, err := ResolveAndValidate("http://127.0.0.1/"); err == nil {
t.Fatal("ResolveAndValidate(loopback) = nil, want SSRF rejection")
}
- if _, err := ValidateDBHost("127.0.0.1"); err == nil {
- t.Fatal("ValidateDBHost(loopback) = nil, want SSRF rejection")
+
+ dbHost, err := ValidateDBHost("127.0.0.1")
+ if err != nil {
+ t.Fatalf("ValidateDBHost(loopback) = %v, want nil when ALLOW_ANY_HOST is set", err)
+ }
+ if dbHost != "127.0.0.1" {
+ t.Fatalf("ValidateDBHost(loopback) = %q, want 127.0.0.1", dbHost)
+ }
+}
+
+// TestValidateDBHostAllowAnyHostPinsPrivateResolution checks that a
+// private DNS answer is accepted and the dial stays pinned to that IP.
+func TestValidateDBHostAllowAnyHostPinsPrivateResolution(t *testing.T) {
+ t.Setenv(common.EnvAllowAnyHost, "1")
+ orig := common.LookupHost
+ common.LookupHost = func(host string) ([]string, error) {
+ if host == "host.docker.internal" {
+ return []string{"192.168.65.254"}, nil
+ }
+ return nil, errors.New("no such host")
+ }
+ t.Cleanup(func() { common.LookupHost = orig })
+
+ got, err := ValidateDBHost("host.docker.internal")
+ if err != nil {
+ t.Fatalf("ValidateDBHost(host.docker.internal) = %v", err)
+ }
+ if got != "192.168.65.254" {
+ t.Fatalf("ValidateDBHost(host.docker.internal) = %q, want 192.168.65.254", got)
+ }
+ if _, err = ValidateDBHost("missing.internal"); err == nil {
+ t.Fatal("unresolvable host must still fail when ALLOW_ANY_HOST is set")
}
}
diff --git a/internal/common/allow_private_host.go b/internal/common/allow_private_host.go
new file mode 100644
index 0000000000..b8651fb753
--- /dev/null
+++ b/internal/common/allow_private_host.go
@@ -0,0 +1,100 @@
+//
+// 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"
+ "net"
+ "strings"
+ "sync"
+
+ "go.uber.org/zap"
+)
+
+// AllowConfiguredPrivateHost reports whether ALLOW_ANY_HOST is set to a
+// truthy value (1, true, yes, on), matching the Python host guard.
+//
+// The flag is the development opt-in documented in docker/.env. It applies
+// only to host-based database and connector dials (MySQL, PostgreSQL, IMAP,
+// test_db_connection, ExeSQL), including host.docker.internal. URL and Invoke
+// guards do not call this, so the flag cannot turn off DNS pinning for
+// user-controlled URLs. Default is off.
+func AllowConfiguredPrivateHost() bool {
+ switch strings.ToLower(strings.TrimSpace(GetEnv(EnvAllowAnyHost))) {
+ case "1", "true", "yes", "on":
+ return true
+ default:
+ return false
+ }
+}
+
+var noteAllowConfiguredPrivateHost sync.Once
+
+// noteConfiguredPrivateHost logs once that private hosts are permitted.
+func noteConfiguredPrivateHost(host string) {
+ noteAllowConfiguredPrivateHost.Do(func() {
+ zap.L().Warn("ALLOW_ANY_HOST is enabled; private database and connector hosts are allowed",
+ zap.String("host", host),
+ )
+ })
+}
+
+// PinConfiguredPrivateHost is the shared host-dial opt-in. When ALLOW_ANY_HOST
+// is unset, enabled is false and the caller keeps the strict public-address
+// check. When it is set, the host is resolved and the dial must use the
+// returned address. enabled stays true when resolution fails.
+func PinConfiguredPrivateHost(host string) (pinned string, enabled bool, err error) {
+ if !AllowConfiguredPrivateHost() {
+ return "", false, nil
+ }
+ noteConfiguredPrivateHost(host)
+ pinned, err = ResolveHostPin(host)
+ return pinned, true, err
+}
+
+// ResolveHostPin resolves host and returns the first address without checking
+// whether it is globally routable. Callers dial the returned IP so a later
+// DNS change cannot rebind the connection.
+func ResolveHostPin(host string) (string, error) {
+ host = strings.TrimSpace(host)
+ if host == "" {
+ return "", fmt.Errorf("host is missing")
+ }
+ if ip := net.ParseIP(host); ip != nil {
+ return ip.String(), nil
+ }
+
+ addresses, err := LookupHost(host)
+ if err != nil {
+ return "", fmt.Errorf("could not resolve hostname '%s': %w", host, err)
+ }
+ if len(addresses) == 0 {
+ return "", fmt.Errorf("hostname '%s' resolved to no addresses", host)
+ }
+
+ var resolved string
+ for _, addr := range addresses {
+ ip := net.ParseIP(addr)
+ if ip == nil {
+ return "", fmt.Errorf("could not parse resolved address '%s' for hostname '%s'", addr, host)
+ }
+ if resolved == "" {
+ resolved = ip.String()
+ }
+ }
+ return resolved, nil
+}
diff --git a/internal/common/allow_private_host_test.go b/internal/common/allow_private_host_test.go
new file mode 100644
index 0000000000..e7c40f54ae
--- /dev/null
+++ b/internal/common/allow_private_host_test.go
@@ -0,0 +1,109 @@
+//
+// 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 (
+ "errors"
+ "testing"
+)
+
+// TestAllowConfiguredPrivateHost checks the ALLOW_ANY_HOST truthy values
+// accepted by the Python host guard.
+func TestAllowConfiguredPrivateHost(t *testing.T) {
+ cases := []struct {
+ value string
+ want bool
+ }{
+ {value: "", want: false},
+ {value: "0", want: false},
+ {value: "false", want: false},
+ {value: "no", want: false},
+ {value: "off", want: false},
+ {value: "1", want: true},
+ {value: "true", want: true},
+ {value: "TRUE", want: true},
+ {value: " yes ", want: true},
+ {value: "on", want: true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.value, func(t *testing.T) {
+ t.Setenv(EnvAllowAnyHost, tc.value)
+ if got := AllowConfiguredPrivateHost(); got != tc.want {
+ t.Fatalf("AllowConfiguredPrivateHost(%q) = %v, want %v", tc.value, got, tc.want)
+ }
+ })
+ }
+}
+
+// TestPinConfiguredPrivateHost checks that the shared opt-in is a no-op when
+// the flag is unset, and that an enabled flag pins the resolved address.
+func TestPinConfiguredPrivateHost(t *testing.T) {
+ t.Setenv(EnvAllowAnyHost, "")
+ if _, enabled, err := PinConfiguredPrivateHost("10.0.0.1"); enabled || err != nil {
+ t.Fatalf("disabled flag: enabled=%v err=%v", enabled, err)
+ }
+
+ t.Setenv(EnvAllowAnyHost, "1")
+ orig := LookupHost
+ LookupHost = func(host string) ([]string, error) {
+ if host == "host.docker.internal" {
+ return []string{"192.168.65.254"}, nil
+ }
+ return nil, errors.New("no such host")
+ }
+ t.Cleanup(func() { LookupHost = orig })
+
+ got, enabled, err := PinConfiguredPrivateHost("host.docker.internal")
+ if err != nil || !enabled || got != "192.168.65.254" {
+ t.Fatalf("PinConfiguredPrivateHost = %q, %v, %v", got, enabled, err)
+ }
+ if _, enabled, err = PinConfiguredPrivateHost("missing.internal"); !enabled || err == nil {
+ t.Fatalf("unresolvable host: enabled=%v err=%v", enabled, err)
+ }
+}
+
+// TestResolveHostPinSkipsPublicCheck checks that a private resolution is
+// returned as the pin, and that empty or unresolvable hosts still fail.
+func TestResolveHostPinSkipsPublicCheck(t *testing.T) {
+ orig := LookupHost
+ LookupHost = func(host string) ([]string, error) {
+ if host == "host.docker.internal" {
+ return []string{"192.168.65.254", "10.0.0.2"}, nil
+ }
+ return nil, errors.New("no such host")
+ }
+ t.Cleanup(func() { LookupHost = orig })
+
+ got, err := ResolveHostPin("host.docker.internal")
+ if err != nil {
+ t.Fatalf("ResolveHostPin: %v", err)
+ }
+ if got != "192.168.65.254" {
+ t.Fatalf("ResolveHostPin = %q, want 192.168.65.254", got)
+ }
+
+ literal, err := ResolveHostPin("10.1.2.3")
+ if err != nil || literal != "10.1.2.3" {
+ t.Fatalf("ResolveHostPin(literal) = %q, %v", literal, err)
+ }
+ if _, err = ResolveHostPin("missing.internal"); err == nil {
+ t.Fatal("unresolvable host must still fail")
+ }
+ if _, err = ResolveHostPin(" "); err == nil {
+ t.Fatal("empty host must still fail")
+ }
+}
diff --git a/internal/common/http.go b/internal/common/http.go
index 74d7f56000..d5782100d3 100644
--- a/internal/common/http.go
+++ b/internal/common/http.go
@@ -428,6 +428,10 @@ var LookupHost = net.LookupHost
// process memory only, so it cannot be enabled by an env var or
// a deployment mistake. The explicit "_ForTest" suffix is the
// signal that production code must never touch it.
+//
+// Host-based database and connector dials are a separate opt-in.
+// AllowConfiguredPrivateHost reads ALLOW_ANY_HOST for those dials
+// only. This function stays limited to the in-memory test hook.
var AllowAnyHostForTest = false
// allowAnyHost reads the test-only override. Kept as a private
diff --git a/internal/service/agent_dbcheck.go b/internal/service/agent_dbcheck.go
index 3a71460e19..5433c87216 100644
--- a/internal/service/agent_dbcheck.go
+++ b/internal/service/agent_dbcheck.go
@@ -44,19 +44,14 @@ type TestDBConnectionRequest struct {
Password string `json:"password"`
}
-// AllowAnyHostForTest mirrors common.AllowAnyHostForTest: a test-only
-// override that disables the SSRF guard in AssertHostIsSafe. Production
-// code MUST leave this at false. Tests that need to talk to a local
-// httptest server or stub-resolved DB host flip it on and reset it
-// in t.Cleanup.
-//
-// The previous form was an env-var check (ALLOW_ANY_HOST=1) which was
-// a live runtime toggle any operator could flip to disable the SSRF
-// guard globally. PR review round 6, Major #3: this is a process-
-// memory boolean only — no env var, no deployment flag, no path to
-// bypass from outside the test binary.
+// AllowAnyHostForTest is a test-only override that disables the SSRF guard
+// in AssertHostIsSafe. Production code must leave it false. Operators allow
+// private database hosts with ALLOW_ANY_HOST; that flag does not relax URL
+// or Invoke checks.
var AllowAnyHostForTest = false
+// allowAnyHost reports the in-memory test override. AssertHostIsSafe checks
+// ALLOW_ANY_HOST separately so URL and Invoke guards stay strict.
func allowAnyHost() bool {
return AllowAnyHostForTest
}
@@ -76,6 +71,9 @@ func AssertHostIsSafe(host string) (string, error) {
)
return host, nil
}
+ if pinned, enabled, err := common.PinConfiguredPrivateHost(host); enabled {
+ return pinned, err
+ }
ips, err := net.LookupIP(host)
if err != nil {
diff --git a/internal/service/agent_test.go b/internal/service/agent_test.go
index bd18aa3558..fd9f833759 100644
--- a/internal/service/agent_test.go
+++ b/internal/service/agent_test.go
@@ -1477,7 +1477,10 @@ func TestIsPublicAddr(t *testing.T) {
}
}
+// TestAssertHostIsSafeRejectsLocalhost checks that a loopback name stays
+// blocked when ALLOW_ANY_HOST is unset.
func TestAssertHostIsSafeRejectsLocalhost(t *testing.T) {
+ t.Setenv(common.EnvAllowAnyHost, "")
_, err := AssertHostIsSafe("localhost")
if err == nil {
t.Fatal("expected localhost to be rejected")
@@ -1487,6 +1490,37 @@ func TestAssertHostIsSafeRejectsLocalhost(t *testing.T) {
}
}
+// TestAssertHostIsSafeAllowsPrivateHostWhenConfigured checks that
+// ALLOW_ANY_HOST pins a private database host and still rejects a name
+// that does not resolve.
+func TestAssertHostIsSafeAllowsPrivateHostWhenConfigured(t *testing.T) {
+ t.Setenv(common.EnvAllowAnyHost, "1")
+ orig := common.LookupHost
+ common.LookupHost = func(host string) ([]string, error) {
+ if host == "host.docker.internal" {
+ return []string{"192.168.65.254"}, nil
+ }
+ return nil, errors.New("no such host")
+ }
+ t.Cleanup(func() { common.LookupHost = orig })
+
+ got, err := AssertHostIsSafe("host.docker.internal")
+ if err != nil {
+ t.Fatalf("AssertHostIsSafe(host.docker.internal) = %v", err)
+ }
+ if got != "192.168.65.254" {
+ t.Fatalf("AssertHostIsSafe(host.docker.internal) = %q, want 192.168.65.254", got)
+ }
+
+ literal, err := AssertHostIsSafe("10.1.2.3")
+ if err != nil || literal != "10.1.2.3" {
+ t.Fatalf("AssertHostIsSafe(10.1.2.3) = %q, %v", literal, err)
+ }
+ if _, err = AssertHostIsSafe("missing.internal"); err == nil {
+ t.Fatal("unresolvable host must still fail when ALLOW_ANY_HOST is set")
+ }
+}
+
func TestTestDBConnectionMissingFields(t *testing.T) {
ctx := t.Context()
code, err := NewAgentService().TestDBConnection(ctx, "user-1", &TestDBConnectionRequest{DBType: "mysql"})
diff --git a/internal/syncer/connector/ssrf.go b/internal/syncer/connector/ssrf.go
index 27ba85bb86..b5085042d3 100644
--- a/internal/syncer/connector/ssrf.go
+++ b/internal/syncer/connector/ssrf.go
@@ -49,6 +49,10 @@ var connectorAssertHostSafe = common.AssertHostSafe
// validated public IP so callers can pin the dial, preventing DNS rebinding
// between validation and the connection.
//
+// When ALLOW_ANY_HOST is set, the public-address check is skipped for this
+// host dial (MySQL, PostgreSQL, IMAP). The hostname is still resolved and
+// the dial stays pinned to that address. URL connectors do not use this path.
+//
// When connectorAllowLoopbackForTest is set, loopback-only hosts are allowed
// (unit tests run against local listeners); anything else falls through to the
// strict guard, so a mixed private address is still rejected.
@@ -69,6 +73,16 @@ func assertConnectorHostSafe(host string) (net.IP, error) {
}
// Not allowed by the test hook — fall through to the strict guard.
}
+ if pinned, enabled, err := common.PinConfiguredPrivateHost(host); enabled {
+ if err != nil {
+ return nil, err
+ }
+ ip := net.ParseIP(pinned)
+ if ip == nil {
+ return nil, fmt.Errorf("Could not parse validated address %q for host %q", pinned, host)
+ }
+ return ip, nil
+ }
ipStr, err := connectorAssertHostSafe(host)
if err != nil {
return nil, err
diff --git a/internal/syncer/connector/ssrf_test.go b/internal/syncer/connector/ssrf_test.go
index 47ee859d09..921379949d 100644
--- a/internal/syncer/connector/ssrf_test.go
+++ b/internal/syncer/connector/ssrf_test.go
@@ -309,7 +309,10 @@ func TestConnectorStripAuthHeadersRemovesCredentials(t *testing.T) {
// Host-type SSRF guards (IMAP / MySQL / PostgreSQL / S3-compatible)
// ---------------------------------------------------------------------------
+// TestAssertConnectorHostSafe checks the strict host guard used by
+// MySQL, PostgreSQL, and IMAP when ALLOW_ANY_HOST is unset.
func TestAssertConnectorHostSafe(t *testing.T) {
+ t.Setenv(common.EnvAllowAnyHost, "")
connectorAllowLoopbackForTest = false
t.Cleanup(func() { connectorAllowLoopbackForTest = false })
@@ -343,7 +346,10 @@ func TestAssertConnectorHostSafe(t *testing.T) {
}
}
+// TestAssertConnectorHostSafeLoopbackHookAllowsOnlyLoopback checks that
+// the unit-test loopback hook does not allow other private addresses.
func TestAssertConnectorHostSafeLoopbackHookAllowsOnlyLoopback(t *testing.T) {
+ t.Setenv(common.EnvAllowAnyHost, "")
withConnectorLoopbackTestHook(t)
if _, err := assertConnectorHostSafe("127.0.0.1"); err != nil {
t.Fatalf("loopback should be allowed with hook on: %v", err)
@@ -360,6 +366,43 @@ func TestAssertConnectorHostSafeLoopbackHookAllowsOnlyLoopback(t *testing.T) {
}
}
+// TestAssertConnectorHostSafeHonorsAllowAnyHost checks that a private
+// connector host is pinned when ALLOW_ANY_HOST is set, and that URL
+// connector checks stay strict.
+func TestAssertConnectorHostSafeHonorsAllowAnyHost(t *testing.T) {
+ t.Setenv(common.EnvAllowAnyHost, "1")
+ connectorAllowLoopbackForTest = false
+ t.Cleanup(func() { connectorAllowLoopbackForTest = false })
+
+ orig := common.LookupHost
+ common.LookupHost = func(host string) ([]string, error) {
+ if host == "host.docker.internal" {
+ return []string{"192.168.65.254"}, nil
+ }
+ return nil, &net.DNSError{Err: "no such host", Name: host, IsNotFound: true}
+ }
+ t.Cleanup(func() { common.LookupHost = orig })
+
+ ip, err := assertConnectorHostSafe("host.docker.internal")
+ if err != nil {
+ t.Fatalf("assertConnectorHostSafe(host.docker.internal) = %v, want nil", err)
+ }
+ if ip == nil || ip.String() != "192.168.65.254" {
+ t.Fatalf("assertConnectorHostSafe(host.docker.internal) = %v, want 192.168.65.254", ip)
+ }
+
+ literal, err := assertConnectorHostSafe("10.0.0.5")
+ if err != nil || literal == nil || literal.String() != "10.0.0.5" {
+ t.Fatalf("assertConnectorHostSafe(10.0.0.5) = %v, %v", literal, err)
+ }
+ if _, err = assertConnectorHostSafe("missing.internal"); err == nil {
+ t.Fatal("unresolvable host must still fail when ALLOW_ANY_HOST is set")
+ }
+ if err = validateConnectorURL("http://10.0.0.5/x"); err == nil {
+ t.Fatal("ALLOW_ANY_HOST must not relax URL connector checks")
+ }
+}
+
// TestConnectorHostSSRFDNSRebinding closes the host-type TOCTOU window: after
// the guard validates a public host, the dial must be pinned to the validated
// IP and never re-resolve the hostname. The guard seam is stubbed to simulate