SSRF Protection#

RAGFlow implements defense-in-depth against Server-Side Request Forgery (SSRF) through a centralized guard module applied across HTTP, database, and crawling request paths. The core primitive is common/ssrf_guard.py, a stdlib-only module importable from both api/ and common/ without heavyweight dependencies.

Core Guard Functions#

common/ssrf_guard.py exposes two validation functions:

• assert_url_is_safe(url, *, allowed_schemes) — For HTTP/HTTPS targets. Validates scheme, resolves the hostname via getaddrinfo, and rejects any address that is not globally routable (ip.is_global). This allowlist approach blocks loopback, private (RFC 1918), link-local, multicast, cloud metadata (169.254.169.254), and all other special-purpose ranges in one check. Returns (hostname, resolved_ip) for subsequent DNS pinning.

• assert_host_is_safe(host) — For raw host/port connections (database drivers, non-HTTP protocols). Performs the same IP-globalness check without URL parsing.

An escape hatch exists via the ALLOW_ANY_HOST environment variable 1, which disables IP validation while emitting a warning — intended only for development environments.

DNS Pinning / Rebinding Prevention#

Validating a hostname and then connecting to it creates a TOCTOU window: an attacker can change DNS between the guard check and the actual TCP connection. RAGFlow closes this with socket-level DNS pinning 2:

• pin_dns(hostname, ip) — Thread-local context manager for synchronous requests.get() callers. Pins the validated IP in the current thread only.
• pin_dns_global(hostname, ip) — Process-global context manager for async callers (e.g., crawl4ai-based crawlers) where DNS resolution happens in thread-pool executor threads that don't share thread-local state.

Both work by monkey-patching socket.getaddrinfo at import time 3 so that pinned hostnames are always resolved to the pre-validated IP, making rebinding attacks ineffective.

IPv4-mapped IPv6 addresses (e.g., ::ffff:127.0.0.1) are normalized to their IPv4 form via _effective_ip() before the globalness check, preventing bypass via IPv6 representation.

Protected Request Paths#

Invoke Component Details#

The agent Invoke component applies SSRF guards at both the target URL and any configured proxy URL before issuing a request 7:

1. The URL is resolved and validated in _build_url(), storing the pinned hostname and IP on the instance.
2. If a proxy is configured, its URL is also validated with assert_url_is_safe 8.
3. The actual request runs inside nested pin_dns() context managers for both the target and proxy 9.
4. Redirects are disabled via allow_redirects=False 10 to prevent redirect-based SSRF bypass.

PR History#