Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(sdk): pin the validated address when fetching URLs (SSRF DNS rebinding) (#4172)

Alberto Schiabeld544006a25c4
diff --git a/.changeset/ssrf-pin-validated-address.md b/.changeset/ssrf-pin-validated-address.md
new file mode 100644
index 000000000..fb0fdc8d2
--- /dev/null
+++ b/.changeset/ssrf-pin-validated-address.md
@@ -0,0 +1,5 @@
+---
+'@composio/core': patch
+---
+
+Close a DNS-rebinding window in the SSRF guard: the address validated by `assertSafeFetchTarget` is now the address `ssrfSafeFetch` connects to, so a hostname is no longer resolved a second time between the check and the connection. Each redirect hop is re-validated and re-pinned. The request still carries the original hostname in `Host` and TLS SNI, so certificate verification is unchanged. Hops whose effective dispatcher is a configured route — a caller-supplied `dispatcher`, a global `ProxyAgent`/`EnvHttpProxyAgent`, or `NODE_USE_ENV_PROXY` env-proxy mode — keep the pre-flight check only, mirroring the Python guard's documented proxy residual.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 214daed22..bbfe1bb89 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1394,6 +1394,9 @@ importers:
semver:
specifier: ^7.8.5
version: 7.8.5
+ undici:
+ specifier: ^7.29.0
+ version: 7.29.0
zod-to-json-schema:
specifier: 'catalog:'
version: 3.25.2([email protected])
@@ -1738,6 +1741,9 @@ importers:
semver:
specifier: ^7.8.5
version: 7.8.5
+ undici:
+ specifier: ^7.29.0
+ version: 7.29.0
zod:
specifier: '>=3.25.76 <5'
version: 4.4.3
diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.py
index 245a0c9c7..2dbaf3e61 100644
--- a/python/composio/core/models/_files.py
+++ b/python/composio/core/models/_files.py
@@ -27,8 +27,8 @@ from composio.utils import mimetypes
from composio.utils.json_schema import dereference_json_schema
from composio.utils.safe_path import secure_basename_join, secure_join
from composio.utils.url_safety import (
- assert_safe_fetch_target,
parse_content_length,
+ safe_get,
safe_request,
)
from composio.utils.sensitive_file_upload_paths import (
@@ -398,14 +398,12 @@ def _fetch_file_from_url(
ResponseTooLargeError: If response exceeds max_size
ErrorUploadingFile: If fetch fails for other reasons
"""
- assert_safe_fetch_target(url)
-
- # Make request without following redirects
+ # `safe_get` validates the target, connects to the address it validated
+ # (so DNS cannot rebind between the two), and never follows redirects.
try:
- response = requests.get(
+ response = safe_get(
url,
stream=True, # Enable streaming for size limiting
- allow_redirects=False, # Disable redirects for security
timeout=(_CONNECT_TIMEOUT, _READ_TIMEOUT),
)
except requests.exceptions.Timeout:
@@ -696,13 +694,10 @@ class FileDownloadable(BaseModel):
outfile = secure_basename_join(outdir, self.name, root=root)
except UnsafePathComponentError as e:
raise ErrorDownloadingFile(str(e)) from e
- assert_safe_fetch_target(self.s3url)
- outdir.mkdir(exist_ok=True, parents=True)
try:
- response = requests.get(
- url=self.s3url,
+ response = safe_get(
+ self.s3url,
stream=True,
- allow_redirects=False,
timeout=(_CONNECT_TIMEOUT, _READ_TIMEOUT),
)
except requests.exceptions.RequestException as e:
@@ -717,6 +712,10 @@ class FileDownloadable(BaseModel):
)
try:
+ # Only once the fetch is validated and connected, so a blocked URL
+ # leaves no directory behind — and inside the `try`, so a failure
+ # here still closes the response.
+ outdir.mkdir(exist_ok=True, parents=True)
with outfile.open("wb") as fd:
for chunk in response.iter_content(chunk_size=chunk_size):
fd.write(chunk)
diff --git a/python/composio/core/models/tool_router_session_files.py b/python/composio/core/models/tool_router_session_files.py
index 1668e6d65..70e28855a 100644
--- a/python/composio/core/models/tool_router_session_files.py
+++ b/python/composio/core/models/tool_router_session_files.py
@@ -30,8 +30,8 @@ from composio.exceptions import (
from composio.utils.mimetypes import get_extension_from_mime_type
from composio.utils.safe_path import secure_basename_join
from composio.utils.url_safety import (
- assert_safe_fetch_target,
parse_content_length,
+ safe_get,
safe_request,
)
from composio.utils.uuid import generate_short_id
@@ -90,12 +90,10 @@ def _fetch_url_bytes(url: str) -> t.Tuple[bytes, str]:
Returns (content, mimetype). Raises :class:`_UrlFetchError`.
"""
- assert_safe_fetch_target(url)
try:
- response = requests.get(
+ response = safe_get(
url,
stream=True,
- allow_redirects=False,
timeout=(_CONNECT_TIMEOUT, _READ_TIMEOUT),
)
except requests.exceptions.RequestException as e:
diff --git a/python/composio/utils/url_safety.py b/python/composio/utils/url_safety.py
index bdfd599b6..af0ff979a 100644
--- a/python/composio/utils/url_safety.py
+++ b/python/composio/utils/url_safety.py
@@ -8,13 +8,16 @@ SDK at loopback, RFC1918 space, or a link-local cloud-metadata endpoint
(``169.254.169.254``) and turn it into a request proxy for internal
infrastructure.
-Known residual — DNS rebinding: the host is resolved here with
-``getaddrinfo``, and the HTTP client resolves it again independently when it
-connects. A short-TTL record that alternates a public and a private answer can
-pass this check and still connect to the private address. Closing that window
-requires pinning the validated address and connecting to it directly (a custom
-``requests`` transport adapter), which is out of scope for this module; the
-TypeScript guard carries the same limitation.
+Validating a hostname is not enough on its own, because the hostname is
+resolved twice: once here, and once by the HTTP client when it opens the
+socket. A short-TTL record can answer with a public address for the first
+lookup and an internal one for the second — a time-of-check/time-of-use
+window better known as DNS rebinding. So the address validated here is also
+the address connected to: :func:`safe_get` and :func:`safe_request` pin it
+onto the connection, keeping the original hostname for the ``Host`` header
+and TLS SNI/certificate verification. Every fetch in the SDK goes through one
+of those two, so no call site can reintroduce the gap by calling
+``requests.get`` next to a bare check. The TypeScript guard pins the same way.
Also parses response headers that gate how much of a body the SDK reads:
``parse_content_length`` treats ``Content-Length`` as the untrusted hint it
@@ -30,9 +33,20 @@ import typing as t
from urllib.parse import urljoin, urlparse
import requests
+import urllib3.exceptions
from composio.exceptions import BlockedInternalUrlError
+# urllib3 rewraps connect failures into its own hierarchy, none of which
+# inherits from OSError, so a bare `except OSError` would never see them and
+# the address fallback below would never run.
+_CONNECT_ERRORS = (
+ OSError,
+ urllib3.exceptions.NewConnectionError,
+ urllib3.exceptions.ConnectTimeoutError,
+ urllib3.exceptions.NameResolutionError,
+)
+
_REDIRECT_STATUS_CODES = frozenset({301, 302, 303, 307, 308})
_MAX_REDIRECTS = 5
@@ -57,11 +71,15 @@ def is_blocked_ip(value: str) -> bool:
return not address.is_global
-def assert_safe_fetch_target(url: str) -> None:
+def assert_safe_fetch_target(url: str) -> t.List[str]:
"""Refuse non-HTTP(S) URLs and hosts that resolve to internal addresses.
Parse the URL after Requests prepares it so validation uses the same
canonical hostname that the eventual connection will use.
+
+ :returns: The validated addresses to connect to, in resolver order.
+ Callers must connect to *these* rather than re-resolving the hostname;
+ see :func:`safe_get`.
"""
try:
prepared_url = requests.Request(method="GET", url=url).prepare().url
@@ -76,14 +94,17 @@ def assert_safe_fetch_target(url: str) -> None:
) from None
try:
- addresses: set[str] = set()
+ # Resolver order is kept: it encodes the system's address preference
+ # (RFC 6724), and connecting walks it the way urllib3 would.
+ addresses: t.List[str] = []
for result in socket.getaddrinfo(parsed.hostname, None):
address = result[4][0]
if not isinstance(address, str):
raise BlockedInternalUrlError(
f'Could not resolve host "{parsed.hostname}"'
)
- addresses.add(address)
+ if address not in addresses:
+ addresses.append(address)
except socket.gaierror as error:
raise BlockedInternalUrlError(
f'Could not resolve host "{parsed.hostname}"'
@@ -95,6 +116,11 @@ def assert_safe_fetch_target(url: str) -> None:
f'Refusing to fetch "{parsed.hostname}" because it resolves to a non-public address'
)
+ if not addresses:
+ raise BlockedInternalUrlError(f'Could not resolve host "{parsed.hostname}"')
+
+ return addresses
+
def parse_content_length(value: t.Optional[str]) -> t.Optional[int]:
"""Parse a ``Content-Length`` header into a non-negative ``int``.
@@ -126,15 +152,15 @@ def safe_request(
) -> requests.Response:
"""Send a request, validating the target before *every* hop.
- Redirects are followed manually so each new location is validated too.
- Validating only the first URL is not enough: a target that passes the check
- and then answers ``302 Location: http://169.254.169.254/`` would have the
- redirect followed by ``requests`` with no further validation. Mirrors
- ``ssrfSafeFetch`` in the TypeScript SDK.
+ Redirects are followed manually so each new location is validated — and
+ pinned — too. Validating only the first URL is not enough: a target that
+ passes the check and then answers ``302 Location: http://169.254.169.254/``
+ would have the redirect followed by ``requests`` with no further
+ validation. Mirrors ``ssrfSafeFetch`` in the TypeScript SDK.
Use this where redirects are legitimate (S3 can answer a PUT with a 307
- region redirect). Call sites that require a direct URL should instead call
- :func:`assert_safe_fetch_target` and pass ``allow_redirects=False``.
+ region redirect). Call sites that require a direct URL should use
+ :func:`safe_get`, which rejects nothing but simply does not follow them.
:param max_redirects: Hops to follow before giving up.
:raises BlockedInternalUrlError: If any hop fails validation, or the
@@ -144,10 +170,7 @@ def safe_request(
current_url = url
for _ in range(max_redirects + 1):
- assert_safe_fetch_target(current_url)
- response = requests.request(
- method, current_url, allow_redirects=False, **kwargs
- )
+ response = _pinned_request(method, current_url, **kwargs)
location = response.headers.get("Location")
if response.status_code not in _REDIRECT_STATUS_CODES or location is None:
@@ -165,3 +188,157 @@ def safe_request(
raise BlockedInternalUrlError(
f"Refusing to fetch: too many redirects (max {max_redirects})"
)
+
+
+class _PinnedAddressAdapter(requests.adapters.HTTPAdapter):
+ """Transport adapter that connects to a pre-validated address.
+
+ The hostname is left untouched on the connection, so the ``Host`` header
+ and the TLS SNI/certificate check still use it; only the address the
+ socket dials is replaced. Doing it the other way round — rewriting
+ ``conn._dns_host`` for the whole connection — would also rewrite
+ ``conn.host``, which urllib3 derives from it, and the request would go out
+ with an IP in ``Host`` and an IP in SNI, failing certificate verification
+ against every real origin.
+
+ This reaches into two urllib3 internals, ``HTTPConnection._new_conn`` and
+ ``HTTPConnection._dns_host``. ``test_url_safety_pinning.py`` asserts both
+ exist so a urllib3 upgrade that removes them fails loudly rather than
+ silently un-pinning the connection.
+ """
+
+ def __init__(self, addresses: t.Sequence[str], **kwargs: t.Any) -> None:
+ self._addresses = list(addresses)
+ super().__init__(**kwargs)
+
+ def get_connection_with_tls_context(
+ self,
+ request: requests.PreparedRequest,
+ verify: t.Union[bool, str, None],
+ proxies: t.Optional[t.Mapping[str, str]] = None,
+ cert: t.Union[str, t.Tuple[str, str], None] = None,
+ ) -> t.Any:
+ # `Any`, because the pinning below reaches for urllib3 internals that
+ # the typed `ConnectionPool` surface does not expose.
+ pool: t.Any = super().get_connection_with_tls_context(
+ request, verify, proxies=proxies, cert=cert
+ )
+ addresses = self._addresses
+ build_connection = pool._new_conn
+
+ def _new_conn() -> t.Any:
+ connection = build_connection()
+ open_socket = connection._new_conn
+
+ def _pinned_new_conn() -> t.Any:
+ # Swap the resolution target for the duration of the socket
+ # connect only. urllib3 reads `self.host` for SNI *after*
+ # `_new_conn()` returns, and `http.client` reads it later
+ # still for the `Host` header, so both see the hostname.
+ #
+ # Every validated address is tried in resolver order, the way
+ # urllib3 would have: pinning one address of a dual-stack host
+ # would strand callers whose network cannot reach that family.
+ hostname = connection._dns_host
+ last_error: t.Optional[BaseException] = None
+ for address in addresses:
+ connection._dns_host = address
+ try:
+ sock = open_socket()
+ except _CONNECT_ERRORS as error:
+ last_error = error
+ continue
+ finally:
+ connection._dns_host = hostname
+ _assert_pinned_peer(sock, address, hostname)
+ return sock
+
+ assert last_error is not None
+ raise last_error
+
+ connection._new_conn = _pinned_new_conn
+ return connection
+
+ pool._new_conn = _new_conn
+ return pool
+
+
+def _assert_pinned_peer(sock: t.Any, address: str, hostname: str) -> None:
+ """Fail closed if the open socket is not connected to the pinned address.
+
+ A redundancy check on the pinning above, run before a single byte is
+ written to the socket — a post-response check would be too late and
+ unreliable, because urllib3 detaches the socket as soon as the server
+ signals ``Connection: close``, while the body stays readable.
+ """
+ try:
+ peer = sock.getpeername()[0]
+ except (AttributeError, OSError, IndexError):
+ return
+
+ try:
+ connected_to_pinned = ipaddress.ip_address(peer) == ipaddress.ip_address(
+ address
+ )
+ except ValueError:
+ connected_to_pinned = peer == address
+
+ if connected_to_pinned:
+ return
+
+ sock.close()
+ raise BlockedInternalUrlError(
+ f'Refusing to talk to "{hostname}": the connection was established to '
+ f"{peer}, not to the validated address {address}"
+ )
+
+
+def _proxy_applies(url: str, proxies: t.Optional[t.Mapping[str, str]]) -> bool:
+ """Whether Requests would send ``url`` through a proxy.
+
+ Requests honours ``HTTP_PROXY``/``HTTPS_PROXY``/``ALL_PROXY`` (minus
+ ``NO_PROXY``) by default. Through a proxy the socket is dialled to the
+ *proxy*, so pinning the target address would connect to the wrong host
+ entirely.
+
+ Residual: proxied requests keep only the pre-flight check, because the
+ proxy resolves the hostname itself and the SDK cannot see or pin that
+ resolution. A rebinding window therefore remains for callers that run
+ behind a proxy — including one inherited from the environment.
+ """
+ try:
+ environment_proxies = requests.utils.get_environ_proxies(url)
+ merged = {**environment_proxies, **(proxies or {})}
+ return requests.utils.select_proxy(url, merged) is not None
+ except Exception: # pragma: no cover - platform proxy discovery can fail
+ # Unknowable, so assume a proxy rather than pinning onto a connection
+ # that may not go where we think it goes.
+ return True
+
+
+def safe_get(url: str, **kwargs: t.Any) -> requests.Response:
+ """Validate a URL and fetch it without re-resolving its hostname.
+
+ Redirects are never followed: call sites that need a direct URL treat a
+ 3xx as an error, and call sites where redirects are legitimate use
+ :func:`safe_request`.
+ """
+ return _pinned_request("GET", url, **kwargs)
+
+
+def _pinned_request(method: str, url: str, **kwargs: t.Any) -> requests.Response:
+ addresses = assert_safe_fetch_target(url)
+
+ session = requests.Session()
+ if not _proxy_applies(url, kwargs.get("proxies")):
+ # A fresh Session per request, so a connection pinned to one address is
+ # never reused for a request validated against another.
+ adapter = _PinnedAddressAdapter(addresses)
+ session.mount("http://", adapter)
+ session.mount("https://", adapter)
+
+ response = session.request(method, url, allow_redirects=False, **kwargs)
+ # The response may still be streaming, and closing the session would close
+ # the pool holding its connection, so tie the session's lifetime to it.
+ response._composio_session = session # type: ignore[attr-defined]
+ return response
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 3164ec076..ef8ba4177 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -12,6 +12,14 @@ dependencies = [
"openai>=2.48.0",
"json-schema-to-pydantic>=0.4.11",
"jsonschema>=4.23.0",
+ # The pinning adapter mounts through `get_connection_with_tls_context`,
+ # which `HTTPAdapter.send` only calls on requests >= 2.32.2; older
+ # versions silently skip it and the pinning never engages.
+ "requests>=2.32.2",
+ # `url_safety` imports urllib3 directly: `NameResolutionError` only exists
+ # from 2.0, and the pinning adapter reaches into 2.x connection internals.
+ # requests alone allows 1.x, which would fail at import time.
+ "urllib3>=2",
]
classifiers = [
"Programming Language :: Python :: 3",
diff --git a/python/setup.py b/python/setup.py
index 72b88857a..bae7ae894 100644
--- a/python/setup.py
+++ b/python/setup.py
@@ -30,6 +30,12 @@ setup(
"openai>=2.48.0",
"json-schema-to-pydantic>=0.4.11",
"jsonschema>=4.23.0",
+ # `get_connection_with_tls_context` (the pinning adapter's mount
+ # point) is only called by `HTTPAdapter.send` on requests >= 2.32.2.
+ "requests>=2.32.2",
+ # `url_safety` imports urllib3 directly and needs 2.x: 1.x has no
+ # `NameResolutionError` and different connection internals.
+ "urllib3>=2",
],
include_package_data=True,
)
diff --git a/python/tests/test_file_upload_robustness.py b/python/tests/test_file_upload_robustness.py
index 2361f6749..9ad61480a 100644
--- a/python/tests/test_file_upload_robustness.py
+++ b/python/tests/test_file_upload_robustness.py
@@ -186,11 +186,8 @@ class TestMalformedContentLength:
@pytest.mark.parametrize(
"header", ["abc", "12.5", "1,024", "1e3", "0x10", "100 200", ""]
)
- @patch("composio.core.models._files.assert_safe_fetch_target")
- @patch("composio.core.models._files.requests.get")
- def test_malformed_header_does_not_raise(
- self, mock_get: MagicMock, _mock_assert: MagicMock, header: str
- ):
+ @patch("composio.core.models._files.safe_get")
+ def test_malformed_header_does_not_raise(self, mock_get: MagicMock, header: str):
"""A malformed header must not surface a raw ValueError to the caller."""
mock_get.return_value = _stream_response(
{"content-type": "image/jpeg", "Content-Length": header}
@@ -204,11 +201,8 @@ class TestMalformedContentLength:
assert content == b"payload"
assert mimetype == "image/jpeg"
- @patch("composio.core.models._files.assert_safe_fetch_target")
- @patch("composio.core.models._files.requests.get")
- def test_negative_header_still_enforced_while_streaming(
- self, mock_get: MagicMock, _mock_assert: MagicMock
- ):
+ @patch("composio.core.models._files.safe_get")
+ def test_negative_header_still_enforced_while_streaming(self, mock_get: MagicMock):
"""A negative header means unknown size, not a trusted "small" value."""
mock_get.return_value = _stream_response(
{"Content-Length": "-1"},
diff --git a/python/tests/test_files.py b/python/tests/test_files.py
index ac6dda819..939751205 100644
--- a/python/tests/test_files.py
+++ b/python/tests/test_files.py
@@ -1560,7 +1560,7 @@ class TestUrlHelperFunctions:
class TestFetchFileFromUrl:
"""Test cases for _fetch_file_from_url function."""
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_success(self, mock_get):
"""Test successful file fetch from URL."""
mock_response = MagicMock()
@@ -1581,11 +1581,10 @@ class TestFetchFileFromUrl:
mock_get.assert_called_once_with(
"https://example.com/image.jpg",
stream=True,
- allow_redirects=False,
timeout=(5, 60),
)
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_with_charset_in_content_type(self, mock_get):
"""Test that charset is stripped from content-type."""
mock_response = MagicMock()
@@ -1602,7 +1601,7 @@ class TestFetchFileFromUrl:
assert mimetype == "text/html"
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_generates_filename_when_missing(self, mock_get):
"""Test filename generation when URL has no filename."""
mock_response = MagicMock()
@@ -1618,7 +1617,7 @@ class TestFetchFileFromUrl:
assert filename.startswith("file_")
assert filename.endswith(".png")
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_generates_filename_when_no_extension(self, mock_get):
"""Test filename generation when URL filename has no extension."""
mock_response = MagicMock()
@@ -1636,7 +1635,7 @@ class TestFetchFileFromUrl:
assert filename.startswith("file_")
assert filename.endswith(".pdf")
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_failure(self, mock_get):
"""Test error handling when URL fetch fails."""
mock_response = MagicMock()
@@ -1651,7 +1650,7 @@ class TestFetchFileFromUrl:
assert "Failed to fetch file from URL" in str(exc_info.value)
assert "404" in str(exc_info.value)
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_decodes_percent_encoded_filename(self, mock_get):
"""Test that percent-encoded characters in URL filenames are decoded."""
mock_response = MagicMock()
@@ -1672,7 +1671,7 @@ class TestFetchFileFromUrl:
assert content == b"document content"
assert mimetype == "application/pdf"
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_decodes_unicode_filename(self, mock_get):
"""Test that percent-encoded unicode characters in URL filenames are decoded."""
mock_response = MagicMock()
@@ -1691,7 +1690,7 @@ class TestFetchFileFromUrl:
# Filename should be decoded to unicode
assert filename == "ファイル.jpg"
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_file_from_url_handles_plus_sign_in_filename(self, mock_get):
"""Test that plus signs in URL paths are preserved (not converted to spaces)."""
mock_response = MagicMock()
@@ -2215,9 +2214,8 @@ class TestTruncateFilename:
class TestFetchFileFromUrlWithTruncation:
"""Test cases for _fetch_file_from_url with filename truncation."""
- @patch("composio.core.models._files.assert_safe_fetch_target")
- @patch("composio.core.models._files.requests.get")
- def test_fetch_truncates_long_filename(self, mock_get, _mock_safe_fetch_target):
+ @patch("composio.core.models._files.safe_get")
+ def test_fetch_truncates_long_filename(self, mock_get):
"""Long filenames from URLs should be truncated."""
mock_response = MagicMock()
mock_response.ok = True
@@ -2239,7 +2237,7 @@ class TestFetchFileFromUrlWithTruncation:
assert filename.endswith(".pdf")
assert content == b"test content"
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_preserves_short_filename(self, mock_get):
"""Short filenames should be preserved unchanged."""
mock_response = MagicMock()
@@ -2256,11 +2254,8 @@ class TestFetchFileFromUrlWithTruncation:
assert filename == "photo.jpg"
- @patch("composio.core.models._files.assert_safe_fetch_target")
- @patch("composio.core.models._files.requests.get")
- def test_fetch_truncates_after_adding_extension(
- self, mock_get, _mock_safe_fetch_target
- ):
+ @patch("composio.core.models._files.safe_get")
+ def test_fetch_truncates_after_adding_extension(self, mock_get):
"""Truncation should happen after extension is appended."""
mock_response = MagicMock()
mock_response.ok = True
@@ -2280,7 +2275,7 @@ class TestFetchFileFromUrlWithTruncation:
assert len(filename) <= _MAX_FILENAME_LENGTH
assert filename.endswith(".pdf")
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_generated_filename_not_truncated(self, mock_get):
"""Generated timestamped filenames (when URL has no filename) should be short enough."""
mock_response = MagicMock()
@@ -2299,7 +2294,7 @@ class TestFetchFileFromUrlWithTruncation:
assert filename.endswith(".png")
assert len(filename) < 50 # Timestamped names are short
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_fetch_long_real_world_url(self, mock_get):
"""Long real-world URLs should be handled correctly."""
mock_response = MagicMock()
@@ -2326,7 +2321,7 @@ class TestFetchFileFromUrlWithTruncation:
class TestResponseSizeLimit:
"""Test response size limiting."""
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_rejects_oversized_content_length(self, mock_get):
"""Files with Content-Length > max_size should be rejected early."""
mock_response = MagicMock()
@@ -2341,7 +2336,7 @@ class TestResponseSizeLimit:
"https://example.com/large.zip", max_size=100 * 1024 * 1024
)
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_rejects_oversized_during_streaming(self, mock_get):
"""Files that exceed max_size during download should be rejected."""
mock_response = MagicMock()
@@ -2360,7 +2355,7 @@ class TestResponseSizeLimit:
"https://example.com/large.zip", max_size=10 * 1024 * 1024
)
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_accepts_file_within_limit(self, mock_get):
"""Files within size limit should be accepted."""
mock_response = MagicMock()
@@ -2382,7 +2377,7 @@ class TestResponseSizeLimit:
class TestRedirectHandling:
"""Test redirect handling (redirects should be rejected)."""
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_rejects_redirect_302(self, mock_get):
"""302 redirects should be rejected with clear error message."""
mock_response = MagicMock()
@@ -2394,7 +2389,7 @@ class TestRedirectHandling:
with pytest.raises(ErrorUploadingFile, match="redirect"):
_fetch_file_from_url("https://example.com/redirect")
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_rejects_redirect_301(self, mock_get):
"""301 redirects should be rejected."""
mock_response = MagicMock()
@@ -2406,7 +2401,7 @@ class TestRedirectHandling:
with pytest.raises(ErrorUploadingFile, match="redirect"):
_fetch_file_from_url("https://example.com/test")
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_rejects_redirect_307(self, mock_get):
"""307 redirects should be rejected."""
mock_response = MagicMock()
@@ -2418,7 +2413,7 @@ class TestRedirectHandling:
with pytest.raises(ErrorUploadingFile, match="redirect"):
_fetch_file_from_url("https://example.com/test")
- @patch("composio.core.models._files.requests.get")
+ @patch("composio.core.models._files.safe_get")
def test_rejects_redirect_308(self, mock_get):
"""308 redirects should be rejected."""
mock_response = MagicMock()
@@ -2540,8 +2535,7 @@ class TestFileDownloadablePathTraversal:
@pytest.fixture(autouse=True)
def _allow_fetch_target(self):
- with patch("composio.core.models._files.assert_safe_fetch_target"):
- yield
+ yield
def _mock_response(self, content: bytes = b"data") -> MagicMock:
response = MagicMock()
@@ -2559,7 +2553,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(b"#!/bin/sh\n"),
):
written = f.download(outdir, root=outdir)
@@ -2578,7 +2572,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(b"x"),
):
written = f.download(outdir, root=outdir)
@@ -2599,7 +2593,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(),
):
with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):
@@ -2615,7 +2609,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(b"%PDF-1.4"),
):
written = f.download(outdir, root=outdir)
@@ -2631,15 +2625,14 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(b"%PDF-1.4"),
) as mock_get:
f.download(outdir, root=outdir)
mock_get.assert_called_once_with(
- url="https://example.com/file",
+ "https://example.com/file",
stream=True,
- allow_redirects=False,
timeout=(5, 60),
)
@@ -2651,7 +2644,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file?token=abc",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
side_effect=requests.exceptions.Timeout(
"Max retries exceeded with url: /file?token=abc"
),
@@ -2676,7 +2669,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file?token=abc",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=response,
):
with pytest.raises(ErrorDownloadingFile) as exc_info:
@@ -2696,7 +2689,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file?token=abc",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=response,
):
with pytest.raises(ErrorDownloadingFile) as exc_info:
@@ -2720,7 +2713,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(),
):
with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):
@@ -2747,7 +2740,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(b"x"),
):
with pytest.raises(ErrorDownloadingFile, match="no usable basename"):
@@ -2783,7 +2776,7 @@ class TestFileDownloadablePathTraversal:
s3url="https://example.com/file",
)
with patch(
- "composio.core.models._files.requests.get",
+ "composio.core.models._files.safe_get",
return_value=self._mock_response(b"x"),
):
with pytest.raises(ErrorDownloadingFile, match=reason):
@@ -2838,7 +2831,7 @@ class TestDownloadDirSlugTraversal:
response.status_code = 200
response.iter_content = lambda chunk_size: [content]
response.close = MagicMock()
- return patch("composio.core.models._files.requests.get", return_value=response)
+ return patch("composio.core.models._files.safe_get", return_value=response)
@pytest.mark.parametrize("slug", TRAVERSALS)
def test_hostile_tool_slug_is_rejected(self, slug, tmp_path):
@@ -3069,15 +3062,14 @@ class TestResponseDerivedUrlsAreGuarded:
s3url="https://s3.example.com/file",
)
with patch(
- "composio.core.models._files.assert_safe_fetch_target"
- ) as mock_assert:
- with patch(
- "composio.core.models._files.requests.get",
- return_value=self._download_response(),
- ):
- f.download(tmp_path / "out", root=tmp_path / "out")
+ "composio.core.models._files.safe_get",
+ return_value=self._download_response(),
+ ) as mock_get:
+ f.download(tmp_path / "out", root=tmp_path / "out")
- mock_assert.assert_called_once_with("https://s3.example.com/file")
+ # `safe_get` is the guard: it validates the target and connects to the
+ # address it validated, rather than re-resolving the hostname.
+ assert mock_get.call_args.args == ("https://s3.example.com/file",)
def test_download_blocked_url_never_reaches_the_network(self, tmp_path):
outdir = tmp_path / "out"
@@ -3087,14 +3079,16 @@ class TestResponseDerivedUrlsAreGuarded:
s3url="http://169.254.169.254/latest/meta-data",
)
with patch(
- "composio.core.models._files.assert_safe_fetch_target",
+ "composio.utils.url_safety.assert_safe_fetch_target",
side_effect=BlockedInternalUrlError("blocked"),
):
- with patch("composio.core.models._files.requests.get") as mock_get:
+ with patch(
+ "composio.utils.url_safety.requests.Session.request"
+ ) as mock_send:
with pytest.raises(BlockedInternalUrlError):
f.download(outdir, root=outdir)
- mock_get.assert_not_called()
+ mock_send.assert_not_called()
assert not outdir.exists()
def test_download_refuses_to_follow_redirects(self, tmp_path):
@@ -3103,14 +3097,15 @@ class TestResponseDerivedUrlsAreGuarded:
mimetype="application/pdf",
s3url="https://s3.example.com/file",
)
- with patch("composio.core.models._files.assert_safe_fetch_target"):
- with patch(
- "composio.core.models._files.requests.get",
- return_value=self._download_response(),
- ) as mock_get:
- f.download(tmp_path / "out", root=tmp_path / "out")
+ with patch(
+ "composio.core.models._files.safe_get",
+ return_value=self._download_response(),
+ ) as mock_get:
+ f.download(tmp_path / "out", root=tmp_path / "out")
- assert mock_get.call_args.kwargs["allow_redirects"] is False
+ # `safe_get` never follows redirects, and passing `allow_redirects`
+ # through to it would be a way to turn that off.
+ assert "allow_redirects" not in mock_get.call_args.kwargs
def test_upload_bytes_to_s3_goes_through_safe_request(self):
client = self._s3_client("https://s3.example.com/upload")
@@ -3136,7 +3131,9 @@ class TestResponseDerivedUrlsAreGuarded:
"composio.utils.url_safety.assert_safe_fetch_target",
side_effect=BlockedInternalUrlError("blocked"),
):
- with patch("composio.utils.url_safety.requests.request") as mock_request:
+ with patch(
+ "composio.utils.url_safety.requests.Session.request"
+ ) as mock_request:
with pytest.raises(BlockedInternalUrlError):
_upload_bytes_to_s3(
client=client,
@@ -3170,7 +3167,9 @@ class TestResponseDerivedUrlsAreGuarded:
"composio.utils.url_safety.assert_safe_fetch_target",
side_effect=BlockedInternalUrlError("blocked"),
):
- with patch("composio.utils.url_safety.requests.request") as mock_request:
+ with patch(
+ "composio.utils.url_safety.requests.Session.request"
+ ) as mock_request:
with pytest.raises(BlockedInternalUrlError):
upload(url="http://127.0.0.1:9000/upload", file=source)
diff --git a/python/tests/test_tool_router_session_files.py b/python/tests/test_tool_router_session_files.py
index 7d795a0be..273f42009 100644
--- a/python/tests/test_tool_router_session_files.py
+++ b/python/tests/test_tool_router_session_files.py
@@ -18,7 +18,9 @@ from composio.exceptions import (
MODULE = "composio.core.models.tool_router_session_files"
SAFE_REQUEST = f"{MODULE}.safe_request"
-ASSERT_SAFE_FETCH_TARGET = f"{MODULE}.assert_safe_fetch_target"
+SAFE_GET = f"{MODULE}.safe_get"
+ASSERT_SAFE_FETCH_TARGET = "composio.utils.url_safety.assert_safe_fetch_target"
+SESSION_REQUEST = "composio.utils.url_safety.requests.Session.request"
def mock_stream_response(
@@ -214,14 +216,13 @@ class TestRemoteFile:
download_url="https://example.com/file",
)
with patch(ASSERT_SAFE_FETCH_TARGET):
- with patch("requests.get", return_value=mock_stream_response()) as mock_get:
+ with patch(SAFE_GET, return_value=mock_stream_response()) as mock_get:
result = rf.buffer()
assert result == b"file content"
mock_get.assert_called_once_with(
"https://example.com/file",
stream=True,
- allow_redirects=False,
timeout=(5, 60),
)
@@ -234,9 +235,7 @@ class TestRemoteFile:
download_url="https://example.com/file",
)
with patch(ASSERT_SAFE_FETCH_TARGET):
- with patch(
- "requests.get", return_value=mock_stream_response(status_code=404)
- ):
+ with patch(SAFE_GET, return_value=mock_stream_response(status_code=404)):
with pytest.raises(RemoteFileDownloadError) as exc_info:
rf.buffer()
@@ -252,9 +251,7 @@ class TestRemoteFile:
download_url="https://example.com/file",
)
with patch(ASSERT_SAFE_FETCH_TARGET):
- with patch(
- "requests.get", side_effect=requests.exceptions.Timeout("timeout")
- ):
+ with patch(SAFE_GET, side_effect=requests.exceptions.Timeout("timeout")):
with pytest.raises(RemoteFileDownloadError) as exc_info:
rf.buffer()
@@ -344,11 +341,12 @@ class TestResponseDerivedUrlsAreGuarded:
def test_buffer_validates_download_url(self):
rf = self._remote_file("https://s3.example.com/download")
- with patch(ASSERT_SAFE_FETCH_TARGET) as mock_assert:
- with patch("requests.get", return_value=mock_stream_response()):
- rf.buffer()
+ with patch(SAFE_GET, return_value=mock_stream_response()) as mock_get:
+ rf.buffer()
- mock_assert.assert_called_once_with("https://s3.example.com/download")
+ # `safe_get` is the guard: it validates the target and then connects to
+ # the address it validated instead of re-resolving the hostname.
+ assert mock_get.call_args.args == ("https://s3.example.com/download",)
def test_buffer_blocked_url_never_reaches_the_network(self):
rf = self._remote_file("http://169.254.169.254/latest/meta-data")
@@ -357,11 +355,11 @@ class TestResponseDerivedUrlsAreGuarded:
ASSERT_SAFE_FETCH_TARGET,
side_effect=BlockedInternalUrlError("blocked"),
):
- with patch("requests.get") as mock_get:
+ with patch(SESSION_REQUEST) as mock_send:
with pytest.raises(BlockedInternalUrlError):
rf.buffer()
- mock_get.assert_not_called()
+ mock_send.assert_not_called()
def test_buffer_rejects_redirects(self):
"""A validated URL must not be able to bounce the fetch elsewhere."""
@@ -369,12 +367,14 @@ class TestResponseDerivedUrlsAreGuarded:
with patch(ASSERT_SAFE_FETCH_TARGET):
with patch(
- "requests.get", return_value=mock_stream_response(status_code=302)
+ SAFE_GET, return_value=mock_stream_response(status_code=302)
) as mock_get:
with pytest.raises(RemoteFileDownloadError, match="redirect"):
rf.buffer()
- assert mock_get.call_args.kwargs["allow_redirects"] is False
+ # `safe_get` never follows redirects; passing `allow_redirects` through
+ # to it would be a way to turn that off.
+ assert "allow_redirects" not in mock_get.call_args.kwargs
def test_buffer_tolerates_malformed_content_length(self):
"""A malformed `Content-Length` means unknown size, not a crash.
@@ -391,7 +391,7 @@ class TestResponseDerivedUrlsAreGuarded:
}
with patch(ASSERT_SAFE_FETCH_TARGET):
- with patch("requests.get", return_value=malformed):
+ with patch(SAFE_GET, return_value=malformed):
assert rf.buffer() == b"file content"
def test_buffer_caps_response_size(self):
@@ -404,7 +404,7 @@ class TestResponseDerivedUrlsAreGuarded:
}
with patch(ASSERT_SAFE_FETCH_TARGET):
- with patch("requests.get", return_value=oversized):
+ with patch(SAFE_GET, return_value=oversized):
with pytest.raises(RemoteFileDownloadError, match="exceeds maximum"):
rf.buffer()
@@ -416,13 +416,13 @@ class TestResponseDerivedUrlsAreGuarded:
ASSERT_SAFE_FETCH_TARGET,
side_effect=BlockedInternalUrlError("blocked"),
):
- with patch("requests.get") as mock_get:
+ with patch(SESSION_REQUEST) as mock_send:
with pytest.raises(BlockedInternalUrlError):
rf.text()
with pytest.raises(BlockedInternalUrlError):
rf.save(str(tmp_path / "out.txt"))
- mock_get.assert_not_called()
+ mock_send.assert_not_called()
assert not (tmp_path / "out.txt").exists()
def test_upload_blocked_url_sends_nothing(self, files_mount):
@@ -430,7 +430,7 @@ class TestResponseDerivedUrlsAreGuarded:
"composio.utils.url_safety.assert_safe_fetch_target",
side_effect=BlockedInternalUrlError("blocked"),
):
- with patch("composio.utils.url_safety.requests.request") as mock_request:
+ with patch(SESSION_REQUEST) as mock_request:
with pytest.raises(BlockedInternalUrlError):
files_mount.upload(
b"hello world",
diff --git a/python/tests/test_url_safety.py b/python/tests/test_url_safety.py
index 723ea4421..0abbc93ac 100644
--- a/python/tests/test_url_safety.py
+++ b/python/tests/test_url_safety.py
@@ -109,7 +109,7 @@ def _response(status_code: int, location: str | None = None) -> MagicMock:
return response
-@patch("composio.utils.url_safety.requests.request")
+@patch("composio.utils.url_safety.requests.Session.request")
@patch("composio.utils.url_safety.assert_safe_fetch_target")
def test_safe_request_validates_before_sending(mock_assert, mock_request) -> None:
mock_assert.side_effect = BlockedInternalUrlError("blocked")
@@ -121,7 +121,7 @@ def test_safe_request_validates_before_sending(mock_assert, mock_request) -> Non
mock_request.assert_not_called()
-@patch("composio.utils.url_safety.requests.request")
+@patch("composio.utils.url_safety.requests.Session.request")
@patch("composio.utils.url_safety.assert_safe_fetch_target")
def test_safe_request_disables_automatic_redirects(mock_assert, mock_request) -> None:
mock_request.return_value = _response(200)
@@ -135,11 +135,11 @@ def test_safe_request_disables_automatic_redirects(mock_assert, mock_request) ->
assert mock_request.call_args.kwargs["allow_redirects"] is False
-@patch("composio.utils.url_safety.requests.request")
+@patch("composio.utils.url_safety.requests.Session.request")
@patch("composio.utils.url_safety.assert_safe_fetch_target")
def test_safe_request_revalidates_each_redirect_hop(mock_assert, mock_request) -> None:
"""A public URL that redirects into private space must be caught at the hop."""
- mock_assert.side_effect = [None, BlockedInternalUrlError("blocked")]
+ mock_assert.side_effect = [["93.184.216.34"], BlockedInternalUrlError("blocked")]
mock_request.return_value = _response(
307, "http://169.254.169.254/latest/meta-data"
)
@@ -155,7 +155,7 @@ def test_safe_request_revalidates_each_redirect_hop(mock_assert, mock_request) -
assert mock_request.call_count == 1
-@patch("composio.utils.url_safety.requests.request")
+@patch("composio.utils.url_safety.requests.Session.request")
@patch("composio.utils.url_safety.assert_safe_fetch_target")
def test_safe_request_follows_validated_redirect(mock_assert, mock_request) -> None:
"""S3 can answer a PUT with a 307 region redirect; that must still work."""
@@ -177,7 +177,7 @@ def test_safe_request_follows_validated_redirect(mock_assert, mock_request) -> N
assert body.read() == b"payload"
-@patch("composio.utils.url_safety.requests.request")
+@patch("composio.utils.url_safety.requests.Session.request")
@patch("composio.utils.url_safety.assert_safe_fetch_target")
def test_safe_request_relative_redirect_is_resolved(mock_assert, mock_request) -> None:
mock_request.side_effect = [_response(302, "/elsewhere"), _response(200)]
@@ -187,7 +187,7 @@ def test_safe_request_relative_redirect_is_resolved(mock_assert, mock_request) -
assert mock_assert.call_args_list[1] == call("https://files.example.com/elsewhere")
-@patch("composio.utils.url_safety.requests.request")
+@patch("composio.utils.url_safety.requests.Session.request")
@patch("composio.utils.url_safety.assert_safe_fetch_target")
def test_safe_request_rejects_endless_redirects(mock_assert, mock_request) -> None:
mock_request.return_value = _response(302, "https://s3.example.com/upload")
diff --git a/python/tests/test_url_safety_pinning.py b/python/tests/test_url_safety_pinning.py
new file mode 100644
index 000000000..ab245e424
--- /dev/null
+++ b/python/tests/test_url_safety_pinning.py
@@ -0,0 +1,276 @@
+"""Regression tests for the DNS-rebinding window in the SSRF guard.
+
+The guard resolves a hostname to decide whether a URL is safe. If the HTTP
+client then resolves that hostname a *second* time to open the socket, an
+attacker who controls the authoritative DNS can answer with a public address
+for the check and an internal one for the connect — the check and the use are
+about different addresses (issue #4151).
+
+These tests run against real sockets on loopback rather than mocking the HTTP
+client, because a mocked client cannot resolve anything twice and so cannot
+express the bug at all. The resolver is the only thing faked: it answers the
+first lookup of the hostname with one endpoint and every later lookup with
+another, which is exactly what a short-TTL rebinding record does.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import socket
+import threading
+import typing as t
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+import urllib3.connection
+
+from composio.exceptions import BlockedInternalUrlError
+from composio.utils.url_safety import _assert_pinned_peer, safe_get
+
+HOSTNAME = "rebind.test"
+
+
+def _is_ip_literal(host: str) -> bool:
+ try:
+ ipaddress.ip_address(host)
+ except ValueError:
+ return False
+ return True
+
+
+class _RecordingServer:
+ """A loopback HTTP server that records what actually reached it."""
+
+ def __init__(self, body: bytes) -> None:
+ self.hits: t.List[str] = []
+ recorder = self
+
+ class Handler(BaseHTTPRequestHandler):
+ protocol_version = "HTTP/1.1"
+
+ def do_GET(self) -> None: # noqa: N802 - stdlib naming
+ recorder.hits.append(self.headers.get("Host", ""))
+ self.send_response(200)
+ self.send_header("Content-Type", "text/plain")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def log_message(self, *args: t.Any) -> None:
+ pass
+
+ self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ # Keep-alive connections would otherwise hold `shutdown()` open.
+ self._server.daemon_threads = True
+ self.port = self._server.server_address[1]
+ self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+ self._thread.start()
+
+ def close(self) -> None:
+ self._server.shutdown()
+ self._server.server_close()
+
+
+def validated_server() -> t.Iterator[_RecordingServer]:
+ server = _RecordingServer(b"public payload")
+ yield server
+ server.close()
+
+
+def rebound_server() -> t.Iterator[_RecordingServer]:
+ server = _RecordingServer(b"internal secret")
+ yield server
+ server.close()
+
+
+def no_inherited_proxy(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Make ``_proxy_applies`` deterministic: no proxy, from env or system.
+
+ An inherited ``HTTP_PROXY`` (or a macOS/Windows system proxy, which
+ ``getproxies`` also reads) would disable the pinning adapter, and the
+ request would dial the proxy's answer to the hostname instead of the
+ validated address — failing these tests on machines that carry one.
+ """
+ monkeypatch.setattr(
+ "requests.utils.get_environ_proxies",
+ lambda url: {},
+ )
+
+
+def rebinding_dns(
+ no_inherited_proxy: None,
+ validated_server: _RecordingServer,
+ rebound_server: _RecordingServer,
+) -> t.Iterator[None]:
+ """Answer the first lookup of the hostname benignly, later ones with the victim.
+
+ Both endpoints live on 127.0.0.1 because a test cannot bind a public
+ address, so they are told apart by port; `is_blocked_ip` is stubbed out for
+ the same reason. Neither substitution touches the property under test,
+ which is whether the fetch connects to the endpoint that was validated or
+ re-resolves and connects somewhere else. The blocklist itself is covered by
+ ``test_url_safety.py``.
+ """
+ lookups: t.List[str] = []
+ real_getaddrinfo = socket.getaddrinfo
+
+ def fake_getaddrinfo(host, port, *args, **kwargs): # type: ignore[no-untyped-def]
+ # A real resolver hands an IP literal straight back, which is what the
+ # fix relies on when it connects to the address it already validated.
+ if _is_ip_literal(host):
+ return real_getaddrinfo(host, port, *args, **kwargs)
+
+ lookups.append(host)
+ victim = rebound_server if len(lookups) > 1 else validated_server
+ return [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", victim.port))]
+
+ with patch("socket.getaddrinfo", side_effect=fake_getaddrinfo):
+ with patch("composio.utils.url_safety.is_blocked_ip", return_value=False):
+ yield
+
+
+def test_proxy_environment_keeps_only_the_pre_flight_check(
+ validated_server: _RecordingServer,
+) -> None:
+ """Behind a proxy the SDK cannot pin: the proxy resolves the hostname.
+
+ Documented residual — ``_proxy_applies`` disables the pinning adapter, so
+ the request dials the proxy. A proxy nothing can reach makes that
+ observable: the request must fail by trying the proxy, never by dialling
+ the validated address. (This test deliberately does not use
+ ``no_inherited_proxy`` — it needs ``HTTP_PROXY`` visible — so it patches
+ the resolver inline instead.)
+ """
+ real_getaddrinfo = socket.getaddrinfo
+
+ def fake_getaddrinfo(host, port, *args, **kwargs): # type: ignore[no-untyped-def]
+ if _is_ip_literal(host):
+ return real_getaddrinfo(host, port, *args, **kwargs)
+ return [
+ (
+ socket.AF_INET,
+ socket.SOCK_STREAM,
+ 6,
+ "",
+ ("127.0.0.1", validated_server.port),
+ )
+ ]
+
+ # Empty NO_PROXY so no machine-level bypass list can cover the hostname.
+ env = {"HTTP_PROXY": "http://127.0.0.1:9", "NO_PROXY": "", "no_proxy": ""}
+ with patch("socket.getaddrinfo", side_effect=fake_getaddrinfo):
+ with patch("composio.utils.url_safety.is_blocked_ip", return_value=False):
+ with patch("composio.utils.url_safety._PinnedAddressAdapter") as adapter:
+ with patch.dict(os.environ, env):
+ with pytest.raises(requests.exceptions.RequestException):
+ safe_get(
+ f"http://{HOSTNAME}:{validated_server.port}/payload",
+ timeout=(1, 1),
+ )
+
+ adapter.assert_not_called()
+ assert validated_server.hits == []
+
+
[email protected]("rebinding_dns")
+def test_fetch_connects_to_the_address_it_validated(
+ validated_server: _RecordingServer, rebound_server: _RecordingServer
+) -> None:
+ response = safe_get(
+ f"http://{HOSTNAME}:{validated_server.port}/payload", timeout=(5, 5)
+ )
+
+ assert response.content == b"public payload"
+ assert len(validated_server.hits) == 1
+ # The whole point: the rebound endpoint is never even connected to, so
+ # neither its body nor a bare TCP connection to it is available to the
+ # attacker.
+ assert rebound_server.hits == []
+
+
[email protected]("rebinding_dns")
+def test_pinning_keeps_the_hostname_on_the_wire(
+ validated_server: _RecordingServer,
+) -> None:
+ """The address is pinned; the hostname is not replaced by it.
+
+ Pinning by rewriting the connection's host would send ``Host: 127.0.0.1``
+ and offer the IP as TLS SNI, which fails certificate verification against
+ every real origin.
+ """
+ safe_get(f"http://{HOSTNAME}:{validated_server.port}/payload", timeout=(5, 5))
+
+ assert validated_server.hits == [f"{HOSTNAME}:{validated_server.port}"]
+
+
+def test_pinning_still_has_the_urllib3_internals_it_relies_on() -> None:
+ """Fail loudly if a urllib3 upgrade removes what the adapter hooks into.
+
+ Silently losing either of these would silently un-pin every connection.
+ """
+ connection = urllib3.connection.HTTPConnection("example.com")
+
+ assert hasattr(connection, "_new_conn")
+ assert hasattr(connection, "_dns_host")
+
+
+def test_peer_mismatch_fails_closed() -> None:
+ """The last line of defence, checked before a byte is written to the socket."""
+ sock = MagicMock()
+ sock.getpeername.return_value = ("169.254.169.254", 80)
+
+ with pytest.raises(BlockedInternalUrlError, match="169.254.169.254"):
+ _assert_pinned_peer(sock, "93.184.216.34", HOSTNAME)
+
+ sock.close.assert_called_once()
+
+
+def test_connect_falls_back_to_the_next_validated_address(
+ no_inherited_proxy: None,
+ validated_server: _RecordingServer,
+) -> None:
+ """A dual-stack host must not be stranded on its first answer.
+
+ ``::1`` is validated but nothing listens there, so the connect has to move
+ on to the second answer the way the HTTP client would have. urllib3 rewraps
+ connect failures into its own exception hierarchy, none of which inherits
+ from ``OSError``, so this also pins down which exceptions the fallback has
+ to catch.
+ """
+ real_getaddrinfo = socket.getaddrinfo
+
+ def fake_getaddrinfo(host, port, *args, **kwargs): # type: ignore[no-untyped-def]
+ if _is_ip_literal(host):
+ return real_getaddrinfo(host, port, *args, **kwargs)
+ return [
+ (
+ socket.AF_INET6,
+ socket.SOCK_STREAM,
+ 6,
+ "",
+ ("::1", validated_server.port, 0, 0),
+ ),
+ (
+ socket.AF_INET,
+ socket.SOCK_STREAM,
+ 6,
+ "",
+ ("127.0.0.1", validated_server.port),
+ ),
+ ]
+
+ with patch("socket.getaddrinfo", side_effect=fake_getaddrinfo):
+ with patch("composio.utils.url_safety.is_blocked_ip", return_value=False):
+ response = safe_get(
+ f"http://{HOSTNAME}:{validated_server.port}/payload", timeout=(5, 5)
+ )
+
+ assert response.content == b"public payload"
+ assert len(validated_server.hits) == 1
diff --git a/ts/packages/core/package.json b/ts/packages/core/package.json
index 4f5197be5..cbaded142 100644
--- a/ts/packages/core/package.json
+++ b/ts/packages/core/package.json
@@ -119,6 +119,7 @@
"picocolors": "catalog:",
"pusher-js": "^8.6.0",
"semver": "^7.8.5",
+ "undici": "^7.29.0",
"zod-to-json-schema": "catalog:"
},
"gitHead": "4fae6e54d5c150fba955cc5fa314281da5a1e064",
diff --git a/ts/packages/core/src/utils/pinnedDispatcher.node.ts b/ts/packages/core/src/utils/pinnedDispatcher.node.ts
new file mode 100644
index 000000000..632fef014
--- /dev/null
+++ b/ts/packages/core/src/utils/pinnedDispatcher.node.ts
@@ -0,0 +1,118 @@
+import { isIP } from 'node:net';
+import type { Agent } from 'undici';
+
+/**
+ * The `globalThis` symbols that hold the process-wide dispatcher `fetch` falls
+ * back to. Every undici in the process shares them — including the one inside
+ * the Node runtime — and `setGlobalDispatcher` writes both, so reading them
+ * directly sees the same dispatcher the runtime's own `fetch` would use.
+ *
+ * Read rather than imported: importing `undici` installs a dispatcher of its
+ * own as an import side effect (see {@link loadUndici}), which is exactly what
+ * this module must not do at load time.
+ */
+const GLOBAL_DISPATCHER_SYMBOLS = [
+ Symbol.for('undici.globalDispatcher.1'),
+ Symbol.for('undici.globalDispatcher.2'),
+] as const;
+
+/**
+ * `undici`, imported on first use rather than at module load.
+ *
+ * Importing it runs `if (getGlobalDispatcher() === undefined) setGlobalDispatcher(new Agent())`
+ * as a side effect, which would hand every unrelated `fetch` in the host
+ * application this package's undici instead of the runtime's own — a global
+ * change no caller asked for by importing `@composio/core`. Deferring the
+ * import to the first pinned request keeps that side effect on the code path
+ * that actually needs undici, and behind the `hasCustomGlobalDispatcher` check
+ * that reads the slot's true, pre-import state.
+ *
+ * A process that does make a pinned request still ends up on this package's
+ * `Agent` if nothing had claimed the slot yet. That much is not reversible:
+ * undici defines the slot non-configurable and writable, so it cannot be
+ * cleared back to empty — assigning `undefined` leaves the runtime's own
+ * `fetch` asserting on a missing dispatcher.
+ */
+let undici: Promise<typeof import('undici')> | undefined;
+const loadUndici = (): Promise<typeof import('undici')> => (undici ??= import('undici'));
+
+/**
+ * A `fetch` dispatcher that connects to `addresses` instead of resolving the
+ * hostname again.
+ *
+ * The SSRF guard resolves a hostname to decide whether a URL is safe to fetch.
+ * `fetch` would then resolve that hostname a second time when it opens the
+ * socket, and the two answers need not match: a short-TTL record can answer
+ * with a public address for the check and an internal one for the connect
+ * (DNS rebinding). Pinning the connect to the address that was validated
+ * removes the second lookup, so there is nothing left to rebind.
+ *
+ * Only the connect target is replaced. The request still carries the original
+ * hostname in `Host` and offers it as TLS SNI, so certificate verification is
+ * unchanged — connecting by IP with the IP as SNI would fail against every
+ * origin whose certificate names a hostname.
+ *
+ * The dispatcher is handed to the runtime's own `fetch`, so callers that stub
+ * `globalThis.fetch` keep working. That does tie the `undici` major to the one
+ * Node's `fetch` speaks — undici 8 dispatchers are rejected by the Node
+ * versions this package supports — which is why the dependency is pinned to
+ * `^7`, and why `pinnedDispatcher.node.test.ts` exercises a real socket on
+ * every Node version in CI rather than mocking the transport.
+ */
+export const createPinnedDispatcher = async (addresses: ReadonlyArray<string>): Promise<Agent> => {
+ const { Agent } = await loadUndici();
+
+ return new Agent({
+ connect: {
+ lookup: (_hostname, options, callback) => {
+ // Node calls a lookup in one of two shapes and picks between them at
+ // connect time: `(err, addresses)` when it is doing Happy Eyeballs,
+ // and `(err, address, family)` otherwise — when `autoSelectFamily` is
+ // off, or a `family`/`localAddress` was requested. Answering in the
+ // wrong shape is rejected as an invalid address, which would fail
+ // every pinned fetch in such a process.
+ if (options.all) {
+ // All of them, in resolver order: handing over a single address of a
+ // dual-stack host would strand callers whose network cannot reach
+ // that family, where the runtime would otherwise have fallen back.
+ callback(
+ null,
+ addresses.map(address => ({ address, family: isIP(address) }))
+ );
+ return;
+ }
+
+ const [address] = addresses;
+ callback(null, address, isIP(address));
+ },
+ },
+ });
+};
+
+/**
+ * Whether the process-wide dispatcher `fetch` falls back to (when a request
+ * carries no `dispatcher` of its own) is something other than a stock `Agent`.
+ *
+ * A `ProxyAgent`, `EnvHttpProxyAgent`, or custom dispatcher installed through
+ * `setGlobalDispatcher` is visible here, and pinning stands down for it: the
+ * connect would dial the validated origin instead of that route's next hop.
+ *
+ * Nothing installed yet is *not* custom. The dispatcher slot is empty until
+ * either the runtime's `fetch` or an undici import fills it, so an absent
+ * dispatcher means no caller has configured a route — treating it as custom
+ * would disable pinning for every process that had not yet made a request.
+ *
+ * Stock-ness is compared by constructor *name*, deliberately not with
+ * `instanceof Agent`: an `Agent` created by the runtime's internal undici is a
+ * different class from this package's `Agent`, so once the runtime's own
+ * `fetch` has initialized its default dispatcher, an `instanceof` check would
+ * report a stock setup as custom and silently disable pinning.
+ */
+export const hasCustomGlobalDispatcher = (): boolean => {
+ const slots = globalThis as unknown as Record<symbol, { constructor?: { name?: string } }>;
+ const dispatcher = GLOBAL_DISPATCHER_SYMBOLS.map(symbol => slots[symbol]).find(
+ installed => installed !== undefined
+ );
+
+ return dispatcher !== undefined && dispatcher.constructor?.name !== 'Agent';
+};
diff --git a/ts/packages/core/src/utils/ssrfGuard.node.ts b/ts/packages/core/src/utils/ssrfGuard.node.ts
index 366e737ed..1a941deff 100644
--- a/ts/packages/core/src/utils/ssrfGuard.node.ts
+++ b/ts/packages/core/src/utils/ssrfGuard.node.ts
@@ -1,6 +1,7 @@
import { lookup } from 'node:dns/promises'; // we're in a Node.js-specific module
import { isIP } from 'node:net';
import { ComposioBlockedInternalUrlError } from '../errors/SsrfErrors';
+import { createPinnedDispatcher, hasCustomGlobalDispatcher } from './pinnedDispatcher.node';
/**
* SSRF guard for user-supplied URL file inputs.
@@ -16,14 +17,43 @@ import { ComposioBlockedInternalUrlError } from '../errors/SsrfErrors';
* which defeats decimal/octal/hex IP obfuscation) before every fetch, and
* follows redirects manually so each hop is re-validated.
*
- * Known residual: a DNS name could resolve to a public address here and rebind
- * to an internal one before the underlying `fetch` connects (a TOCTOU / DNS
- * rebinding window). Closing that fully requires pinning the validated IP at
- * connect time (a custom dispatcher), which is out of scope for this guard.
+ * The address that was validated is also the address connected to: `fetch` gets
+ * a dispatcher pinned to it (see {@link createPinnedDispatcher}), so the
+ * hostname is never resolved a second time. Without that, a name could resolve
+ * to a public address during validation and rebind to an internal one before
+ * the connect — a TOCTOU window the Python guard closes the same way.
+ *
+ * Residual: a hop whose effective dispatcher is a configured route — a
+ * caller-supplied `init.dispatcher`, a non-stock global dispatcher (a
+ * `ProxyAgent` or `EnvHttpProxyAgent` installed via `setGlobalDispatcher`), or
+ * the runtime's env-proxy mode (`NODE_USE_ENV_PROXY`) — keeps only the
+ * pre-flight validation. Pinning would dial the validated address instead of
+ * the proxy, and the proxy resolves the hostname itself where the SDK cannot
+ * see or pin that resolution. The Python guard carries the same residual for
+ * the same reason (`_proxy_applies`).
*/
const MAX_REDIRECTS = 5;
+/**
+ * Whether the runtime would route `url` through an env proxy the SDK cannot
+ * see into. Only meaningful when `NODE_USE_ENV_PROXY` opts the built-in
+ * `fetch` into env proxies (Node >= 24); without that flag the runtime's
+ * `fetch` ignores `HTTP_PROXY`/`HTTPS_PROXY` entirely, so mirroring Python's
+ * bare env-var check would drop pinning for users whose fetch never proxied.
+ *
+ * `NO_PROXY=*` is the one bypass honored precisely (nothing is proxied, so
+ * pinning is safe again); per-host `NO_PROXY` entries are treated
+ * conservatively as proxied rather than parsed.
+ */
+const envProxyApplies = (url: URL): boolean => {
+ const useEnvProxy = ['1', 'true'].includes((process.env.NODE_USE_ENV_PROXY ?? '').toLowerCase());
+ if (!useEnvProxy) return false;
+ if ((process.env.NO_PROXY ?? process.env.no_proxy ?? '') === '*') return false;
+ const schemeVar = url.protocol === 'https:' ? 'HTTPS_PROXY' : 'HTTP_PROXY';
+ return Boolean(process.env[schemeVar] ?? process.env[schemeVar.toLowerCase()]);
+};
+
const ipv4ToLong = (ip: string): number => {
const [a, b, c, d] = ip.split('.').map(Number);
return (((a << 24) >>> 0) | (b << 16) | (c << 8) | d) >>> 0;
@@ -133,8 +163,12 @@ export const isBlockedIp = (ip: string): boolean => {
* Validate a single URL: it must be http(s), its host must resolve, and every
* resolved address must be publicly routable. Throws
* {@link ComposioBlockedInternalUrlError} otherwise.
+ *
+ * @returns the validated addresses to connect to, in resolver order. Callers
+ * must connect to *those* rather than let the client resolve the hostname
+ * again; see {@link ssrfSafeFetch}.
*/
-export const assertSafeFetchTarget = async (rawUrl: string): Promise<void> => {
+export const assertSafeFetchTarget = async (rawUrl: string): Promise<string[]> => {
let url: URL;
try {
url = new URL(rawUrl);
@@ -158,6 +192,10 @@ export const assertSafeFetchTarget = async (rawUrl: string): Promise<void> => {
throw new ComposioBlockedInternalUrlError(`Could not resolve host "${host}"`, { url: rawUrl });
}
+ if (resolved.length === 0) {
+ throw new ComposioBlockedInternalUrlError(`Could not resolve host "${host}"`, { url: rawUrl });
+ }
+
for (const { address } of resolved) {
if (isBlockedIp(address)) {
throw new ComposioBlockedInternalUrlError(
@@ -166,13 +204,22 @@ export const assertSafeFetchTarget = async (rawUrl: string): Promise<void> => {
);
}
}
+
+ // Every answer was validated, so all of them are safe to connect to, and
+ // resolver order is the system's own address preference.
+ return resolved.map(({ address }) => address);
};
/**
- * Drop-in replacement for `fetch` that blocks SSRF. Validates the target before
- * connecting and re-validates every redirect hop (redirects are followed
- * manually up to {@link MAX_REDIRECTS}). Intermediate redirect bodies are
- * cancelled; non-redirect responses are returned unchanged.
+ * Drop-in replacement for `fetch` that blocks SSRF. Validates the target, then
+ * connects to the address it validated, and re-validates and re-pins every
+ * redirect hop (redirects are followed manually up to {@link MAX_REDIRECTS}).
+ * Intermediate redirect bodies are cancelled; non-redirect responses are
+ * returned unchanged.
+ *
+ * A hop whose effective dispatcher is a configured route (caller-supplied
+ * `init.dispatcher`, non-stock global dispatcher, env-proxy mode) is *not*
+ * pinned — see the module residual above.
*/
export const ssrfSafeFetch = async (
rawUrl: string,
@@ -182,9 +229,40 @@ export const ssrfSafeFetch = async (
let currentUrl = rawUrl;
for (let hop = 0; hop <= maxRedirects; hop++) {
- await assertSafeFetchTarget(currentUrl);
+ const addresses = await assertSafeFetchTarget(currentUrl);
+
+ // Pinning replaces the connect target; through a configured route that
+ // would dial the validated origin instead of the route's next hop (the
+ // proxy), so those hops keep the pre-flight check only.
+ const callerDispatcher = (init as RequestInit & { dispatcher?: unknown }).dispatcher;
+ const respectConfiguredRoute =
+ callerDispatcher !== undefined ||
+ envProxyApplies(new URL(currentUrl)) ||
+ hasCustomGlobalDispatcher();
+
+ const dispatcher = respectConfiguredRoute ? undefined : await createPinnedDispatcher(addresses);
- const response = await fetch(currentUrl, { ...init, redirect: 'manual' });
+ let response: Response;
+ try {
+ // `dispatcher` is a Node-only extension to `RequestInit`.
+ response = await fetch(
+ currentUrl,
+ (dispatcher === undefined
+ ? { ...init, redirect: 'manual' }
+ : { ...init, redirect: 'manual', dispatcher }) as RequestInit
+ );
+ } catch (error) {
+ if (dispatcher !== undefined) {
+ await dispatcher.close().catch(() => undefined);
+ }
+ throw error;
+ }
+
+ // `close()` is graceful: it waits for the in-flight request — including a
+ // body still being streamed to the caller — before releasing the socket.
+ if (dispatcher !== undefined) {
+ void dispatcher.close().catch(() => undefined);
+ }
const isRedirect =
response.status >= 300 && response.status < 400 && response.headers.has('location');
diff --git a/ts/packages/core/test/models/RemoteFile.test.ts b/ts/packages/core/test/models/RemoteFile.test.ts
index 9d4596161..ae4e05784 100644
--- a/ts/packages/core/test/models/RemoteFile.test.ts
+++ b/ts/packages/core/test/models/RemoteFile.test.ts
@@ -98,10 +98,13 @@ describe('RemoteFile', () => {
const result = await file.buffer();
// `redirect: 'manual'` is the guard following redirects itself so it can
- // re-validate each hop, rather than letting fetch follow them unchecked.
- expect(globalThis.fetch).toHaveBeenCalledWith(validCamelCaseData.downloadUrl, {
- redirect: 'manual',
- });
+ // re-validate each hop, rather than letting fetch follow them unchecked;
+ // the `dispatcher` alongside it pins the connection to the address the
+ // guard validated.
+ expect(globalThis.fetch).toHaveBeenCalledWith(
+ validCamelCaseData.downloadUrl,
+ expect.objectContaining({ redirect: 'manual' })
+ );
expect(result).toBeInstanceOf(Uint8Array);
expect(result).toEqual(content);
});
diff --git a/ts/packages/core/test/utils/fileUtils.test.ts b/ts/packages/core/test/utils/fileUtils.test.ts
index f89e0a07a..e8445d1e8 100644
--- a/ts/packages/core/test/utils/fileUtils.test.ts
+++ b/ts/packages/core/test/utils/fileUtils.test.ts
@@ -118,10 +118,11 @@ describe('fileUtils', () => {
});
expect(result.name).toBe('document.pdf');
- expect(mockFetch).toHaveBeenCalledWith(urlWithQuery, {
- signal: undefined,
- redirect: 'manual',
- });
+ expect(mockFetch).toHaveBeenCalledWith(
+ urlWithQuery,
+ // Plus a `dispatcher` pinned to the address the guard validated.
+ expect.objectContaining({ signal: undefined, redirect: 'manual' })
+ );
});
it('should generate filename when URL has no filename', async () => {
diff --git a/ts/packages/core/test/utils/pinnedDispatcher.node.test.ts b/ts/packages/core/test/utils/pinnedDispatcher.node.test.ts
new file mode 100644
index 000000000..7629b1c45
--- /dev/null
+++ b/ts/packages/core/test/utils/pinnedDispatcher.node.test.ts
@@ -0,0 +1,124 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { createServer, type Server } from 'node:http';
+import { getDefaultAutoSelectFamily, setDefaultAutoSelectFamily, type AddressInfo } from 'node:net';
+import { Agent, ProxyAgent, getGlobalDispatcher, setGlobalDispatcher } from 'undici';
+import {
+ createPinnedDispatcher,
+ hasCustomGlobalDispatcher,
+} from '../../src/utils/pinnedDispatcher.node';
+
+/**
+ * The SSRF guard resolves a hostname to validate it. If `fetch` then resolves
+ * that hostname again to open the socket, the two answers can differ — a
+ * short-TTL record can answer publicly for the check and internally for the
+ * connect (DNS rebinding, issue #4151).
+ *
+ * These tests use a real server and a hostname under `.invalid`, which RFC 2606
+ * guarantees never resolves. A request that arrives at the server therefore
+ * proves the connect used the pinned address and never consulted DNS — which is
+ * exactly the property that closes the rebinding window.
+ */
+describe('createPinnedDispatcher', () => {
+ let server: Server | undefined;
+ const hosts: string[] = [];
+
+ const startServer = async (): Promise<number> => {
+ server = createServer((request, response) => {
+ hosts.push(request.headers.host ?? '');
+ response.writeHead(200, { 'content-type': 'text/plain' });
+ response.end('pinned payload');
+ });
+ await new Promise<void>(resolve => server!.listen(0, '127.0.0.1', resolve));
+ return (server!.address() as AddressInfo).port;
+ };
+
+ afterEach(async () => {
+ hosts.length = 0;
+ if (server) {
+ await new Promise<void>(resolve => server!.close(() => resolve()));
+ server = undefined;
+ }
+ });
+
+ it('connects to the pinned address instead of resolving the hostname', async () => {
+ const port = await startServer();
+ const dispatcher = await createPinnedDispatcher(['127.0.0.1']);
+
+ const response = await fetch(`http://pinned.invalid:${port}/payload`, {
+ dispatcher,
+ } as RequestInit);
+
+ expect(response.status).toBe(200);
+ expect(await response.text()).toBe('pinned payload');
+ await dispatcher.close();
+ });
+
+ it('leaves the hostname on the wire, so Host and TLS SNI are unchanged', async () => {
+ const port = await startServer();
+ const dispatcher = await createPinnedDispatcher(['127.0.0.1']);
+
+ await fetch(`http://pinned.invalid:${port}/payload`, { dispatcher } as RequestInit);
+
+ // Pinning by rewriting the URL to the IP would send `Host: 127.0.0.1` and
+ // offer the IP as SNI, failing certificate verification against every
+ // origin whose certificate names a hostname.
+ expect(hosts).toEqual([`pinned.invalid:${port}`]);
+ await dispatcher.close();
+ });
+
+ it('is the only reason the request lands: unpinned, the hostname does not resolve', async () => {
+ const port = await startServer();
+
+ await expect(fetch(`http://pinned.invalid:${port}/payload`)).rejects.toThrow();
+ expect(hosts).toEqual([]);
+ });
+
+ it('pins just as well with Happy Eyeballs off, which asks for one address', async () => {
+ // Node calls the lookup with `all: false` here and expects a single
+ // address rather than a list. A host that disables auto-select-family —
+ // a common workaround for Happy Eyeballs stalls — would otherwise get
+ // `ERR_INVALID_IP_ADDRESS` on every SDK fetch.
+ const port = await startServer();
+ const previous = getDefaultAutoSelectFamily();
+ setDefaultAutoSelectFamily(false);
+
+ try {
+ const dispatcher = await createPinnedDispatcher(['127.0.0.1']);
+ const response = await fetch(`http://pinned.invalid:${port}/payload`, {
+ dispatcher,
+ } as RequestInit);
+
+ expect(response.status).toBe(200);
+ expect(await response.text()).toBe('pinned payload');
+ await dispatcher.close();
+ } finally {
+ setDefaultAutoSelectFamily(previous);
+ }
+ });
+});
+
+describe('hasCustomGlobalDispatcher', () => {
+ it('reports the stock dispatcher as not custom', () => {
+ expect(hasCustomGlobalDispatcher()).toBe(false);
+ });
+
+ it('reports a configured proxy dispatcher as custom', () => {
+ const previous = getGlobalDispatcher();
+ setGlobalDispatcher(new ProxyAgent({ uri: 'http://127.0.0.1:9' }));
+ try {
+ expect(hasCustomGlobalDispatcher()).toBe(true);
+ } finally {
+ setGlobalDispatcher(previous);
+ }
+ });
+
+ it('still calls a plain Agent stock, even when created by this package', () => {
+ const previous = getGlobalDispatcher();
+ setGlobalDispatcher(new Agent());
+ try {
+ expect(hasCustomGlobalDispatcher()).toBe(false);
+ } finally {
+ setGlobalDispatcher(previous);
+ }
+ });
+});
diff --git a/ts/packages/core/test/utils/ssrfGuard.test.ts b/ts/packages/core/test/utils/ssrfGuard.test.ts
index 4978ba90d..65ecd1f43 100644
--- a/ts/packages/core/test/utils/ssrfGuard.test.ts
+++ b/ts/packages/core/test/utils/ssrfGuard.test.ts
@@ -6,6 +6,19 @@ vi.mock('node:dns/promises', () => ({
lookup: vi.fn(),
}));
+vi.mock('../../src/utils/pinnedDispatcher.node', () => ({
+ createPinnedDispatcher: vi.fn(() => Promise.resolve({ close: () => Promise.resolve() })),
+ hasCustomGlobalDispatcher: vi.fn(() => false),
+}));
+
+import {
+ createPinnedDispatcher,
+ hasCustomGlobalDispatcher,
+} from '../../src/utils/pinnedDispatcher.node';
+
+const mockCreatePinnedDispatcher = vi.mocked(createPinnedDispatcher);
+const mockHasCustomGlobalDispatcher = vi.mocked(hasCustomGlobalDispatcher);
+
// eslint-disable-next-line no-restricted-imports
import { lookup } from 'node:dns/promises';
@@ -97,9 +110,11 @@ describe('assertSafeFetchTarget', () => {
);
});
- it('allows a host that resolves only to public addresses', async () => {
+ it('allows a host that resolves only to public addresses, returning the address to connect to', async () => {
resolvesTo('93.184.216.34');
- await expect(assertSafeFetchTarget('https://example.com/file.pdf')).resolves.toBeUndefined();
+ await expect(assertSafeFetchTarget('https://example.com/file.pdf')).resolves.toEqual([
+ '93.184.216.34',
+ ]);
});
it('blocks an IPv6 literal loopback host', async () => {
@@ -116,10 +131,97 @@ describe('ssrfSafeFetch', () => {
beforeEach(() => {
mockLookup.mockReset();
mockFetch.mockReset();
+ mockCreatePinnedDispatcher.mockClear();
+ mockHasCustomGlobalDispatcher.mockReturnValue(false);
+ // Deterministic even on machines that carry the runtime env-proxy opt-in.
+ vi.stubEnv('NODE_USE_ENV_PROXY', '');
vi.stubGlobal('fetch', mockFetch);
});
afterEach(() => vi.unstubAllGlobals());
+ it('connects to the address it validated, rather than resolving the host again', async () => {
+ resolvesTo('93.184.216.34');
+ mockFetch.mockResolvedValue(new Response('data', { status: 200 }));
+
+ await ssrfSafeFetch('https://example.com/file.pdf');
+
+ // Without this the host is resolved twice — once to validate, once to
+ // connect — and a short-TTL record can answer those two lookups
+ // differently (DNS rebinding, issue #4151).
+ expect(mockCreatePinnedDispatcher).toHaveBeenCalledWith(['93.184.216.34']);
+ expect(mockFetch.mock.calls[0][1].dispatcher).toBeDefined();
+ });
+
+ it("re-pins each redirect hop to that hop's own validated address", async () => {
+ mockLookup
+ .mockResolvedValueOnce([{ address: '93.184.216.34', family: 4 }] as never)
+ .mockResolvedValueOnce([{ address: '151.101.1.140', family: 4 }] as never);
+ mockFetch
+ .mockResolvedValueOnce(
+ new Response(null, { status: 302, headers: { location: 'https://cdn.example.com/f' } })
+ )
+ .mockResolvedValueOnce(new Response('data', { status: 200 }));
+
+ await ssrfSafeFetch('https://example.com/file.pdf');
+
+ expect(mockCreatePinnedDispatcher.mock.calls).toEqual([
+ [['93.184.216.34']],
+ [['151.101.1.140']],
+ ]);
+ });
+
+ it('respects a caller-supplied dispatcher instead of pinning', async () => {
+ resolvesTo('93.184.216.34');
+ mockFetch.mockResolvedValue(new Response('data', { status: 200 }));
+ const callerDispatcher = { close: () => Promise.resolve() };
+
+ await ssrfSafeFetch('https://example.com/file.pdf', {
+ dispatcher: callerDispatcher,
+ } as RequestInit);
+
+ // An explicit dispatcher is a routing choice by the caller (e.g. a proxy);
+ // overriding it would dial the validated origin instead of that route.
+ expect(mockCreatePinnedDispatcher).not.toHaveBeenCalled();
+ expect(mockFetch.mock.calls[0][1].dispatcher).toBe(callerDispatcher);
+ });
+
+ it('does not pin when a non-stock global dispatcher is configured', async () => {
+ resolvesTo('93.184.216.34');
+ mockFetch.mockResolvedValue(new Response('data', { status: 200 }));
+ mockHasCustomGlobalDispatcher.mockReturnValue(true);
+
+ await ssrfSafeFetch('https://example.com/file.pdf');
+
+ // The configured route (a ProxyAgent and friends) resolves the hostname
+ // itself; fetch falls back to it when no dispatcher is passed.
+ expect(mockCreatePinnedDispatcher).not.toHaveBeenCalled();
+ expect(mockFetch.mock.calls[0][1].dispatcher).toBeUndefined();
+ });
+
+ it('does not pin while the runtime env-proxy mode is active', async () => {
+ resolvesTo('93.184.216.34');
+ mockFetch.mockResolvedValue(new Response('data', { status: 200 }));
+ vi.stubEnv('NODE_USE_ENV_PROXY', '1');
+ vi.stubEnv('HTTPS_PROXY', 'http://proxy.example:3128');
+
+ await ssrfSafeFetch('https://example.com/file.pdf');
+
+ expect(mockCreatePinnedDispatcher).not.toHaveBeenCalled();
+ expect(mockFetch.mock.calls[0][1].dispatcher).toBeUndefined();
+ });
+
+ it('pins again when NO_PROXY=* bypasses every host', async () => {
+ resolvesTo('93.184.216.34');
+ mockFetch.mockResolvedValue(new Response('data', { status: 200 }));
+ vi.stubEnv('NODE_USE_ENV_PROXY', '1');
+ vi.stubEnv('HTTPS_PROXY', 'http://proxy.example:3128');
+ vi.stubEnv('NO_PROXY', '*');
+
+ await ssrfSafeFetch('https://example.com/file.pdf');
+
+ expect(mockCreatePinnedDispatcher).toHaveBeenCalledWith(['93.184.216.34']);
+ });
+
it('validates and fetches a public URL', async () => {
resolvesTo('93.184.216.34');
const ok = new Response('data', { status: 200 });
diff --git a/ts/packages/slim/package.json b/ts/packages/slim/package.json
index 680b2c29f..0dafab04f 100644
--- a/ts/packages/slim/package.json
+++ b/ts/packages/slim/package.json
@@ -112,6 +112,7 @@
"picocolors": "catalog:",
"pusher-js": "^8.6.0",
"semver": "^7.8.5",
+ "undici": "^7.29.0",
"zod-to-json-schema": "catalog:"
},
"repository": {
diff --git a/uv.lock b/uv.lock
index e9996933b..938c61737 100644
--- a/uv.lock
+++ b/uv.lock
@@ -723,7 +723,9 @@ dependencies = [
{ name = "openai" },
{ name = "pydantic" },
{ name = "pysher" },
+ { name = "requests" },
{ name = "typing-extensions" },
+ { name = "urllib3" },
]
[package.dev-dependencies]
@@ -751,7 +753,9 @@ requires-dist = [
{ name = "openai", specifier = ">=2.48.0" },
{ name = "pydantic", specifier = ">=2.11.9" },
{ name = "pysher", specifier = ">=1.0.8" },
+ { name = "requests", specifier = ">=2.32.2" },
{ name = "typing-extensions", specifier = ">=4.16.0" },
+ { name = "urllib3", specifier = ">=2" },
]
[package.metadata.requires-dev]