Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(python-sdk): address SEC-365 review — loud failure + allowlist sanitization
Zen Agent908aad7e1e40
diff --git a/python/composio/core/models/custom_tool_execution.py b/python/composio/core/models/custom_tool_execution.pyindex 3454ae5db..6df6bd74e 100644--- a/python/composio/core/models/custom_tool_execution.py+++ b/python/composio/core/models/custom_tool_execution.py@@ -1,6 +1,14 @@"""Standalone functions for custom tool lookup and execution.Extracted for reuse in SessionContextImpl (sibling routing).++Security invariant (CWE-639 / SEC-365): on this code path the trusted+``user_id`` arrives via ``SessionContext`` — never via ``arguments``. The+``arguments`` dict is LLM-supplied and is validated through the tool's+Pydantic ``input_params`` model, which discards unknown fields, so an+attempt to smuggle ``user_id`` (or any other identity-bearing key) inside+``arguments`` cannot reach the tool's execute function or auth lookup.+Keep this property when modifying ``execute_custom_tool``."""from __future__ import annotationsdiff --git a/python/composio/core/models/custom_tools.py b/python/composio/core/models/custom_tools.pyindex 7a8875b0e..92d7b2d2d 100644--- a/python/composio/core/models/custom_tools.py+++ b/python/composio/core/models/custom_tools.py@@ -1,4 +1,30 @@-"""Custom Tools module"""+"""Custom Tools module.++Security model — SEC-365 / CWE-639 (cross-tenant credential access)+-------------------------------------------------------------------++Custom tools execute against the caller's OAuth credentials, looked up by+``user_id``. The LLM supplies the *request* arguments for a tool call; the+SDK supplies the ``user_id``. These two inputs MUST stay structurally+separate — if they ever collapse into one ``**kwargs`` dict, an LLM (or a+prompt-injection input) can set ``user_id`` and have us load another+tenant's tokens.++The trust boundary is ``CustomTools.execute(slug, request, user_id)``:++ * ``request`` is treated as untrusted and is filtered through an+ *allowlist* of fields declared on the tool's Pydantic ``request_model``,+ so today's ``user_id`` smuggling — and any future identity-bearing key+ that might be added to the auth path (``tenant_id``, ``org_id``, …) —+ is dropped before it can reach credential lookup.+ * ``user_id`` is forwarded to ``CustomTool.invoke_trusted(user_id, request_kwargs)``+ as a structurally separate parameter.++``CustomTool.__call__`` (the public ``tool(**kwargs)`` shorthand) raises+``TypeError`` if ``user_id`` appears in ``kwargs`` — refusing the smuggled+key loudly rather than silently using a fallback that could collide with a+real tenant.+"""import functoolsimport inspect@@ -133,29 +159,29 @@ class CustomTool:def __call__(self, **kwargs: t.Any) -> t.Any:"""Call the custom tool with the default ``user_id``.- ``kwargs`` is treated as untrusted LLM-supplied input. ``user_id`` is- therefore NOT extracted from ``kwargs``: allowing an LLM (or- prompt-injection input) to pick which tenant's ``user_id`` is used to- look up OAuth credentials would let it read another tenant's tokens- (CWE-639, see SEC-365). Any ``user_id`` key in ``kwargs`` is dropped- before the request body is validated.-- To use a non-default ``user_id``, call through- ``CustomTools.execute(slug, request, user_id)`` (the canonical entry- point), which sanitizes the request dict and supplies the trusted- ``user_id`` from server-side context.+ Refuses ``user_id`` in ``kwargs`` with ``TypeError`` rather than+ silently dropping it — see the module docstring for why. Use+ ``CustomTools.execute(slug, request, user_id=...)`` (the trusted+ entry point) when you need a non-default ``user_id``."""- kwargs.pop("user_id", None)- return self._invoke(user_id="default", request_kwargs=kwargs)-- def _invoke(self, user_id: str, request_kwargs: t.Dict[str, t.Any]) -> t.Any:- """Trusted internal entry point.+ if "user_id" in kwargs:+ raise TypeError(+ "CustomTool.__call__ does not accept user_id; "+ "use CustomTools.execute(slug, request, user_id=...) instead."+ )+ return self.invoke_trusted(user_id="default", request_kwargs=kwargs)- Called by ``CustomTools.execute`` after ``request_kwargs`` has been- sanitized at the LLM trust boundary. ``user_id`` is supplied here as- a positional / keyword argument that is structurally separate from- the ``request_kwargs`` dict, so an LLM-controlled key inside the- dict cannot be promoted to override the trusted value.+ def invoke_trusted(+ self,+ user_id: str,+ request_kwargs: t.Dict[str, t.Any],+ ) -> t.Any:+ """Trusted entry point used by ``CustomTools.execute``.++ ``user_id`` is taken as a structurally separate parameter, so an+ LLM-controlled ``user_id`` key sitting inside ``request_kwargs``+ cannot override it (the request model's default ``extra='ignore'``+ means any such key is also dropped during validation)."""request = self.request_model.model_validate(request_kwargs)if self.toolkit is None:@@ -168,6 +194,16 @@ class CustomTool:)+def _allowed_request_field_names(request_model: t.Type[BaseModel]) -> t.Set[str]:+ """Names accepted by ``request_model`` (canonical name + alias)."""+ allowed: t.Set[str] = set()+ for field_name, field_info in request_model.model_fields.items():+ allowed.add(field_name)+ if field_info.alias is not None:+ allowed.add(field_info.alias)+ return allowed++class CustomTools:"""CustomTools class@@ -226,22 +262,23 @@ class CustomTools:slug: str,request: t.Dict,user_id: t.Optional[str] = None,- ) -> t.Dict:- """Execute a custom tool.-- ``request`` is the LLM-supplied argument dict and is treated as- untrusted: any ``user_id`` key it contains is stripped here so that- only the explicit ``user_id`` parameter (sourced from trusted- server-side context) is used to look up auth credentials. Without- this sanitization an LLM (or prompt-injection input) could specify- another tenant's ``user_id`` and read their OAuth tokens- (CWE-639, see SEC-365).+ ) -> t.Any:+ """Execute a custom tool — the trust boundary for LLM-supplied args.++ ``request`` is filtered through an allowlist of fields declared on+ the tool's Pydantic ``request_model`` (canonical names + aliases).+ Anything else — including the historical ``user_id`` smuggling+ vector and any future identity-bearing keys — is dropped before+ the call reaches credential lookup. ``user_id`` is forwarded as a+ structurally separate parameter; see the module docstring for the+ full security model."""custom_tool = self.get(slug)if custom_tool is None:raise NotFoundError(f"Custom tool with slug {slug} not found")- sanitized_request = {k: v for k, v in request.items() if k != "user_id"}- return custom_tool._invoke(+ allowed = _allowed_request_field_names(custom_tool.request_model)+ sanitized_request = {k: v for k, v in request.items() if k in allowed}+ return custom_tool.invoke_trusted(user_id=user_id or "default",request_kwargs=sanitized_request,)diff --git a/python/tests/test_custom_tools_security.py b/python/tests/test_custom_tools_security.pyindex 03ed4f379..80584206f 100644--- a/python/tests/test_custom_tools_security.py+++ b/python/tests/test_custom_tools_security.py@@ -6,18 +6,20 @@ Before the fix, ``CustomTool.__call__`` extracted ``user_id`` from the same``**kwargs`` dict that carried LLM-supplied tool arguments, and``CustomTools.execute`` happily forwarded that LLM-controlled dict via``custom_tool(**request, user_id=user_id)``. An LLM (or prompt-injection-input) could therefore set ``user_id`` to another tenant's identifier —-either getting it forwarded into ``CustomTool.__call__`` directly or-relying on Python's duplicate-kwarg ``TypeError`` to leak whose tokens-were nearly looked up.--The fix:- * ``CustomTools.execute`` strips ``user_id`` from the LLM-supplied- ``request`` dict at the trust boundary, so only the trusted, explicit- ``user_id`` parameter reaches the credential lookup.- * ``CustomTool.__call__`` exposes ``user_id`` as a keyword-only- parameter and drops any ``user_id`` left in ``kwargs`` before the- request body is validated.+input) could therefore set ``user_id`` to another tenant's identifier and+have ``CustomTool.__get_auth_credentials`` look up that victim's OAuth+tokens.++After the fix:+ * ``CustomTools.execute`` filters the LLM-supplied ``request`` through+ an *allowlist* of fields declared on the tool's Pydantic+ ``request_model`` — ``user_id`` and any other unexpected key are+ dropped before they can influence credential lookup or reach the+ tool's execute function.+ * ``CustomTool.invoke_trusted`` is the structurally separate trusted+ entry point; ``user_id`` cannot be smuggled inside ``request_kwargs``.+ * ``CustomTool.__call__`` raises ``TypeError`` if ``user_id`` appears+ in ``kwargs`` rather than silently using a fallback."""from unittest.mock import MagicMock@@ -33,9 +35,9 @@ class _IssueInput(BaseModel):issue_number: int = Field(description="GitHub issue number")-def _make_mock_client() -> MagicMock:- """Build a mock HttpClient suitable for CustomTool.__get_auth_credentials."""-+def mock_http_client() -> MagicMock:+ """Mock HttpClient that returns a single connected account on lookup."""state = MagicMock()state.val.model_dump.return_value = {"access_token": "trusted-token"}@@ -52,144 +54,221 @@ def _make_mock_client() -> MagicMock:return client-def test_execute_strips_user_id_from_llm_request() -> None:- """``CustomTools.execute`` MUST strip ``user_id`` from the request dict."""- client = _make_mock_client()- tools = CustomTools(client=client)+def github_tool(mock_http_client: MagicMock) -> CustomTool:+ """A registered ``github`` custom tool whose handler echoes the auth token."""def github_tool(request: _IssueInput, execute_request, auth_credentials):"""Fetch issue info."""- return {"token": auth_credentials["access_token"]}+ return {+ "issue_number": request.issue_number,+ "token": auth_credentials["access_token"],+ }++ return CustomTool(f=github_tool, client=mock_http_client, toolkit="github")+- tools.register(toolkit="github")(github_tool)+def custom_tools(mock_http_client: MagicMock, github_tool: CustomTool) -> CustomTools:+ """A ``CustomTools`` registry pre-loaded with ``github_tool``."""+ tools = CustomTools(client=mock_http_client)+ tools.custom_tools_registry[github_tool.slug] = github_tool+ return tools- result = tools.execute(- slug="GITHUB_GITHUB_TOOL",++def test_execute_strips_user_id_from_llm_request(+ mock_http_client: MagicMock, custom_tools: CustomTools, github_tool: CustomTool+) -> None:+ """``CustomTools.execute`` MUST drop ``user_id`` from the request dict."""+ result = custom_tools.execute(+ slug=github_tool.slug,request={"issue_number": 1, "user_id": "victim-user"},user_id="trusted-user",)- assert result == {"token": "trusted-token"}- # Only the trusted, explicit user_id reaches the credential lookup.- client.connected_accounts.list.assert_called_once_with(+ assert result == {"issue_number": 1, "token": "trusted-token"}+ mock_http_client.connected_accounts.list.assert_called_once_with(toolkit_slugs=["github"],user_ids=["trusted-user"],)-def test_execute_falls_back_to_default_when_user_id_missing() -> None:- """If the caller forgets a trusted ``user_id``, fall back to ``"default"``.+def test_execute_strips_unexpected_fields_via_allowlist(+ mock_http_client: MagicMock, custom_tools: CustomTools, github_tool: CustomTool+) -> None:+ """The allowlist is durable: any non-declared key is dropped, not just user_id.- Specifically, ``execute`` must NOT silently use the LLM-supplied- ``user_id`` from ``request`` as a fallback — that would re-introduce- the SEC-365 vulnerability under a different code path.+ Pins the allowlist behaviour so a future identity-bearing key in the+ auth path (``tenant_id``, ``org_id``, ``connected_account_id``, …)+ cannot re-introduce CWE-639 by being smuggled through ``request``."""- client = _make_mock_client()- tools = CustomTools(client=client)+ captured: dict = {}- def github_tool(request: _IssueInput, execute_request, auth_credentials):- """Fetch issue info."""+ def echo_tool(request: _IssueInput, execute_request, auth_credentials):+ """Echo back the validated request."""+ captured["fields"] = request.model_dump()return {"ok": True}- tools.register(toolkit="github")(github_tool)+ tools = CustomTools(client=mock_http_client)+ tool = CustomTool(f=echo_tool, client=mock_http_client, toolkit="github")+ tools.custom_tools_registry[tool.slug] = tooltools.execute(- slug="GITHUB_GITHUB_TOOL",- request={"issue_number": 1, "user_id": "victim-user"},- user_id=None,+ slug=tool.slug,+ request={+ "issue_number": 1,+ "user_id": "victim-user",+ "tenant_id": "evil-tenant",+ "connected_account_id": "ca_evil",+ "extra_garbage": "xyz",+ },+ user_id="trusted-user",)- client.connected_accounts.list.assert_called_once_with(+ assert captured["fields"] == {"issue_number": 1}+ mock_http_client.connected_accounts.list.assert_called_once_with(toolkit_slugs=["github"],- user_ids=["default"],+ user_ids=["trusted-user"],)-def test_execute_does_not_mutate_caller_request_dict() -> None:- """Sanitization MUST NOT mutate the caller's ``request`` dict in place."""- client = _make_mock_client()- tools = CustomTools(client=client)+def test_execute_keeps_aliases_declared_on_request_model(+ mock_http_client: MagicMock,+) -> None:+ """Aliases declared on the request model are honoured by the allowlist."""- def github_tool(request: _IssueInput, execute_request, auth_credentials):- """Fetch issue info."""+ class _AliasedInput(BaseModel):+ issue_number: int = Field(alias="issueNumber")++ captured: dict = {}++ def aliased_tool(request: _AliasedInput, execute_request, auth_credentials):+ """Echo back the validated request."""+ captured["fields"] = request.model_dump()return {"ok": True}- tools.register(toolkit="github")(github_tool)+ tools = CustomTools(client=mock_http_client)+ tool = CustomTool(f=aliased_tool, client=mock_http_client, toolkit="github")+ tools.custom_tools_registry[tool.slug] = tool- request_dict = {"issue_number": 1, "user_id": "victim-user"}tools.execute(- slug="GITHUB_GITHUB_TOOL",- request=request_dict,+ slug=tool.slug,+ request={"issueNumber": 5, "user_id": "victim"},user_id="trusted-user",)- # The original dict is untouched (the SDK should not surprise the caller).- assert request_dict == {"issue_number": 1, "user_id": "victim-user"}+ assert captured["fields"] == {"issue_number": 5}-def test_call_drops_user_id_smuggled_in_kwargs_dict() -> None:- """``CustomTool.__call__`` MUST ignore any ``user_id`` smuggled in kwargs.+def test_execute_falls_back_to_default_when_user_id_missing(+ mock_http_client: MagicMock, custom_tools: CustomTools, github_tool: CustomTool+) -> None:+ """If no trusted ``user_id`` is provided, ``execute`` MUST use ``"default"``.- A caller might unpack a partially-trusted dict like ``tool(**llm_dict)``- without realizing that the LLM controls every key in it. Before the fix,- a ``user_id`` key in that dict was popped and used to look up OAuth- credentials — letting an LLM read another tenant's tokens. After the fix,- ``__call__`` always uses the safe ``"default"`` user_id and the smuggled- value is dropped before request validation.+ Specifically, ``execute`` MUST NOT silently use the LLM-supplied+ ``user_id`` from ``request`` as a fallback — that would re-introduce+ SEC-365 under a different code path."""- client = _make_mock_client()-- def github_tool(request: _IssueInput, execute_request, auth_credentials):- """Fetch issue info."""- return {"ok": True}-- tool = CustomTool(f=github_tool, client=client, toolkit="github")-- smuggled_kwargs = {"issue_number": 1, "user_id": "victim-user"}- tool(**smuggled_kwargs)+ custom_tools.execute(+ slug=github_tool.slug,+ request={"issue_number": 1, "user_id": "victim-user"},+ user_id=None,+ )- client.connected_accounts.list.assert_called_once_with(+ mock_http_client.connected_accounts.list.assert_called_once_with(toolkit_slugs=["github"],user_ids=["default"],)-def test_invoke_uses_trusted_user_id_separate_from_request() -> None:- """``_invoke`` takes ``user_id`` separately from the request dict.+def test_execute_does_not_mutate_caller_request_dict(+ custom_tools: CustomTools, github_tool: CustomTool+) -> None:+ """Sanitization MUST NOT mutate the caller's ``request`` dict in place."""+ request_dict = {"issue_number": 1, "user_id": "victim-user"}+ custom_tools.execute(+ slug=github_tool.slug,+ request=request_dict,+ user_id="trusted-user",+ )++ assert request_dict == {"issue_number": 1, "user_id": "victim-user"}+- This is the trusted internal entry point used by ``CustomTools.execute``.- Even if the LLM-controlled ``request_kwargs`` happens to contain a- ``user_id`` key (and somehow gets past the sanitization in ``execute``),- the ``user_id`` argument here is structurally separate, so the trusted- value is what reaches the credential lookup.+def test_call_raises_typeerror_when_user_id_smuggled_in_kwargs(+ github_tool: CustomTool,+) -> None:+ """``CustomTool.__call__`` MUST refuse a ``user_id`` kwarg loudly.++ Silent fallbacks expand blast radius: a tool that quietly transacts+ against ``"default"`` could end up using a real tenant who happens to+ be registered under that id. Failing fast also surfaces prompt-injection+ attempts instead of swallowing them."""- client = _make_mock_client()+ smuggled_kwargs = {"issue_number": 1, "user_id": "victim-user"}- captured: dict = {}+ with pytest.raises(TypeError, match="user_id"):+ github_tool(**smuggled_kwargs)- def github_tool(request: _IssueInput, execute_request, auth_credentials):- """Fetch issue info."""- captured["request"] = request- return {"ok": True}- tool = CustomTool(f=github_tool, client=client, toolkit="github")- tool._invoke(user_id="trusted-user", request_kwargs={"issue_number": 7})+def test_invoke_trusted_uses_explicit_user_id_over_smuggled_one(+ mock_http_client: MagicMock, github_tool: CustomTool+) -> None:+ """``invoke_trusted``'s explicit ``user_id`` MUST win over a smuggled key.++ The auth-path argument is structurally separate from ``request_kwargs``,+ so an LLM-controlled ``user_id`` inside ``request_kwargs`` cannot+ override the trusted parameter. This pins the docstring contract.+ """+ github_tool.invoke_trusted(+ user_id="trusted-user",+ request_kwargs={"issue_number": 7, "user_id": "victim-user"},+ )- client.connected_accounts.list.assert_called_once_with(+ mock_http_client.connected_accounts.list.assert_called_once_with(toolkit_slugs=["github"],user_ids=["trusted-user"],)- assert captured["request"].issue_number == 7-def test_execute_unknown_slug_raises() -> None:+def test_execute_unknown_slug_raises(custom_tools: CustomTools) -> None:"""Sanity check: unknown slugs still surface ``NotFoundError``."""- client = _make_mock_client()- tools = CustomTools(client=client)-with pytest.raises(NotFoundError):- tools.execute(+ custom_tools.execute(slug="DOES_NOT_EXIST",request={"foo": "bar"},user_id="trusted-user",)+++def test_tools_execute_e2e_strips_user_id_through_full_stack(+ mock_http_client: MagicMock, custom_tools: CustomTools, github_tool: CustomTool+) -> None:+ """End-to-end check through ``Tools.execute`` (the public SDK entry point).++ ``Tools._execute_tool`` routes custom-tool calls into+ ``CustomTools.execute``. The modifier-hook block can also overwrite+ ``arguments`` and ``user_id`` from a ``processed_params`` dict, so we+ pin that the sanitization still applies after that path.+ """+ from composio.core.models.tools import Tools++ provider = MagicMock()+ provider.name = "test"++ tools = Tools(client=mock_http_client, provider=provider)+ tools._custom_tools = custom_tools++ response = tools.execute(+ slug=github_tool.slug,+ arguments={"issue_number": 1, "user_id": "victim-user"},+ user_id="trusted-user",+ )++ assert response["successful"] is True+ assert response["data"]["issue_number"] == 1+ assert response["data"]["token"] == "trusted-token"+ mock_http_client.connected_accounts.list.assert_called_once_with(+ toolkit_slugs=["github"],+ user_ids=["trusted-user"],+ )