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 394 lines 15.2 KB
Raw
1 """Tests for the path containment primitives in `composio.utils.safe_path`.
2
3 See that module's docstring for why containment must be anchored on a constant
4 root rather than on a directory the input helped build.
5 """
6
7 import re
8 import sys
9 from pathlib import Path
10
11 import pytest
12
13 from composio.exceptions import UnsafePathComponentError
14 from composio.utils.safe_path import (
15 MAX_COMPONENT_LENGTH,
16 SAFE_COMPONENT_REGEX,
17 assert_safe_path_component,
18 is_inside_dir,
19 resolve_root,
20 safe_basename,
21 secure_basename_join,
22 secure_join,
23 )
24
25
26 class TestResolveRoot:
27 """Both ends of a containment check must normalize through this one
28 function; when they diverge the check compares mismatched paths."""
29
30 def test_expands_tilde(self, tmp_path, monkeypatch):
31 monkeypatch.setenv("HOME", str(tmp_path))
32 assert resolve_root("~/downloads") == (tmp_path / "downloads").resolve()
33
34 def test_resolves_relative(self, tmp_path, monkeypatch):
35 monkeypatch.chdir(tmp_path)
36 assert resolve_root("./downloads") == (tmp_path / "downloads").resolve()
37
38 def test_accepts_path_and_str_identically(self, tmp_path):
39 assert resolve_root(tmp_path) == resolve_root(str(tmp_path))
40
41 def test_nonexistent_root_does_not_raise(self, tmp_path):
42 assert resolve_root(tmp_path / "nope") == (tmp_path / "nope").resolve()
43
44
45 class TestAssertSafePathComponent:
46 @pytest.mark.parametrize(
47 "value",
48 [
49 "GMAIL",
50 "GMAIL_GET_ATTACHMENT",
51 "github",
52 "some-toolkit",
53 "v2",
54 "a",
55 "A1_b-2",
56 ],
57 )
58 def test_accepts_realistic_slugs(self, value):
59 assert assert_safe_path_component(value) == value
60
61 @pytest.mark.parametrize(
62 "value",
63 [
64 "..",
65 ".",
66 "../etc",
67 "../../../../../etc/escaped",
68 "a/b",
69 "a\\b",
70 "..\\..\\evil",
71 "/etc",
72 "/",
73 "C:\\Windows",
74 "C:/Windows",
75 "",
76 "a\x00b",
77 "a b",
78 "a.b",
79 "café",
80 "x" * 129,
81 ],
82 )
83 def test_rejects_unsafe_values(self, value):
84 with pytest.raises(UnsafePathComponentError):
85 assert_safe_path_component(value)
86
87 @pytest.mark.parametrize("value", ["GMAIL\n", "GMAIL\r\n", "GMAIL\x0b", "\nGMAIL"])
88 def test_rejects_control_characters(self, value):
89 """`re.match` with a `$` anchor also matches just before a single
90 trailing newline, so `"GMAIL\\n"` satisfied the pattern and reached the
91 filesystem. `fullmatch` is what closes that."""
92 with pytest.raises(UnsafePathComponentError):
93 assert_safe_path_component(value)
94
95 @pytest.mark.parametrize("value", ["CON", "con", "NUL", "COM1", "lpt9", "AUX"])
96 def test_rejects_windows_device_names_on_every_platform(self, value):
97 """Rejected regardless of host OS so a POSIX test run cannot pass code
98 that would target a device on a Windows deployment."""
99 with pytest.raises(UnsafePathComponentError, match="reserved device name"):
100 assert_safe_path_component(value)
101
102 def test_rejects_non_string(self):
103 with pytest.raises(UnsafePathComponentError):
104 assert_safe_path_component(None) # type: ignore[arg-type]
105
106 def test_label_appears_in_the_error(self):
107 with pytest.raises(UnsafePathComponentError, match="tool slug"):
108 assert_safe_path_component("../x", label="tool slug")
109
110 def test_boundary_length(self):
111 assert assert_safe_path_component("x" * 128) == "x" * 128
112 with pytest.raises(UnsafePathComponentError, match="longer than"):
113 assert_safe_path_component("x" * 129)
114
115 def test_matches_the_custom_tool_slug_pattern(self):
116 """The SDK already enforced this pattern on client-created custom
117 tools; backend-fetched tools are now held to the same standard."""
118 from composio.core.models.custom_tool_types import SLUG_REGEX
119
120 assert SAFE_COMPONENT_REGEX.pattern == SLUG_REGEX.pattern
121
122
123 class TestIsInsideDir:
124 def test_nested_path_is_inside(self, tmp_path):
125 assert is_inside_dir(tmp_path / "a" / "b", tmp_path)
126
127 def test_same_path_is_inside(self, tmp_path):
128 assert is_inside_dir(tmp_path, tmp_path)
129
130 def test_sibling_prefix_is_not_inside(self, tmp_path):
131 """`/tmp/foo` must not be treated as containing `/tmp/foo-bar`. A plain
132 string prefix check gets this wrong."""
133 assert not is_inside_dir(Path(f"{tmp_path}-evil") / "x", tmp_path)
134
135 def test_parent_is_not_inside(self, tmp_path):
136 assert not is_inside_dir(tmp_path.parent, tmp_path)
137
138 @pytest.mark.skipif(sys.platform != "win32", reason="Windows-only casing rule")
139 def test_case_insensitive_on_windows(self):
140 assert is_inside_dir(Path("C:\\Foo\\Bar"), Path("c:\\foo"))
141
142
143 TAG_BYTES = 17
144 """Bytes a changed name gains: ``-`` and 16 hex digits of the original's
145 digest."""
146
147
148 def tagged(stem: str, extension: str = "") -> "re.Pattern[str]":
149 """Match ``stem``, the digest tag of a changed name, then ``extension``."""
150 return re.compile(re.escape(stem) + "-[0-9a-f]{16}" + re.escape(extension))
151
152
153 class TestSafeBasename:
154 @pytest.mark.parametrize(
155 ("value", "expected"),
156 [
157 ("report.pdf", "report.pdf"),
158 ("output/report.pdf", "report.pdf"),
159 ("archive.tar.gz", "archive.tar.gz"),
160 (".gitignore", ".gitignore"),
161 ("..\\..\\evil", "evil"),
162 (" report.pdf", "report.pdf"),
163 ("report.pdf ", "report.pdf"),
164 ("\x1creport.txt\x1f", "report.txt"),
165 ("café.txt", "café.txt"),
166 ("C:report.txt", "report.txt"),
167 ("\ufeffreport.txt", "\ufeffreport.txt"),
168 ("\u0085report.txt\u0085", "report.txt"),
169 ],
170 )
171 def test_reduces_to_the_basename(self, value, expected):
172 assert safe_basename(value) == expected
173
174 @pytest.mark.parametrize("value", ["", ".", "..", "...", "foo/..", "/", " "])
175 def test_rejects_names_with_no_usable_basename(self, value):
176 with pytest.raises(UnsafePathComponentError, match="no usable basename"):
177 safe_basename(value)
178
179 @pytest.mark.parametrize(
180 "value",
181 ["\u00a0.\u00a0", ".\u00a0", "\u00a0.", "\u2007..\u2007", "\u2028.\u2029"],
182 )
183 def test_rejects_whitespace_wrapped_dot_runs(self, value):
184 """``str.strip`` removes Unicode whitespace, so these are written as
185 ``.`` or ``..``: the usability check must see the stripped value."""
186 with pytest.raises(UnsafePathComponentError, match="no usable basename"):
187 safe_basename(value)
188
189 @pytest.mark.parametrize("value", [". .", ".. ", " . . "])
190 def test_rejects_dot_runs_once_windows_trims_them(self, value):
191 with pytest.raises(UnsafePathComponentError, match="no usable basename"):
192 safe_basename(value)
193
194 def test_rejects_nul_byte(self):
195 with pytest.raises(UnsafePathComponentError, match="NUL byte"):
196 safe_basename("report\x00.pdf")
197
198 @pytest.mark.parametrize(
199 ("value", "stem", "extension"),
200 [
201 ("report_2026-09-29T10:30:00.csv", "report_2026-09-29T10_30_00", ".csv"),
202 ("What is this?.png", "What is this_", ".png"),
203 ('invoice "final".pdf', "invoice _final_", ".pdf"),
204 ("report.txt:payload", "report", ".txt_payload"),
205 ("report<1>.txt", "report_1_", ".txt"),
206 ("a|b*.txt", "a_b_", ".txt"),
207 ("tab\there.txt", "tab_here", ".txt"),
208 ("output/C:report.txt", "C_report", ".txt"),
209 ],
210 )
211 def test_replaces_windows_reserved_characters(self, value, stem, extension):
212 assert tagged(stem, extension).fullmatch(safe_basename(value))
213
214 @pytest.mark.parametrize(
215 ("value", "stem", "extension"),
216 [
217 ("report.txt.", "report", ".txt"),
218 ("report. .", "report", ""),
219 ("report.\u00a0", "report", ""),
220 ("report.\u0085", "report", ""),
221 ("\ufeff..", "\ufeff", ""),
222 ],
223 )
224 def test_drops_trailing_spaces_and_dots(self, value, stem, extension):
225 assert tagged(stem, extension).fullmatch(safe_basename(value))
226
227 @pytest.mark.parametrize(
228 ("value", "stem", "extension"),
229 [
230 ("NUL", "_NUL", ""),
231 ("nul", "_nul", ""),
232 ("NUL.tar.gz", "_NUL.tar", ".gz"),
233 ("COM1.log.bak", "_COM1.log", ".bak"),
234 ("COM¹.txt", "_COM¹", ".txt"),
235 ("LPT³.data", "_LPT³", ".data"),
236 ("aux.txt", "_aux", ".txt"),
237 ("CON .txt", "_CON ", ".txt"),
238 ("COM1:.txt", "COM1_", ".txt"),
239 ],
240 )
241 def test_prefixes_windows_device_names_with_any_extension(
242 self, value, stem, extension
243 ):
244 assert tagged(stem, extension).fullmatch(safe_basename(value))
245
246 def test_prefixes_a_device_name_exposed_by_truncation(self):
247 # Truncation keeps `NUL` plus spaces before `.txt`, and Windows ignores
248 # the spaces, so the checked name must be the fitted one.
249 spaces = " " * (MAX_COMPONENT_LENGTH - TAG_BYTES - 8)
250 assert tagged("_NUL" + spaces, ".txt").fullmatch(
251 safe_basename("NUL" + " " * 200 + "x.txt")
252 )
253 assert tagged("_CON").fullmatch(safe_basename("CON" + " " * 200 + "x"))
254
255 def test_keeps_a_filename_at_the_byte_limit(self):
256 name = "x" * MAX_COMPONENT_LENGTH
257 assert safe_basename(name) == name
258
259 def test_truncates_to_the_byte_limit_and_keeps_the_extension(self):
260 result = safe_basename("x" * 200 + ".pdf")
261 assert tagged("x" * (MAX_COMPONENT_LENGTH - TAG_BYTES - 4), ".pdf").fullmatch(
262 result
263 )
264 assert len(result) == MAX_COMPONENT_LENGTH
265
266 def test_truncates_by_whole_code_points_measured_in_bytes(self):
267 cjk = safe_basename("請" * 70 + ".pdf")
268 assert tagged("請" * 35, ".pdf").fullmatch(cjk)
269 assert len(cjk.encode()) <= MAX_COMPONENT_LENGTH
270 assert tagged("😀" * 27).fullmatch(safe_basename("😀" * 33))
271
272 def test_truncates_an_over_long_extension_with_the_rest(self):
273 stem = "report." + "x" * (MAX_COMPONENT_LENGTH - TAG_BYTES - 7)
274 assert tagged(stem).fullmatch(safe_basename("report." + "x" * 200))
275
276 def test_drops_a_trailing_dot_exposed_by_truncation(self):
277 name = "x" * (MAX_COMPONENT_LENGTH - 1) + "." + "y" * 40
278 assert tagged("x" * (MAX_COMPONENT_LENGTH - TAG_BYTES)).fullmatch(
279 safe_basename(name)
280 )
281
282 @pytest.mark.parametrize(
283 ("value", "expected"),
284 [
285 # safePath.test.ts asserts the same vectors, so both SDKs write a
286 # given server name to the same file.
287 ("report?.png", "report_-05fcb95aa5b918e9.png"),
288 ("report*.png", "report_-aa921bdab2b33292.png"),
289 (
290 "report_2026-09-29T10:30:00.csv",
291 "report_2026-09-29T10_30_00-d7211bb25cb815fe.csv",
292 ),
293 ("NUL.txt", "_NUL-d0848f78ce05ded6.txt"),
294 ],
295 )
296 def test_tags_a_changed_name_with_a_digest_of_the_original(self, value, expected):
297 assert safe_basename(value) == expected
298
299 def test_distinct_names_that_normalize_alike_stay_distinct(self):
300 names = ["report?.png", "report*.png", "report:.png", "report_.png"]
301 assert len({safe_basename(name) for name in names}) == len(names)
302
303 def test_distinct_long_names_sharing_a_truncated_prefix_stay_distinct(self):
304 prefix = "a" * 200
305 assert safe_basename(prefix + "-1.txt") != safe_basename(prefix + "-2.txt")
306
307 def test_returns_an_already_portable_name_unchanged(self):
308 assert safe_basename("report_.png") == "report_.png"
309
310 def test_treats_a_tagged_name_as_already_portable(self):
311 written = safe_basename("report?.png")
312 assert safe_basename(written) == written
313
314 def test_rejects_unencodable_filename(self):
315 with pytest.raises(UnsafePathComponentError, match="invalid Unicode"):
316 safe_basename("report-\ud800.txt")
317
318
319 class TestSecureBasenameJoin:
320 def test_tilde_base_is_expanded_before_containment(self, tmp_path, monkeypatch):
321 monkeypatch.setenv("HOME", str(tmp_path))
322 assert (
323 secure_basename_join("~/downloads", "report.pdf")
324 == (tmp_path / "downloads" / "report.pdf").resolve()
325 )
326
327
328 class TestSecureJoin:
329 def test_joins_safe_components(self, tmp_path):
330 assert (
331 secure_join(tmp_path, "GMAIL", "GMAIL_GET_ATTACHMENT")
332 == (tmp_path / "GMAIL" / "GMAIL_GET_ATTACHMENT").resolve()
333 )
334
335 def test_no_components_returns_the_root(self, tmp_path):
336 assert secure_join(tmp_path) == tmp_path.resolve()
337
338 @pytest.mark.parametrize("component", ["..", "../etc", "/etc", "a/b", "..\\evil"])
339 def test_rejects_traversal_components(self, component, tmp_path):
340 with pytest.raises(UnsafePathComponentError):
341 secure_join(tmp_path, component)
342
343 def test_rejects_traversal_in_any_position(self, tmp_path):
344 with pytest.raises(UnsafePathComponentError):
345 secure_join(tmp_path, "GMAIL", "..")
346
347 def test_creates_nothing_on_disk(self, tmp_path):
348 """Validation must complete before any filesystem write, so a rejected
349 join leaves no attacker-chosen directories behind."""
350 root = tmp_path / "root"
351 root.mkdir()
352 with pytest.raises(UnsafePathComponentError):
353 secure_join(root, "../evil")
354 assert list(root.iterdir()) == []
355
356 secure_join(root, "GMAIL", "TOOL")
357 assert list(root.iterdir()) == []
358
359 def test_symlink_escape_is_caught_after_resolve(self, tmp_path):
360 """Per-component validation cannot see a symlink pointing out of the
361 root; the post-resolve containment check is what catches it."""
362 root = tmp_path / "root"
363 root.mkdir()
364 outside = tmp_path / "outside"
365 outside.mkdir()
366 (root / "GMAIL").symlink_to(outside, target_is_directory=True)
367
368 with pytest.raises(UnsafePathComponentError, match="outside"):
369 secure_join(root, "GMAIL", "TOOL")
370
371 def test_root_is_expanded_and_resolved(self, tmp_path):
372 nested = tmp_path / "a" / ".." / "b"
373 (tmp_path / "b").mkdir(parents=True)
374 assert secure_join(nested, "TOOL") == (tmp_path / "b" / "TOOL").resolve()
375
376 def test_accepts_str_root(self, tmp_path):
377 assert secure_join(str(tmp_path), "TOOL") == (tmp_path / "TOOL").resolve()
378
379 def test_tilde_root_is_expanded(self, tmp_path, monkeypatch):
380 """`~` must expand identically here and in every containment check that
381 shares this root, or a legitimate download is rejected as an attack."""
382 monkeypatch.setenv("HOME", str(tmp_path))
383 assert (
384 secure_join("~/downloads", "GMAIL")
385 == (tmp_path / "downloads" / "GMAIL").resolve()
386 )
387
388 def test_nonexistent_root_still_validates(self, tmp_path):
389 """`resolve(strict=False)` means the root need not exist yet — the
390 download directory is created lazily."""
391 root = tmp_path / "not-created-yet"
392 assert secure_join(root, "TOOL") == (root / "TOOL").resolve()
393 with pytest.raises(UnsafePathComponentError):
394 secure_join(root, "..")