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 214 lines 7.84 KB
Raw
1 """Allowlist enforcement for automatic file upload during tool execution.
2
3 This is only consulted when
4 ``dangerously_allow_auto_upload_download_files=True``. Manual upload APIs are
5 not subject to the allowlist (parity with the TypeScript SDK).
6
7 - A local path is accepted iff its symlink-resolved absolute path is inside one
8 of the allowed directories on a path-component boundary. ``/tmp/foo`` allows
9 ``/tmp/foo/bar`` but NOT ``/tmp/foo-bar``.
10 - URLs never hit this check.
11 - User-provided ``file_upload_dirs`` fully REPLACES the default
12 ``[~/.composio/temp]``.
13 - On Windows, path comparisons are case-insensitive.
14 """
15
16 from __future__ import annotations
17
18 import os
19 import sys
20 import typing as t
21 from pathlib import Path
22
23 from composio.exceptions import (
24 FileUploadPathNotAllowedError,
25 SDKFileNotFoundError,
26 )
27 from composio.utils.safe_path import is_inside_dir, resolve_root
28
29 UPLOAD_TEMP_DIRECTORY_NAME = "temp"
30
31
32 def get_default_upload_dir() -> t.Optional[Path]:
33 """Absolute path of the default upload staging directory
34 (``<home>/.composio/temp``), or None when a home directory cannot be
35 determined."""
36 try:
37 home = Path.home()
38 except (RuntimeError, OSError):
39 return None
40 return (home / ".composio" / UPLOAD_TEMP_DIRECTORY_NAME).resolve()
41
42
43 def ensure_dir_exists(p: Path) -> None:
44 """Best-effort directory creation. Allowlist enforcement still works if
45 creation fails (e.g. read-only filesystem)."""
46 try:
47 p.mkdir(parents=True, exist_ok=True)
48 except OSError:
49 pass
50
51
52 FileUploadDirs = t.Union[t.Sequence[str], t.Literal[False], None]
53 """User-facing type for ``file_upload_dirs``.
54
55 - ``None`` (default) -> use ``[<home>/.composio/temp]``.
56 - ``False`` -> reject every local path during auto-upload (URLs / bytes still
57 work).
58 - ``[]`` -> same as ``False`` (kept as an alias; prefer ``False``).
59 - ``Sequence[str]`` (non-empty) -> allowlist replacing the default.
60 """
61
62
63 def resolve_effective_upload_allowlist(
64 user_dirs: FileUploadDirs,
65 ) -> t.List[Path]:
66 """Resolve the effective allowlist.
67
68 - ``None`` -> ``[<default>]`` when available, else ``[]`` (fail-closed).
69 - ``False`` -> ``[]`` (explicit "reject all local paths"). URLs and
70 in-memory bytes still work because they aren't path-checked.
71 - ``Sequence[str]`` (including ``[]``) REPLACES the default and is returned
72 verbatim after ``~``-expansion and ``resolve()``. ``[]`` is treated as
73 equivalent to ``False``.
74 - Empty / blank / non-string entries are skipped.
75 - Duplicates are removed (case-insensitive on Windows).
76 """
77 if user_dirs is None:
78 default = get_default_upload_dir()
79 return [default] if default is not None else []
80 if user_dirs is False:
81 return []
82
83 seen: t.Set[str] = set()
84 out: t.List[Path] = []
85 for raw in user_dirs:
86 if not isinstance(raw, (str, os.PathLike)):
87 continue
88 s = str(raw).strip()
89 if not s:
90 continue
91 abs_path = Path(s).expanduser().resolve()
92 key = str(abs_path).lower() if sys.platform == "win32" else str(abs_path)
93 if key in seen:
94 continue
95 seen.add(key)
96 out.append(abs_path)
97 return out
98
99
100 def _format_allowlist(dirs: t.Sequence[Path]) -> str:
101 if not dirs:
102 return " (none configured — all local paths are blocked)"
103 return "\n".join(f" - {d}" for d in dirs)
104
105
106 def _build_help_footer(allowlist: t.Sequence[Path]) -> str:
107 return "\n".join(
108 [
109 "",
110 "Allowed upload directories (file_upload_dirs):",
111 _format_allowlist(allowlist),
112 "",
113 "Fix one of the following:",
114 "",
115 " 1. Recommended — move the file under an allowed directory, or add your",
116 " directory to the allowlist:",
117 " Composio(",
118 " file_upload_dirs=['/abs/path/to/uploads', '~/.composio/temp'],",
119 " )",
120 " Note: user-provided `file_upload_dirs` REPLACES the default",
121 " `~/.composio/temp`. Include it explicitly if you want staged uploads",
122 " to keep working.",
123 "",
124 " 2. Pass the file by URL (http://... / https://...) instead of a",
125 " filesystem path. URLs are never path-checked.",
126 "",
127 " 3. (Dangerous) Bypass the allowlist entirely by opting into automatic",
128 " file upload/download from any readable path:",
129 " Composio(dangerously_allow_auto_upload_download_files=True, ...)",
130 " WARNING: This lets a prompt-injected or misbehaving tool read ANY",
131 " file the process can access. Only enable it in trusted, sandboxed",
132 " environments. The built-in sensitive-path denylist (.ssh, .aws,",
133 " .env, private SSH keys, etc.) still applies unless you also set",
134 " `sensitive_file_upload_protection=False`.",
135 ]
136 )
137
138
139 def assert_path_inside_upload_dirs(
140 file_path: t.Union[str, Path],
141 allowlist: t.Sequence[Path],
142 ) -> None:
143 """Raise an elaborate error if the path is missing or outside the allowlist.
144
145 :raises SDKFileNotFoundError: when ``file_path`` does not exist on disk.
146 :raises FileUploadPathNotAllowedError: when resolved path is outside every
147 entry of ``allowlist`` (including when allowlist is empty).
148 """
149 attempted = str(file_path)
150 abs_path = resolve_root(attempted)
151
152 if not abs_path.exists():
153 cwd = Path.cwd()
154 parent = abs_path.parent
155 parent_exists = parent.exists()
156 raise SDKFileNotFoundError(
157 "\n".join(
158 [
159 f'Refusing to auto-upload "{attempted}": the file does not exist on disk.',
160 "",
161 f"Path attempted: {attempted}",
162 f"Resolved to: {abs_path}",
163 f"Process cwd: {cwd}",
164 f"Parent exists: {'yes (' + str(parent) + ')' if parent_exists else 'no (' + str(parent) + ')'}",
165 "",
166 "Common causes:",
167 " - Typo in the filename passed to the tool.",
168 " - Relative path resolved against the wrong working directory",
169 " (relative paths use os.getcwd() at the moment of upload).",
170 " - File was deleted between the tool being called and the upload starting.",
171 "",
172 _build_help_footer(allowlist),
173 ]
174 )
175 )
176
177 try:
178 real_path = abs_path.resolve(strict=True)
179 except OSError:
180 real_path = abs_path
181
182 if not allowlist:
183 raise FileUploadPathNotAllowedError(
184 "\n".join(
185 [
186 f'Refusing to auto-upload "{attempted}": no upload directories are configured.',
187 "",
188 f"Path attempted: {attempted}",
189 f"Resolved to: {real_path}",
190 "",
191 "Automatic file upload during tool execution is locked down by default",
192 "to prevent a prompt-injected tool from exfiltrating server files",
193 "(source code, .env, SSH keys, etc.).",
194 _build_help_footer(allowlist),
195 ]
196 )
197 )
198
199 for dir_entry in allowlist:
200 if is_inside_dir(real_path, resolve_root(dir_entry)):
201 return
202
203 raise FileUploadPathNotAllowedError(
204 "\n".join(
205 [
206 f'Refusing to auto-upload "{attempted}": resolved path is not inside any',
207 "directory in the configured `file_upload_dirs` allowlist.",
208 "",
209 f"Path attempted: {attempted}",
210 f"Resolved to: {real_path}",
211 _build_help_footer(allowlist),
212 ]
213 )
214 )