1
+"""Guardrail against building filesystem paths out of untrusted input.
2
+
3
+The failure mode this prevents: a path built from unvalidated API response
4
+fields, with a containment check that compares the result against the very
5
+directory those fields helped build — tainted against tainted, so it always
6
+passes.
7
+
8
+A convention in `AGENTS.md` would not catch that. Such a line gets written by
9
+someone who has already thought about traversal and added a check. So this
10
+enforces the rule mechanically: every path built from something that is
11
+not a literal or a module-level constant must be recorded in `REVIEWED_JOINS`
12
+with a reason, and each entry must still be backed by the validation its reason
13
+cites.
14
+
15
+Three properties matter, and each is a test below, because each is easy to get
16
+wrong in a way that leaves the check looking present but doing nothing:
17
+
18
+1. **Cover every spelling.** A detector that only understands the `/` operator
19
+ is green while `os.path.join` reintroduces the bug.
20
+2. **Fail closed.** No guessing from variable names — renaming `outdir` to
21
+ `base` must not silently disable the check.
22
+3. **Bind the allowlist to its evidence.** An entry keyed only on source text
23
+ keeps passing after the validation around it is deleted.
24
+
25
+To satisfy this test, prefer `composio.utils.safe_path.secure_join`, which
26
+validates each untrusted component and anchors containment on a trusted root.
27
+"""
28
+
29
+import ast
30
+import functools
31
+import typing as t
32
+from pathlib import Path
33
+
34
+import pytest
35
+
36
+PYTHON_ROOT = Path(__file__).parent.parent
37
+SCANNED_ROOTS = (PYTHON_ROOT / "composio", PYTHON_ROOT / "providers")
38
+
39
+_PATH_CALLS = frozenset({"Path", "PurePath", "PurePosixPath", "PureWindowsPath"})
40
+"""Constructors whose result is a path."""
41
+
42
+_DIRECT_PATH_SINKS = frozenset({"open", "makedirs", "mkdir"})
43
+"""Functions whose first argument becomes a filesystem path."""
44
+
45
+
46
+def _reviewed_path(
47
+ reason: str,
48
+ *requires: str,
49
+ occurrences: int = 1,
50
+) -> t.Dict[str, t.Any]:
51
+ return {
52
+ "reason": reason,
53
+ "requires": frozenset(requires),
54
+ "occurrences": occurrences,
55
+ }
56
+
57
+
58
+REVIEWED_JOINS: t.Dict[t.Tuple[str, str], t.Dict[str, t.Any]] = {
59
+ (
60
+ "composio/core/models/_files.py",
61
+ (
62
+ "Path( os.environ.get( ENV_LOCAL_CACHE_DIRECTORY, Path.home() / "
63
+ "LOCAL_CACHE_DIRECTORY_NAME, # Fallback to user directory ) )"
64
+ ),
65
+ ): _reviewed_path(
66
+ "The cache root comes from local configuration or the user's home, not an "
67
+ "API response."
68
+ ),
69
+ (
70
+ "composio/core/models/_files.py",
71
+ "Path(path_in)",
72
+ ): _reviewed_path(
73
+ "`FileUploadable.from_path` converts the caller's local upload path after "
74
+ "the upload allowlist and sensitive-path checks have run.",
75
+ "assert_path_inside_upload_dirs",
76
+ "assert_safe_local_file_upload_path",
77
+ ),
78
+ (
79
+ "composio/core/models/_files.py",
80
+ "Path(outdir)",
81
+ ): _reviewed_path(
82
+ "`FileHelper` accepts this download root from local SDK configuration; API "
83
+ "response values are joined beneath it through the safe-path helpers."
84
+ ),
85
+ (
86
+ "composio/core/models/tool_router_session_files.py",
87
+ "PureWindowsPath(self.mount_relative_path)",
88
+ ): _reviewed_path(
89
+ "This property only extracts a display basename. `RemoteFile.save` validates "
90
+ "the same server value before using it as a filesystem path."
91
+ ),
92
+ (
93
+ "composio/core/models/tool_router_session_files.py",
94
+ "Path(path)",
95
+ ): _reviewed_path(
96
+ "A non-default `RemoteFile.save` destination is selected explicitly by the "
97
+ "caller and does not contain an API-derived path component."
98
+ ),
99
+ (
100
+ "composio/core/models/tool_router_session_files.py",
101
+ "Path(path_str)",
102
+ ): _reviewed_path(
103
+ "The upload input is a caller-selected local file and is checked before it is "
104
+ "read; it is not a path constructed from a remote response.",
105
+ "exists",
106
+ "is_file",
107
+ ),
108
+ (
109
+ "composio/integration_test/conftest.py",
110
+ "Path(__file__)",
111
+ ): _reviewed_path("`__file__` is the trusted location of this installed module."),
112
+ (
113
+ "composio/utils/mimetypes.py",
114
+ "Path(file)",
115
+ ): _reviewed_path(
116
+ "`mimetypes.guess` uses `Path` for suffix parsing only and never accesses the "
117
+ "filesystem."
118
+ ),
119
+ (
120
+ "composio/utils/safe_path.py",
121
+ "PureWindowsPath(value)",
122
+ ): _reviewed_path(
123
+ "The path parser detects cross-platform separators before the component is "
124
+ "accepted by the strict slug pattern.",
125
+ "fullmatch",
126
+ ),
127
+ (
128
+ "composio/utils/safe_path.py",
129
+ "PureWindowsPath(name)",
130
+ ): _reviewed_path(
131
+ "`safe_basename` collapses the value, rejects Windows-invalid forms, checks "
132
+ "its encoded length, and rejects reserved device names.",
133
+ "fsencode",
134
+ ),
135
+ (
136
+ "composio/utils/safe_path.py",
137
+ "Path(root)",
138
+ ): _reviewed_path(
139
+ "`resolve_root` normalizes a caller-supplied trusted anchor before any "
140
+ "containment comparison.",
141
+ "expanduser",
142
+ "resolve",
143
+ ),
144
+ (
145
+ "composio/utils/safe_path.py",
146
+ "resolved_base / safe_basename(name, label=label)",
147
+ ): {
148
+ "reason": (
149
+ "`secure_basename_join`, the sanctioned single-filename join. The "
150
+ "name is collapsed and validated by `safe_basename`, and the result "
151
+ "is re-checked with `is_inside_dir` against a `resolve_root`-derived "
152
+ "anchor that the caller supplies separately from the join base — the "
153
+ "distinction this whole module turns on."
154
+ ),
155
+ "requires": frozenset({"resolve_root", "safe_basename", "is_inside_dir"}),
156
+ "occurrences": 1,
157
+ },
158
+ ("composio/utils/safe_path.py", "resolved_root.joinpath(*safe_components)"): {
159
+ "reason": (
160
+ "`secure_join`, the sanctioned multi-component join. Every component "
161
+ "has passed `assert_safe_path_component`, the root came from "
162
+ "`resolve_root`, and the joined result is re-checked with "
163
+ "`is_inside_dir` before return."
164
+ ),
165
+ "requires": frozenset(
166
+ {"resolve_root", "assert_safe_path_component", "is_inside_dir"}
167
+ ),
168
+ "occurrences": 1,
169
+ },
170
+ (
171
+ "composio/utils/sensitive_file_upload_paths.py",
172
+ "Path(file_path)",
173
+ ): _reviewed_path(
174
+ "This converts a caller-selected upload path so the sensitive-path denylist "
175
+ "can inspect its normalized components.",
176
+ "expanduser",
177
+ "resolve",
178
+ ),
179
+ (
180
+ "composio/utils/upload_dir_allowlist.py",
181
+ "Path(s)",
182
+ ): _reviewed_path(
183
+ "This converts a locally configured upload-allowlist entry and resolves it "
184
+ "before comparisons.",
185
+ "expanduser",
186
+ "resolve",
187
+ ),
188
+}
189
+"""Reviewed dynamic path construction in the shipped Python packages.
190
+
191
+Entries outside `safe_path` are limited to caller-selected local paths, local
192
+configuration, module locations, or lexical parsing. API-derived components
193
+must use `secure_join` or `secure_basename_join`.
194
+"""
195
+
196
+for _provider_setup in (
197
+ "anthropic",
198
+ "autogen",
199
+ "claude_agent_sdk",
200
+ "crewai",
201
+ "gemini",
202
+ "google",
203
+ "google_adk",
204
+ "langchain",
205
+ "langgraph",
206
+ "llamaindex",
207
+ "openai",
208
+ "openai_agents",
209
+):
210
+ REVIEWED_JOINS[(f"providers/{_provider_setup}/setup.py", "Path(__file__)")] = (
211
+ _reviewed_path("`__file__` is the trusted location of this provider package.")
212
+ )
213
+del _provider_setup
214
+
215
+
216
+def _module_constants(tree: ast.Module) -> t.Set[str]:
217
+ """Module-level ALL_CAPS names bound to a literal.
218
+
219
+ Both halves matter. Without the module-level requirement a function-local
220
+ `SLUG = tool.slug` is exempt; without the literal requirement a module-level
221
+ `SLUG = os.environ[...]` is exempt. Either one is a one-token bypass.
222
+ """
223
+ out: t.Set[str] = set()
224
+ for node in tree.body:
225
+ targets: t.List[ast.expr]
226
+ if isinstance(node, ast.Assign):
227
+ targets = list(node.targets)
228
+ value = node.value
229
+ elif isinstance(node, ast.AnnAssign) and node.value is not None:
230
+ targets = [node.target]
231
+ value = node.value
232
+ else:
233
+ continue
234
+ if not _is_literal_expr(value):
235
+ continue
236
+ for tgt in targets:
237
+ if isinstance(tgt, ast.Name) and tgt.id.isupper():
238
+ out.add(tgt.id)
239
+ return out
240
+
241
+
242
+def _is_literal_expr(node: ast.expr) -> bool:
243
+ """True for expressions built only from literals."""
244
+ try:
245
+ ast.literal_eval(node)
246
+ return True
247
+ except (ValueError, TypeError, SyntaxError, MemoryError, RecursionError):
248
+ return False
249
+
250
+
251
+def _is_trusted(node: ast.expr, consts: t.Set[str]) -> bool:
252
+ if isinstance(node, ast.Constant):
253
+ return True
254
+ if isinstance(node, ast.Name) and node.id in consts:
255
+ return True
256
+ return False
257
+
258
+
259
+def _call_name(func: ast.expr) -> str:
260
+ if isinstance(func, ast.Attribute):
261
+ return func.attr
262
+ if isinstance(func, ast.Name):
263
+ return func.id
264
+ return ""
265
+
266
+
267
+def _is_os_path_join(func: ast.expr) -> bool:
268
+ """`os.path.join(...)` / `posixpath.join(...)`, not `",".join(...)`."""
269
+ if not (isinstance(func, ast.Attribute) and func.attr == "join"):
270
+ return False
271
+ recv = func.value
272
+ if isinstance(recv, ast.Attribute):
273
+ return recv.attr == "path"
274
+ if isinstance(recv, ast.Name):
275
+ return recv.id in {"posixpath", "ntpath", "path"}
276
+ return False
277
+
278
+
279
+def _is_direct_path_sink(func: ast.expr) -> bool:
280
+ """Builtins or ``os`` functions whose first argument is the path.
281
+
282
+ Method calls such as ``Path.open(mode)`` and ``Path.write_bytes(data)``
283
+ carry the path in their receiver, not in the positional arguments. Their
284
+ receiver construction is reviewed separately by the ``_PATH_CALLS`` rule.
285
+ """
286
+ if isinstance(func, ast.Name):
287
+ return func.id in _DIRECT_PATH_SINKS
288
+ return (
289
+ isinstance(func, ast.Attribute)
290
+ and func.attr in _DIRECT_PATH_SINKS
291
+ and isinstance(func.value, ast.Name)
292
+ and func.value.id == "os"
293
+ )
294
+
295
+
296
+@functools.lru_cache(maxsize=None)
297
+def _read_and_parse(path: Path, mtime_ns: int) -> t.Tuple[str, ast.Module]:
298
+ source = path.read_text()
299
+ return source, ast.parse(source)
300
+
301
+
302
+def _parse_cached(path: Path) -> t.Tuple[str, ast.Module]:
303
+ """Parse ``path``, reusing the previous result while its mtime is unchanged.
304
+
305
+ Keyed on mtime so the detector's own self-tests, which rewrite the same
306
+ synthetic file with different content, still see the new source.
307
+ """
308
+ return _read_and_parse(path, path.stat().st_mtime_ns)
309
+
310
+
311
+class Join(t.NamedTuple):
312
+ module: str
313
+ lineno: int
314
+ text: str
315
+ kind: str
316
+
317
+
318
+def _collect_joins(roots: t.Sequence[Path] = SCANNED_ROOTS) -> t.List[Join]:
319
+ """Every path construction from a non-literal, non-module-constant value."""
320
+ found: t.List[Join] = []
321
+ for root in roots:
322
+ if not root.exists():
323
+ continue
324
+ for py in sorted(root.rglob("*.py")):
325
+ try:
326
+ source, tree = _parse_cached(py)
327
+ except SyntaxError: # pragma: no cover - lint job fails first
328
+ continue
329
+ consts = _module_constants(tree)
330
+ try:
331
+ module = str(py.relative_to(PYTHON_ROOT))
332
+ except ValueError:
333
+ # Synthetic roots used by the detector's own self-tests.
334
+ module = str(py.relative_to(root.parent))
335
+
336
+ def record(node: t.Union[ast.expr, ast.stmt], kind: str) -> None:
337
+ text = ast.get_source_segment(source, node) or ""
338
+ found.append(Join(module, node.lineno, " ".join(text.split()), kind))
339
+
340
+ for node in ast.walk(tree):
341
+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Div):
342
+ if not _is_trusted(node.right, consts):
343
+ record(node, "div")
344
+ elif isinstance(node, ast.AugAssign) and isinstance(node.op, ast.Div):
345
+ if not _is_trusted(node.value, consts):
346
+ record(node, "augdiv")
347
+ elif isinstance(node, ast.Call):
348
+ name = _call_name(node.func)
349
+ args = node.args
350
+ if name == "joinpath":
351
+ if any(not _is_trusted(a, consts) for a in args):
352
+ record(node, "joinpath")
353
+ elif _is_os_path_join(node.func):
354
+ if any(not _is_trusted(a, consts) for a in args):
355
+ record(node, "os.path.join")
356
+ elif name in _PATH_CALLS:
357
+ if any(not _is_trusted(a, consts) for a in args):
358
+ record(node, "Path(...)")
359
+ elif _is_direct_path_sink(node.func):
360
+ if args and not _is_trusted(args[0], consts):
361
+ record(node, name)
362
+ return found
363
+
364
+
365
+def _enclosing_function_calls(module: str, lineno: int) -> t.Set[str]:
366
+ """Names called inside the function containing ``lineno``."""
367
+ path = PYTHON_ROOT / module
368
+ _, tree = _parse_cached(path)
369
+ best: t.Optional[t.Union[ast.FunctionDef, ast.AsyncFunctionDef]] = None
370
+ for node in ast.walk(tree):
371
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
372
+ end = getattr(node, "end_lineno", None) or lineno
373
+ if node.lineno <= lineno <= end:
374
+ if best is None or node.lineno > best.lineno: # innermost
375
+ best = node
376
+ if best is None:
377
+ return set()
378
+ return {_call_name(n.func) for n in ast.walk(best) if isinstance(n, ast.Call)}
379
+
380
+
381
+def test_every_untrusted_path_join_is_reviewed():
382
+ unreviewed = [
383
+ j for j in _collect_joins() if (j.module, j.text) not in REVIEWED_JOINS
384
+ ]
385
+ assert not unreviewed, (
386
+ "Found path construction(s) from non-constant input that are not "
387
+ "recorded in REVIEWED_JOINS:\n"
388
+ + "\n".join(f" [{j.kind}] {j.module}:{j.lineno}: {j.text}" for j in unreviewed)
389
+ + "\n\nIf the value can come from an API response, use "
390
+ "`composio.utils.safe_path.secure_join(root, *components)` instead. "
391
+ "If the construction is genuinely safe, add it to REVIEWED_JOINS in "
392
+ f"{Path(__file__).name} with a reason and the validators it relies on."
393
+ )
394
+
395
+
396
+def test_reviewed_joins_all_still_exist():
397
+ """Keeps the allowlist from rotting into stale entries that silently permit
398
+ whatever moves into their place."""
399
+ found = {(j.module, j.text) for j in _collect_joins()}
400
+ stale = set(REVIEWED_JOINS) - found
401
+ assert not stale, (
402
+ "REVIEWED_JOINS entries no longer present in the source (remove them):\n"
403
+ + "\n".join(f" {m}: {tx}" for m, tx in sorted(stale))
404
+ )
405
+
406
+
407
+def test_reviewed_joins_still_have_their_validation():
408
+ """Entries that depend on validators still call them in the same function."""
409
+ for join in _collect_joins():
410
+ entry = REVIEWED_JOINS.get((join.module, join.text))
411
+ if entry is None:
412
+ continue
413
+ calls = _enclosing_function_calls(join.module, join.lineno)
414
+ missing = entry["requires"] - calls
415
+ assert not missing, (
416
+ f"{join.module}:{join.lineno}: `{join.text}` is allowlisted because "
417
+ f"it is guarded by {sorted(entry['requires'])}, but "
418
+ f"{sorted(missing)} is no longer called in the enclosing function. "
419
+ "Either restore the validation or re-review the entry."
420
+ )
421
+
422
+
423
+def test_reviewed_joins_occurrence_counts_match():
424
+ """One entry must not blanket-approve unlimited future joins that happen to
425
+ share its source text."""
426
+ counts: t.Dict[t.Tuple[str, str], int] = {}
427
+ for join in _collect_joins():
428
+ counts[(join.module, join.text)] = counts.get((join.module, join.text), 0) + 1
429
+ for key, entry in REVIEWED_JOINS.items():
430
+ actual = counts.get(key, 0)
431
+ assert actual == entry["occurrences"], (
432
+ f"{key[0]}: `{key[1]}` appears {actual} time(s), but the "
433
+ f"REVIEWED_JOINS entry expects {entry['occurrences']}. A new "
434
+ "occurrence is not covered by the existing review."
435
+ )
436
+
437
+
438
+EVASIONS = {
439
+ "div": "return self._outdir / tool.toolkit.slug / tool.slug",
440
+ "div-unhinted-name": "return base / tool.slug",
441
+ "augdiv": "p = Path('/tmp')\n p /= tool.slug\n return p",
442
+ "joinpath": "return self._outdir.joinpath(tool.slug)",
443
+ "os.path.join": "return os.path.join(self._outdir, tool.slug)",
444
+ "Path(a, b)": "return Path(self._outdir, tool.slug)",
445
+ "Path(value)": "return Path(tool.slug)",
446
+ "Path(value, literal)": "return Path(tool.slug, 'payload')",
447
+ "Path(value).write": "Path(tool.slug).write_bytes(b'x')\n return None",
448
+ "f-string": "return Path(f'{self._outdir}/{tool.slug}')",
449
+ "concat": "return Path(self._outdir + '/' + tool.slug)",
450
+ "local-uppercase": "SLUG = tool.slug\n return self._outdir / SLUG",
451
+ "open-direct": "return open(tool.slug, 'rb')",
452
+ "open-fstring": "return open(f'{self._outdir}/{tool.slug}', 'rb')",
453
+ "mkdir-direct": "return os.mkdir(tool.slug)",
454
+ "makedirs-concat": "return os.makedirs(self._outdir + tool.slug)",
455
+}
456
+
457
+
458
+@pytest.mark.parametrize("label", sorted(EVASIONS))
459
+def test_detector_catches_known_evasions(label, tmp_path):
460
+ """Each of these builds a path from untrusted input in a different
461
+ spelling. A detector that recognizes only the first stays green for the
462
+ rest, which is the whole reason this test is table-driven."""
463
+ pkg = tmp_path / "composio"
464
+ pkg.mkdir()
465
+ (pkg / "vulnerable.py").write_text(
466
+ "import os\nfrom pathlib import Path\n\n\n"
467
+ f"def f(self, tool):\n {EVASIONS[label]}\n"
468
+ )
469
+ found = _collect_joins([pkg])
470
+ assert found, f"detector missed evasion: {label}"
471
+
472
+
473
+def test_module_constant_exemption_requires_a_literal(tmp_path):
474
+ """A module-level ALL_CAPS name bound at runtime is not a constant."""
475
+ pkg = tmp_path / "composio"
476
+ pkg.mkdir()
477
+ (pkg / "vulnerable.py").write_text(
478
+ "import os\nfrom pathlib import Path\n\n"
479
+ "SAFE = 'literal'\n"
480
+ "SLUG = os.environ['SLUG']\n\n\n"
481
+ "def f(self):\n return self._outdir / SLUG\n"
482
+ )
483
+ assert _collect_joins([pkg]), "runtime-bound ALL_CAPS name was treated as constant"
484
+
485
+ (pkg / "vulnerable.py").write_text(
486
+ "from pathlib import Path\n\n"
487
+ "SAFE = 'literal'\n\n\n"
488
+ "def f(self):\n return self._outdir / SAFE\n"
489
+ )
490
+ assert not _collect_joins([pkg]), "literal module constant should be exempt"
491
+
492
+
493
+def test_scan_roots_are_pinned():
494
+ """Narrowing the scan silently shrinks the guarantee, so the roots are
495
+ asserted rather than assumed."""
496
+ assert {p.name for p in SCANNED_ROOTS} == {"composio", "providers"}
497
+ for root in SCANNED_ROOTS:
498
+ assert root.is_dir(), f"scanned root missing: {root}"