Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
"""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