@devries-cameron20 / composio Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 03:37 UTC

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