Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
refactor(python): consolidate path construction from untrusted input (#4144)
Alberto Schiabelf67d565743c1
diff --git a/python/AGENTS.md b/python/AGENTS.mdindex 4b5d7cec2..4907faf9e 100644--- a/python/AGENTS.md+++ b/python/AGENTS.md@@ -40,3 +40,28 @@ make build- Add pytest coverage for behavior changes.- Keep provider-specific changes under the relevant `python/providers/<provider>/` package.- When bumping `composio-client`, update `python/pyproject.toml`, `python/setup.py`, and root `uv.lock` together.++## Trust boundary++**Every field of an API response is untrusted input** — including slugs, IDs, and+filenames. The SDK's threat model assumes the backend may be compromised or the+connection MITM'd, and that a third-party toolkit can return anything.++When untrusted directory components such as slugs or IDs become part of a+filesystem path, use+`composio.utils.safe_path.secure_join(root, *components)`. For an untrusted+filename, use `secure_basename_join(base, filename, root=root)` so ordinary+extensions remain valid while the write stays anchored to the trusted root.+Both helpers enforce two rules:++1. **Anchor containment on a constant.** Checking a derived path against a+ directory that untrusted input helped build compares tainted against tainted+ and always passes. A directory built as `root / untrusted_a / untrusted_b`+ and then validated against that same built directory is checked against a+ reference the input was free to move.+2. **Validate before touching the filesystem.** No `mkdir` or `open` until the+ final path is known to be inside the root, so a rejected write leaves no+ attacker-chosen directories behind.++`tests/test_path_join_guardrail.py` enforces this: any path join whose right-hand+side is not a literal or module constant must be listed there with a reason.diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.pyindex f54d0eb2e..2c20d0fd9 100644--- a/python/composio/core/models/_files.py+++ b/python/composio/core/models/_files.py@@ -22,9 +22,11 @@ from composio.exceptions import (FileUploadAbortedError,ResponseTooLargeError,SDKFileNotFoundError,+ UnsafePathComponentError,)from composio.utils import mimetypesfrom composio.utils.json_schema import dereference_json_schema+from composio.utils.safe_path import secure_basename_join, secure_joinfrom composio.utils.url_safety import assert_safe_fetch_targetfrom composio.utils.sensitive_file_upload_paths import (assert_safe_local_file_upload_path,@@ -580,19 +582,31 @@ class FileDownloadable(BaseModel):mimetype: str = Field(..., description="Mime type of the file.")s3url: str = Field(..., description="URL of the file.")- def download(self, outdir: Path, chunk_size: int = _DEFAULT_CHUNK_SIZE) -> Path:- # SEC-316: `self.name` comes from the (potentially compromised or- # MITM'd) Composio API response. Strip directory components with- # `Path(...).name` so traversal sequences like `../../../foo` collapse- # to `foo`, then verify the resolved output stays under `outdir` so a- # name like `output_evil/foo` (sibling-prefix attack) is also rejected.- safe_name = Path(self.name).name- outfile = outdir / safe_name- if not outfile.resolve().is_relative_to(outdir.resolve()):- raise ErrorDownloadingFile(- f"Path traversal detected: filename '{self.name}' resolves "- "outside the intended output directory."- )+ def download(+ self,+ outdir: Path,+ chunk_size: int = _DEFAULT_CHUNK_SIZE,+ *,+ root: Path,+ ) -> Path:+ """Fetch the file into ``outdir``.++ :param outdir: Directory to write into. May be derived from untrusted+ input, provided it was produced by :func:`secure_join`.+ :param root: Trusted containment anchor, configured locally and never+ derived from an API response. Required rather than defaulted:+ checking containment against a directory that untrusted input has+ already relocated is not a check at all, and ``outdir`` may be+ exactly such a directory. Callers must name the anchor explicitly.+ """+ # SEC-316: `self.name` also comes from the (potentially compromised or+ # MITM'd) API response. Collapsed to a bare filename and checked against+ # `root` — not `outdir` — so a name like `output_evil/foo`+ # (sibling-prefix attack) is rejected too.+ try:+ outfile = secure_basename_join(outdir, self.name, root=root)+ except UnsafePathComponentError as e:+ raise ErrorDownloadingFile(str(e)) from eoutdir.mkdir(exist_ok=True, parents=True)try:response = requests.get(@@ -1085,9 +1099,15 @@ class FileHelper(WithLogger):def _download_file_value(self, value: t.Any, tool: Tool) -> t.Any:if isinstance(value, dict) and "s3url" in value:+ # `tool.toolkit.slug` and `tool.slug` come from the API response and+ # are untrusted, so joining them directly would let the response pick+ # the download directory. `secure_join` validates each component and+ # anchors containment on `self._outdir`, which is configured locally+ # and never derived from the response.return str(FileDownloadable(**value).download(- self._outdir / tool.toolkit.slug / tool.slug+ outdir=secure_join(self._outdir, tool.toolkit.slug, tool.slug),+ root=self._outdir,))return valuediff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.pyindex f43b07afc..9e0f11cb5 100644--- a/python/composio/core/models/custom_tool_types.py+++ b/python/composio/core/models/custom_tool_types.py@@ -5,7 +5,6 @@ Mirrors the TypeScript types in ts/packages/core/src/types/customTool.types.tsfrom __future__ import annotations-import reimport typing as tfrom dataclasses import dataclass, field@@ -20,13 +19,23 @@ from composio_client.types.tool_router.session_proxy_execute_response import (SessionProxyExecuteResponse,)+from composio.utils.safe_path import SAFE_COMPONENT_REGEX+# ────────────────────────────────────────────────────────────────# Constants# ────────────────────────────────────────────────────────────────LOCAL_TOOL_PREFIX = "LOCAL_"MAX_SLUG_LENGTH = 60-SLUG_REGEX = re.compile(r"^[A-Za-z0-9_-]+$")++SLUG_REGEX = SAFE_COMPONENT_REGEX+"""Alias of the canonical pattern in :mod:`composio.utils.safe_path`.++One definition, not two kept in sync by hand: this pattern is what makes a slug+safe to use as a filesystem path component, so client-created custom tools and+backend-fetched tools must be held to exactly the same rule. Keeping two copies+in sync by hand is how they drift apart.+"""# ────────────────────────────────────────────────────────────────# Execute function typediff --git a/python/composio/core/models/tool_router_session_files.py b/python/composio/core/models/tool_router_session_files.pyindex 1b990d93c..09b626a54 100644--- a/python/composio/core/models/tool_router_session_files.py+++ b/python/composio/core/models/tool_router_session_files.py@@ -6,7 +6,7 @@ in the session's virtual filesystem.from __future__ import annotationsimport typing as t-from pathlib import Path+from pathlib import Path, PureWindowsPathfrom urllib.parse import unquote, urlparseimport requests@@ -22,8 +22,13 @@ from composio_client.types.tool_router.session.file_list_response import ()from composio.client import HttpClient-from composio.exceptions import RemoteFileDownloadError, ValidationError+from composio.exceptions import (+ RemoteFileDownloadError,+ UnsafePathComponentError,+ ValidationError,+)from composio.utils.mimetypes import get_extension_from_mime_type+from composio.utils.safe_path import secure_basename_joinfrom composio.utils.url_safety import assert_safe_fetch_targetfrom composio.utils.uuid import generate_short_id@@ -115,8 +120,18 @@ class RemoteFile:@propertydef filename(self) -> str:- """Filename extracted from the mount path (e.g. 'report.pdf' from 'output/report.pdf')."""- return Path(self.mount_relative_path).name+ """Filename extracted from the mount path (e.g. 'report.pdf' from 'output/report.pdf').++ Deliberately non-raising: this is a display value, and ``buffer()``+ reads it while constructing ``RemoteFileDownloadError``. A validator+ here would replace a genuine download error with a validation error+ raised from inside the error constructor. ``save()`` validates instead,+ at the point the value actually becomes a path.++ ``PureWindowsPath`` so a mount path crafted for a Windows target+ (``..\\..\\evil``) is stripped on POSIX too.+ """+ return PureWindowsPath(self.mount_relative_path).namedef buffer(self) -> bytes:"""Fetch the file content as bytes."""@@ -160,17 +175,21 @@ class RemoteFile:if path is not None:save_path = Path(path)else:- # SEC-316 defense-in-depth: `self.filename` is `Path(mount_relative_path).name`,- # so directory components are already stripped — but verify the resolved- # default-location path stays inside the cache dir to reject residual `..`- # cases (e.g. ``mount_relative_path == ".."`` keeps ``filename == ".."``).+ # SEC-316 defense-in-depth. `safe_basename` collapses the+ # server-controlled mount path and rejects what has no usable+ # basename — `""` and `"."` previously made `save_path` equal+ # `default_dir`, passed the containment check (a path contains+ # itself), and failed as a raw `IsADirectoryError` after the+ # directory had been created. The containment check stays as a+ # second line of defence, anchored on the constant `default_dir`,+ # which is what makes it meaningful; see `composio.utils.safe_path`.default_dir = Path.home() / COMPOSIO_DIR / TEMP_FILES_DIRECTORY_NAME- save_path = default_dir / self.filename- if not save_path.resolve().is_relative_to(default_dir.resolve()):- raise ValidationError(- f"Path traversal detected: filename {self.filename!r} resolves "- "outside the intended output directory."+ try:+ save_path = secure_basename_join(+ default_dir, self.mount_relative_path, label="mount path")+ except UnsafePathComponentError as e:+ raise ValidationError(str(e)) from esave_path.parent.mkdir(parents=True, exist_ok=True)save_path.write_bytes(content)diff --git a/python/composio/exceptions.py b/python/composio/exceptions.pyindex f3f2d789b..16eab8930 100644--- a/python/composio/exceptions.py+++ b/python/composio/exceptions.py@@ -210,6 +210,16 @@ class FileUploadAbortedError(FileError):"""Raised when a ``before_file_upload`` hook returns ``False``."""+class UnsafePathComponentError(FileError):+ """+ Raised when untrusted input (a tool slug, toolkit slug, or server-supplied+ filename) cannot be safely used as part of a filesystem path.++ Fails closed: the SDK refuses the write rather than sanitizing the value+ into something that merely looks safe.+ """++class ErrorDownloadingFile(FileError):passdiff --git a/python/composio/utils/safe_path.py b/python/composio/utils/safe_path.pynew file mode 100644index 000000000..fd151c17b--- /dev/null+++ b/python/composio/utils/safe_path.py@@ -0,0 +1,295 @@+"""Path containment primitives for untrusted input.++Every field of an API response is untrusted, including slugs, identifiers, and+filenames. A compromised toolkit or a MITM on the Composio API can set them to+anything. When such a value becomes part of a filesystem path, it must pass+through this module.++Two rules make the difference between a real check and a decorative one:++1. **Anchor on a constant.** Containment is only meaningful when the root is a+ trusted value. Checking a derived path against a directory that untrusted+ input helped build compares tainted against tainted and always passes. A+ directory built as ``root / untrusted_a / untrusted_b`` and then validated+ against that same built directory is checked against a reference the input+ was free to move.++2. **Validate before touching the filesystem.** No ``mkdir``, no ``open``, until+ the final path is known to be inside the root. Otherwise a rejected write+ still leaves attacker-chosen directories behind.++:func:`secure_join` enforces both. Prefer it over hand-rolled+``resolve() / is_relative_to()`` pairs — see ``python/AGENTS.md``.+"""++from __future__ import annotations++import os+import re+import sys+import typing as t+from pathlib import Path, PureWindowsPath++from composio.exceptions import UnsafePathComponentError++SAFE_COMPONENT_REGEX = re.compile(r"^[A-Za-z0-9_-]+$")+"""Characters permitted in a path component derived from untrusted input.++Deliberately identical to ``SLUG_REGEX`` in ``custom_tool_types.py``, which the+SDK already enforces on client-created custom tools. Backend-fetched tools were+never held to the same standard; they are now.++Every one of the 1070 toolkit slugs in the catalog snapshot at+``ts/packages/cli/src/generated/toolkit-slugs.ts`` conforms, so this is not+expected to reject anything legitimate. That snapshot is not the live catalog:+a production slug containing a dot or a non-ASCII character would hard-fail its+downloads rather than degrade.+"""++MAX_COMPONENT_LENGTH = 128+"""Upper bound on a single component, well under the 255-byte limit common to+ext4/APFS/NTFS. Keeps a long slug from raising ``OSError`` mid-write."""++WINDOWS_RESERVED_NAMES = frozenset(+ {"CON", "PRN", "AUX", "NUL"}+ | {f"COM{i}" for i in range(1, 10)}+ | {f"LPT{i}" for i in range(1, 10)}+ | {f"COM{i}" for i in "¹²³"}+ | {f"LPT{i}" for i in "¹²³"}+)+"""Reserved DOS device names. Writing to one on Windows targets the device+rather than a file. Rejected on every platform so behaviour does not diverge+between a POSIX developer machine and a Windows deployment."""+++def is_inside_dir(child: Path, parent: Path) -> bool:+ """True iff ``child`` equals ``parent`` or is nested inside it on a path+ component boundary.++ ``/tmp/foo`` contains ``/tmp/foo/bar`` but NOT ``/tmp/foo-bar`` — a plain+ string prefix test gets that wrong. Comparison is case-insensitive on+ Windows, where ``C:\\Foo`` and ``c:\\foo`` are the same directory.++ Both arguments are assumed absolute and normalized.+ """+ try:+ child_str = str(child)+ parent_str = str(parent)+ if sys.platform == "win32":+ child_str = child_str.lower()+ parent_str = parent_str.lower()+ if child_str == parent_str:+ return True+ sep = os.sep+ parent_with_sep = parent_str if parent_str.endswith(sep) else parent_str + sep+ return child_str.startswith(parent_with_sep)+ except OSError:+ return False+++def assert_safe_path_component(value: str, *, label: str = "path component") -> str:+ """Return ``value`` unchanged if it is safe to use as a single path+ component, else raise.++ Fails closed. Rejects traversal (``..``), separators of either platform,+ absolute paths, drive letters, NUL bytes, reserved device names, and+ anything outside :data:`SAFE_COMPONENT_REGEX`.++ :raises UnsafePathComponentError: when ``value`` is unsafe.+ """+ if not isinstance(value, str) or not value:+ raise UnsafePathComponentError(+ f"Refusing to build a path from an empty or non-string {label}: {value!r}"+ )++ # `PureWindowsPath` treats both `/` and `\` as separators, so a single check+ # catches `../x` and `..\x` regardless of the host platform. A slug crafted+ # for a Windows target must not slip through on a POSIX build machine.+ as_windows_path = PureWindowsPath(value)+ if len(as_windows_path.parts) != 1 or as_windows_path.anchor:+ raise UnsafePathComponentError(+ f"Refusing to build a path from a {label} containing path separators "+ f"or a drive letter: {value!r}"+ )++ if len(value) > MAX_COMPONENT_LENGTH:+ raise UnsafePathComponentError(+ f"Refusing to build a path from a {label} longer than "+ f"{MAX_COMPONENT_LENGTH} characters: {value[:32]!r}... "+ f"({len(value)} characters)"+ )++ # `.` and `..` are excluded by the regex (no `.` in the character class),+ # as are NUL bytes and every separator. The explicit checks above exist to+ # produce a precise error message rather than a generic pattern mismatch.+ #+ # `fullmatch`, not `match`: in a `match`, `$` also matches just before a+ # single trailing newline, so `"GMAIL\n"` would satisfy `^[A-Za-z0-9_-]+$`+ # and reach the filesystem with a control character in the name.+ if not SAFE_COMPONENT_REGEX.fullmatch(value):+ raise UnsafePathComponentError(+ f"Refusing to build a path from an unsafe {label}: {value!r}. "+ f"Expected only letters, digits, underscores, and hyphens "+ f"(pattern {SAFE_COMPONENT_REGEX.pattern})."+ )++ if value.upper() in WINDOWS_RESERVED_NAMES:+ raise UnsafePathComponentError(+ f"Refusing to build a path from a reserved device name as {label}: {value!r}"+ )++ return value+++def safe_basename(name: str, *, label: str = "filename") -> str:+ """Collapse an untrusted filename to a bare, writable basename.++ Filenames need their own validator: :func:`assert_safe_path_component`+ forbids ``.``, which nearly every real filename contains. This applies the+ remaining checks — no separators, no traversal, no NUL, bounded length, no+ reserved device name — to the one component a server most directly controls.++ ``PureWindowsPath`` treats both ``/`` and ``\\`` as separators, so a name+ crafted for a Windows target (``..\\..\\evil``) is stripped even when the+ SDK runs on POSIX, where ``Path(...).name`` would return it intact.++ Names that leave no usable basename are refused rather than replaced with a+ generated one: a response that cannot name its own file is malformed or+ hostile, and inventing a name would hide that. ``.`` and the empty string+ both basename to ``""``, which makes an output path equal to its own+ directory and surfaces as ``IsADirectoryError`` at write time.++ :raises UnsafePathComponentError: when ``name`` yields no usable basename or+ is unsafe to write.+ """+ if not isinstance(name, str):+ raise UnsafePathComponentError(+ f"Refusing to write a non-string {label}: {name!r}"+ )++ raw_basename = PureWindowsPath(name).name+ if not raw_basename or not raw_basename.strip() or set(raw_basename) == {"."}:+ raise UnsafePathComponentError(+ f"Path traversal detected: {label} {name!r} leaves no usable "+ "basename to write to."+ )+ if "\x00" in raw_basename:+ raise UnsafePathComponentError(+ f"Refusing to write {label} containing a NUL byte: {name!r}"+ )+ if any(ord(char) < 32 or char in '<>:"|?*' for char in raw_basename):+ raise UnsafePathComponentError(+ f"Refusing to write {label} containing characters reserved by "+ f"Windows: {name!r}"+ )+ if raw_basename.endswith((" ", ".")):+ raise UnsafePathComponentError(+ f"Refusing to write {label} ending in a space or dot: {name!r}"+ )++ basename = raw_basename.strip()+ try:+ encoded_length = len(os.fsencode(basename))+ except UnicodeEncodeError as e:+ raise UnsafePathComponentError(+ f"Refusing to write {label} containing invalid Unicode: {name!r}"+ ) from e+ if encoded_length > MAX_COMPONENT_LENGTH:+ raise UnsafePathComponentError(+ f"Refusing to write {label} longer than {MAX_COMPONENT_LENGTH} bytes: "+ f"{basename[:32]!r}... ({encoded_length} bytes)"+ )+ # Compare everything before the first dot: on Windows `NUL.tar.gz` opens+ # the null device just as `NUL` does, so any number of extensions provides+ # no protection.+ device_name = basename.split(".", 1)[0].rstrip(" ").upper()+ if device_name in WINDOWS_RESERVED_NAMES:+ raise UnsafePathComponentError(+ f"Refusing to write {label} that is a reserved device name: {name!r}"+ )+ return basename+++def resolve_root(root: t.Union[str, Path]) -> Path:+ """Normalize a trusted root to an absolute, symlink-resolved path.++ Every containment check must derive its anchor through this one function.+ When two call sites normalize differently — one expanding ``~`` and one not+ — the check compares mismatched paths and rejects legitimate writes while+ reporting them as attacks. Sharing the normalization is what keeps the two+ ends of a containment check comparable.+ """+ expanded = Path(root).expanduser()+ try:+ return expanded.resolve(strict=False)+ except OSError:+ return expanded+++def secure_basename_join(+ base: t.Union[str, Path],+ name: str,+ *,+ root: t.Optional[t.Union[str, Path]] = None,+ label: str = "filename",+) -> Path:+ """Join a single untrusted filename under ``base``, contained within ``root``.++ The filename counterpart to :func:`secure_join`, which cannot be reused here+ because it forbids ``.`` — correct for a slug, wrong for ``report.pdf``.++ ``root`` defaults to ``base`` but is separate for the download path, where+ ``base`` is a per-tool subdirectory that untrusted slugs helped build and+ only the configured ``root`` above it is trusted. Anchoring on ``base``+ there would check the result against a directory those slugs had moved.++ :raises UnsafePathComponentError: when ``name`` is unsafe, or when the+ result escapes ``root``.+ """+ resolved_base = resolve_root(base)+ resolved_root = resolved_base if root is None else resolve_root(root)+ candidate = resolved_base / safe_basename(name, label=label)+ if not is_inside_dir(candidate.resolve(), resolved_root):+ raise UnsafePathComponentError(+ f"Path traversal detected: {label} {name!r} resolves to "+ f"{candidate.resolve()}, which is outside {resolved_root}."+ )+ return candidate+++def secure_join(root: t.Union[str, Path], *components: str) -> Path:+ """Join untrusted ``components`` beneath the trusted ``root``.++ ``root`` is the sole anchor of trust and must not itself be derived from+ untrusted input — that is the whole point. Each component is validated by+ :func:`assert_safe_path_component`, then the joined result is resolved and+ re-checked against the resolved root. The second check is belt-and-braces:+ it catches a symlink inside ``root`` pointing outside it, which per-component+ validation cannot see.++ Performs no filesystem writes; the caller creates directories only after+ this returns.++ :raises UnsafePathComponentError: when any component is unsafe, or when the+ joined path escapes ``root``.+ """+ resolved_root = resolve_root(root)++ safe_components = [+ assert_safe_path_component(component) for component in components+ ]++ candidate = resolved_root.joinpath(*safe_components)+ try:+ resolved_candidate = candidate.resolve(strict=False)+ except OSError:+ resolved_candidate = candidate++ if not is_inside_dir(resolved_candidate, resolved_root):+ raise UnsafePathComponentError(+ f"Refusing to write outside the configured directory: "+ f"{components!r} resolves to {resolved_candidate}, "+ f"which is outside {resolved_root}."+ )++ return resolved_candidatediff --git a/python/composio/utils/upload_dir_allowlist.py b/python/composio/utils/upload_dir_allowlist.pyindex eabc951d2..5a118387c 100644--- a/python/composio/utils/upload_dir_allowlist.py+++ b/python/composio/utils/upload_dir_allowlist.py@@ -24,6 +24,7 @@ from composio.exceptions import (FileUploadPathNotAllowedError,SDKFileNotFoundError,)+from composio.utils.safe_path import is_inside_dir, resolve_rootUPLOAD_TEMP_DIRECTORY_NAME = "temp"@@ -96,24 +97,6 @@ def resolve_effective_upload_allowlist(return out-def _is_inside_dir(child: Path, parent: Path) -> bool:- """True iff ``child`` equals ``parent`` or is nested inside on a component- boundary. Assumes both are absolute and normalized."""- try:- child_str = str(child)- parent_str = str(parent)- if sys.platform == "win32":- child_str = child_str.lower()- parent_str = parent_str.lower()- if child_str == parent_str:- return True- sep = os.sep- parent_with_sep = parent_str if parent_str.endswith(sep) else parent_str + sep- return child_str.startswith(parent_with_sep)- except OSError:- return False--def _format_allowlist(dirs: t.Sequence[Path]) -> str:if not dirs:return " (none configured — all local paths are blocked)"@@ -164,11 +147,7 @@ def assert_path_inside_upload_dirs(entry of ``allowlist`` (including when allowlist is empty)."""attempted = str(file_path)- abs_path = Path(attempted).expanduser()- try:- abs_path = abs_path.resolve(strict=False)- except OSError:- pass+ abs_path = resolve_root(attempted)if not abs_path.exists():cwd = Path.cwd()@@ -218,11 +197,7 @@ def assert_path_inside_upload_dirs()for dir_entry in allowlist:- try:- real_dir = Path(dir_entry).expanduser().resolve(strict=False)- except OSError:- real_dir = Path(dir_entry)- if _is_inside_dir(real_path, real_dir):+ if is_inside_dir(real_path, resolve_root(dir_entry)):returnraise FileUploadPathNotAllowedError(diff --git a/python/tests/conftest.py b/python/tests/conftest.pyindex 7bcc7cdcf..b611ca6c8 100644--- a/python/tests/conftest.py+++ b/python/tests/conftest.py@@ -4,6 +4,7 @@ import base64import hashlibimport hmacimport json+import osfrom pathlib import Pathfrom unittest.mock import Mock@@ -120,3 +121,58 @@ def webhook_fixtures() -> list[dict]:def golden_signatures() -> dict:"""Load golden signatures."""return load_golden_signatures()++[email protected](scope="session")+def _real_home_baseline():+ """The real home directory and its top-level entries, captured once.++ Session-scoped so it is read before any test can monkeypatch ``$HOME``.+ Resolving it per-test would let a test that repoints ``$HOME`` also move+ the guard's own reference point, which is exactly the class of mistake the+ guard exists to catch.+ """+ real_home = Path(os.path.expanduser("~"))+ try:+ return {"path": real_home, "entries": set(os.listdir(real_home))}+ except OSError:+ return {"path": real_home, "entries": None}++[email protected](autouse=True)+def guard_real_home_directory(request, _real_home_baseline):+ """Fail any test that creates entries directly in the real home directory.++ A test that meant to sandbox `~` but patched the wrong thing+ (`Path.home` does not affect `Path.expanduser`, which reads `$HOME`)+ silently writes into the developer's actual home instead. That has already+ destroyed real user data once. This turns the silent case into a failure.++ Only top-level entries are compared, so a test writing under an existing+ `~/.composio` is unaffected; creating `~/downloads` is not.+ """+ if _real_home_baseline["entries"] is None:+ yield+ return++ yield++ real_home = _real_home_baseline["path"]+ try:+ after = set(os.listdir(real_home))+ except OSError:+ return++ created = after - _real_home_baseline["entries"]+ # Roll the baseline forward before failing, so one offending test does not+ # then fail every test that follows it.+ _real_home_baseline["entries"] = after+ if not created:+ return++ pytest.fail(+ f"{request.node.nodeid} created {sorted(created)} in the real home "+ f"directory ({real_home}). Sandbox `$HOME` with "+ f"`monkeypatch.setenv('HOME', str(tmp_path))` — patching `Path.home` "+ f"does not affect `Path.expanduser`."+ )diff --git a/python/tests/test_files.py b/python/tests/test_files.pyindex bbccb57c2..550910cc7 100644--- a/python/tests/test_files.py+++ b/python/tests/test_files.py@@ -31,6 +31,7 @@ from composio.exceptions import (ErrorUploadingFile,ResponseTooLargeError,SensitiveFilePathBlockedError,+ UnsafePathComponentError,)@@ -2546,7 +2547,7 @@ class TestFileDownloadablePathTraversal:"composio.core.models._files.requests.get",return_value=self._mock_response(b"#!/bin/sh\n"),):- written = f.download(outdir)+ written = f.download(outdir, root=outdir)# Traversal sequence collapsed to basename and stayed inside outdir.assert written == outdir / "PWNED.sh"@@ -2565,7 +2566,7 @@ class TestFileDownloadablePathTraversal:"composio.core.models._files.requests.get",return_value=self._mock_response(b"x"),):- written = f.download(outdir)+ written = f.download(outdir, root=outdir)# `Path('/etc/passwd').name == 'passwd'` — absolute path is stripped.assert written == outdir / "passwd"@@ -2587,7 +2588,7 @@ class TestFileDownloadablePathTraversal:return_value=self._mock_response(),):with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):- f.download(outdir)+ f.download(outdir, root=outdir)# No file was written under the parent.assert not (tmp_path / "x").exists()@@ -2602,7 +2603,7 @@ class TestFileDownloadablePathTraversal:"composio.core.models._files.requests.get",return_value=self._mock_response(b"%PDF-1.4"),):- written = f.download(outdir)+ written = f.download(outdir, root=outdir)assert written == outdir / "report.pdf"assert written.read_bytes() == b"%PDF-1.4"@@ -2618,7 +2619,7 @@ class TestFileDownloadablePathTraversal:"composio.core.models._files.requests.get",return_value=self._mock_response(b"%PDF-1.4"),) as mock_get:- f.download(outdir)+ f.download(outdir, root=outdir)mock_get.assert_called_once_with(url="https://example.com/file",@@ -2640,7 +2641,7 @@ class TestFileDownloadablePathTraversal:),):with pytest.raises(ErrorDownloadingFile) as exc_info:- f.download(outdir)+ f.download(outdir, root=outdir)assert "Error downloading file" in str(exc_info.value)assert "token=abc" not in str(exc_info.value)@@ -2663,7 +2664,7 @@ class TestFileDownloadablePathTraversal:return_value=response,):with pytest.raises(ErrorDownloadingFile) as exc_info:- f.download(outdir)+ f.download(outdir, root=outdir)assert "Error downloading file" in str(exc_info.value)assert "token=abc" not in str(exc_info.value)@@ -2683,7 +2684,7 @@ class TestFileDownloadablePathTraversal:return_value=response,):with pytest.raises(ErrorDownloadingFile) as exc_info:- f.download(outdir)+ f.download(outdir, root=outdir)assert "token=abc" not in str(exc_info.value)response.close.assert_called_once()@@ -2707,20 +2708,25 @@ class TestFileDownloadablePathTraversal:return_value=self._mock_response(),):with pytest.raises(ErrorDownloadingFile, match="Path traversal detected"):- f.download(outdir)+ f.download(outdir, root=outdir)# SEC-316 P3.1: check runs before mkdir, so outdir is not created# as a side effect of a rejected payload.assert not outdir.exists()- def test_empty_name_safe_fails_at_write_time(self, tmp_path):- """`Path('').name == ''` — `outdir / ''` resolves to `outdir` itself,- which passes the containment check (a path is relative to itself).- The write then fails with `IsADirectoryError` because the target is- the directory. Documents the safe-fail behavior so a future change- to the check cannot silently weaken it without breaking this test."""+ @pytest.mark.parametrize("name", ["", "."])+ def test_name_without_usable_basename_is_rejected(self, name, tmp_path):+ """`Path('').name` and `Path('.').name` are both `''`, so `outdir / ''`+ used to resolve to `outdir` itself, pass the containment check (a path+ is relative to itself), and only fail at write time with a raw+ `IsADirectoryError` after the directory had been created.++ These are now refused up front. Documents the fail-closed behavior so a+ future change cannot silently weaken it without breaking this test."""+ from composio.exceptions import ErrorDownloadingFile+outdir = tmp_path / "safe"f = FileDownloadable(- name="",+ name=name,mimetype="application/octet-stream",s3url="https://example.com/file",)@@ -2728,13 +2734,192 @@ class TestFileDownloadablePathTraversal:"composio.core.models._files.requests.get",return_value=self._mock_response(b"x"),):- with pytest.raises(IsADirectoryError):- f.download(outdir)- # outdir got created (mkdir runs after the check, which passed),- # but no file was written inside it.- assert outdir.is_dir()+ with pytest.raises(ErrorDownloadingFile, match="no usable basename"):+ f.download(outdir, root=outdir)++ # Rejected before `mkdir`, so nothing was created on disk at all.+ assert not outdir.exists()++ @pytest.mark.parametrize(+ "name,reason",+ [+ ("NUL", "reserved device name"),+ ("nul.txt", "reserved device name"),+ ("NUL.tar.gz", "reserved device name"),+ ("COM1", "reserved device name"),+ ("report.txt:payload", "reserved by Windows"),+ ("a\x00b", "NUL byte"),+ ("😀" * 128, "longer than"),+ ("x" * 300, "longer than"),+ ],+ )+ def test_unsafe_filenames_are_rejected(self, name, reason, tmp_path):+ """`self.name` is untrusted by the same rule as the slugs. Without these+ checks a NUL byte escapes as a raw ValueError from `resolve()`, an+ over-long name as a raw OSError mid-write, and `NUL` opens the Windows+ null device — silently discarding the payload while returning a path."""+ from composio.exceptions import ErrorDownloadingFile++ outdir = tmp_path / "safe"+ f = FileDownloadable(+ name=name,+ mimetype="application/octet-stream",+ s3url="https://example.com/file",+ )+ with patch(+ "composio.core.models._files.requests.get",+ return_value=self._mock_response(b"x"),+ ):+ with pytest.raises(ErrorDownloadingFile, match=reason):+ f.download(outdir, root=outdir)+ assert not outdir.exists()+++class TestDownloadDirSlugTraversal:+ """Server-controlled tool/toolkit slugs must not relocate the download+ directory.++ The directory is built from API response fields, so containment has to be+ checked against the locally configured root rather than against the built+ directory itself — the latter is a reference those fields can move. These+ tests pin the anchor to the configured root.+ """++ TRAVERSALS = [+ "../../../../../etc/escaped",+ "..",+ ".",+ "",+ "/etc",+ "..\\..\\evil",+ "a/b",+ "CON",+ "x" * 200,+ "a\x00b",+ ]++ def _tool(self, tool_slug="GMAIL_GET_ATTACHMENT", toolkit_slug="GMAIL"):+ tool = MagicMock()+ tool.slug = tool_slug+ tool.toolkit.slug = toolkit_slug+ tool.output_parameters = {+ "type": "object",+ "properties": {"attachment": {"file_downloadable": True}},+ }+ return tool++ def _response(self):+ return {+ "attachment": {+ "name": "composio",+ "mimetype": "text/plain",+ "s3url": "https://example.com/file",+ }+ }++ def _mock_get(self, content: bytes = b"payload"):+ response = MagicMock()+ 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)++ @pytest.mark.parametrize("slug", TRAVERSALS)+ def test_hostile_tool_slug_is_rejected(self, slug, tmp_path):+ outdir = tmp_path / "files"+ outdir.mkdir()+ helper = FileHelper(client=None, outdir=str(outdir))+ with self._mock_get():+ with pytest.raises(UnsafePathComponentError):+ helper.substitute_file_downloads(+ tool=self._tool(tool_slug=slug), response=self._response()+ )+ # The write is refused before any directory is created.assert list(outdir.iterdir()) == []+ @pytest.mark.parametrize("slug", TRAVERSALS)+ def test_hostile_toolkit_slug_is_rejected(self, slug, tmp_path):+ outdir = tmp_path / "files"+ outdir.mkdir()+ helper = FileHelper(client=None, outdir=str(outdir))+ with self._mock_get():+ with pytest.raises(UnsafePathComponentError):+ helper.substitute_file_downloads(+ tool=self._tool(toolkit_slug=slug), response=self._response()+ )+ assert list(outdir.iterdir()) == []++ def test_traversal_does_not_escape_the_configured_root(self, tmp_path):+ """A deep `../` chain in `tool.slug` must not land the payload in a+ sibling of the configured directory."""+ outdir = tmp_path / "home" / "app" / ".composio" / "files"+ outdir.mkdir(parents=True)+ helper = FileHelper(client=None, outdir=str(outdir))+ depth = len(outdir.resolve().parts) - len(tmp_path.resolve().parts) + 1+ traversal = "/".join([".."] * depth) + "/etc/escaped"++ with self._mock_get(b"payload-that-must-not-be-written"):+ with pytest.raises(UnsafePathComponentError):+ helper.substitute_file_downloads(+ tool=self._tool(tool_slug=traversal), response=self._response()+ )++ assert not (tmp_path / "etc").exists()+ assert list(outdir.iterdir()) == []++ def test_legitimate_slugs_still_nest_under_the_root(self, tmp_path):+ outdir = tmp_path / "files"+ outdir.mkdir()+ helper = FileHelper(client=None, outdir=str(outdir))+ with self._mock_get(b"payload"):+ result = helper.substitute_file_downloads(+ tool=self._tool(), response=self._response()+ )++ written = Path(result["attachment"])+ assert (+ written.resolve()+ == (outdir / "GMAIL" / "GMAIL_GET_ATTACHMENT" / "composio").resolve()+ )+ assert written.read_bytes() == b"payload"++ def test_tilde_download_dir_still_works(self, tmp_path, monkeypatch):+ """`secure_join` expands `~` in the root; the containment check in+ `download()` must expand it too. When only one side did, every download+ under `file_download_dir='~/...'` failed as a path traversal."""+ monkeypatch.setenv("HOME", str(tmp_path))+ helper = FileHelper(client=None, outdir="~/downloads")+ with self._mock_get(b"payload"):+ result = helper.substitute_file_downloads(+ tool=self._tool(), response=self._response()+ )++ written = Path(result["attachment"])+ assert (+ written.resolve()+ == (+ tmp_path / "downloads" / "GMAIL" / "GMAIL_GET_ATTACHMENT" / "composio"+ ).resolve()+ )+ assert written.read_bytes() == b"payload"++ def test_symlink_inside_root_cannot_be_used_to_escape(self, tmp_path):+ """Per-component validation cannot see a symlink; the post-resolve+ containment check in `secure_join` is what catches this."""+ outdir = tmp_path / "files"+ outdir.mkdir()+ outside = tmp_path / "outside"+ outside.mkdir()+ (outdir / "GMAIL").symlink_to(outside, target_is_directory=True)++ helper = FileHelper(client=None, outdir=str(outdir))+ with self._mock_get():+ with pytest.raises(UnsafePathComponentError, match="outside"):+ helper.substitute_file_downloads(+ tool=self._tool(), response=self._response()+ )+ assert list(outside.iterdir()) == []+class TestEnhanceSchemaDescriptionsEmptySchema:"""Regression tests for the empty-input-parameters crash.diff --git a/python/tests/test_home_guard.py b/python/tests/test_home_guard.pynew file mode 100644index 000000000..bc60a1c22--- /dev/null+++ b/python/tests/test_home_guard.py@@ -0,0 +1,22 @@+"""Behavioral tests for the real-home write guard."""++from types import SimpleNamespace++import pytest++from tests.conftest import guard_real_home_directory+++def test_real_home_guard_reports_without_deleting_new_directory(tmp_path):+ baseline = {"path": tmp_path, "entries": set()}+ request = SimpleNamespace(node=SimpleNamespace(nodeid="test_external_write"))+ guard = guard_real_home_directory.__wrapped__(request, baseline)++ next(guard)+ unrelated = tmp_path / "unrelated-empty-directory"+ unrelated.mkdir()++ with pytest.raises(pytest.fail.Exception, match="created"):+ next(guard)++ assert unrelated.is_dir()diff --git a/python/tests/test_path_join_guardrail.py b/python/tests/test_path_join_guardrail.pynew file mode 100644index 000000000..fbb3cd9aa--- /dev/null+++ b/python/tests/test_path_join_guardrail.py@@ -0,0 +1,498 @@+"""Guardrail against building filesystem paths out of untrusted input.++The failure mode this prevents: a path built from unvalidated API response+fields, with a containment check that compares the result against the very+directory those fields helped build — tainted against tainted, so it always+passes.++A convention in `AGENTS.md` would not catch that. Such a line gets written by+someone who has already thought about traversal and added a check. So this+enforces the rule mechanically: every path built from something that is+not a literal or a module-level constant must be recorded in `REVIEWED_JOINS`+with a reason, and each entry must still be backed by the validation its reason+cites.++Three properties matter, and each is a test below, because each is easy to get+wrong in a way that leaves the check looking present but doing nothing:++1. **Cover every spelling.** A detector that only understands the `/` operator+ is green while `os.path.join` reintroduces the bug.+2. **Fail closed.** No guessing from variable names — renaming `outdir` to+ `base` must not silently disable the check.+3. **Bind the allowlist to its evidence.** An entry keyed only on source text+ keeps passing after the validation around it is deleted.++To satisfy this test, prefer `composio.utils.safe_path.secure_join`, which+validates each untrusted component and anchors containment on a trusted root.+"""++import ast+import functools+import typing as t+from pathlib import Path++import pytest++PYTHON_ROOT = Path(__file__).parent.parent+SCANNED_ROOTS = (PYTHON_ROOT / "composio", PYTHON_ROOT / "providers")++_PATH_CALLS = frozenset({"Path", "PurePath", "PurePosixPath", "PureWindowsPath"})+"""Constructors whose result is a path."""++_DIRECT_PATH_SINKS = frozenset({"open", "makedirs", "mkdir"})+"""Functions whose first argument becomes a filesystem path."""+++def _reviewed_path(+ reason: str,+ *requires: str,+ occurrences: int = 1,+) -> t.Dict[str, t.Any]:+ return {+ "reason": reason,+ "requires": frozenset(requires),+ "occurrences": occurrences,+ }+++REVIEWED_JOINS: t.Dict[t.Tuple[str, str], t.Dict[str, t.Any]] = {+ (+ "composio/core/models/_files.py",+ (+ "Path( os.environ.get( ENV_LOCAL_CACHE_DIRECTORY, Path.home() / "+ "LOCAL_CACHE_DIRECTORY_NAME, # Fallback to user directory ) )"+ ),+ ): _reviewed_path(+ "The cache root comes from local configuration or the user's home, not an "+ "API response."+ ),+ (+ "composio/core/models/_files.py",+ "Path(path_in)",+ ): _reviewed_path(+ "`FileUploadable.from_path` converts the caller's local upload path after "+ "the upload allowlist and sensitive-path checks have run.",+ "assert_path_inside_upload_dirs",+ "assert_safe_local_file_upload_path",+ ),+ (+ "composio/core/models/_files.py",+ "Path(outdir)",+ ): _reviewed_path(+ "`FileHelper` accepts this download root from local SDK configuration; API "+ "response values are joined beneath it through the safe-path helpers."+ ),+ (+ "composio/core/models/tool_router_session_files.py",+ "PureWindowsPath(self.mount_relative_path)",+ ): _reviewed_path(+ "This property only extracts a display basename. `RemoteFile.save` validates "+ "the same server value before using it as a filesystem path."+ ),+ (+ "composio/core/models/tool_router_session_files.py",+ "Path(path)",+ ): _reviewed_path(+ "A non-default `RemoteFile.save` destination is selected explicitly by the "+ "caller and does not contain an API-derived path component."+ ),+ (+ "composio/core/models/tool_router_session_files.py",+ "Path(path_str)",+ ): _reviewed_path(+ "The upload input is a caller-selected local file and is checked before it is "+ "read; it is not a path constructed from a remote response.",+ "exists",+ "is_file",+ ),+ (+ "composio/integration_test/conftest.py",+ "Path(__file__)",+ ): _reviewed_path("`__file__` is the trusted location of this installed module."),+ (+ "composio/utils/mimetypes.py",+ "Path(file)",+ ): _reviewed_path(+ "`mimetypes.guess` uses `Path` for suffix parsing only and never accesses the "+ "filesystem."+ ),+ (+ "composio/utils/safe_path.py",+ "PureWindowsPath(value)",+ ): _reviewed_path(+ "The path parser detects cross-platform separators before the component is "+ "accepted by the strict slug pattern.",+ "fullmatch",+ ),+ (+ "composio/utils/safe_path.py",+ "PureWindowsPath(name)",+ ): _reviewed_path(+ "`safe_basename` collapses the value, rejects Windows-invalid forms, checks "+ "its encoded length, and rejects reserved device names.",+ "fsencode",+ ),+ (+ "composio/utils/safe_path.py",+ "Path(root)",+ ): _reviewed_path(+ "`resolve_root` normalizes a caller-supplied trusted anchor before any "+ "containment comparison.",+ "expanduser",+ "resolve",+ ),+ (+ "composio/utils/safe_path.py",+ "resolved_base / safe_basename(name, label=label)",+ ): {+ "reason": (+ "`secure_basename_join`, the sanctioned single-filename join. The "+ "name is collapsed and validated by `safe_basename`, and the result "+ "is re-checked with `is_inside_dir` against a `resolve_root`-derived "+ "anchor that the caller supplies separately from the join base — the "+ "distinction this whole module turns on."+ ),+ "requires": frozenset({"resolve_root", "safe_basename", "is_inside_dir"}),+ "occurrences": 1,+ },+ ("composio/utils/safe_path.py", "resolved_root.joinpath(*safe_components)"): {+ "reason": (+ "`secure_join`, the sanctioned multi-component join. Every component "+ "has passed `assert_safe_path_component`, the root came from "+ "`resolve_root`, and the joined result is re-checked with "+ "`is_inside_dir` before return."+ ),+ "requires": frozenset(+ {"resolve_root", "assert_safe_path_component", "is_inside_dir"}+ ),+ "occurrences": 1,+ },+ (+ "composio/utils/sensitive_file_upload_paths.py",+ "Path(file_path)",+ ): _reviewed_path(+ "This converts a caller-selected upload path so the sensitive-path denylist "+ "can inspect its normalized components.",+ "expanduser",+ "resolve",+ ),+ (+ "composio/utils/upload_dir_allowlist.py",+ "Path(s)",+ ): _reviewed_path(+ "This converts a locally configured upload-allowlist entry and resolves it "+ "before comparisons.",+ "expanduser",+ "resolve",+ ),+}+"""Reviewed dynamic path construction in the shipped Python packages.++Entries outside `safe_path` are limited to caller-selected local paths, local+configuration, module locations, or lexical parsing. API-derived components+must use `secure_join` or `secure_basename_join`.+"""++for _provider_setup in (+ "anthropic",+ "autogen",+ "claude_agent_sdk",+ "crewai",+ "gemini",+ "google",+ "google_adk",+ "langchain",+ "langgraph",+ "llamaindex",+ "openai",+ "openai_agents",+):+ REVIEWED_JOINS[(f"providers/{_provider_setup}/setup.py", "Path(__file__)")] = (+ _reviewed_path("`__file__` is the trusted location of this provider package.")+ )+del _provider_setup+++def _module_constants(tree: ast.Module) -> t.Set[str]:+ """Module-level ALL_CAPS names bound to a literal.++ Both halves matter. Without the module-level requirement a function-local+ `SLUG = tool.slug` is exempt; without the literal requirement a module-level+ `SLUG = os.environ[...]` is exempt. Either one is a one-token bypass.+ """+ out: t.Set[str] = set()+ for node in tree.body:+ targets: t.List[ast.expr]+ if isinstance(node, ast.Assign):+ targets = list(node.targets)+ value = node.value+ elif isinstance(node, ast.AnnAssign) and node.value is not None:+ targets = [node.target]+ value = node.value+ else:+ continue+ if not _is_literal_expr(value):+ continue+ for tgt in targets:+ if isinstance(tgt, ast.Name) and tgt.id.isupper():+ out.add(tgt.id)+ return out+++def _is_literal_expr(node: ast.expr) -> bool:+ """True for expressions built only from literals."""+ try:+ ast.literal_eval(node)+ return True+ except (ValueError, TypeError, SyntaxError, MemoryError, RecursionError):+ return False+++def _is_trusted(node: ast.expr, consts: t.Set[str]) -> bool:+ if isinstance(node, ast.Constant):+ return True+ if isinstance(node, ast.Name) and node.id in consts:+ return True+ return False+++def _call_name(func: ast.expr) -> str:+ if isinstance(func, ast.Attribute):+ return func.attr+ if isinstance(func, ast.Name):+ return func.id+ return ""+++def _is_os_path_join(func: ast.expr) -> bool:+ """`os.path.join(...)` / `posixpath.join(...)`, not `",".join(...)`."""+ if not (isinstance(func, ast.Attribute) and func.attr == "join"):+ return False+ recv = func.value+ if isinstance(recv, ast.Attribute):+ return recv.attr == "path"+ if isinstance(recv, ast.Name):+ return recv.id in {"posixpath", "ntpath", "path"}+ return False+++def _is_direct_path_sink(func: ast.expr) -> bool:+ """Builtins or ``os`` functions whose first argument is the path.++ Method calls such as ``Path.open(mode)`` and ``Path.write_bytes(data)``+ carry the path in their receiver, not in the positional arguments. Their+ receiver construction is reviewed separately by the ``_PATH_CALLS`` rule.+ """+ if isinstance(func, ast.Name):+ return func.id in _DIRECT_PATH_SINKS+ return (+ isinstance(func, ast.Attribute)+ and func.attr in _DIRECT_PATH_SINKS+ and isinstance(func.value, ast.Name)+ and func.value.id == "os"+ )++[email protected]_cache(maxsize=None)+def _read_and_parse(path: Path, mtime_ns: int) -> t.Tuple[str, ast.Module]:+ source = path.read_text()+ return source, ast.parse(source)+++def _parse_cached(path: Path) -> t.Tuple[str, ast.Module]:+ """Parse ``path``, reusing the previous result while its mtime is unchanged.++ Keyed on mtime so the detector's own self-tests, which rewrite the same+ synthetic file with different content, still see the new source.+ """+ return _read_and_parse(path, path.stat().st_mtime_ns)+++class Join(t.NamedTuple):+ module: str+ lineno: int+ text: str+ kind: str+++def _collect_joins(roots: t.Sequence[Path] = SCANNED_ROOTS) -> t.List[Join]:+ """Every path construction from a non-literal, non-module-constant value."""+ found: t.List[Join] = []+ for root in roots:+ if not root.exists():+ continue+ for py in sorted(root.rglob("*.py")):+ try:+ source, tree = _parse_cached(py)+ except SyntaxError: # pragma: no cover - lint job fails first+ continue+ consts = _module_constants(tree)+ try:+ module = str(py.relative_to(PYTHON_ROOT))+ except ValueError:+ # Synthetic roots used by the detector's own self-tests.+ module = str(py.relative_to(root.parent))++ def record(node: t.Union[ast.expr, ast.stmt], kind: str) -> None:+ text = ast.get_source_segment(source, node) or ""+ found.append(Join(module, node.lineno, " ".join(text.split()), kind))++ for node in ast.walk(tree):+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Div):+ if not _is_trusted(node.right, consts):+ record(node, "div")+ elif isinstance(node, ast.AugAssign) and isinstance(node.op, ast.Div):+ if not _is_trusted(node.value, consts):+ record(node, "augdiv")+ elif isinstance(node, ast.Call):+ name = _call_name(node.func)+ args = node.args+ if name == "joinpath":+ if any(not _is_trusted(a, consts) for a in args):+ record(node, "joinpath")+ elif _is_os_path_join(node.func):+ if any(not _is_trusted(a, consts) for a in args):+ record(node, "os.path.join")+ elif name in _PATH_CALLS:+ if any(not _is_trusted(a, consts) for a in args):+ record(node, "Path(...)")+ elif _is_direct_path_sink(node.func):+ if args and not _is_trusted(args[0], consts):+ record(node, name)+ return found+++def _enclosing_function_calls(module: str, lineno: int) -> t.Set[str]:+ """Names called inside the function containing ``lineno``."""+ path = PYTHON_ROOT / module+ _, tree = _parse_cached(path)+ best: t.Optional[t.Union[ast.FunctionDef, ast.AsyncFunctionDef]] = None+ for node in ast.walk(tree):+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):+ end = getattr(node, "end_lineno", None) or lineno+ if node.lineno <= lineno <= end:+ if best is None or node.lineno > best.lineno: # innermost+ best = node+ if best is None:+ return set()+ return {_call_name(n.func) for n in ast.walk(best) if isinstance(n, ast.Call)}+++def test_every_untrusted_path_join_is_reviewed():+ unreviewed = [+ j for j in _collect_joins() if (j.module, j.text) not in REVIEWED_JOINS+ ]+ assert not unreviewed, (+ "Found path construction(s) from non-constant input that are not "+ "recorded in REVIEWED_JOINS:\n"+ + "\n".join(f" [{j.kind}] {j.module}:{j.lineno}: {j.text}" for j in unreviewed)+ + "\n\nIf the value can come from an API response, use "+ "`composio.utils.safe_path.secure_join(root, *components)` instead. "+ "If the construction is genuinely safe, add it to REVIEWED_JOINS in "+ f"{Path(__file__).name} with a reason and the validators it relies on."+ )+++def test_reviewed_joins_all_still_exist():+ """Keeps the allowlist from rotting into stale entries that silently permit+ whatever moves into their place."""+ found = {(j.module, j.text) for j in _collect_joins()}+ stale = set(REVIEWED_JOINS) - found+ assert not stale, (+ "REVIEWED_JOINS entries no longer present in the source (remove them):\n"+ + "\n".join(f" {m}: {tx}" for m, tx in sorted(stale))+ )+++def test_reviewed_joins_still_have_their_validation():+ """Entries that depend on validators still call them in the same function."""+ for join in _collect_joins():+ entry = REVIEWED_JOINS.get((join.module, join.text))+ if entry is None:+ continue+ calls = _enclosing_function_calls(join.module, join.lineno)+ missing = entry["requires"] - calls+ assert not missing, (+ f"{join.module}:{join.lineno}: `{join.text}` is allowlisted because "+ f"it is guarded by {sorted(entry['requires'])}, but "+ f"{sorted(missing)} is no longer called in the enclosing function. "+ "Either restore the validation or re-review the entry."+ )+++def test_reviewed_joins_occurrence_counts_match():+ """One entry must not blanket-approve unlimited future joins that happen to+ share its source text."""+ counts: t.Dict[t.Tuple[str, str], int] = {}+ for join in _collect_joins():+ counts[(join.module, join.text)] = counts.get((join.module, join.text), 0) + 1+ for key, entry in REVIEWED_JOINS.items():+ actual = counts.get(key, 0)+ assert actual == entry["occurrences"], (+ f"{key[0]}: `{key[1]}` appears {actual} time(s), but the "+ f"REVIEWED_JOINS entry expects {entry['occurrences']}. A new "+ "occurrence is not covered by the existing review."+ )+++EVASIONS = {+ "div": "return self._outdir / tool.toolkit.slug / tool.slug",+ "div-unhinted-name": "return base / tool.slug",+ "augdiv": "p = Path('/tmp')\n p /= tool.slug\n return p",+ "joinpath": "return self._outdir.joinpath(tool.slug)",+ "os.path.join": "return os.path.join(self._outdir, tool.slug)",+ "Path(a, b)": "return Path(self._outdir, tool.slug)",+ "Path(value)": "return Path(tool.slug)",+ "Path(value, literal)": "return Path(tool.slug, 'payload')",+ "Path(value).write": "Path(tool.slug).write_bytes(b'x')\n return None",+ "f-string": "return Path(f'{self._outdir}/{tool.slug}')",+ "concat": "return Path(self._outdir + '/' + tool.slug)",+ "local-uppercase": "SLUG = tool.slug\n return self._outdir / SLUG",+ "open-direct": "return open(tool.slug, 'rb')",+ "open-fstring": "return open(f'{self._outdir}/{tool.slug}', 'rb')",+ "mkdir-direct": "return os.mkdir(tool.slug)",+ "makedirs-concat": "return os.makedirs(self._outdir + tool.slug)",+}++[email protected]("label", sorted(EVASIONS))+def test_detector_catches_known_evasions(label, tmp_path):+ """Each of these builds a path from untrusted input in a different+ spelling. A detector that recognizes only the first stays green for the+ rest, which is the whole reason this test is table-driven."""+ pkg = tmp_path / "composio"+ pkg.mkdir()+ (pkg / "vulnerable.py").write_text(+ "import os\nfrom pathlib import Path\n\n\n"+ f"def f(self, tool):\n {EVASIONS[label]}\n"+ )+ found = _collect_joins([pkg])+ assert found, f"detector missed evasion: {label}"+++def test_module_constant_exemption_requires_a_literal(tmp_path):+ """A module-level ALL_CAPS name bound at runtime is not a constant."""+ pkg = tmp_path / "composio"+ pkg.mkdir()+ (pkg / "vulnerable.py").write_text(+ "import os\nfrom pathlib import Path\n\n"+ "SAFE = 'literal'\n"+ "SLUG = os.environ['SLUG']\n\n\n"+ "def f(self):\n return self._outdir / SLUG\n"+ )+ assert _collect_joins([pkg]), "runtime-bound ALL_CAPS name was treated as constant"++ (pkg / "vulnerable.py").write_text(+ "from pathlib import Path\n\n"+ "SAFE = 'literal'\n\n\n"+ "def f(self):\n return self._outdir / SAFE\n"+ )+ assert not _collect_joins([pkg]), "literal module constant should be exempt"+++def test_scan_roots_are_pinned():+ """Narrowing the scan silently shrinks the guarantee, so the roots are+ asserted rather than assumed."""+ assert {p.name for p in SCANNED_ROOTS} == {"composio", "providers"}+ for root in SCANNED_ROOTS:+ assert root.is_dir(), f"scanned root missing: {root}"diff --git a/python/tests/test_provider_argument_serialization.py b/python/tests/test_provider_argument_serialization.pyindex d4e988f2a..944e9f9a8 100644--- a/python/tests/test_provider_argument_serialization.py+++ b/python/tests/test_provider_argument_serialization.py@@ -14,6 +14,12 @@ from composio.utils.shared import (PROVIDERS = ("crewai", "langchain", "langgraph")[email protected](autouse=True)+def _sandbox_provider_home(tmp_path, monkeypatch):+ """Keep provider initialization from writing caches into the real home."""+ monkeypatch.setenv("HOME", str(tmp_path))++def _make_tool(input_parameters: t.Dict[str, t.Any]) -> Tool:return Tool(name="Test tool",diff --git a/python/tests/test_safe_path.py b/python/tests/test_safe_path.pynew file mode 100644index 000000000..d1dfc7e75--- /dev/null+++ b/python/tests/test_safe_path.py@@ -0,0 +1,242 @@+"""Tests for the path containment primitives in `composio.utils.safe_path`.++See that module's docstring for why containment must be anchored on a constant+root rather than on a directory the input helped build.+"""++import sys+from pathlib import Path++import pytest++from composio.exceptions import UnsafePathComponentError+from composio.utils.safe_path import (+ SAFE_COMPONENT_REGEX,+ assert_safe_path_component,+ is_inside_dir,+ resolve_root,+ safe_basename,+ secure_basename_join,+ secure_join,+)+++class TestResolveRoot:+ """Both ends of a containment check must normalize through this one+ function; when they diverge the check compares mismatched paths."""++ def test_expands_tilde(self, tmp_path, monkeypatch):+ monkeypatch.setenv("HOME", str(tmp_path))+ assert resolve_root("~/downloads") == (tmp_path / "downloads").resolve()++ def test_resolves_relative(self, tmp_path, monkeypatch):+ monkeypatch.chdir(tmp_path)+ assert resolve_root("./downloads") == (tmp_path / "downloads").resolve()++ def test_accepts_path_and_str_identically(self, tmp_path):+ assert resolve_root(tmp_path) == resolve_root(str(tmp_path))++ def test_nonexistent_root_does_not_raise(self, tmp_path):+ assert resolve_root(tmp_path / "nope") == (tmp_path / "nope").resolve()+++class TestAssertSafePathComponent:+ @pytest.mark.parametrize(+ "value",+ [+ "GMAIL",+ "GMAIL_GET_ATTACHMENT",+ "github",+ "some-toolkit",+ "v2",+ "a",+ "A1_b-2",+ ],+ )+ def test_accepts_realistic_slugs(self, value):+ assert assert_safe_path_component(value) == value++ @pytest.mark.parametrize(+ "value",+ [+ "..",+ ".",+ "../etc",+ "../../../../../etc/escaped",+ "a/b",+ "a\\b",+ "..\\..\\evil",+ "/etc",+ "/",+ "C:\\Windows",+ "C:/Windows",+ "",+ "a\x00b",+ "a b",+ "a.b",+ "café",+ "x" * 129,+ ],+ )+ def test_rejects_unsafe_values(self, value):+ with pytest.raises(UnsafePathComponentError):+ assert_safe_path_component(value)++ @pytest.mark.parametrize("value", ["GMAIL\n", "GMAIL\r\n", "GMAIL\x0b", "\nGMAIL"])+ def test_rejects_control_characters(self, value):+ """`re.match` with a `$` anchor also matches just before a single+ trailing newline, so `"GMAIL\\n"` satisfied the pattern and reached the+ filesystem. `fullmatch` is what closes that."""+ with pytest.raises(UnsafePathComponentError):+ assert_safe_path_component(value)++ @pytest.mark.parametrize("value", ["CON", "con", "NUL", "COM1", "lpt9", "AUX"])+ def test_rejects_windows_device_names_on_every_platform(self, value):+ """Rejected regardless of host OS so a POSIX test run cannot pass code+ that would target a device on a Windows deployment."""+ with pytest.raises(UnsafePathComponentError, match="reserved device name"):+ assert_safe_path_component(value)++ def test_rejects_non_string(self):+ with pytest.raises(UnsafePathComponentError):+ assert_safe_path_component(None) # type: ignore[arg-type]++ def test_label_appears_in_the_error(self):+ with pytest.raises(UnsafePathComponentError, match="tool slug"):+ assert_safe_path_component("../x", label="tool slug")++ def test_boundary_length(self):+ assert assert_safe_path_component("x" * 128) == "x" * 128+ with pytest.raises(UnsafePathComponentError, match="longer than"):+ assert_safe_path_component("x" * 129)++ def test_matches_the_custom_tool_slug_pattern(self):+ """The SDK already enforced this pattern on client-created custom+ tools; backend-fetched tools are now held to the same standard."""+ from composio.core.models.custom_tool_types import SLUG_REGEX++ assert SAFE_COMPONENT_REGEX.pattern == SLUG_REGEX.pattern+++class TestIsInsideDir:+ def test_nested_path_is_inside(self, tmp_path):+ assert is_inside_dir(tmp_path / "a" / "b", tmp_path)++ def test_same_path_is_inside(self, tmp_path):+ assert is_inside_dir(tmp_path, tmp_path)++ def test_sibling_prefix_is_not_inside(self, tmp_path):+ """`/tmp/foo` must not be treated as containing `/tmp/foo-bar`. A plain+ string prefix check gets this wrong."""+ assert not is_inside_dir(Path(f"{tmp_path}-evil") / "x", tmp_path)++ def test_parent_is_not_inside(self, tmp_path):+ assert not is_inside_dir(tmp_path.parent, tmp_path)++ @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only casing rule")+ def test_case_insensitive_on_windows(self):+ assert is_inside_dir(Path("C:\\Foo\\Bar"), Path("c:\\foo"))+++class TestSafeBasename:+ @pytest.mark.parametrize(+ "value",+ ["NUL.tar.gz", "COM1.log.bak", "COM¹.txt", "LPT³.data"],+ )+ def test_rejects_windows_device_names_with_any_extension(self, value):+ with pytest.raises(UnsafePathComponentError, match="reserved device name"):+ safe_basename(value)++ @pytest.mark.parametrize(+ "value",+ ["report?.txt", "report.txt:payload", "report.txt.", "report.txt "],+ )+ def test_rejects_windows_invalid_names_on_every_platform(self, value):+ with pytest.raises(UnsafePathComponentError):+ safe_basename(value)++ def test_limits_encoded_filename_bytes(self):+ with pytest.raises(UnsafePathComponentError, match="longer than"):+ safe_basename("😀" * 128)++ def test_rejects_unencodable_filename(self):+ with pytest.raises(UnsafePathComponentError, match="invalid Unicode"):+ safe_basename("report-\ud800.txt")+++class TestSecureBasenameJoin:+ def test_tilde_base_is_expanded_before_containment(self, tmp_path, monkeypatch):+ monkeypatch.setenv("HOME", str(tmp_path))+ assert (+ secure_basename_join("~/downloads", "report.pdf")+ == (tmp_path / "downloads" / "report.pdf").resolve()+ )+++class TestSecureJoin:+ def test_joins_safe_components(self, tmp_path):+ assert (+ secure_join(tmp_path, "GMAIL", "GMAIL_GET_ATTACHMENT")+ == (tmp_path / "GMAIL" / "GMAIL_GET_ATTACHMENT").resolve()+ )++ def test_no_components_returns_the_root(self, tmp_path):+ assert secure_join(tmp_path) == tmp_path.resolve()++ @pytest.mark.parametrize("component", ["..", "../etc", "/etc", "a/b", "..\\evil"])+ def test_rejects_traversal_components(self, component, tmp_path):+ with pytest.raises(UnsafePathComponentError):+ secure_join(tmp_path, component)++ def test_rejects_traversal_in_any_position(self, tmp_path):+ with pytest.raises(UnsafePathComponentError):+ secure_join(tmp_path, "GMAIL", "..")++ def test_creates_nothing_on_disk(self, tmp_path):+ """Validation must complete before any filesystem write, so a rejected+ join leaves no attacker-chosen directories behind."""+ root = tmp_path / "root"+ root.mkdir()+ with pytest.raises(UnsafePathComponentError):+ secure_join(root, "../evil")+ assert list(root.iterdir()) == []++ secure_join(root, "GMAIL", "TOOL")+ assert list(root.iterdir()) == []++ def test_symlink_escape_is_caught_after_resolve(self, tmp_path):+ """Per-component validation cannot see a symlink pointing out of the+ root; the post-resolve containment check is what catches it."""+ root = tmp_path / "root"+ root.mkdir()+ outside = tmp_path / "outside"+ outside.mkdir()+ (root / "GMAIL").symlink_to(outside, target_is_directory=True)++ with pytest.raises(UnsafePathComponentError, match="outside"):+ secure_join(root, "GMAIL", "TOOL")++ def test_root_is_expanded_and_resolved(self, tmp_path):+ nested = tmp_path / "a" / ".." / "b"+ (tmp_path / "b").mkdir(parents=True)+ assert secure_join(nested, "TOOL") == (tmp_path / "b" / "TOOL").resolve()++ def test_accepts_str_root(self, tmp_path):+ assert secure_join(str(tmp_path), "TOOL") == (tmp_path / "TOOL").resolve()++ def test_tilde_root_is_expanded(self, tmp_path, monkeypatch):+ """`~` must expand identically here and in every containment check that+ shares this root, or a legitimate download is rejected as an attack."""+ monkeypatch.setenv("HOME", str(tmp_path))+ assert (+ secure_join("~/downloads", "GMAIL")+ == (tmp_path / "downloads" / "GMAIL").resolve()+ )++ def test_nonexistent_root_still_validates(self, tmp_path):+ """`resolve(strict=False)` means the root need not exist yet — the+ download directory is created lazily."""+ root = tmp_path / "not-created-yet"+ assert secure_join(root, "TOOL") == (root / "TOOL").resolve()+ with pytest.raises(UnsafePathComponentError):+ secure_join(root, "..")