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.

refactor(python): consolidate path construction from untrusted input (#4144)

Alberto Schiabelf67d565743c1
diff --git a/python/AGENTS.md b/python/AGENTS.md
index 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.py
index 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 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
from 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 e
outdir.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 value
diff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.py
index 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.ts
from __future__ import annotations
-import re
import typing as t
from 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 type
diff --git a/python/composio/core/models/tool_router_session_files.py b/python/composio/core/models/tool_router_session_files.py
index 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 annotations
import typing as t
-from pathlib import Path
+from pathlib import Path, PureWindowsPath
from urllib.parse import unquote, urlparse
import 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_join
from composio.utils.url_safety import assert_safe_fetch_target
from composio.utils.uuid import generate_short_id
@@ -115,8 +120,18 @@ class RemoteFile:
@property
def 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).name
def 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 e
save_path.parent.mkdir(parents=True, exist_ok=True)
save_path.write_bytes(content)
diff --git a/python/composio/exceptions.py b/python/composio/exceptions.py
index 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):
pass
diff --git a/python/composio/utils/safe_path.py b/python/composio/utils/safe_path.py
new file mode 100644
index 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_candidate
diff --git a/python/composio/utils/upload_dir_allowlist.py b/python/composio/utils/upload_dir_allowlist.py
index 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_root
UPLOAD_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)):
return
raise FileUploadPathNotAllowedError(
diff --git a/python/tests/conftest.py b/python/tests/conftest.py
index 7bcc7cdcf..b611ca6c8 100644
--- a/python/tests/conftest.py
+++ b/python/tests/conftest.py
@@ -4,6 +4,7 @@ import base64
import hashlib
import hmac
import json
+import os
from pathlib import Path
from 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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, "..")