fix(security): support IPv6 in SSRF validation via whitelist mechanism

- Keep strict mode blocking all direct IPs (IPv4 and IPv6 uniformly)
- Unify all SSRF call sites to use ValidateURLForSSRF (whitelist-aware)
- Add Teredo (2001:0000::/32) and 6to4 (2002::/16) tunnel detection
- Make redirect handler and DNS pinning respect SSRF_WHITELIST
- Unexport isSSRFSafeURL to prevent future callers bypassing whitelist
- Add scheme validation for whitelisted redirect targets
- Document IPv6 whitelist syntax in .env.example
- Add comprehensive IPv6 test coverage

Author: voidkey

.env.example

@@ -105,8 +105,9 @@ TENANT_AES_KEY=weknorarag-api-key-secret-secret
 SYSTEM_AES_KEY=weknora-system-aes-key-32bytes!!
 
 # SSRF 校验白名单（可选）。逗号分隔；每条可为：精确域名（api.internal）、通配域名（*.example.com）、
-# IP（203.0.113.5）或 CIDR（10.0.0.0/8）。列入者会在 URL 校验等地方绕过常规 SSRF 规则，生产环境请谨慎配置。
-# SSRF_WHITELIST=internal.service,*.corp.example,172.16.0.0/12
+# IPv4（203.0.113.5）、IPv6（2001:db8::1，不带方括号）或 CIDR（10.0.0.0/8, 2001:db8::/32）。
+# 列入者会在 URL 校验等地方绕过常规 SSRF 规则，生产环境请谨慎配置。
+# SSRF_WHITELIST=internal.service,*.corp.example,172.16.0.0/12,2001:db8::1,fd00::/8
 
 # 是否开启知识图谱构建和检索（构建阶段需调用大模型，耗时较长）
 ENABLE_GRAPH_RAG=false

internal/agent/tools/web_fetch.go

@@ -262,9 +262,9 @@ func (t *WebFetchTool) validateAndResolve(p webFetchParams) (*validatedParams, e
 		return nil, fmt.Errorf("invalid URL format")
 	}
 
-	// SSRF protection: validate URL is safe (scheme, hostname, and that resolved IPs are not restricted)
-	if safe, reason := utils.IsSSRFSafeURL(p.URL); !safe {
-		return nil, fmt.Errorf("URL rejected for security reasons: %s", reason)
+	// SSRF protection: validate URL is safe (uses centralised entry-point with whitelist support)
+	if err := utils.ValidateURLForSSRF(p.URL); err != nil {
+		return nil, fmt.Errorf("URL rejected for security reasons: %v", err)
 	}
 
 	u, err := url.Parse(p.URL)
@@ -281,14 +281,16 @@ func (t *WebFetchTool) validateAndResolve(p webFetchParams) (*validatedParams, e
 		}
 	}
 
-	// Resolve and pin to the first public IP (same resolver as IsSSRFSafeURL; we pin so chromedp cannot re-resolve)
+	// Resolve and pin to the first safe IP (same resolver as isSSRFSafeURL; we pin so chromedp cannot re-resolve).
+	// Whitelisted hosts may resolve to private/restricted IPs, so we allow any IP for them.
 	ips, err := net.DefaultResolver.LookupIP(context.Background(), "ip", hostname)
 	if err != nil || len(ips) == 0 {
 		return nil, fmt.Errorf("DNS lookup failed for %s: %w", hostname, err)
 	}
+	isWhitelisted := utils.IsSSRFWhitelisted(hostname)
 	var pinnedIP net.IP
 	for _, ip := range ips {
-		if utils.IsPublicIP(ip) {
+		if isWhitelisted || utils.IsPublicIP(ip) {
 			pinnedIP = ip
 			break
 		}

internal/application/service/knowledge.go

@@ -473,9 +473,9 @@ func (s *knowledgeService) CreateKnowledgeFromURL(ctx context.Context,
 		return nil, ErrInvalidURL
 	}
 
-	// SSRF protection: validate URL is safe to fetch
-	if safe, reason := secutils.IsSSRFSafeURL(url); !safe {
-		logger.Errorf(ctx, "URL rejected for SSRF protection: %s, reason: %s", url, reason)
+	// SSRF protection: validate URL is safe to fetch (uses centralised entry-point with whitelist support)
+	if err := secutils.ValidateURLForSSRF(url); err != nil {
+		logger.Errorf(ctx, "URL rejected for SSRF protection: %s, err: %v", url, err)
 		return nil, ErrInvalidURL
 	}
 
@@ -659,8 +659,8 @@ func (s *knowledgeService) createKnowledgeFromFileURL(
 		logger.Error(ctx, "Invalid or unsafe file URL format")
 		return nil, ErrInvalidURL
 	}
-	if safe, reason := secutils.IsSSRFSafeURL(fileURL); !safe {
-		logger.Errorf(ctx, "File URL rejected for SSRF protection: %s, reason: %s", fileURL, reason)
+	if err := secutils.ValidateURLForSSRF(fileURL); err != nil {
+		logger.Errorf(ctx, "File URL rejected for SSRF protection: %s, err: %v", fileURL, err)
 		return nil, ErrInvalidURL
 	}
 
@@ -7458,8 +7458,8 @@ func (s *knowledgeService) ProcessDocument(ctx context.Context, t *asynq.Task) e
 
 	if payload.FileURL != "" {
 		// file_url import: SSRF re-check (防 DNS 重绑定), download, persist, then delegate to convert()
-		if safe, reason := secutils.IsSSRFSafeURL(payload.FileURL); !safe {
-			logger.Errorf(ctx, "File URL rejected for SSRF protection in ProcessDocument: %s, reason: %s", payload.FileURL, reason)
+		if err := secutils.ValidateURLForSSRF(payload.FileURL); err != nil {
+			logger.Errorf(ctx, "File URL rejected for SSRF protection in ProcessDocument: %s, err: %v", payload.FileURL, err)
 			knowledge.ParseStatus = "failed"
 			knowledge.ErrorMessage = "File URL is not allowed for security reasons"
 			knowledge.UpdatedAt = time.Now()
@@ -7668,8 +7668,8 @@ func (s *knowledgeService) convert(
 	overrides := s.getParserEngineOverridesFromContext(ctx)
 
 	if isURL {
-		if safe, reason := secutils.IsSSRFSafeURL(payload.URL); !safe {
-			logger.Errorf(ctx, "URL rejected for SSRF protection: %s, reason: %s", payload.URL, reason)
+		if err := secutils.ValidateURLForSSRF(payload.URL); err != nil {
+			logger.Errorf(ctx, "URL rejected for SSRF protection: %s, err: %v", payload.URL, err)
 			knowledge.ParseStatus = "failed"
 			knowledge.ErrorMessage = "URL is not allowed for security reasons"
 			knowledge.UpdatedAt = time.Now()

internal/handler/system.go

@@ -643,7 +643,7 @@ func sanitizeStorageCheckError(err error) string {
 }
 
 // isBlockedStorageEndpoint checks whether a storage endpoint resolves to a dangerous
-// address (cloud metadata, loopback, link-local). Unlike the stricter IsSSRFSafeURL,
+// address (cloud metadata, loopback, link-local). Unlike the stricter isSSRFSafeURL,
 // this allows private IPs since MinIO is commonly deployed on internal networks.
 // It also respects the SSRF_WHITELIST environment variable for whitelisted hosts.
 func isBlockedStorageEndpoint(endpoint string) (bool, string) {

internal/im/wecom/webhook_adapter.go

@@ -503,8 +503,8 @@ func (a *WebhookAdapter) DownloadFile(ctx context.Context, msg *im.IncomingMessa
 func downloadFromURL(ctx context.Context, rawURL, fileName string) (io.ReadCloser, string, error) {
 	// SSRF protection: reject internal/private URLs unless on the WeCom API allowlist.
 	if !isAllowedIMAPIHost(rawURL) {
-		if safe, reason := secutils.IsSSRFSafeURL(rawURL); !safe {
-			return nil, "", fmt.Errorf("URL rejected for security reasons: %s", reason)
+		if err := secutils.ValidateURLForSSRF(rawURL); err != nil {
+			return nil, "", fmt.Errorf("URL rejected for security reasons: %v", err)
 		}
 	}
 
@@ -582,7 +582,7 @@ func downloadFromURL(ctx context.Context, rawURL, fileName string) (io.ReadClose
 }
 
 // allowedIMAPIHosts lists IM platform API hosts that are trusted for file downloads.
-// URLs pointing to these hosts bypass IsSSRFSafeURL checks because the WeCom API
+// URLs pointing to these hosts bypass isSSRFSafeURL checks because the WeCom API
 // itself returns these URLs in callback payloads (e.g. temporary media links).
 var allowedIMAPIHosts = []string{
 	"qyapi.weixin.qq.com",

internal/infrastructure/docparser/image_resolver.go

@@ -667,9 +667,9 @@ func (r *ImageResolver) ResolveRemoteImages(
 			continue
 		}
 
-		// --- SSRF check ---
-		if safe, reason := secutils.IsSSRFSafeURL(imgURL); !safe {
-			log.Printf("WARN: remote image blocked by SSRF check (%s): %s", reason, imgURL)
+		// --- SSRF check (centralised entry-point with whitelist support) ---
+		if err := secutils.ValidateURLForSSRF(imgURL); err != nil {
+			log.Printf("WARN: remote image blocked by SSRF check (%v): %s", err, imgURL)
 			continue
 		}
 

internal/infrastructure/docparser/mineru_cloud_converter.go

@@ -345,8 +345,8 @@ func (c *MinerUCloudReader) extractDoneResult(_ context.Context, item *extractRe
 var imgRefPattern = regexp.MustCompile(`!\[[^\]]*\]\(([^)]+)\)`)
 
 func downloadAndExtractZip(zipURL string) (string, []types.ImageRef, error) {
-	if safe, reason := utils.IsSSRFSafeURL(zipURL); !safe {
-		return "", nil, fmt.Errorf("zip URL blocked by SSRF check: %s", reason)
+	if err := utils.ValidateURLForSSRF(zipURL); err != nil {
+		return "", nil, fmt.Errorf("zip URL blocked by SSRF check: %v", err)
 	}
 	client := utils.NewSSRFSafeHTTPClient(utils.SSRFSafeHTTPClientConfig{Timeout: 120 * time.Second, MaxRedirects: 5})
 	resp, err := client.Get(zipURL)

internal/utils/security.go

@@ -302,6 +302,19 @@ func isRestrictedIP(ip net.IP) (bool, string) {
 				return true, fmt.Sprintf("IPv4-mapped %s", reason)
 			}
 		}
+		// Teredo tunneling addresses: 2001:0000::/32
+		// Embed arbitrary IPv4 in the payload; can reach internal hosts via relay.
+		if ip[0] == 0x20 && ip[1] == 0x01 && ip[2] == 0x00 && ip[3] == 0x00 {
+			return true, "Teredo tunneling address"
+		}
+		// 6to4 addresses: 2002::/16
+		// Bits 16-47 carry an IPv4 address; block when embedded IPv4 is restricted.
+		if ip[0] == 0x20 && ip[1] == 0x02 {
+			embeddedIP := net.IP(ip[2:6])
+			if restricted, reason := isRestrictedIP(embeddedIP); restricted {
+				return true, fmt.Sprintf("6to4 embedded %s", reason)
+			}
+		}
 	}
 
 	return false, ""
@@ -357,15 +370,15 @@ func isIPLikeHostname(hostname string) bool {
 	return false
 }
 
-// IsSSRFSafeURL validates a URL to prevent SSRF attacks
+// isSSRFSafeURL validates a URL to prevent SSRF attacks
 // It checks for:
 // - Valid http/https protocol
 // - Private IP addresses (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
 // - Loopback addresses (127.x.x.x, ::1)
 // - Link-local addresses (169.254.x.x, fe80::)
 // - Cloud metadata endpoints
 // - Reserved hostnames (localhost, *.local, etc.)
-func IsSSRFSafeURL(rawURL string) (bool, string) {
+func isSSRFSafeURL(rawURL string) (bool, string) {
 	if rawURL == "" {
 		return false, "URL is empty"
 	}
@@ -408,11 +421,14 @@ func IsSSRFSafeURL(rawURL string) (bool, string) {
 		}
 	}
 
-	// STRICT MODE: Completely block IP addresses in URLs
-	// This prevents all IP-based SSRF attacks including edge cases and bypasses
+	// STRICT MODE: Block all direct IP addresses in URLs (both IPv4 and IPv6).
+	// This prevents IP-based SSRF attacks including obfuscation, tunneling, and
+	// transition mechanism bypasses. Legitimate IPs should be whitelisted via
+	// SSRF_WHITELIST env var; the whitelist is checked by ValidateURLForSSRF
+	// before this function is called.
 	ip := net.ParseIP(hostname)
 	if ip != nil {
-		return false, "direct IP address access is not allowed, use domain name instead"
+		return false, "direct IP address access is not allowed, use domain name or add to SSRF_WHITELIST"
 	}
 
 	// Also check for IP addresses in various formats that ParseIP might not catch
@@ -425,11 +441,6 @@ func IsSSRFSafeURL(rawURL string) (bool, string) {
 	// This prevents DNS rebinding attacks where a domain resolves to internal IPs
 	ips, err := net.LookupIP(hostname)
 	if err != nil {
-		// DNS resolution failed - reject the URL for security
-		// This prevents attacks where:
-		// 1. The domain is only resolvable within internal network (intranet domains)
-		// 2. Different DNS servers between validation and actual request
-		// 3. Attacker-controlled DNS that selectively responds
 		return false, fmt.Sprintf("DNS resolution failed for hostname %s: cannot verify if it resolves to safe IP", hostname)
 	}
 
@@ -760,9 +771,18 @@ func NewSSRFSafeHTTPClient(config SSRFSafeHTTPClientConfig) *http.Client {
 				return fmt.Errorf("stopped after %d redirects", config.MaxRedirects)
 			}
 
-			// Validate the redirect target URL for SSRF
+			// Validate the redirect target URL for SSRF (whitelist-aware).
+			// Even whitelisted hosts must use http/https to prevent scheme-based attacks.
+			redirectScheme := strings.ToLower(req.URL.Scheme)
+			if redirectScheme != "http" && redirectScheme != "https" {
+				return fmt.Errorf("%w: invalid scheme %s", ErrSSRFRedirectBlocked, redirectScheme)
+			}
+			redirectHost := req.URL.Hostname()
+			if redirectHost != "" && IsSSRFWhitelisted(redirectHost) {
+				return nil
+			}
 			redirectURL := req.URL.String()
-			if safe, reason := IsSSRFSafeURL(redirectURL); !safe {
+			if safe, reason := isSSRFSafeURL(redirectURL); !safe {
 				return fmt.Errorf("%w: %s", ErrSSRFRedirectBlocked, reason)
 			}
 
@@ -782,7 +802,9 @@ func SSRFSafeDialContext(ctx context.Context, network, addr string) (net.Conn, e
 	}
 
 	// Whitelisted hosts bypass all dial-time SSRF checks, consistent with
-	// ValidateURLForSSRF which skips IsSSRFSafeURL for whitelisted hosts.
+	// ValidateURLForSSRF which skips isSSRFSafeURL for whitelisted hosts.
+	// NOTE: This intentionally relaxes DNS-rebinding protection for whitelisted
+	// hosts. Admins must ensure whitelisted domains are under their control.
 	if IsSystemProxy(addr) || IsSSRFWhitelisted(host) {
 		dialer := &net.Dialer{
 			Timeout:   30 * time.Second,
@@ -834,10 +856,11 @@ func SSRFSafeDialContext(ctx context.Context, network, addr string) (net.Conn, e
 // allowed host patterns. Each entry can be:
 //   - An exact domain: "example.com"
 //   - A wildcard domain: "*.example.com" (matches all subdomains)
-//   - An IP address: "203.0.113.5"
-//   - A CIDR range: "10.0.0.0/8"
+//   - An IPv4 address: "203.0.113.5"
+//   - An IPv6 address: "2001:db8::1"
+//   - A CIDR range (v4 or v6): "10.0.0.0/8", "2001:db8::/32"
 //
-// Whitelisted entries bypass the normal SSRF checks performed by IsSSRFSafeURL.
+// Whitelisted entries bypass the normal SSRF checks performed by isSSRFSafeURL.
 
 var (
 	ssrfWhitelistOnce sync.Once
@@ -932,16 +955,16 @@ func IsSSRFWhitelisted(hostname string) bool {
 	return false
 }
 
-// ResetSSRFWhitelistForTest resets the whitelist singleton so tests can
+// resetSSRFWhitelistForTest resets the whitelist singleton so tests can
 // re-read the environment variable. NOT for production use.
-func ResetSSRFWhitelistForTest() {
+func resetSSRFWhitelistForTest() {
 	ssrfWhitelistOnce = sync.Once{}
 	ssrfWhitelist = nil
 }
 
 // ValidateURLForSSRF is the centralised entry-point that all handlers should
 // call to validate a user-supplied URL. It first checks the SSRF_WHITELIST;
-// whitelisted hosts skip the full IsSSRFSafeURL check.
+// whitelisted hosts skip the full isSSRFSafeURL check.
 //
 // rawURL may be a full URL ("https://example.com/v1") or a bare host/host:port
 // (for cases like ReconnectDocReader). If a scheme is missing the function
@@ -975,7 +998,7 @@ func ValidateURLForSSRF(rawURL string) error {
 	}
 
 	// Delegate to the full SSRF validation (uses the normalised URL).
-	if safe, reason := IsSSRFSafeURL(normalized); !safe {
+	if safe, reason := isSSRFSafeURL(normalized); !safe {
 		return fmt.Errorf("SSRF validation failed: %s", reason)
 	}
 	return nil