validate_safe_url() — langchain Function Reference

Source Code

libs/core/langchain_core/_security/_ssrf_protection.py lines 138–253

def validate_safe_url(
    url: str | AnyHttpUrl,
    *,
    allow_private: bool = False,
    allow_http: bool = True,
) -> str:
    """Validate a URL for SSRF protection.

    This function validates URLs to prevent Server-Side Request Forgery (SSRF) attacks
    by blocking requests to private networks and cloud metadata endpoints.

    Args:
        url: The URL to validate (string or Pydantic HttpUrl)
        allow_private: If True, allows private IPs and localhost (for development).
                      Cloud metadata endpoints are ALWAYS blocked.
        allow_http: If True, allows both HTTP and HTTPS. If False, only HTTPS.

    Returns:
        The validated URL as a string

    Raises:
        ValueError: If URL is invalid or potentially dangerous

    Examples:
        >>> validate_safe_url("https://hooks.slack.com/services/xxx")
        'https://hooks.slack.com/services/xxx'

        >>> validate_safe_url("http://127.0.0.1:8080")
        ValueError: Localhost URLs are not allowed

        >>> validate_safe_url("http://192.168.1.1")
        ValueError: URL resolves to private IP: 192.168.1.1

        >>> validate_safe_url("http://169.254.169.254/latest/meta-data/")
        ValueError: URL resolves to cloud metadata IP: 169.254.169.254

        >>> validate_safe_url("http://localhost:8080", allow_private=True)
        'http://localhost:8080'
    """
    url_str = str(url)
    parsed = urlparse(url_str)

    # Validate URL scheme
    if not allow_http and parsed.scheme != "https":
        msg = "Only HTTPS URLs are allowed"
        raise ValueError(msg)

    if parsed.scheme not in ("http", "https"):
        msg = f"Only HTTP/HTTPS URLs are allowed, got scheme: {parsed.scheme}"
        raise ValueError(msg)

    # Extract hostname
    hostname = parsed.hostname
    if not hostname:
        msg = "URL must have a valid hostname"
        raise ValueError(msg)

    # Special handling for test environments - allow test server hostnames
    # testserver is used by FastAPI/Starlette test clients and doesn't resolve via DNS
    # Only enabled when LANGCHAIN_ENV=local_test (set in conftest.py)
    if (
        os.environ.get("LANGCHAIN_ENV") == "local_test"
        and hostname.startswith("test")
        and "server" in hostname
    ):
        return url_str

    # ALWAYS block cloud metadata endpoints (even with allow_private=True)
    if is_cloud_metadata(hostname):
        msg = f"Cloud metadata endpoints are not allowed: {hostname}"
        raise ValueError(msg)

    # Check for localhost
    if is_localhost(hostname) and not allow_private:
        msg = f"Localhost URLs are not allowed: {hostname}"
        raise ValueError(msg)

    # Resolve hostname to IP addresses and validate each one.
    # Note: DNS resolution results are cached by the OS, so repeated calls are fast.
    try:
        # Get all IP addresses for this hostname