Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

10.3 KB
Raw Blame
"""Path and URL validation utilities for crewai-tools.

Provides validation for file paths and URLs to prevent unauthorized
file access and server-side request forgery (SSRF) when tools accept
user-controlled or LLM-controlled inputs at runtime.

Set CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true to bypass validation (not
recommended for production). Managed workers should set
CREWAI_TOOLS_FORCE_SAFE_PATHS=true so a tenant cannot disable these
checks by exporting the escape hatch on their own deployment.
"""

from __future__ import annotations

import ipaddress
import logging
import os
import socket
from urllib.parse import urlparse


logger = logging.getLogger(__name__)

_UNSAFE_PATHS_ENV = "CREWAI_TOOLS_ALLOW_UNSAFE_PATHS"
_FORCE_SAFE_PATHS_ENV = "CREWAI_TOOLS_FORCE_SAFE_PATHS"
_BYPASS_HINT = f"Set {_UNSAFE_PATHS_ENV}=true to bypass this check."


def format_path_for_display(path: str, base_dir: str | None = None) -> str:
    """Return a path label that does not expose absolute directory prefixes."""
    if base_dir is None:
        base_dir = os.getcwd()

    try:
        resolved_base = os.path.realpath(base_dir)
        resolved_path = os.path.realpath(
            os.path.join(resolved_base, path) if not os.path.isabs(path) else path
        )
        if os.path.commonpath([resolved_base, resolved_path]) == resolved_base:
            return os.path.relpath(resolved_path, resolved_base)
    except (OSError, ValueError) as exc:
        logger.debug("Falling back to basename for display path formatting: %s", exc)

    return os.path.basename(os.path.realpath(path)) or "[redacted path]"


def format_error_for_display(error: Exception) -> str:
    """Return exception details without OS-added absolute path context."""
    if isinstance(error, OSError):
        return error.strerror or error.__class__.__name__
    return str(error)


def format_sandbox_error(error: Exception, remedy: str) -> str:
    """Restate a containment rejection with a tool-specific remedy.

    Rejections from :func:`validate_file_path` end by advertising the
    process-wide escape hatch, which also disables the SSRF checks on
    URL-fetching tools. Tools that accept a narrower ``base_dir`` should point
    at that instead, so callers reach for the blunt instrument last.

    Args:
        error: The rejection raised by path validation.
        remedy: Guidance to offer in place of the escape-hatch advice.

    Returns:
        The rejection text with *remedy* substituted for the bypass advice.
    """
    text = str(error)
    if text.endswith(_BYPASS_HINT):
        text = text[: -len(_BYPASS_HINT)].rstrip()
    return f"{text} {remedy}".strip()


def _env_flag_enabled(name: str) -> bool:
    return os.environ.get(name, "").lower() in ("true", "1", "yes")


def _is_escape_hatch_enabled() -> bool:
    """True when ``ALLOW_UNSAFE_PATHS`` is set and ``FORCE_SAFE_PATHS`` is not."""
    if _env_flag_enabled(_FORCE_SAFE_PATHS_ENV):
        if _env_flag_enabled(_UNSAFE_PATHS_ENV):
            logger.warning(
                "%s is set; ignoring %s",
                _FORCE_SAFE_PATHS_ENV,
                _UNSAFE_PATHS_ENV,
            )
        return False
    return _env_flag_enabled(_UNSAFE_PATHS_ENV)


def validate_file_path(path: str, base_dir: str | None = None) -> str:
    """Validate that a file path is safe to read.

    Resolves symlinks and ``..`` components, then checks that the resolved
    path falls within *base_dir* (defaults to the current working directory).

    Args:
        path: The file path to validate.
        base_dir: Allowed root directory. Defaults to ``os.getcwd()``.

    Returns:
        The resolved, validated absolute path.

    Raises:
        ValueError: If the path escapes the allowed directory.
    """
    if _is_escape_hatch_enabled():
        logger.warning(
            "%s is enabled — skipping file path validation for: %s",
            _UNSAFE_PATHS_ENV,
            path,
        )
        return os.path.realpath(path)

    if base_dir is None:
        base_dir = os.getcwd()

    resolved_base = os.path.realpath(base_dir)
    resolved_path = os.path.realpath(
        os.path.join(resolved_base, path) if not os.path.isabs(path) else path
    )

    # Ensure the resolved path is within the base directory.
    # When resolved_base already ends with a separator (e.g. the filesystem
    # root "/"), appending os.sep would double it ("//"), so use the base
    # as-is in that case.
    prefix = resolved_base if resolved_base.endswith(os.sep) else resolved_base + os.sep
    if not resolved_path.startswith(prefix) and resolved_path != resolved_base:
        raise ValueError(
            f"Path '{format_path_for_display(resolved_path, resolved_base)}' is "
            f"outside the allowed directory. "
            f"Set {_UNSAFE_PATHS_ENV}=true to bypass this check."
        )

    return resolved_path


def validate_directory_path(path: str, base_dir: str | None = None) -> str:
    """Validate that a directory path is safe to read.

    Same as :func:`validate_file_path` but also checks that the path
    is an existing directory.

    Args:
        path: The directory path to validate.
        base_dir: Allowed root directory. Defaults to ``os.getcwd()``.

    Returns:
        The resolved, validated absolute path.

    Raises:
        ValueError: If the path escapes the allowed directory or is not a directory.
    """
    validated = validate_file_path(path, base_dir)
    if not os.path.isdir(validated):
        raise ValueError(f"Path '{validated}' is not a directory.")
    return validated


# Private and reserved IP ranges that should not be accessed
_BLOCKED_IPV4_NETWORKS = [
    ipaddress.ip_network("10.0.0.0/8"),
    ipaddress.ip_network("172.16.0.0/12"),
    ipaddress.ip_network("192.168.0.0/16"),
    ipaddress.ip_network("127.0.0.0/8"),
    ipaddress.ip_network("169.254.0.0/16"),  # Link-local / cloud metadata
    ipaddress.ip_network("0.0.0.0/32"),
    # Listed explicitly so the result doesn't depend on the interpreter's
    # ``is_global`` table, which has changed between Python versions.
    ipaddress.ip_network("100.64.0.0/10"),  # CGNAT / Tailscale / Alibaba metadata
    ipaddress.ip_network("198.18.0.0/15"),  # Benchmarking
    ipaddress.ip_network("168.63.129.16/32"),  # Azure WireServer (is_global=True)
]

_BLOCKED_IPV6_NETWORKS = [
    ipaddress.ip_network("::1/128"),
    ipaddress.ip_network("::/128"),
    ipaddress.ip_network("fc00::/7"),  # Unique local addresses
    ipaddress.ip_network("fe80::/10"),  # Link-local IPv6
    ipaddress.ip_network("fd00:ec2::254/128"),  # AWS IMDS over IPv6
    ipaddress.ip_network("fec0::/10"),  # Deprecated site-local
    # Wrappers around IPv4 that is_global misclassifies on some releases
    # (6to4 and local-use NAT64 were global before the CVE-2024-4032 fix).
    ipaddress.ip_network("::/96"),  # IPv4-compatible
    ipaddress.ip_network("::ffff:0:0:0/96"),  # IPv4-translated (RFC 2765)
    ipaddress.ip_network("2001::/32"),  # Teredo
    ipaddress.ip_network("2002::/16"),  # 6to4
    ipaddress.ip_network("64:ff9b:1::/48"),  # Local-use NAT64
]

# NAT64 well-known prefix: the low 32 bits are the IPv4 destination.
_NAT64_PREFIX = ipaddress.ip_network("64:ff9b::/96")


def is_blocked_ip(ip_str: str) -> bool:
    """Return True if *ip_str* is private, reserved, or otherwise unsafe to fetch.

    Default-deny: anything that is not globally routable is blocked, plus the
    explicit lists above for ranges ``is_global`` may allow or that changed
    between Python versions. IPv6 forms that wrap an IPv4 address (IPv4-mapped
    and NAT64) are checked as the embedded IPv4. Other transition ranges
    (6to4, Teredo, local-use NAT64, IPv4-compatible/translated) are blocked
    outright.
    """
    try:
        addr = ipaddress.ip_address(ip_str)
        # Unwrap so the embedded IPv4 is checked against IPv4 networks (also
        # avoids a TypeError comparing an IPv4Address to an IPv6Network).
        if isinstance(addr, ipaddress.IPv6Address):
            if addr.ipv4_mapped:
                addr = addr.ipv4_mapped
            elif addr in _NAT64_PREFIX:
                addr = ipaddress.IPv4Address(int(addr) & 0xFFFFFFFF)
        networks = (
            _BLOCKED_IPV4_NETWORKS
            if isinstance(addr, ipaddress.IPv4Address)
            else _BLOCKED_IPV6_NETWORKS
        )
        return not addr.is_global or any(addr in network for network in networks)
    except ValueError:
        return True  # If we can't parse, block it


def validate_url(url: str) -> str:
    """Validate that a URL is safe to fetch.

    Blocks ``file://`` scheme entirely. For ``http``/``https``, resolves
    DNS and checks that the target IP is not private or reserved (prevents
    SSRF to internal services and cloud metadata endpoints).

    This checks the URL string only. Fetch with ``safe_get`` so the
    connection is pinned to an authorised IP.

    Args:
        url: The URL to validate.

    Returns:
        The validated URL string.

    Raises:
        ValueError: If the URL uses a blocked scheme or resolves to a
            private/reserved IP address.
    """
    if _is_escape_hatch_enabled():
        logger.warning(
            "%s is enabled — skipping URL validation for: %s",
            _UNSAFE_PATHS_ENV,
            url,
        )
        return url

    parsed = urlparse(url)

    # Block file:// scheme
    if parsed.scheme == "file":
        raise ValueError(
            f"file:// URLs are not allowed: '{url}'. "
            f"Use a file path instead, or set {_UNSAFE_PATHS_ENV}=true to bypass."
        )

    # Only allow http and https
    if parsed.scheme not in ("http", "https"):
        raise ValueError(
            f"URL scheme '{parsed.scheme}' is not allowed. Only http and https are supported."
        )

    if not parsed.hostname:
        raise ValueError(f"URL has no hostname: '{url}'")

    try:
        addrinfos = socket.getaddrinfo(
            parsed.hostname, parsed.port or (443 if parsed.scheme == "https" else 80)
        )
    except socket.gaierror as exc:
        raise ValueError(f"Could not resolve hostname: '{parsed.hostname}'") from exc

    for _family, _, _, _, sockaddr in addrinfos:
        ip_str = str(sockaddr[0])
        if is_blocked_ip(ip_str):
            raise ValueError(
                f"URL '{url}' resolves to private/reserved IP {ip_str}. "
                f"Access to internal networks is not allowed. "
                f"Set {_UNSAFE_PATHS_ENV}=true to bypass."
            )

    return url