@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
mdx 143 lines 6.11 KB
Raw
1 ---
2 title: 'SDK file upload hardening: sensitive path blocking and upload hooks'
3 description: 'TypeScript and Python SDKs now block automatic uploads from common credential locations by default, support extra denylist segments, and offer a before-upload hook. New error types when a path is blocked or a hook aborts the upload.'
4 date: '2026-04-23'
5 ---
6
7 The Composio SDKs add defense-in-depth for **automatic file uploads** (when a tool input is marked `file_uploadable` and the SDK reads a local path and sends the file to Composio storage). The goal is to reduce the risk of agent or app code accidentally exfiltrating secrets, SSH keys, or project env files that sit under well-known paths on disk.
8
9 **URLs and `File` objects are not subject to the path-based denylist** in the same way as string paths; the checks apply to resolved local filesystem paths used for auto-upload and the programmatic upload helpers that accept paths.
10
11 ### SDK versions
12
13 | SDK | Version (includes this behavior) |
14 | ---------- | --------------------------------- |
15 | TypeScript | `@composio/core` v0.6.11 or later |
16 | Python | `composio` v0.11.6 or later |
17
18 ### What changed
19
20 - **Default sensitive path protection** — Before reading and uploading, the SDK checks the resolved local path against a built-in list of path segments (for example `.ssh`, `.aws`, `.claude`, `.kube`) and file-name patterns (for example `.env`, default SSH private key names, `credentials`). If the path matches, the upload is refused unless you change configuration.
21 - **Extra denylist segments** — You can add path component names to merge with the built-in list (for example a proprietary secrets directory name).
22 - **`beforeFileUpload` / `before_file_upload` hook** — Optional hook for each file upload: return a different path, return `false` to abort, or throw. TypeScript: pass `beforeFileUpload` on the third argument to `tools.execute`. Python: use [`@before_file_upload`](/reference/sdk-reference/python/index#before_file_upload) in the `modifiers` list (same as other Python modifiers), not a separate keyword. Use this to enforce app-specific policies, audit logging, or copy-on-write to a safe temp file before upload. See [Before file upload (Python)](/docs/tools-direct/modify-tool-behavior/before-execution-modifiers#before-file-upload-python).
23 - **New errors** — `ComposioSensitiveFilePathBlockedError` / `SensitiveFilePathBlockedError` when a path is blocked, and `ComposioFileUploadAbortedError` / `FileUploadAbortedError` when the hook returns `false` or a hook throws in an aborting way.
24 - **Python: modifier order** — `substitute_file_uploads` runs before `before_execute` modifiers, matching TypeScript behavior (including Tool Router `execute_meta`).
25
26 ### Examples
27
28 #### Configure the client (defaults + extra denylist segments)
29
30 Keep the built-in blocklist enabled and add path **component** names (anywhere in the resolved path) that your app treats as secret:
31
32 <Tabs groupId="language" items={['TypeScript', 'Python']} persist>
33 <Tab value="TypeScript">
34 ```typescript
35 // @noErrors
36 import { Composio } from '@composio/core';
37
38 const composio = new Composio({
39 apiKey: process.env.COMPOSIO_API_KEY!,
40 sensitiveFileUploadProtection: true,
41 fileUploadPathDenySegments: ['company-secrets', 'private-keys'],
42 });
43 ```
44 </Tab>
45 <Tab value="Python">
46 ```python
47 from composio import Composio
48
49 composio = Composio(
50 api_key="your_composio_key",
51 sensitive_file_upload_protection=True,
52 file_upload_path_deny_segments=("company-secrets", "private-keys"),
53 )
54 ```
55 </Tab>
56 </Tabs>
57
58 #### Run a hook before each automatic file read
59
60 Return a new path, return `false` / `False` to abort, or throw. TypeScript passes `beforeFileUpload` in the **third** argument to `tools.execute`. In Python, use [`@before_file_upload`](/reference/sdk-reference/python/index#before_file_upload) in `modifiers`:
61
62 <Tabs groupId="language" items={['TypeScript', 'Python']} persist>
63 <Tab value="TypeScript">
64 ```typescript
65 // @noErrors
66 import { Composio, type beforeFileUploadModifier } from '@composio/core';
67 import path from 'node:path';
68
69 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY! });
70
71 const beforeFileUpload: beforeFileUploadModifier = async ctx => {
72 // e.g. log, rewrite path, or return false to block
73 return ctx.path;
74 };
75
76 await composio.tools.execute(
77 'GOOGLEDRIVE_UPLOAD_FILE',
78 {
79 userId: 'user-123',
80 arguments: { file_to_upload: path.join(__dirname, 'document.pdf') },
81 dangerouslySkipVersionCheck: true,
82 },
83 { beforeFileUpload },
84 );
85 ```
86 </Tab>
87 <Tab value="Python">
88 ```python
89 import os
90
91 from composio import Composio, before_file_upload
92
93
94 @before_file_upload(tools=["GOOGLEDRIVE_UPLOAD_FILE"])
95 def before_upload(path: str, tool: str, toolkit: str) -> "str | bool":
96 return path
97
98
99 composio = Composio()
100
101 composio.tools.execute(
102 "GOOGLEDRIVE_UPLOAD_FILE",
103 {"file_to_upload": os.path.join(os.getcwd(), "document.pdf")},
104 user_id="user-123",
105 modifiers=[before_upload],
106 )
107 ```
108 </Tab>
109 </Tabs>
110
111 ### Opting out
112
113 Set **`sensitiveFileUploadProtection: false`** (TypeScript) or **`sensitive_file_upload_protection=False`** (Python) only if you have a clear reason and accept the security tradeoff. Prefer copying files to a non-sensitive path or using the hook to gate uploads.
114
115 <Tabs groupId="language" items={['TypeScript', 'Python']} persist>
116 <Tab value="TypeScript">
117 ```typescript
118 // @noErrors
119 import { Composio } from '@composio/core';
120
121 const composio = new Composio({
122 apiKey: process.env.COMPOSIO_API_KEY!,
123 sensitiveFileUploadProtection: false,
124 });
125 ```
126 </Tab>
127 <Tab value="Python">
128 ```python
129 from composio import Composio
130
131 composio = Composio(
132 api_key="your_composio_key",
133 sensitive_file_upload_protection=False,
134 )
135 ```
136 </Tab>
137 </Tabs>
138
139 ### Where to read more
140
141 - [Executing tools: automatic file handling and security options](/docs/tools-direct/executing-tools#security-for-local-file-paths) — configuration and code patterns.
142 - [TypeScript `Composio` client](/reference/sdk-reference/typescript/composio#file-upload-security) — related constructor options in the reference.
143 - TypeScript SDK (repository): `ts/docs/advanced/auto-upload-download.md` — extended guide with error types and edge cases.