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

next
py 406 lines 16.3 KB
Raw
1 """Path containment primitives for untrusted input.
2
3 Every field of an API response is untrusted, including slugs, identifiers, and
4 filenames. A compromised toolkit or a MITM on the Composio API can set them to
5 anything. When such a value becomes part of a filesystem path, it must pass
6 through this module.
7
8 Two rules make the difference between a real check and a decorative one:
9
10 1. **Anchor on a constant.** Containment is only meaningful when the root is a
11 trusted value. Checking a derived path against a directory that untrusted
12 input helped build compares tainted against tainted and always passes. A
13 directory built as ``root / untrusted_a / untrusted_b`` and then validated
14 against that same built directory is checked against a reference the input
15 was free to move.
16
17 2. **Validate before touching the filesystem.** No ``mkdir``, no ``open``, until
18 the final path is known to be inside the root. Otherwise a rejected write
19 still leaves attacker-chosen directories behind.
20
21 :func:`secure_join` enforces both. Prefer it over hand-rolled
22 ``resolve() / is_relative_to()`` pairs — see ``python/AGENTS.md``.
23 """
24
25 from __future__ import annotations
26
27 import os
28 import re
29 import sys
30 import typing as t
31 from pathlib import Path, PureWindowsPath
32
33 from composio.exceptions import UnsafePathComponentError
34
35 SAFE_COMPONENT_REGEX = re.compile(r"^[A-Za-z0-9_-]+$")
36 """Characters permitted in a path component derived from untrusted input.
37
38 Deliberately identical to ``SLUG_REGEX`` in ``custom_tool_types.py``, which the
39 SDK already enforces on client-created custom tools. Backend-fetched tools were
40 never held to the same standard; they are now.
41
42 Every one of the 1070 toolkit slugs in the catalog snapshot at
43 ``ts/packages/cli/src/generated/toolkit-slugs.ts`` conforms, so this is not
44 expected to reject anything legitimate. That snapshot is not the live catalog:
45 a production slug containing a dot or a non-ASCII character would hard-fail its
46 downloads rather than degrade.
47 """
48
49 MAX_COMPONENT_LENGTH = 128
50 """Upper bound on a single component, well under the 255-byte limit common to
51 ext4/APFS/NTFS. Keeps a long slug from raising ``OSError`` mid-write."""
52
53 WINDOWS_RESERVED_NAMES = frozenset(
54 {"CON", "PRN", "AUX", "NUL"}
55 | {f"COM{i}" for i in range(1, 10)}
56 | {f"LPT{i}" for i in range(1, 10)}
57 | {f"COM{i}" for i in "¹²³"}
58 | {f"LPT{i}" for i in "¹²³"}
59 )
60 """Reserved DOS device names. Writing to one on Windows targets the device
61 rather than a file. Rejected as slugs and prefixed in filenames, on every
62 platform, so behaviour does not diverge between a POSIX developer machine and a
63 Windows deployment."""
64
65 MAX_PRESERVED_EXTENSION_BYTES = 32
66 """Longest extension, in bytes and including its dot, that filename truncation
67 keeps. Anything longer is not a real extension and is truncated with the rest."""
68
69 _WINDOWS_INVALID_FILENAME_CHARS = re.compile(r'[\x00-\x1f<>:"|?*]')
70 """Control characters and characters reserved by Windows."""
71
72
73 def is_inside_dir(child: Path, parent: Path) -> bool:
74 """True iff ``child`` equals ``parent`` or is nested inside it on a path
75 component boundary.
76
77 ``/tmp/foo`` contains ``/tmp/foo/bar`` but NOT ``/tmp/foo-bar`` — a plain
78 string prefix test gets that wrong. Comparison is case-insensitive on
79 Windows, where ``C:\\Foo`` and ``c:\\foo`` are the same directory.
80
81 Both arguments are assumed absolute and normalized.
82 """
83 try:
84 child_str = str(child)
85 parent_str = str(parent)
86 if sys.platform == "win32":
87 child_str = child_str.lower()
88 parent_str = parent_str.lower()
89 if child_str == parent_str:
90 return True
91 sep = os.sep
92 parent_with_sep = parent_str if parent_str.endswith(sep) else parent_str + sep
93 return child_str.startswith(parent_with_sep)
94 except OSError:
95 return False
96
97
98 def assert_safe_path_component(value: str, *, label: str = "path component") -> str:
99 """Return ``value`` unchanged if it is safe to use as a single path
100 component, else raise.
101
102 Fails closed. Rejects traversal (``..``), separators of either platform,
103 absolute paths, drive letters, NUL bytes, reserved device names, and
104 anything outside :data:`SAFE_COMPONENT_REGEX`.
105
106 :raises UnsafePathComponentError: when ``value`` is unsafe.
107 """
108 if not isinstance(value, str) or not value:
109 raise UnsafePathComponentError(
110 f"Refusing to build a path from an empty or non-string {label}: {value!r}"
111 )
112
113 # `PureWindowsPath` treats both `/` and `\` as separators, so a single check
114 # catches `../x` and `..\x` regardless of the host platform. A slug crafted
115 # for a Windows target must not slip through on a POSIX build machine.
116 as_windows_path = PureWindowsPath(value)
117 if len(as_windows_path.parts) != 1 or as_windows_path.anchor:
118 raise UnsafePathComponentError(
119 f"Refusing to build a path from a {label} containing path separators "
120 f"or a drive letter: {value!r}"
121 )
122
123 if len(value) > MAX_COMPONENT_LENGTH:
124 raise UnsafePathComponentError(
125 f"Refusing to build a path from a {label} longer than "
126 f"{MAX_COMPONENT_LENGTH} characters: {value[:32]!r}... "
127 f"({len(value)} characters)"
128 )
129
130 # `.` and `..` are excluded by the regex (no `.` in the character class),
131 # as are NUL bytes and every separator. The explicit checks above exist to
132 # produce a precise error message rather than a generic pattern mismatch.
133 #
134 # `fullmatch`, not `match`: in a `match`, `$` also matches just before a
135 # single trailing newline, so `"GMAIL\n"` would satisfy `^[A-Za-z0-9_-]+$`
136 # and reach the filesystem with a control character in the name.
137 if not SAFE_COMPONENT_REGEX.fullmatch(value):
138 raise UnsafePathComponentError(
139 f"Refusing to build a path from an unsafe {label}: {value!r}. "
140 f"Expected only letters, digits, underscores, and hyphens "
141 f"(pattern {SAFE_COMPONENT_REGEX.pattern})."
142 )
143
144 if value.upper() in WINDOWS_RESERVED_NAMES:
145 raise UnsafePathComponentError(
146 f"Refusing to build a path from a reserved device name as {label}: {value!r}"
147 )
148
149 return value
150
151
152 def _encoded_length(value: str) -> int:
153 return len(os.fsencode(value))
154
155
156 def _truncate_to_bytes(value: str, max_bytes: int) -> str:
157 """The longest prefix of ``value``, by whole code points, that fits in
158 ``max_bytes``."""
159 truncated = []
160 size = 0
161 for char in value:
162 size += _encoded_length(char)
163 if size > max_bytes:
164 break
165 truncated.append(char)
166 return "".join(truncated)
167
168
169 def _split_extension(name: str) -> t.Tuple[str, str]:
170 """Split off a short trailing extension (with its dot); a leading dot is
171 not one."""
172 dot = name.rfind(".")
173 extension = name[dot:] if dot > 0 else ""
174 if extension and _encoded_length(extension) <= MAX_PRESERVED_EXTENSION_BYTES:
175 return name[:dot], extension
176 return name, ""
177
178
179 def _fit_filename_bytes(name: str, max_bytes: int = MAX_COMPONENT_LENGTH) -> str:
180 """Truncate ``name`` to ``max_bytes``, keeping a short extension so the file
181 still opens with the right application."""
182 if _encoded_length(name) <= max_bytes:
183 return name
184 stem, extension = _split_extension(name)
185 return _truncate_to_bytes(stem, max_bytes - _encoded_length(extension)) + extension
186
187
188 def numbered_basename(name: str, copy: int) -> str:
189 """Add a copy number before the extension within the filename byte limit."""
190 suffix = f"-{copy}"
191 stem, extension = _split_extension(name)
192 return (
193 _truncate_to_bytes(
194 stem, MAX_COMPONENT_LENGTH - _encoded_length(extension) - len(suffix)
195 )
196 + suffix
197 + extension
198 )
199
200
201 def open_unique_file(path: Path) -> t.Tuple[Path, t.BinaryIO]:
202 """Claim a validated download path without replacing an existing file.
203
204 Numbered alternatives stay in the same directory and preserve a short
205 extension. Exclusive creation also prevents concurrent saves from sharing
206 a destination.
207 """
208 copy = 0
209 while True:
210 candidate = (
211 path if copy == 0 else path.with_name(numbered_basename(path.name, copy))
212 )
213 try:
214 return candidate, candidate.open("xb")
215 except FileExistsError:
216 copy += 1
217
218
219 _FNV_OFFSET_BASIS_64 = 0xCBF29CE484222325
220 _FNV_PRIME_64 = 0x100000001B3
221 _UINT64_MASK = 0xFFFFFFFFFFFFFFFF
222
223
224 def _fnv1a64_hex(value: str) -> str:
225 """64-bit FNV-1a of the UTF-8 bytes, as 16 hex digits. ``fnv1a64Hex`` in
226 the TypeScript SDK matches it."""
227 digest = _FNV_OFFSET_BASIS_64
228 for byte in value.encode("utf-8", "surrogatepass"):
229 digest = ((digest ^ byte) * _FNV_PRIME_64) & _UINT64_MASK
230 return f"{digest:016x}"
231
232
233 def _tag_with_original(portable: str, original: str) -> str:
234 """Tag a name that portability changed with a digest of the name it came
235 from, before the extension: ``report?.png`` and ``report*.png`` both become
236 ``report_.png``, and two long names can share a truncated prefix, so
237 without the tag one download would overwrite the other in a shared
238 directory."""
239 tag = f"-{_fnv1a64_hex(original)}"
240 stem, extension = _split_extension(
241 _fit_filename_bytes(portable, MAX_COMPONENT_LENGTH - len(tag))
242 )
243 return stem + tag + extension
244
245
246 def safe_basename(name: str, *, label: str = "filename") -> str:
247 """Collapse an untrusted filename to a bare basename that is safe to write
248 on every platform.
249
250 Filenames need their own validator: :func:`assert_safe_path_component`
251 forbids ``.``, which nearly every real filename contains.
252
253 ``PureWindowsPath`` treats both ``/`` and ``\\`` as separators, so a name
254 crafted for a Windows target (``..\\..\\evil``) is stripped even when the
255 SDK runs on POSIX, where ``Path(...).name`` would return it intact.
256
257 Names that cannot be written at all are refused: a NUL byte, invalid
258 Unicode, or no usable basename (empty or a run of dots). A response that
259 cannot name its own file is malformed or hostile, and inventing a name
260 would hide that. ``.`` and the empty string both basename to ``""``, which
261 makes an output path equal to its own directory and surfaces as
262 ``IsADirectoryError`` at write time.
263
264 Names that are merely unportable are made portable instead, because
265 ordinary files have them (``report_2026-09-29T10:30:00.csv``,
266 ``What is this?.png``), on every platform so a name does not depend on
267 where the SDK runs: control and Windows-reserved characters become ``_``,
268 names over :data:`MAX_COMPONENT_LENGTH` bytes are truncated with their
269 extension kept, trailing spaces and dots are dropped as Windows would, and
270 a resulting reserved device name gets a ``_`` prefix. A name any of these
271 rules changed is then tagged with a digest of the original before its
272 extension (``report_-<16 hex>.png``) to distinguish ordinary normalization
273 collisions; a name that was already portable is returned unchanged. The
274 result can still equal a literal server name, so download writes use
275 :func:`open_unique_file` to preserve existing files.
276 ``safeBasename`` in the TypeScript SDK applies the same rules in the same
277 order.
278
279 ``str.strip`` removes surrounding whitespace first, and the usability check
280 runs last, on the value that gets written, so neither ``"\\u00a0.\\u00a0"``
281 nor ``". ."`` can be written as ``.`` or as its own directory.
282
283 :raises UnsafePathComponentError: when ``name`` contains a NUL byte or
284 invalid Unicode, or leaves no usable basename.
285 """
286 if not isinstance(name, str):
287 raise UnsafePathComponentError(
288 f"Refusing to write a non-string {label}: {name!r}"
289 )
290
291 basename = PureWindowsPath(name).name.strip()
292 if "\x00" in basename:
293 raise UnsafePathComponentError(
294 f"Refusing to write {label} containing a NUL byte: {name!r}"
295 )
296 try:
297 _encoded_length(basename)
298 except UnicodeEncodeError as e:
299 raise UnsafePathComponentError(
300 f"Refusing to write {label} containing invalid Unicode: {name!r}"
301 ) from e
302
303 def fit(value: str) -> str:
304 return _fit_filename_bytes(value).rstrip(". ")
305
306 portable = fit(_WINDOWS_INVALID_FILENAME_CHARS.sub("_", basename))
307 # Checked on the fitted name, because truncation and trailing-dot removal
308 # can expose one (`NUL` followed by spaces and a long tail). Compare
309 # everything before the first dot: on Windows `NUL.tar.gz` opens the null
310 # device just as `NUL` does, so extensions provide no protection. Fitting
311 # again keeps the byte bound, and a `_`-prefixed name is never a device.
312 device_name = portable.split(".", 1)[0].rstrip(" ").upper()
313 if device_name in WINDOWS_RESERVED_NAMES:
314 portable = fit(f"_{portable}")
315
316 if not portable:
317 raise UnsafePathComponentError(
318 f"Path traversal detected: {label} {name!r} leaves no usable "
319 "basename to write to."
320 )
321 return portable if portable == basename else _tag_with_original(portable, basename)
322
323
324 def resolve_root(root: t.Union[str, Path]) -> Path:
325 """Normalize a trusted root to an absolute, symlink-resolved path.
326
327 Every containment check must derive its anchor through this one function.
328 When two call sites normalize differently — one expanding ``~`` and one not
329 — the check compares mismatched paths and rejects legitimate writes while
330 reporting them as attacks. Sharing the normalization is what keeps the two
331 ends of a containment check comparable.
332 """
333 expanded = Path(root).expanduser()
334 try:
335 return expanded.resolve(strict=False)
336 except OSError:
337 return expanded
338
339
340 def secure_basename_join(
341 base: t.Union[str, Path],
342 name: str,
343 *,
344 root: t.Optional[t.Union[str, Path]] = None,
345 label: str = "filename",
346 ) -> Path:
347 """Join a single untrusted filename under ``base``, contained within ``root``.
348
349 The filename counterpart to :func:`secure_join`, which cannot be reused here
350 because it forbids ``.`` — correct for a slug, wrong for ``report.pdf``.
351
352 ``root`` defaults to ``base`` but is separate for the download path, where
353 ``base`` is a per-tool subdirectory that untrusted slugs helped build and
354 only the configured ``root`` above it is trusted. Anchoring on ``base``
355 there would check the result against a directory those slugs had moved.
356
357 :raises UnsafePathComponentError: when ``name`` is unsafe, or when the
358 result escapes ``root``.
359 """
360 resolved_base = resolve_root(base)
361 resolved_root = resolved_base if root is None else resolve_root(root)
362 candidate = resolved_base / safe_basename(name, label=label)
363 if not is_inside_dir(candidate.resolve(), resolved_root):
364 raise UnsafePathComponentError(
365 f"Path traversal detected: {label} {name!r} resolves to "
366 f"{candidate.resolve()}, which is outside {resolved_root}."
367 )
368 return candidate
369
370
371 def secure_join(root: t.Union[str, Path], *components: str) -> Path:
372 """Join untrusted ``components`` beneath the trusted ``root``.
373
374 ``root`` is the sole anchor of trust and must not itself be derived from
375 untrusted input — that is the whole point. Each component is validated by
376 :func:`assert_safe_path_component`, then the joined result is resolved and
377 re-checked against the resolved root. The second check is belt-and-braces:
378 it catches a symlink inside ``root`` pointing outside it, which per-component
379 validation cannot see.
380
381 Performs no filesystem writes; the caller creates directories only after
382 this returns.
383
384 :raises UnsafePathComponentError: when any component is unsafe, or when the
385 joined path escapes ``root``.
386 """
387 resolved_root = resolve_root(root)
388
389 safe_components = [
390 assert_safe_path_component(component) for component in components
391 ]
392
393 candidate = resolved_root.joinpath(*safe_components)
394 try:
395 resolved_candidate = candidate.resolve(strict=False)
396 except OSError:
397 resolved_candidate = candidate
398
399 if not is_inside_dir(resolved_candidate, resolved_root):
400 raise UnsafePathComponentError(
401 f"Refusing to write outside the configured directory: "
402 f"{components!r} resolves to {resolved_candidate}, "
403 f"which is outside {resolved_root}."
404 )
405
406 return resolved_candidate