Skip to content

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

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.py
index 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 annotations
diff --git a/python/composio/core/models/custom_tools.py b/python/composio/core/models/custom_tools.py
index 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 functools
import 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.py
index 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] = tool
tools.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"],
+ )