Skip to content

Commit 57e8bc6

Browse files
prasanna8585copybara-github
authored andcommitted
fix: do not resolve Bigtable view parameters from session state
Merge #7132 View parameters are no longer resolved from tool_context.state to prevent caller or model tampering. Callers configuring custom view parameters can supply them via view_parameters on BigtableToolset or BigtableParameterizedViewTool (supporting a mapping or a per-invocation resolver callable). PiperOrigin-RevId: 1002437706
1 parent 772f139 commit 57e8bc6

2 files changed

Lines changed: 654 additions & 66 deletions

File tree

‎src/google/adk/tools/bigtable/bigtable_toolset.py‎

Lines changed: 202 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@
1414

1515
from __future__ import annotations
1616

17+
from collections.abc import Awaitable
18+
from collections.abc import Mapping
19+
from contextvars import ContextVar
1720
import inspect
1821
import logging
1922
from typing import Any
@@ -39,6 +42,22 @@
3942

4043
logger = logging.getLogger("google_adk." + __name__)
4144

45+
_view_param_error: ContextVar[list[Exception] | None] = ContextVar(
46+
"_view_param_error", default=None
47+
)
48+
49+
50+
def _validate_view_parameters(view_parameters: object) -> None:
51+
if (
52+
view_parameters is not None
53+
and not callable(view_parameters)
54+
and not isinstance(view_parameters, Mapping)
55+
):
56+
raise TypeError(
57+
"view_parameters must be a Mapping, callable, or None, got"
58+
f" {type(view_parameters).__name__}"
59+
)
60+
4261

4362
class _BigtableQueryTool(GoogleTool):
4463
"""Plain execute_sql tool that keeps _view_parameters away from the model."""
@@ -74,9 +93,10 @@ class BigtableParameterizedViewTool(GoogleTool):
7493
"""Wrapper FunctionTool for Bigtable execute_sql query tool that passes view parameters.
7594
7695
This tool wraps the Bigtable query tool to automatically resolve and inject
77-
parameters from the ToolContext (e.g. user_id) into the query's
78-
view_parameters. The parameter names to resolve are configured via
79-
view_parameter_names.
96+
parameters into the query's `view_parameters`. Top-level `ToolContext`
97+
attribute names (e.g. `user_id`) are configured via `view_parameter_names`,
98+
and static or per-invocation resolved parameter values (e.g. `tenant_id`) are
99+
configured via `view_parameters`.
80100
81101
Example:
82102
If a parameterized view `purchase_history_pv` was created with the query:
@@ -87,6 +107,29 @@ class BigtableParameterizedViewTool(GoogleTool):
87107
pass it as `view_parameters={"user_id": user_id}`.
88108
This securely restricts query execution to the logged-in user's data
89109
without exposing the `user_id` parameter to the LLM.
110+
111+
Only names that resolve to an attribute of `tool_context` itself (such as
112+
`user_id`) are honored by `view_parameter_names`. `tool_context.state` is
113+
not consulted: state is writable by the caller, so a name that fell back
114+
to state could be overridden to run the query in a different user's scope,
115+
defeating the view's own row-level restriction. Additional parameters such
116+
as `tenant_id` should be supplied via `view_parameters` from a trusted
117+
source that the caller and model cannot write (for example, a lookup keyed
118+
on `tool_context.user_id`), and never from `tool_context.state` or
119+
`tool_context.custom_metadata`:
120+
121+
- Mapping: `view_parameters={"tenant_id": "tenant-abc"}`
122+
- Mapping of callables:
123+
`view_parameters={"tenant_id": lambda ctx: get_tenant(ctx.user_id)}`
124+
- Callable receiving `ToolContext`:
125+
`view_parameters=lambda ctx: {"tenant_id": get_tenant(ctx.user_id)}`
126+
127+
Attributes:
128+
view_parameter_names: Parameter names to resolve from `tool_context`'s own
129+
attributes (not `tool_context.state`) and pass into `view_parameters`.
130+
view_parameters: Mapping of parameter values or per-value callables, or a
131+
callable receiving `ToolContext` that returns a mapping of trusted
132+
parameter values (or `None`) resolved per invocation.
90133
"""
91134

92135
def __init__(
@@ -96,6 +139,14 @@ def __init__(
96139
credentials_config: BigtableCredentialsConfig | None = None,
97140
tool_settings: BigtableToolSettings | None = None,
98141
view_parameter_names: list[str] | None = None,
142+
view_parameters: (
143+
Mapping[str, Any]
144+
| Callable[
145+
[ToolContext],
146+
Mapping[str, Any] | None | Awaitable[Mapping[str, Any] | None],
147+
]
148+
| None
149+
) = None,
99150
):
100151
"""Initializes the BigtableParameterizedViewTool.
101152
@@ -104,9 +155,26 @@ def __init__(
104155
credentials_config: The credentials configuration.
105156
tool_settings: The tool settings.
106157
view_parameter_names: A list of parameter names to resolve from
107-
tool_context and pass into view_parameters. This is configured on the
108-
toolset (BigtableToolset) and forwarded here.
158+
`tool_context`'s own attributes (such as `user_id`, not
159+
`tool_context.state`) and pass into `view_parameters`. This is
160+
configured on `BigtableToolset` and forwarded here.
161+
view_parameters: A mapping of parameter values, a mapping of per-value
162+
callables (sync or async), or a callable (sync or async) receiving
163+
`ToolContext` that returns a mapping of parameter values (such as
164+
`tenant_id`). Values must come from a source that the caller and model
165+
cannot write (e.g. a lookup keyed on `ctx.user_id`), and must never be
166+
read from `ctx.state` or `ctx.custom_metadata`. Keys from
167+
`view_parameters` take precedence over and overwrite keys resolved
168+
from `view_parameter_names` (including `user_id`). If a top-level
169+
callable returns `None`, no parameters from `view_parameters` are
170+
merged; any key whose value or per-value callable resolves to `None`
171+
is omitted (and removes any value resolved from
172+
`view_parameter_names`); if a top-level callable returns a
173+
non-mapping value, a `TypeError` is raised. Any exception raised by a
174+
resolver callable propagates to the caller and fails the tool
175+
invocation.
109176
"""
177+
_validate_view_parameters(view_parameters)
110178
super().__init__(
111179
func=func,
112180
credentials_config=credentials_config,
@@ -118,9 +186,80 @@ def __init__(
118186
" views to securely check permissions."
119187
)
120188
self.view_parameter_names = view_parameter_names
189+
self.view_parameters = view_parameters
121190
# Exclude from being parsed and exposed to the LLM when generating tool schemas
122191
self._ignore_params.append("_view_parameters")
123192

193+
async def _resolve_view_parameters(
194+
self, tool_context: ToolContext
195+
) -> dict[str, Any]:
196+
view_params: dict[str, Any] = {}
197+
for param_name in self.view_parameter_names or ():
198+
if (val := getattr(tool_context, param_name, None)) is not None:
199+
view_params[param_name] = val
200+
201+
if self.view_parameters is not None:
202+
if callable(self.view_parameters):
203+
resolved = self.view_parameters(tool_context)
204+
if inspect.isawaitable(resolved):
205+
resolved = await resolved
206+
if resolved is not None:
207+
if not isinstance(resolved, Mapping):
208+
raise TypeError(
209+
"view_parameters callable must return a Mapping or None,"
210+
f" got {type(resolved).__name__}"
211+
)
212+
for k, val in resolved.items():
213+
if val is not None:
214+
view_params[k] = val
215+
else:
216+
view_params.pop(k, None)
217+
elif isinstance(self.view_parameters, Mapping):
218+
for k, v in self.view_parameters.items():
219+
if callable(v):
220+
val = v(tool_context)
221+
if inspect.isawaitable(val):
222+
val = await val
223+
else:
224+
val = v
225+
if val is not None:
226+
view_params[k] = val
227+
else:
228+
view_params.pop(k, None)
229+
else:
230+
raise TypeError(
231+
"view_parameters must be a Mapping, callable, or None, got"
232+
f" {type(self.view_parameters).__name__}"
233+
)
234+
235+
for param_name in self.view_parameter_names or ():
236+
if (
237+
param_name not in view_params
238+
and tool_context.state
239+
and param_name in tool_context.state
240+
):
241+
logger.warning(
242+
"View parameter %r is no longer read from session state; pass"
243+
" it via view_parameters instead.",
244+
param_name,
245+
)
246+
247+
return view_params
248+
249+
@override
250+
async def run_async(
251+
self, *, args: dict[str, Any], tool_context: ToolContext
252+
) -> Any:
253+
error_holder: list[Exception] = []
254+
token = _view_param_error.set(error_holder)
255+
try:
256+
result = await super().run_async(args=args, tool_context=tool_context)
257+
finally:
258+
_view_param_error.reset(token)
259+
if error_holder:
260+
raise error_holder[0]
261+
return result
262+
124263
@override
125264
async def _run_async_with_credential(
126265
self,
@@ -130,18 +269,19 @@ async def _run_async_with_credential(
130269
tool_context: ToolContext,
131270
) -> Any:
132271
args_to_call = args.copy()
272+
args_to_call.pop("_view_parameters", None)
133273
signature = inspect.signature(self.func)
134-
if "_view_parameters" in signature.parameters and self.view_parameter_names:
135-
view_params = {}
136-
for param_name in self.view_parameter_names:
137-
# 1. Check if it's a strongly-typed top-level property (like 'user_id')
138-
if (val := getattr(tool_context, param_name, None)) is not None:
139-
view_params[param_name] = val
140-
# 2. Fallback to checking application-level session state
141-
elif tool_context.state and param_name in tool_context.state:
142-
view_params[param_name] = tool_context.state[param_name]
143-
144-
args_to_call["_view_parameters"] = view_params
274+
if "_view_parameters" in signature.parameters and (
275+
self.view_parameter_names or self.view_parameters is not None
276+
):
277+
try:
278+
args_to_call["_view_parameters"] = await self._resolve_view_parameters(
279+
tool_context
280+
)
281+
except Exception as ex:
282+
if (error_holder := _view_param_error.get()) is not None:
283+
error_holder.append(ex)
284+
raise
145285
return await super()._run_async_with_credential(
146286
credentials, tool_settings, args_to_call, tool_context
147287
)
@@ -163,9 +303,33 @@ class BigtableToolset(BaseToolset):
163303
- bigtable_get_cluster_info
164304
- bigtable_execute_sql
165305
166-
When view_parameter_names is configured, bigtable_execute_sql is replaced by
167-
bigtable_execute_sql_parameterized, which fills the view parameters in from
168-
the tool context.
306+
When view_parameter_names or view_parameters is configured,
307+
bigtable_execute_sql is replaced by bigtable_execute_sql_parameterized, which
308+
resolves view parameters from `tool_context`'s own attributes (such as
309+
`user_id`, never session state `tool_context.state`) and from
310+
`view_parameters`.
311+
312+
Attributes:
313+
view_parameter_names: Optional list of parameter names to resolve from
314+
`tool_context`'s own attributes (such as `user_id`, not
315+
`tool_context.state`) and pass into `view_parameters` for parameterized
316+
views.
317+
view_parameters: Optional mapping of parameter values, mapping of per-value
318+
callables (sync or async), or a callable (sync or async) receiving
319+
`ToolContext` that returns a mapping of trusted parameter values (such as
320+
`tenant_id`, or `None`) resolved per invocation for parameterized views:
321+
- Mapping: `view_parameters={"tenant_id": "tenant-abc"}`
322+
- Mapping of callables:
323+
`view_parameters={"tenant_id": lambda ctx: get_tenant(ctx.user_id)}`
324+
- Callable receiving `ToolContext`:
325+
`view_parameters=lambda ctx: {"tenant_id": get_tenant(ctx.user_id)}`
326+
Values must come from a source that the caller and model cannot write, and
327+
never from `tool_context.state` or `tool_context.custom_metadata`. Keys
328+
from `view_parameters` take precedence over keys resolved from
329+
`view_parameter_names`; `None` returns or `None` values are omitted (and
330+
remove any value resolved from `view_parameter_names`); a non-mapping
331+
callable return raises `TypeError`; and any exception raised by a resolver
332+
callable propagates to the caller and fails the tool invocation.
169333
"""
170334

171335
def __init__(
@@ -175,7 +339,16 @@ def __init__(
175339
credentials_config: BigtableCredentialsConfig | None = None,
176340
bigtable_tool_settings: BigtableToolSettings | None = None,
177341
view_parameter_names: list[str] | None = None,
342+
view_parameters: (
343+
Mapping[str, Any]
344+
| Callable[
345+
[ToolContext],
346+
Mapping[str, Any] | None | Awaitable[Mapping[str, Any] | None],
347+
]
348+
| None
349+
) = None,
178350
):
351+
_validate_view_parameters(view_parameters)
179352
super().__init__(
180353
tool_filter=tool_filter,
181354
tool_name_prefix=DEFAULT_BIGTABLE_TOOL_NAME_PREFIX,
@@ -187,6 +360,7 @@ def __init__(
187360
else BigtableToolSettings()
188361
)
189362
self.view_parameter_names = view_parameter_names
363+
self.view_parameters = view_parameters
190364

191365
def _is_tool_selected(
192366
self, tool: BaseTool, readonly_context: ReadonlyContext | None
@@ -203,16 +377,19 @@ def _is_tool_selected(
203377
return False
204378

205379
def _warn_on_filtered_out_query_tool(self) -> None:
206-
if not self.view_parameter_names or not isinstance(self.tool_filter, list):
380+
if not (
381+
self.view_parameter_names or self.view_parameters
382+
) or not isinstance(self.tool_filter, list):
207383
return
208384
if (
209385
"execute_sql" in self.tool_filter
210386
and "execute_sql_parameterized" not in self.tool_filter
211387
):
212388
logger.warning(
213-
"tool_filter names execute_sql, which view_parameter_names replaces"
214-
" with execute_sql_parameterized, so no query tool is returned. Add"
215-
" execute_sql_parameterized to tool_filter."
389+
"tool_filter names execute_sql, which view_parameter_names or"
390+
" view_parameters replaces with execute_sql_parameterized, so no"
391+
" query tool is returned. Add execute_sql_parameterized to"
392+
" tool_filter."
216393
)
217394

218395
@override
@@ -237,13 +414,14 @@ async def get_tools(
237414
for func in tool_functions
238415
]
239416
# Registering both would let the model pick its own view parameters.
240-
if self.view_parameter_names:
417+
if self.view_parameter_names or self.view_parameters:
241418
all_tools.append(
242419
BigtableParameterizedViewTool(
243420
func=query_tool.execute_sql,
244421
credentials_config=self._credentials_config,
245422
tool_settings=self._tool_settings,
246423
view_parameter_names=self.view_parameter_names,
424+
view_parameters=self.view_parameters,
247425
)
248426
)
249427
else:

0 commit comments

Comments
 (0)