Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | ) |