From 615b6f2ed023d7d3b2b91524b8a012df41ec9168 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Fri, 30 Oct 2026 11:00:49 +0100 Subject: [PATCH 1/7] Python: enforce FIDES MCP IFC labels --- python/packages/core/agent_framework/_mcp.py | 49 +- .../packages/core/agent_framework/_tools.py | 39 +- .../packages/core/agent_framework/security.py | 164 ++++- python/packages/core/tests/core/test_mcp.py | 634 +++++++++++++++++- python/packages/core/tests/test_security.py | 30 +- 5 files changed, 866 insertions(+), 50 deletions(-) diff --git a/python/packages/core/agent_framework/_mcp.py b/python/packages/core/agent_framework/_mcp.py index 41e37a0d9ff..3bef7e3d3a6 100644 --- a/python/packages/core/agent_framework/_mcp.py +++ b/python/packages/core/agent_framework/_mcp.py @@ -208,6 +208,7 @@ class MCPSpecificApproval(TypedDict, total=False): _MCP_IS_TOOL_KEY = "_mcp_is_tool" _MCP_NORMALIZED_NAME_KEY = "_mcp_normalized_name" _MCP_TOOL_RESULT_HOST_PAYLOAD_KEY = "_mcp_tool_result_host_payload" +_MCP_TOOL_RESULT_SECURITY_META_KEY = "_mcp_tool_result_security_meta" _MCP_PROGRESSIVE_LIST_TOOL_NAME = "list_mcp_tools" _MCP_PROGRESSIVE_LOAD_TOOL_NAME = "load_tool" _MCP_PROGRESSIVE_UNLOAD_TOOL_NAME = "unload_tool" @@ -258,6 +259,7 @@ class MCPSpecificApproval(TypedDict, total=False): _DEFAULT_MCP_DISCOVERY_MAX_PAGES = 100 _DEFAULT_MCP_DISCOVERY_MAX_ITEMS = 1_000 _DEFAULT_MCP_HOST_PAYLOAD_SIZE_BYTES = 1024 * 1024 +_MAX_MCP_SECURITY_META_SIZE_BYTES = 4096 @dataclass @@ -287,8 +289,45 @@ class _MCPHostPayloadCapture: apply_server_meta_to_model_items: bool host_payload: dict[str, Any] | None = None meta: dict[str, Any] | None = None + security_meta: dict[str, Any] | None = None recorded: bool = False meta_prepared: bool = False + security_meta_prepared: bool = False + + def prepare_security_meta(self, mcp_type: Any) -> dict[str, Any] | None: + """Retain security-relevant MCP metadata outside generic payload budgets.""" + if self.security_meta_prepared: + return self.security_meta + self.security_meta_prepared = True + + raw_meta = getattr(mcp_type, "meta", None) + if not isinstance(raw_meta, Mapping) or "ifc" not in raw_meta: + return None + + raw_meta_mapping = cast(Mapping[str, Any], raw_meta) + raw_security_meta: dict[str, Any] = {"ifc": raw_meta_mapping["ifc"]} + if _json_size_exceeds(raw_security_meta, _MAX_MCP_SECURITY_META_SIZE_BYTES): + logger.warning("MCP result _meta.ifc exceeds the independent security metadata limit.") + self.security_meta = {"retained": False} + return self.security_meta + + try: + copied = cast( + dict[str, Any], + to_jsonable_python(raw_security_meta, fallback=str), + ) + except (TypeError, ValueError): + logger.warning("MCP result _meta.ifc could not be retained safely.") + self.security_meta = {"retained": False} + return self.security_meta + + if len(json.dumps(copied).encode("utf-8")) > _MAX_MCP_SECURITY_META_SIZE_BYTES: + logger.warning("MCP result _meta.ifc exceeds the independent security metadata limit.") + self.security_meta = {"retained": False} + return self.security_meta + + self.security_meta = {"retained": True, "meta": copied} + return self.security_meta def prepare_meta(self, mcp_type: Any) -> dict[str, Any] | None: if self.meta_prepared: @@ -318,6 +357,7 @@ def record(self, mcp_type: Any) -> None: if self.recorded: return self.recorded = True + self.prepare_security_meta(mcp_type) self.prepare_meta(mcp_type) effective_limit = self.max_size_bytes @@ -350,8 +390,11 @@ def to_carrier(self) -> _FunctionResultCarrier: return _FunctionResultCarrier( additional_properties=additional_properties, item_additional_properties=item_additional_properties, + private_metadata=( + {_MCP_TOOL_RESULT_SECURITY_META_KEY: self.security_meta} if self.security_meta is not None else {} + ), exclusive_outer_keys=frozenset({_MCP_TOOL_RESULT_HOST_PAYLOAD_KEY}), - exclusive_item_keys=frozenset({"_meta"}), + exclusive_item_keys=frozenset({"_meta", _MCP_TOOL_RESULT_SECURITY_META_KEY}), result_already_parsed=True, ) @@ -363,8 +406,11 @@ def prepare_model_result(self, parsed: str | list[Content]) -> list[Content]: updated_item.additional_properties = dict(updated_item.additional_properties) updated_item.additional_properties.pop(_MCP_TOOL_RESULT_HOST_PAYLOAD_KEY, None) updated_item.additional_properties.pop("_meta", None) + updated_item.additional_properties.pop(_MCP_TOOL_RESULT_SECURITY_META_KEY, None) if self.apply_server_meta_to_model_items and self.meta is not None: updated_item.additional_properties["_meta"] = self.meta + if self.security_meta is not None: + updated_item.additional_properties[_MCP_TOOL_RESULT_SECURITY_META_KEY] = self.security_meta items[index] = updated_item return items @@ -1454,6 +1500,7 @@ def _parse_tool_result_from_mcp( capture = _mcp_host_payload_capture.get() if capture is not None: + capture.prepare_security_meta(mcp_type) meta = capture.prepare_meta(mcp_type) else: raw_meta = mcp_type.meta diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 79475e658b1..96534315b77 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -23,7 +23,7 @@ Sequence, ) from contextlib import contextmanager, suppress -from dataclasses import dataclass +from dataclasses import dataclass, field from datetime import date, datetime, timedelta, timezone, tzinfo from datetime import time as datetime_time from decimal import Decimal @@ -324,6 +324,8 @@ class _FunctionResultCarrier: additional_properties: dict[str, Any] item_additional_properties: dict[str, Any] + private_metadata: dict[str, Any] = field(default_factory=dict[str, Any]) + error_result_finalizer: Callable[[], None] | None = None exclusive_outer_keys: frozenset[str] = frozenset() exclusive_item_keys: frozenset[str] = frozenset() result_already_parsed: bool = False @@ -2257,21 +2259,26 @@ def _finalize_function_result( exception=exception, additional_properties=additional_properties, ) - if carrier is None or function_result.items is None: - return function_result - - updated_items = list(function_result.items) - for index, item in enumerate(updated_items): - updated_item = copy.copy(item) - updated_item.additional_properties = dict(updated_item.additional_properties) - for key in carrier.exclusive_outer_keys | carrier.exclusive_item_keys: - updated_item.additional_properties.pop(key, None) - updated_item.additional_properties = merge_additional_properties( - updated_item.additional_properties, - carrier.item_additional_properties, - ) - updated_items[index] = updated_item - function_result.items = updated_items + if carrier is not None and function_result.items is not None: + updated_items = list(function_result.items) + for index, item in enumerate(updated_items): + updated_item = copy.copy(item) + updated_item.additional_properties = dict(updated_item.additional_properties) + for key in carrier.exclusive_outer_keys | carrier.exclusive_item_keys: + updated_item.additional_properties.pop(key, None) + is_hidden_variable_reference = ( + updated_item.type == "text" and updated_item.additional_properties.get("_variable_reference") is True + ) + if not is_hidden_variable_reference: + updated_item.additional_properties = merge_additional_properties( + updated_item.additional_properties, + carrier.item_additional_properties, + ) + updated_items[index] = updated_item + function_result.items = updated_items + + if exception is not None and carrier is not None and carrier.error_result_finalizer is not None: + carrier.error_result_finalizer() return function_result diff --git a/python/packages/core/agent_framework/security.py b/python/packages/core/agent_framework/security.py index dc710f32531..d49599b8c6e 100644 --- a/python/packages/core/agent_framework/security.py +++ b/python/packages/core/agent_framework/security.py @@ -63,11 +63,13 @@ from ._tools import ( _APPROVAL_REQUEST_ID_KEY, # pyright: ignore[reportPrivateUsage] _AUTO_ARGUMENT_PREPARATION_CONTEXT_KEY, # pyright: ignore[reportPrivateUsage] + _FUNCTION_RESULT_CARRIER_CONTEXT_KEY, # pyright: ignore[reportPrivateUsage] _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT, # pyright: ignore[reportPrivateUsage] _SECURITY_ARGUMENTS_SNAPSHOT_CONTEXT_KEY, # pyright: ignore[reportPrivateUsage] FunctionTool, _argument_authority_token, # pyright: ignore[reportPrivateUsage] _bind_approval_response_to_pending_request, # pyright: ignore[reportPrivateUsage] + _FunctionResultCarrier, # pyright: ignore[reportPrivateUsage] _load_pending_approval_requests, # pyright: ignore[reportPrivateUsage] tool, ) @@ -136,6 +138,7 @@ ) _SECURITY_MATERIALIZED_AUTHORITY_CONTEXT_KEY = "_agent_framework_core_security_materialized_authority" _SECURITY_RESOLVED_AUTHORITY_CONTEXT_KEY = "_agent_framework_core_security_resolved_authority" +_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY = "_agent_framework_core_security_result_fallback_label" _TOOL_POLICY_ACCEPTS_UNTRUSTED_KEY = "accepts_untrusted" _TOOL_POLICY_CONFIDENTIALITY_KEY = "confidentiality" _TOOL_POLICY_MAX_ALLOWED_CONFIDENTIALITY_KEY = "max_allowed_confidentiality" @@ -2209,7 +2212,12 @@ def reset_context_label(self, session: AgentSession | None = None) -> None: ) logger.info("Context label reset to TRUSTED + PUBLIC") - def _update_context_label(self, new_content_label: ContentLabel) -> None: + def _update_context_label( + self, + new_content_label: ContentLabel, + *, + scope: _SecurityScope | None = None, + ) -> None: """Update the context label based on new content added to the context. The context label is updated using the most restrictive policy: @@ -2218,21 +2226,24 @@ def _update_context_label(self, new_content_label: ContentLabel) -> None: Args: new_content_label: The label of the new content being added to context. + scope: Exact security scope to update after task-local activation has unwound. """ - old_label = self._context_label - self._context_label = combine_labels(self._context_label, new_content_label) + target_scope = scope if scope is not None else self._scope + old_label = target_scope.context_label + target_scope.context_label = combine_labels(target_scope.context_label, new_content_label) + updated_label = target_scope.context_label - if old_label != self._context_label: + if old_label != updated_label: logger.info( f">>> CONTEXT TAINT: [{old_label.integrity.value}, {old_label.confidentiality.value}] " - f"-> [{self._context_label.integrity.value}, {self._context_label.confidentiality.value}] " + f"-> [{updated_label.integrity.value}, {updated_label.confidentiality.value}] " f"(new content: [{new_content_label.integrity.value}, {new_content_label.confidentiality.value}])" ) else: logger.debug( "Context label unchanged: [%s, %s]", - self._context_label.integrity.value, - self._context_label.confidentiality.value, + updated_label.integrity.value, + updated_label.confidentiality.value, ) @staticmethod @@ -2877,6 +2888,7 @@ async def process( context_label = self._context_label context.metadata["context_label"] = context_label context.metadata["argument_label"] = argument_label + context.metadata[_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY] = fallback_label context.metadata["effective_invocation_label"] = combine_labels(context_label, argument_label) materialization_token = _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT.set(( @@ -5849,6 +5861,7 @@ async def apply_mcp_security_labels( # ruff: ignore[unused-async] # ``_meta`` keys can be interpreted by additional consumers without touching # the transport layer. _MCP_RESULT_META_KEY = "_meta" +_MCP_RESULT_SECURITY_META_KEY = "_mcp_tool_result_security_meta" def _label_from_mcp_meta(meta: Any) -> ContentLabel | None: @@ -5891,13 +5904,13 @@ def _stamp_mcp_content_labels( ) -> Any: """Stamp ``security_label`` on each Content in an MCP tool result. - A parseable server label from ``additional_properties["_meta"]`` can only - restrict ``local_label`` through standard FIDES label combination by - default. When ``trust_server_ifc`` is enabled locally, a complete valid - server label is authoritative for that result. The local label is used - unchanged when metadata is missing, partial, or malformed. The sentinel - ``_meta`` key is consumed regardless so downstream layers do not re-process - it. + A parseable server label can only restrict ``local_label`` through standard + FIDES label combination by default. When ``trust_server_ifc`` is enabled + locally, a complete valid server label is authoritative for that result. + IFC metadata retained by the framework uses an independently bounded + private carrier, so generic Host-payload exhaustion cannot discard it. + Supplied-but-invalid or unretainable IFC metadata fails closed as + UNTRUSTED/PRIVATE. Private carrier keys and ``_meta`` are consumed. """ if not isinstance(contents, list): return contents @@ -5908,9 +5921,35 @@ def _stamp_mcp_content_labels( props = item.additional_properties or {} props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) + security_meta = props.pop(_MCP_RESULT_SECURITY_META_KEY, None) server_meta = props.pop(_MCP_RESULT_META_KEY, None) - dynamic = _label_from_mcp_meta(server_meta) if server_meta else None - if dynamic is None: + invalid_ifc = False + dynamic: ContentLabel | None = None + if security_meta is not None: + if isinstance(security_meta, Mapping): + security_meta_mapping = cast(Mapping[str, Any], security_meta) + else: + security_meta_mapping = None + if security_meta_mapping is not None and security_meta_mapping.get("retained") is True: + dynamic = _label_from_mcp_meta(security_meta_mapping.get("meta")) + invalid_ifc = dynamic is None + else: + invalid_ifc = True + elif isinstance(server_meta, Mapping) and "ifc" in server_meta: + dynamic = _label_from_mcp_meta(server_meta) + invalid_ifc = dynamic is None + + if invalid_ifc: + label = combine_labels( + local_label, + ContentLabel( + integrity=IntegrityLabel.UNTRUSTED, + confidentiality=ConfidentialityLabel.USER_IDENTITY, + metadata={"source": "invalid_mcp_ifc"}, + ), + ) + props[_AUTHORITATIVE_SECURITY_LABEL] = _INTERNAL_RESULT_MARKER + elif dynamic is None: label = local_label elif trust_server_ifc: label = dynamic @@ -5922,17 +5961,62 @@ def _stamp_mcp_content_labels( return contents_list +def _stamp_mcp_error_carrier_label( + context: FunctionInvocationContext, + local_label: ContentLabel, + fallback_label: ContentLabel, + *, + trust_server_ifc: bool, +) -> ContentLabel | None: + """Apply retained MCP IFC to a generic function-error result carrier.""" + raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if not isinstance(raw_carrier, _FunctionResultCarrier): + return None + + security_meta = raw_carrier.private_metadata.pop(_MCP_RESULT_SECURITY_META_KEY, None) + probe = Content.from_text("") + valid_server_ifc = False + if security_meta is not None: + probe.additional_properties[_MCP_RESULT_SECURITY_META_KEY] = security_meta + if isinstance(security_meta, Mapping): + security_meta_mapping = cast(Mapping[str, Any], security_meta) + if security_meta_mapping.get("retained") is True: + valid_server_ifc = _label_from_mcp_meta(security_meta_mapping.get("meta")) is not None + effective_local_label = ( + fallback_label if security_meta is None or (valid_server_ifc and not trust_server_ifc) else local_label + ) + stamped = cast( + list[Content], + _stamp_mcp_content_labels([probe], effective_local_label, trust_server_ifc=trust_server_ifc), + ) + if not stamped: + return None + + stamped_item = stamped[0] + stamped_properties = dict(stamped_item.additional_properties) + stamped_properties.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + stamped_properties.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) + raw_carrier.item_additional_properties = { + **raw_carrier.item_additional_properties, + **stamped_properties, + } + label_data = stamped_properties.get("security_label") + if not isinstance(label_data, MutableMapping): + return None + return ContentLabel.from_dict(cast(MutableMapping[str, Any], label_data)) + + def _current_mcp_local_label(func_tool: FunctionTool, default_integrity: IntegrityLabel) -> ContentLabel: """Read the current local MCP output policy from a FunctionTool.""" props = func_tool.additional_properties or {} try: integrity = IntegrityLabel(props.get("source_integrity", default_integrity.value)) - except ValueError: - integrity = default_integrity + except (TypeError, ValueError): + integrity = IntegrityLabel.UNTRUSTED try: confidentiality = ConfidentialityLabel(props.get("confidentiality", ConfidentialityLabel.PUBLIC.value)) - except ValueError: - confidentiality = ConfidentialityLabel.PUBLIC + except (TypeError, ValueError): + confidentiality = ConfidentialityLabel.PRIVATE return ContentLabel(integrity=integrity, confidentiality=confidentiality) @@ -5956,9 +6040,43 @@ async def _wrapped(*args: Any, **kwargs: Any) -> Any: local_label = _current_mcp_local_label(func_tool, default_integrity) trust_server_ifc = props.get(_MCP_TRUST_SERVER_IFC_KEY) is True - res = original(*args, **kwargs) - if _inspect.isawaitable(res): - res = await res + invocation_context = next( + (value for value in kwargs.values() if isinstance(value, FunctionInvocationContext)), + None, + ) + try: + res = original(*args, **kwargs) + if _inspect.isawaitable(res): + res = await res + except Exception: + if invocation_context is not None: + raw_fallback_label = invocation_context.metadata.get(_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY) + fallback_label = raw_fallback_label if isinstance(raw_fallback_label, ContentLabel) else local_label + error_label = _stamp_mcp_error_carrier_label( + invocation_context, + local_label, + fallback_label, + trust_server_ifc=trust_server_ifc, + ) + active_middleware = _current_middleware.get() + if ( + error_label is not None + and active_middleware is not None + and _current_context.get() is invocation_context + ): + raw_carrier = invocation_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if isinstance(raw_carrier, _FunctionResultCarrier): + active_scope = active_middleware._scope # pyright: ignore[reportPrivateUsage] + + def commit_error_label() -> None: + invocation_context.metadata["result_label"] = error_label + active_middleware._update_context_label( # pyright: ignore[reportPrivateUsage] + error_label, + scope=active_scope, + ) + + raw_carrier.error_result_finalizer = commit_error_label + raise return _stamp_mcp_content_labels(res, local_label, trust_server_ifc=trust_server_ifc) _wrapped._ifc_wrapped = True # type: ignore[attr-defined] diff --git a/python/packages/core/tests/core/test_mcp.py b/python/packages/core/tests/core/test_mcp.py index 9362851adb1..f8df5c349cd 100644 --- a/python/packages/core/tests/core/test_mcp.py +++ b/python/packages/core/tests/core/test_mcp.py @@ -11,8 +11,9 @@ from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping from contextlib import AbstractAsyncContextManager, _AsyncGeneratorContextManager # type: ignore from contextvars import ContextVar +from pathlib import Path from textwrap import dedent -from types import TracebackType +from types import SimpleNamespace, TracebackType from typing import Any, cast from unittest.mock import AsyncMock, Mock, patch @@ -24,17 +25,21 @@ from agent_framework import ( Agent, + AgentSession, ChatResponse, ChatResponseUpdate, Content, + FileSessionStore, FunctionInvocationContext, FunctionMiddleware, FunctionTool, + InMemoryHistoryProvider, MCPStdioTool, MCPStreamableHTTPTool, MCPTaskOptions, # ty: ignore[deprecated] MCPWebsocketTool, # ty: ignore[deprecated] Message, + SessionContext, SupportsChatGetResponse, ) from agent_framework._feature_stage import _WARNED_FEATURES, ExperimentalFeature, ExperimentalWarning @@ -56,7 +61,7 @@ _should_propagate_cancelled_error, logger, ) -from agent_framework._middleware import FunctionMiddlewarePipeline +from agent_framework._middleware import FunctionMiddlewarePipeline, MiddlewareTermination from agent_framework._tools import ( _auto_invoke_function, _FunctionResultPayloadBudget, @@ -245,7 +250,10 @@ async def _call_generated_mcp_tool( middleware_pipeline: FunctionMiddlewarePipeline | None = None, host_payload_budget: _FunctionResultPayloadBudget | None = None, mcp_local_label: tuple[str, str] | None = None, + mcp_local_principals: list[dict[str, str]] | None = None, + invocation_session: AgentSession | None = None, trust_server_ifc: bool = False, + include_detailed_errors: bool = False, **kwargs: Any, ) -> Content: function_kwargs: dict[str, Any] = {} @@ -259,7 +267,7 @@ async def _call_generated_mcp_tool( **function_kwargs, ) if mcp_local_label is not None: - from agent_framework.security import IntegrityLabel, _wrap_mcp_function_for_ifc + from agent_framework.security import PRINCIPAL_METADATA_KEY, IntegrityLabel, _wrap_mcp_function_for_ifc source_integrity, confidentiality = mcp_local_label function.additional_properties = { @@ -268,11 +276,16 @@ async def _call_generated_mcp_tool( "confidentiality": confidentiality, "_mcp_trust_server_ifc": trust_server_ifc, } + if mcp_local_principals is not None: + function.additional_properties[PRINCIPAL_METADATA_KEY] = mcp_local_principals _wrap_mcp_function_for_ifc(function, IntegrityLabel(source_integrity)) return await _auto_invoke_function( Content.from_function_call(call_id=f"call-{tool_name}", name=tool_name, arguments=kwargs), - config=normalize_function_invocation_configuration(None), + config=normalize_function_invocation_configuration({ + "include_detailed_errors": include_detailed_errors, + }), tool_map={tool_name: function}, + invocation_session=invocation_session, middleware_pipeline=middleware_pipeline, host_payload_budget=host_payload_budget, ) @@ -1795,6 +1808,505 @@ def fail_if_copied(*_args: Any, **_kwargs: Any) -> Any: assert _MCP_TOOL_RESULT_HOST_PAYLOAD_KEY not in function_result.additional_properties +async def test_exhausted_aggregate_budget_preserves_ifc_security_label() -> None: + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="private result")], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="helper", + parse_tool_results=lambda _: "model projection", + max_host_payload_size_bytes=128, + ) + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + budget = _FunctionResultPayloadBudget() + assert budget.reserve(128, 128) + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + host_payload_budget=budget, + mcp_local_label=("trusted", "public"), + trust_server_ifc=True, + ) + + assert "_meta" not in function_result.additional_properties + assert function_result.items is not None + assert function_result.items[0].additional_properties["security_label"] == { + "integrity": "trusted", + "confidentiality": "private", + } + assert "_mcp_tool_result_security_meta" not in function_result.items[0].additional_properties + + +@pytest.mark.parametrize( + ("server_ifc", "expected_integrity", "expected_confidentiality"), + [ + pytest.param( + {"integrity": "trusted", "confidentiality": "private"}, + "trusted", + "private", + id="restrictive", + ), + pytest.param( + {"integrity": "trusted"}, + "untrusted", + "user_identity", + id="invalid", + ), + ], +) +async def test_exhausted_aggregate_budget_enforces_ifc_on_detailed_mcp_error( + tmp_path: Path, + server_ifc: dict[str, str], + expected_integrity: str, + expected_confidentiality: str, +) -> None: + from agent_framework.security import ( + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + ) + + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="private MCP error instructions")], + is_error=True, + _meta={"ifc": server_ifc}, + ) + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="helper", + max_host_payload_size_bytes=128, + ) + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + budget = _FunctionResultPayloadBudget() + assert budget.reserve(128, 128) + tracker = LabelTrackingFunctionMiddleware() + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + host_payload_budget=budget, + mcp_local_label=("trusted", "public"), + trust_server_ifc=True, + include_detailed_errors=True, + ) + + assert "private MCP error instructions" in function_result.result + assert function_result.items is not None + assert function_result.items[0].additional_properties["security_label"]["integrity"] == expected_integrity + assert ( + function_result.items[0].additional_properties["security_label"]["confidentiality"] == expected_confidentiality + ) + assert "_security_label_authoritative" not in function_result.items[0].additional_properties + assert "_mcp_tool_result_security_meta" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + store = FileSessionStore(tmp_path / expected_integrity, serialization_format="json") + session = AgentSession(session_id=f"mcp-error-{expected_integrity}") + session.state["mcp_error_result"] = function_result + await store.set(session.session_id, session) + restored = await store.get(session.session_id) + assert restored is not None + restored_result = restored.state["mcp_error_result"] + assert isinstance(restored_result, dict) + restored_items = restored_result["items"] + assert isinstance(restored_items, list) + assert restored_items[0]["additional_properties"]["security_label"]["integrity"] == expected_integrity + context_label = tracker.get_context_label() + assert context_label.integrity.value == expected_integrity + assert context_label.confidentiality.value == expected_confidentiality + + protected_tool = FunctionTool( + func=lambda: "must not run", + name="protected_mcp_error_sink", + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "public", + }, + ) + invocation = FunctionInvocationContext(function=protected_tool, arguments={}) + + with pytest.raises(MiddlewareTermination): + await FunctionMiddlewarePipeline(tracker, PolicyEnforcementFunctionMiddleware()).execute( + invocation, + lambda _context: pytest.fail("MCP error IFC must block the protected public sink"), + ) + + +async def test_retried_mcp_error_does_not_commit_swallowed_label() -> None: + from agent_framework.security import ( + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + ) + + error_result = types.CallToolResult( + content=[types.TextContent(type="text", text="private failed attempt")], + is_error=True, + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + success_result = types.CallToolResult( + content=[types.TextContent(type="text", text="recovered")], + is_error=False, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(side_effect=[error_result, success_result]) + + class RetryOnceMiddleware(FunctionMiddleware): + async def process(self, context: FunctionInvocationContext, call_next: Callable[[], Any]) -> None: + del context + try: + await call_next() + except ToolExecutionException: + await call_next() + + tracker = LabelTrackingFunctionMiddleware() + function_result = await _call_generated_mcp_tool( + tool, + "widget", + middleware_pipeline=FunctionMiddlewarePipeline(RetryOnceMiddleware(), tracker), + mcp_local_label=("trusted", "public"), + trust_server_ifc=True, + ) + + assert function_result.result == "recovered" + context_label = tracker.get_context_label() + assert context_label.integrity.value == "trusted" + assert context_label.confidentiality.value == "public" + + executed = False + + def public_sink() -> str: + nonlocal executed + executed = True + return "sent" + + sink_tool = FunctionTool( + func=public_sink, + name="public_after_retry_sink", + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "public", + }, + ) + invocation = FunctionInvocationContext(function=sink_tool, arguments={}) + + async def execute_public_sink(_: FunctionInvocationContext) -> str: + return public_sink() + + await FunctionMiddlewarePipeline(tracker, PolicyEnforcementFunctionMiddleware()).execute( + invocation, + execute_public_sink, + ) + assert executed is True + + +async def test_mcp_error_finalizer_updates_invocation_session_scope() -> None: + from agent_framework.security import ( + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + ) + + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="session-private failure")], + is_error=True, + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + tracker = LabelTrackingFunctionMiddleware() + session = AgentSession(session_id="mcp-error-session-scope") + + await _call_generated_mcp_tool( + tool, + "widget", + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + mcp_local_label=("trusted", "public"), + invocation_session=session, + trust_server_ifc=True, + include_detailed_errors=True, + ) + + session_label = tracker.get_context_label(session) + assert session_label.integrity.value == "trusted" + assert session_label.confidentiality.value == "private" + default_label = tracker.get_context_label() + assert default_label.integrity.value == "trusted" + assert default_label.confidentiality.value == "public" + + protected_tool = FunctionTool( + func=lambda: "must not run", + name="session_public_after_mcp_error_sink", + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "public", + }, + ) + invocation = FunctionInvocationContext(function=protected_tool, arguments={}, session=session) + + with pytest.raises(MiddlewareTermination): + await FunctionMiddlewarePipeline(tracker, PolicyEnforcementFunctionMiddleware()).execute( + invocation, + lambda _context: pytest.fail("The invocation session must retain the MCP error restriction"), + ) + + +async def test_mcp_error_without_ifc_preserves_local_identity_principals() -> None: + from agent_framework.security import ( + PRINCIPAL_METADATA_KEY, + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + ) + + principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="identity-scoped failure")], + is_error=True, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + tracker = LabelTrackingFunctionMiddleware() + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + mcp_local_label=("trusted", "user_identity"), + mcp_local_principals=principals, + include_detailed_errors=True, + ) + + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "user_identity" + assert result_label["metadata"][PRINCIPAL_METADATA_KEY] == principals + context_label = tracker.get_context_label() + assert context_label.metadata[PRINCIPAL_METADATA_KEY] == principals + + executed = False + + def identity_sink() -> str: + nonlocal executed + executed = True + return "sent" + + sink_tool = FunctionTool( + func=identity_sink, + name="identity_after_mcp_error_sink", + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: principals, + }, + ) + invocation = FunctionInvocationContext(function=sink_tool, arguments={}) + + async def execute_identity_sink(_: FunctionInvocationContext) -> str: + return identity_sink() + + await FunctionMiddlewarePipeline(tracker, PolicyEnforcementFunctionMiddleware()).execute( + invocation, + execute_identity_sink, + ) + assert executed is True + + +async def test_restriction_only_mcp_error_preserves_private_argument_fallback() -> None: + from agent_framework.security import ( + ConfidentialityLabel, + ContentLabel, + IntegrityLabel, + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + ) + + secret = "private argument echoed by MCP error" + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text=secret)], + is_error=True, + _meta={"ifc": {"integrity": "trusted", "confidentiality": "public"}}, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + tracker = LabelTrackingFunctionMiddleware() + variable_id = tracker.get_variable_store().store( + secret, + ContentLabel( + integrity=IntegrityLabel.TRUSTED, + confidentiality=ConfidentialityLabel.PRIVATE, + ), + ) + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + mcp_local_label=("trusted", "public"), + include_detailed_errors=True, + value=f"[{variable_id}]", + ) + + assert secret in function_result.result + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "private" + context_label = tracker.get_context_label() + assert context_label.integrity == IntegrityLabel.TRUSTED + assert context_label.confidentiality == ConfidentialityLabel.PRIVATE + + protected_tool = FunctionTool( + func=lambda: "must not run", + name="public_after_private_mcp_error_sink", + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "public", + }, + ) + invocation = FunctionInvocationContext(function=protected_tool, arguments={}) + + with pytest.raises(MiddlewareTermination): + await FunctionMiddlewarePipeline(tracker, PolicyEnforcementFunctionMiddleware()).execute( + invocation, + lambda _context: pytest.fail("Private MCP error data must block the public sink"), + ) + + +async def test_oversized_identity_ifc_fails_closed_without_confidentiality_downgrade() -> None: + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="identity-scoped result")], + _meta={ + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": [{"tenant_id": "tenant-a", "user_id": "x" * 5000}], + } + }, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + host_payload_budget=_FunctionResultPayloadBudget(), + mcp_local_label=("trusted", "public"), + trust_server_ifc=True, + ) + + assert function_result.items is not None + assert function_result.items[0].additional_properties["security_label"] == { + "integrity": "untrusted", + "confidentiality": "user_identity", + "metadata": {"source": "invalid_mcp_ifc"}, + } + assert "_mcp_tool_result_security_meta" not in function_result.items[0].additional_properties + + +async def test_invalid_identity_ifc_cannot_inherit_local_principals() -> None: + from agent_framework.security import ( + PRINCIPAL_METADATA_KEY, + ConfidentialityLabel, + IntegrityLabel, + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + _wrap_mcp_function_for_ifc, + ) + + principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="identity-scoped result")], + _meta={ + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": [{"tenant_id": "tenant-a", "user_id": "x" * 5000}], + } + }, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + function = FunctionTool( + name="identity_widget", + description="", + func=_make_mcp_tool_caller(tool, "identity_widget"), + input_model={"type": "object", "properties": {}}, + additional_properties={ + "_mcp_remote_name": "identity_widget", + "source_integrity": "trusted", + "confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: principals, + }, + ) + _wrap_mcp_function_for_ifc(function, IntegrityLabel.TRUSTED) + tracker = LabelTrackingFunctionMiddleware(auto_hide_untrusted=True) + policy = PolicyEnforcementFunctionMiddleware() + + result = await _auto_invoke_function( + Content.from_function_call(call_id="identity-call", name=function.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={function.name: function}, + middleware_pipeline=FunctionMiddlewarePipeline(tracker, policy), + host_payload_budget=_FunctionResultPayloadBudget(), + ) + + assert result.items is not None + assert result.items[0].additional_properties["_variable_reference"] is True + context_label = tracker.get_context_label() + assert context_label.confidentiality == ConfidentialityLabel.USER_IDENTITY + assert PRINCIPAL_METADATA_KEY not in context_label.metadata + + executed = False + + def identity_destination() -> str: + nonlocal executed + executed = True + return "sent" + + destination = FunctionTool( + name="identity_destination", + description="Identity-scoped destination", + func=identity_destination, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "accepts_untrusted": True, + "source_integrity": "trusted", + "max_allowed_confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: principals, + }, + ) + + with pytest.raises(MiddlewareTermination): + await _auto_invoke_function( + Content.from_function_call(call_id="destination-call", name=destination.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={destination.name: destination}, + middleware_pipeline=FunctionMiddlewarePipeline(tracker, policy), + ) + + assert executed is False + + async def test_oversized_mcp_meta_is_omitted_from_host_and_model_items() -> None: mcp_result = types.CallToolResult( content=[types.TextContent(type="text", text="ok")], @@ -2085,9 +2597,121 @@ async def test_secure_mcp_builtin_parser_restricts_all_result_shapes(result_shap assert hidden_item.additional_properties["_variable_reference"] is True assert hidden_item.additional_properties["security_label"]["integrity"] == "untrusted" assert hidden_item.additional_properties["security_label"]["confidentiality"] == "private" - assert hidden_item.additional_properties["_meta"] == mcp_result.meta + assert "_meta" not in hidden_item.additional_properties + assert function_result.additional_properties["_meta"] == mcp_result.meta + + +async def test_hidden_builtin_mcp_result_replays_without_tainting_context() -> None: + """A restored hidden MCP placeholder stays integrity-clean on the next run.""" + from agent_framework.security import ( + IntegrityLabel, + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + SecureAgentConfig, + _wrap_mcp_function_for_ifc, + ) + + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="untrusted MCP payload")], + _meta={"ifc": {"integrity": "untrusted", "confidentiality": "private"}}, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + function = FunctionTool( + name="widget", + description="", + func=_make_mcp_tool_caller(tool, "widget"), + input_model={"type": "object", "properties": {}}, + additional_properties={ + "_mcp_remote_name": "widget", + "source_integrity": "untrusted", + "confidentiality": "private", + "max_allowed_confidentiality": "public", + }, + ) + _wrap_mcp_function_for_ifc(function, IntegrityLabel.UNTRUSTED) + security = SecureAgentConfig() + session = AgentSession(session_id="hidden-mcp-replay") + first_context = SessionContext( + session_id=session.session_id, + input_messages=[Message(role="user", contents=["run"])], + ) + await security.before_run( + agent=cast(Any, SimpleNamespace(context_providers=[security])), + session=session, + context=first_context, + state=session.state.setdefault(security.source_id, {}), + ) + first_tracker = first_context.get_middleware()[0] + assert isinstance(first_tracker, LabelTrackingFunctionMiddleware) + + function_result = await _auto_invoke_function( + Content.from_function_call(call_id="call-widget", name="widget", arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={"widget": function}, + invocation_session=session, + middleware_pipeline=FunctionMiddlewarePipeline(first_tracker), + host_payload_budget=_FunctionResultPayloadBudget(), + ) + + assert function_result.items is not None + assert function_result.items[0].additional_properties["_variable_reference"] is True + assert "_meta" not in function_result.items[0].additional_properties assert function_result.additional_properties["_meta"] == mcp_result.meta + restored = AgentSession.from_dict(json.loads(json.dumps(session.to_dict()))) + history = InMemoryHistoryProvider() + replayed = Message(role="tool", contents=[function_result]) + second_context = SessionContext(session_id=restored.session_id, input_messages=[]) + second_context.extend_messages(history.source_id, [replayed]) + await security.before_run( + agent=cast(Any, SimpleNamespace(context_providers=[history, security])), + session=restored, + context=second_context, + state=restored.state.setdefault(security.source_id, {}), + ) + second_tracker, second_policy, _ = second_context.get_middleware() + assert isinstance(second_tracker, LabelTrackingFunctionMiddleware) + assert isinstance(second_policy, PolicyEnforcementFunctionMiddleware) + restored_label = second_tracker.get_context_label() + assert restored_label.integrity.value == "trusted" + assert restored_label.confidentiality.value == "private" + + executed = False + + def protected_action() -> str: + nonlocal executed + executed = True + return "done" + + protected_tool = FunctionTool( + name="protected_action", + description="Run an unrelated protected action", + func=protected_action, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "private", + }, + ) + invocation = FunctionInvocationContext( + function=protected_tool, + arguments={}, + session=restored, + ) + + async def execute_protected(_: FunctionInvocationContext) -> list[Content]: + return [Content.from_text(protected_action())] + + await FunctionMiddlewarePipeline(second_tracker, second_policy).execute( + invocation, + execute_protected, + ) + + assert executed is True + async def test_secure_mcp_builtin_parser_honors_locally_trusted_server_ifc() -> None: from agent_framework.security import LabelTrackingFunctionMiddleware diff --git a/python/packages/core/tests/test_security.py b/python/packages/core/tests/test_security.py index 8961bf41f28..629b9cd5728 100644 --- a/python/packages/core/tests/test_security.py +++ b/python/packages/core/tests/test_security.py @@ -8514,9 +8514,7 @@ def test_stamp_contents_missing_meta_falls_back_to_local_policy( ids=["malformed", "partial"], ) @pytest.mark.parametrize("trust_server_ifc", [False, True]) - def test_stamp_contents_invalid_meta_falls_back_to_local_policy( - self, server_meta: dict[str, Any], trust_server_ifc: bool - ): + def test_stamp_contents_invalid_meta_fails_closed(self, server_meta: dict[str, Any], trust_server_ifc: bool): from agent_framework.security import _stamp_mcp_content_labels static = ContentLabel(integrity=IntegrityLabel.TRUSTED, confidentiality=ConfidentialityLabel.PUBLIC) @@ -8528,11 +8526,33 @@ def test_stamp_contents_invalid_meta_falls_back_to_local_policy( ] _stamp_mcp_content_labels(contents, static, trust_server_ifc=trust_server_ifc) assert contents[0].additional_properties["security_label"] == { - "integrity": "trusted", - "confidentiality": "public", + "integrity": "untrusted", + "confidentiality": "user_identity", + "metadata": {"source": "invalid_mcp_ifc"}, } assert "_meta" not in contents[0].additional_properties + def test_stamp_contents_unretained_ifc_fails_closed(self) -> None: + """A framework-dropped IFC label cannot silently fall back to public.""" + from agent_framework.security import _stamp_mcp_content_labels + + static = ContentLabel(integrity=IntegrityLabel.TRUSTED, confidentiality=ConfidentialityLabel.PUBLIC) + contents = [ + Content.from_text( + "x", + additional_properties={"_mcp_tool_result_security_meta": {"retained": False}}, + ) + ] + + _stamp_mcp_content_labels(contents, static, trust_server_ifc=True) + + assert contents[0].additional_properties["security_label"] == { + "integrity": "untrusted", + "confidentiality": "user_identity", + "metadata": {"source": "invalid_mcp_ifc"}, + } + assert "_mcp_tool_result_security_meta" not in contents[0].additional_properties + def test_stamp_contents_non_ifc_meta_falls_back_to_static(self): """Generic ``_meta`` keys unrelated to IFC don't accidentally produce a label.""" from agent_framework.security import _stamp_mcp_content_labels From aa7855ef3aaf1c48a48e84555db00e8c799d691b Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Thu, 5 Nov 2026 16:19:07 +0100 Subject: [PATCH 2/7] Python: address MCP IFC review findings --- python/packages/core/agent_framework/_mcp.py | 7 +- .../packages/core/agent_framework/_tools.py | 17 ++ .../packages/core/agent_framework/security.py | 157 +++++++++++++----- python/packages/core/tests/core/test_mcp.py | 108 +++++++++++- python/packages/core/tests/test_security.py | 109 ++++++++++-- 5 files changed, 338 insertions(+), 60 deletions(-) diff --git a/python/packages/core/agent_framework/_mcp.py b/python/packages/core/agent_framework/_mcp.py index 3bef7e3d3a6..f57df33f2bb 100644 --- a/python/packages/core/agent_framework/_mcp.py +++ b/python/packages/core/agent_framework/_mcp.py @@ -394,7 +394,12 @@ def to_carrier(self) -> _FunctionResultCarrier: {_MCP_TOOL_RESULT_SECURITY_META_KEY: self.security_meta} if self.security_meta is not None else {} ), exclusive_outer_keys=frozenset({_MCP_TOOL_RESULT_HOST_PAYLOAD_KEY}), - exclusive_item_keys=frozenset({"_meta", _MCP_TOOL_RESULT_SECURITY_META_KEY}), + exclusive_item_keys=frozenset({ + "_meta", + "_security_label_authoritative", + "_security_label_authoritative_confidentiality", + _MCP_TOOL_RESULT_SECURITY_META_KEY, + }), result_already_parsed=True, ) diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 96534315b77..a7ef502c187 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -325,6 +325,8 @@ class _FunctionResultCarrier: additional_properties: dict[str, Any] item_additional_properties: dict[str, Any] private_metadata: dict[str, Any] = field(default_factory=dict[str, Any]) + parsed_result_postprocessor: Callable[[list[Content]], list[Content]] | None = None + parser_exception_handler: Callable[[], None] | None = None error_result_finalizer: Callable[[], None] | None = None exclusive_outer_keys: frozenset[str] = frozenset() exclusive_item_keys: frozenset[str] = frozenset() @@ -1266,7 +1268,13 @@ async def invoke( elif callable(configured_parser): try: parsed = configured_parser(result) + if isinstance(parsed, str): + parsed = [Content.from_text(parsed)] + if isinstance(carrier, _FunctionResultCarrier) and carrier.parsed_result_postprocessor is not None: + parsed = carrier.parsed_result_postprocessor(parsed) except Exception as exception: + if isinstance(carrier, _FunctionResultCarrier) and carrier.parser_exception_handler is not None: + carrier.parser_exception_handler() self.invocation_exception_count += 1 if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: logger.error(f"Function {self.name}: result parser failed. Error: {exception}") @@ -1361,7 +1369,16 @@ async def invoke( elif callable(configured_parser): try: parsed = configured_parser(result) + if isinstance(parsed, str): + parsed = [Content.from_text(parsed)] + if ( + isinstance(carrier, _FunctionResultCarrier) + and carrier.parsed_result_postprocessor is not None + ): + parsed = carrier.parsed_result_postprocessor(parsed) except Exception as exception: + if isinstance(carrier, _FunctionResultCarrier) and carrier.parser_exception_handler is not None: + carrier.parser_exception_handler() self.invocation_exception_count += 1 metric_attributes[OtelAttr.ERROR_TYPE] = type(exception).__name__ if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: diff --git a/python/packages/core/agent_framework/security.py b/python/packages/core/agent_framework/security.py index d49599b8c6e..184cb980e5a 100644 --- a/python/packages/core/agent_framework/security.py +++ b/python/packages/core/agent_framework/security.py @@ -5868,12 +5868,11 @@ def _label_from_mcp_meta(meta: Any) -> ContentLabel | None: """Best-effort parse of an MCP server ``_meta`` payload into a ``ContentLabel``. Looks under ``meta["ifc"]`` for an ``integrity`` and ``confidentiality`` - pair using the wire vocabulary advertised by IFC-aware MCP servers - (e.g. the GitHub MCP server's ``ifc`` schema: integrity is one of - ``"trusted" | "untrusted"`` and confidentiality is one of - ``"public" | "private"``). Returns ``None`` when the payload is missing, - not a dict, or contains values outside the known vocabularies, which lets - callers fall back to a statically derived label. + pair using the wire vocabulary advertised by IFC-aware MCP servers. + ``user_identity`` confidentiality also requires a complete, valid + ``principals`` set. Returns ``None`` when the payload is missing, malformed, + or contains values outside the known vocabularies, which lets callers fail + closed when IFC was supplied. """ if not isinstance(meta, dict): return None @@ -5887,13 +5886,21 @@ def _label_from_mcp_meta(meta: Any) -> ContentLabel | None: try: integrity = IntegrityLabel(integ_raw) if integ_raw is not None else None confidentiality = ConfidentialityLabel(conf_raw) if conf_raw is not None else None - except ValueError: + except (TypeError, ValueError): logger.debug("MCP _meta.ifc had unknown label values: %r", ifc_map) return None if integrity is None or confidentiality is None: logger.debug("MCP _meta.ifc missing integrity/confidentiality: %r", ifc_map) return None - return ContentLabel(integrity=integrity, confidentiality=confidentiality) + metadata: dict[str, Any] | None = None + if confidentiality == ConfidentialityLabel.USER_IDENTITY: + try: + principals = _canonical_principals(ifc_map.get("principals"), source="MCP _meta.ifc") + except ValueError: + logger.debug("MCP _meta.ifc had invalid user-identity principals: %r", ifc_map) + return None + metadata = {PRINCIPAL_METADATA_KEY: _principal_list(principals)} + return ContentLabel(integrity=integrity, confidentiality=confidentiality, metadata=metadata) def _stamp_mcp_content_labels( @@ -5961,6 +5968,54 @@ def _stamp_mcp_content_labels( return contents_list +def _strip_mcp_authority_markers(contents: str | list[Content]) -> str | list[Content]: + """Remove private authority markers when no tracking middleware can consume them.""" + if not isinstance(contents, list): + return contents + for item in contents: + props = item.additional_properties or {} + props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) + item.additional_properties = props + return contents + + +def _stamp_parsed_mcp_content_labels( + context: FunctionInvocationContext, + contents: list[Content], + local_label: ContentLabel, + *, + trust_server_ifc: bool, + retain_authority: bool, +) -> list[Content]: + """Reapply retained MCP IFC after a function-level result parser.""" + raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if not isinstance(raw_carrier, _FunctionResultCarrier): + return contents + + security_meta = raw_carrier.private_metadata.get(_MCP_RESULT_SECURITY_META_KEY) + prepared: list[Content] = [] + for item in contents: + updated_item = copy(item) + props = dict(updated_item.additional_properties) + props.pop(_MCP_RESULT_META_KEY, None) + props.pop(_MCP_RESULT_SECURITY_META_KEY, None) + props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) + if security_meta is not None: + props[_MCP_RESULT_SECURITY_META_KEY] = security_meta + updated_item.additional_properties = props + prepared.append(updated_item) + + stamped = cast( + list[Content], + _stamp_mcp_content_labels(prepared, local_label, trust_server_ifc=trust_server_ifc), + ) + if not retain_authority: + _strip_mcp_authority_markers(stamped) + return stamped + + def _stamp_mcp_error_carrier_label( context: FunctionInvocationContext, local_label: ContentLabel, @@ -5973,7 +6028,7 @@ def _stamp_mcp_error_carrier_label( if not isinstance(raw_carrier, _FunctionResultCarrier): return None - security_meta = raw_carrier.private_metadata.pop(_MCP_RESULT_SECURITY_META_KEY, None) + security_meta = raw_carrier.private_metadata.get(_MCP_RESULT_SECURITY_META_KEY) probe = Content.from_text("") valid_server_ifc = False if security_meta is not None: @@ -6044,40 +6099,68 @@ async def _wrapped(*args: Any, **kwargs: Any) -> Any: (value for value in kwargs.values() if isinstance(value, FunctionInvocationContext)), None, ) + + def prepare_error_label() -> None: + if invocation_context is None: + return + active_context = invocation_context + raw_fallback_label = active_context.metadata.get(_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY) + fallback_label = raw_fallback_label if isinstance(raw_fallback_label, ContentLabel) else local_label + error_label = _stamp_mcp_error_carrier_label( + active_context, + local_label, + fallback_label, + trust_server_ifc=trust_server_ifc, + ) + active_middleware = _current_middleware.get() + if error_label is None or active_middleware is None or _current_context.get() is not active_context: + return + raw_carrier = active_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if not isinstance(raw_carrier, _FunctionResultCarrier): + return + active_scope = active_middleware._scope # pyright: ignore[reportPrivateUsage] + + def commit_error_label() -> None: + active_context.metadata["result_label"] = error_label + active_middleware._update_context_label( # pyright: ignore[reportPrivateUsage] + error_label, + scope=active_scope, + ) + + raw_carrier.error_result_finalizer = commit_error_label + try: res = original(*args, **kwargs) if _inspect.isawaitable(res): res = await res except Exception: - if invocation_context is not None: - raw_fallback_label = invocation_context.metadata.get(_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY) - fallback_label = raw_fallback_label if isinstance(raw_fallback_label, ContentLabel) else local_label - error_label = _stamp_mcp_error_carrier_label( - invocation_context, - local_label, - fallback_label, - trust_server_ifc=trust_server_ifc, - ) - active_middleware = _current_middleware.get() - if ( - error_label is not None - and active_middleware is not None - and _current_context.get() is invocation_context - ): - raw_carrier = invocation_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) - if isinstance(raw_carrier, _FunctionResultCarrier): - active_scope = active_middleware._scope # pyright: ignore[reportPrivateUsage] - - def commit_error_label() -> None: - invocation_context.metadata["result_label"] = error_label - active_middleware._update_context_label( # pyright: ignore[reportPrivateUsage] - error_label, - scope=active_scope, - ) - - raw_carrier.error_result_finalizer = commit_error_label + prepare_error_label() raise - return _stamp_mcp_content_labels(res, local_label, trust_server_ifc=trust_server_ifc) + + retain_authority = _current_middleware.get() is not None + if invocation_context is not None: + raw_carrier = invocation_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if isinstance(raw_carrier, _FunctionResultCarrier): + + def postprocess_parsed_result(contents: list[Content]) -> list[Content]: + return _stamp_parsed_mcp_content_labels( + invocation_context, + contents, + local_label, + trust_server_ifc=trust_server_ifc, + retain_authority=retain_authority, + ) + + raw_carrier.parsed_result_postprocessor = postprocess_parsed_result + raw_carrier.parser_exception_handler = prepare_error_label + + stamped = cast( + str | list[Content], + _stamp_mcp_content_labels(res, local_label, trust_server_ifc=trust_server_ifc), + ) + if not retain_authority: + _strip_mcp_authority_markers(stamped) + return stamped _wrapped._ifc_wrapped = True # type: ignore[attr-defined] func_tool.func = _wrapped diff --git a/python/packages/core/tests/core/test_mcp.py b/python/packages/core/tests/core/test_mcp.py index f8df5c349cd..e96442fc525 100644 --- a/python/packages/core/tests/core/test_mcp.py +++ b/python/packages/core/tests/core/test_mcp.py @@ -1841,6 +1841,86 @@ async def test_exhausted_aggregate_budget_preserves_ifc_security_label() -> None assert "_mcp_tool_result_security_meta" not in function_result.items[0].additional_properties +@pytest.mark.parametrize("enable_instrumentation", [False, True], indirect=True) +@pytest.mark.usefixtures("span_exporter") +async def test_function_result_parser_preserves_exhausted_budget_ifc_label() -> None: + from agent_framework.security import LabelTrackingFunctionMiddleware + + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="private result")], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + tool = MCPTool(name="helper", max_host_payload_size_bytes=128) # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + budget = _FunctionResultPayloadBudget() + assert budget.reserve(128, 128) + tracker = LabelTrackingFunctionMiddleware() + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + result_parser=lambda items: items[0].text, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + host_payload_budget=budget, + mcp_local_label=("trusted", "public"), + trust_server_ifc=True, + ) + + assert function_result.result == "private result" + assert function_result.items is not None + assert function_result.items[0].additional_properties["security_label"] == { + "integrity": "trusted", + "confidentiality": "private", + } + assert tracker.get_context_label().confidentiality.value == "private" + assert "_security_label_authoritative" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + + +@pytest.mark.parametrize("enable_instrumentation", [False, True], indirect=True) +@pytest.mark.usefixtures("span_exporter") +async def test_function_result_parser_failure_preserves_exhausted_budget_ifc_label() -> None: + from agent_framework.security import LabelTrackingFunctionMiddleware + + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="private parser detail")], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + tool = MCPTool(name="helper", max_host_payload_size_bytes=128) # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + budget = _FunctionResultPayloadBudget() + assert budget.reserve(128, 128) + tracker = LabelTrackingFunctionMiddleware() + + def fail_with_result(items: list[Content]) -> str: + raise ValueError(f"parser rejected {items[0].text}") + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + result_parser=fail_with_result, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + host_payload_budget=budget, + mcp_local_label=("trusted", "public"), + trust_server_ifc=True, + include_detailed_errors=True, + ) + + assert "private parser detail" in function_result.result + assert function_result.items is not None + assert function_result.items[0].additional_properties["security_label"] == { + "integrity": "trusted", + "confidentiality": "private", + } + assert tracker.get_context_label().confidentiality.value == "private" + assert "_security_label_authoritative" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + + @pytest.mark.parametrize( ("server_ifc", "expected_integrity", "expected_confidentiality"), [ @@ -2218,10 +2298,22 @@ async def test_oversized_identity_ifc_fails_closed_without_confidentiality_downg "confidentiality": "user_identity", "metadata": {"source": "invalid_mcp_ifc"}, } + assert "_security_label_authoritative" not in function_result.items[0].additional_properties assert "_mcp_tool_result_security_meta" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) -async def test_invalid_identity_ifc_cannot_inherit_local_principals() -> None: +@pytest.mark.parametrize( + "server_principals", + [ + pytest.param(None, id="missing"), + pytest.param([], id="empty"), + pytest.param([{"tenant_id": "tenant-a"}], id="missing-user"), + pytest.param([{"tenant_id": "", "user_id": "user-a"}], id="empty-tenant"), + pytest.param("tenant-a/user-a", id="not-a-sequence-of-mappings"), + ], +) +async def test_invalid_identity_ifc_cannot_inherit_local_principals(server_principals: Any) -> None: from agent_framework.security import ( PRINCIPAL_METADATA_KEY, ConfidentialityLabel, @@ -2232,15 +2324,15 @@ async def test_invalid_identity_ifc_cannot_inherit_local_principals() -> None: ) principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + server_ifc: dict[str, Any] = { + "integrity": "trusted", + "confidentiality": "user_identity", + } + if server_principals is not None: + server_ifc["principals"] = server_principals mcp_result = types.CallToolResult( content=[types.TextContent(type="text", text="identity-scoped result")], - _meta={ - "ifc": { - "integrity": "trusted", - "confidentiality": "user_identity", - "principals": [{"tenant_id": "tenant-a", "user_id": "x" * 5000}], - } - }, + _meta={"ifc": server_ifc}, ) tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] mock_session = Mock() diff --git a/python/packages/core/tests/test_security.py b/python/packages/core/tests/test_security.py index 629b9cd5728..be49c4fa6db 100644 --- a/python/packages/core/tests/test_security.py +++ b/python/packages/core/tests/test_security.py @@ -8362,6 +8362,22 @@ def test_label_from_meta_trusted_public(self): assert label.integrity == IntegrityLabel.TRUSTED assert label.confidentiality == ConfidentialityLabel.PUBLIC + def test_label_from_meta_user_identity_requires_and_preserves_principals(self) -> None: + from agent_framework.security import _label_from_mcp_meta + + principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + label = _label_from_mcp_meta({ + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": principals, + } + }) + + assert label is not None + assert label.confidentiality == ConfidentialityLabel.USER_IDENTITY + assert label.metadata[_PRINCIPALS_KEY] == principals + @pytest.mark.parametrize( "meta", [ @@ -8373,6 +8389,15 @@ def test_label_from_meta_trusted_public(self): {"ifc": {"integrity": "trusted"}}, # missing confidentiality {"ifc": {"integrity": "garbage", "confidentiality": "public"}}, {"ifc": {"integrity": "trusted", "confidentiality": "garbage"}}, + {"ifc": {"integrity": "trusted", "confidentiality": "user_identity"}}, + {"ifc": {"integrity": "trusted", "confidentiality": "user_identity", "principals": []}}, + { + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": [{"tenant_id": "tenant-a"}], + } + }, {"other_key": {"integrity": "trusted", "confidentiality": "public"}}, # non-ifc key ], ) @@ -8440,36 +8465,45 @@ def test_stamp_contents_complete_local_and_remote_label_matrix(self, trust_serve ConfidentialityLabel.PRIVATE: 1, ConfidentialityLabel.USER_IDENTITY: 2, } + local_principals = [{"tenant_id": "tenant-local", "user_id": "user-local"}] + remote_principals = [{"tenant_id": "tenant-remote", "user_id": "user-remote"}] for local_integrity in integrity_labels: for local_confidentiality in confidentiality_labels: for remote_integrity in integrity_labels: for remote_confidentiality in confidentiality_labels: + local_metadata: dict[str, Any] = {"source": "local_mcp_policy"} + if local_confidentiality == ConfidentialityLabel.USER_IDENTITY: + local_metadata[_PRINCIPALS_KEY] = local_principals static = ContentLabel( integrity=local_integrity, confidentiality=local_confidentiality, - metadata={"source": "local_mcp_policy"}, + metadata=local_metadata, ) + remote_ifc: dict[str, Any] = { + "integrity": remote_integrity.value, + "confidentiality": remote_confidentiality.value, + "metadata": {"source": "forged_remote_policy"}, + } + if remote_confidentiality == ConfidentialityLabel.USER_IDENTITY: + remote_ifc["principals"] = remote_principals contents = [ Content.from_text( "x", - additional_properties={ - "_meta": { - "ifc": { - "integrity": remote_integrity.value, - "confidentiality": remote_confidentiality.value, - "metadata": {"source": "forged_remote_policy"}, - } - } - }, + additional_properties={"_meta": {"ifc": remote_ifc}}, ) ] _stamp_mcp_content_labels(contents, static, trust_server_ifc=trust_server_ifc) + expected_metadata: dict[str, Any] | None if trust_server_ifc: expected_integrity = remote_integrity expected_confidentiality = remote_confidentiality - expected_metadata: dict[str, Any] | None = None + expected_metadata = ( + {_PRINCIPALS_KEY: remote_principals} + if remote_confidentiality == ConfidentialityLabel.USER_IDENTITY + else None + ) else: expected_integrity = ( IntegrityLabel.UNTRUSTED @@ -8480,6 +8514,19 @@ def test_stamp_contents_complete_local_and_remote_label_matrix(self, trust_serve (local_confidentiality, remote_confidentiality), key=confidentiality_rank.__getitem__ ) expected_metadata = {"source": "local_mcp_policy"} + if expected_confidentiality == ConfidentialityLabel.USER_IDENTITY: + expected_metadata[_PRINCIPALS_KEY] = [ + *( + local_principals + if local_confidentiality == ConfidentialityLabel.USER_IDENTITY + else [] + ), + *( + remote_principals + if remote_confidentiality == ConfidentialityLabel.USER_IDENTITY + else [] + ), + ] assert contents[0].additional_properties["security_label"] == { "integrity": expected_integrity.value, "confidentiality": expected_confidentiality.value, @@ -8553,6 +8600,40 @@ def test_stamp_contents_unretained_ifc_fails_closed(self) -> None: } assert "_mcp_tool_result_security_meta" not in contents[0].additional_properties + async def test_wrap_mcp_function_invalid_meta_is_serializable_without_tracking(self) -> None: + from agent_framework.security import _wrap_mcp_function_for_ifc + + async def fake_call(**kwargs: Any) -> list[Content]: + return [ + Content.from_text( + "payload", + additional_properties={"_meta": {"ifc": {"integrity": "trusted"}}}, + ) + ] + + function = FunctionTool( + func=fake_call, + name="remote_tool", + description="", + additional_properties={ + "source_integrity": "trusted", + "confidentiality": "public", + "_mcp_remote_name": "remote_tool", + }, + ) + _wrap_mcp_function_for_ifc(function, IntegrityLabel.TRUSTED) + assert function.func is not None + + result = await function.func() + + assert result[0].additional_properties["security_label"] == { + "integrity": "untrusted", + "confidentiality": "user_identity", + "metadata": {"source": "invalid_mcp_ifc"}, + } + assert _AUTHORITY_MARKER_KEY not in result[0].additional_properties + json.dumps(result[0].to_dict()) + def test_stamp_contents_non_ifc_meta_falls_back_to_static(self): """Generic ``_meta`` keys unrelated to IFC don't accidentally produce a label.""" from agent_framework.security import _stamp_mcp_content_labels @@ -8870,13 +8951,13 @@ async def test_framework_stamped_mcp_label_remains_authoritative_through_trackin server_meta=server_meta, ) await apply_mcp_security_labels(mcp_tool, trust_server_ifc=True) - assert function.func is not None - stamped_result = await function.func() + wrapped = function.func + assert wrapped is not None tracker = LabelTrackingFunctionMiddleware() context = FunctionInvocationContext(function=function, arguments={}) async def next_fn() -> None: - context.result = stamped_result + context.result = await wrapped() await tracker.process(context, next_fn) From 2dea793f5d766fbe6bbc2bbfac4bdbcabd2ddc11 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Thu, 12 Nov 2026 14:20:27 +0100 Subject: [PATCH 3/7] Python: adapt MCP replay test after stack merge --- python/packages/core/tests/core/test_mcp.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/python/packages/core/tests/core/test_mcp.py b/python/packages/core/tests/core/test_mcp.py index e96442fc525..7491f79c8bf 100644 --- a/python/packages/core/tests/core/test_mcp.py +++ b/python/packages/core/tests/core/test_mcp.py @@ -2764,9 +2764,9 @@ async def test_hidden_builtin_mcp_result_replays_without_tainting_context() -> N context=second_context, state=restored.state.setdefault(security.source_id, {}), ) - second_tracker, second_policy, _ = second_context.get_middleware() - assert isinstance(second_tracker, LabelTrackingFunctionMiddleware) - assert isinstance(second_policy, PolicyEnforcementFunctionMiddleware) + second_middleware = second_context.get_middleware() + second_tracker = next(item for item in second_middleware if isinstance(item, LabelTrackingFunctionMiddleware)) + second_policy = next(item for item in second_middleware if isinstance(item, PolicyEnforcementFunctionMiddleware)) restored_label = second_tracker.get_context_label() assert restored_label.integrity.value == "trusted" assert restored_label.confidentiality.value == "private" From 063b39c3edd972546e74a2d6418d5900dcdc0ff7 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Thu, 12 Nov 2026 15:12:26 +0100 Subject: [PATCH 4/7] Python: preserve MCP IFC principals and marker scope --- python/packages/core/agent_framework/_mcp.py | 1 + .../packages/core/agent_framework/security.py | 59 ++++- python/packages/core/tests/core/test_mcp.py | 246 ++++++++++++++++++ 3 files changed, 293 insertions(+), 13 deletions(-) diff --git a/python/packages/core/agent_framework/_mcp.py b/python/packages/core/agent_framework/_mcp.py index f57df33f2bb..59f406213a5 100644 --- a/python/packages/core/agent_framework/_mcp.py +++ b/python/packages/core/agent_framework/_mcp.py @@ -398,6 +398,7 @@ def to_carrier(self) -> _FunctionResultCarrier: "_meta", "_security_label_authoritative", "_security_label_authoritative_confidentiality", + "_security_label_validated_principals", _MCP_TOOL_RESULT_SECURITY_META_KEY, }), result_already_parsed=True, diff --git a/python/packages/core/agent_framework/security.py b/python/packages/core/agent_framework/security.py index 184cb980e5a..bb555d208a5 100644 --- a/python/packages/core/agent_framework/security.py +++ b/python/packages/core/agent_framework/security.py @@ -115,6 +115,7 @@ _BARE_REFERENCE_WARNING = "Expanded a bare variable reference in a tool argument; models should use [var_] instead." _UNRESOLVED = object() _AUTHORITATIVE_SECURITY_LABEL = "_security_label_authoritative" +_VALIDATED_SECURITY_LABEL_PRINCIPALS = "_security_label_validated_principals" _INSPECT_VARIABLE_ERROR = "_inspect_variable_error" _INTERNAL_RESULT_MARKER = object() _MAX_VARIABLE_REFERENCE_DEPTH = 16 @@ -2087,6 +2088,11 @@ def list_variables(self) -> list[str]: default=None, ) +_current_function: ContextVar[FunctionTool | None] = ContextVar( + "agent_framework_current_security_function", + default=None, +) + @experimental(feature_id=ExperimentalFeature.FIDES) class LabelTrackingFunctionMiddleware(FunctionMiddleware, _SecurityScopeBinding): @@ -2806,6 +2812,7 @@ async def process( scope_token = self._activate_security_scope(context) middleware_token = _current_middleware.set(self) context_token = _current_context.set(context) + function_token = _current_function.set(context.function) materialization_token: Token[tuple[Any, Callable[[Any], None], asyncio.Task[Any] | None] | None] | None = None try: function_name = context.function.name @@ -2910,6 +2917,7 @@ async def process( finally: if materialization_token is not None: _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT.reset(materialization_token) + _current_function.reset(function_token) _current_context.reset(context_token) _current_middleware.reset(middleware_token) self._active_security_scope.reset(scope_token) @@ -3204,9 +3212,11 @@ def _extract_content_label( """ additional_props = _get_additional_properties(item) authoritative_marker = additional_props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + validated_principals_marker = additional_props.pop(_VALIDATED_SECURITY_LABEL_PRINCIPALS, None) additional_props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) inspect_error_marker = additional_props.pop(_INSPECT_VARIABLE_ERROR, None) authoritative_label = authoritative_marker is _INTERNAL_RESULT_MARKER + validated_principals = validated_principals_marker is _INTERNAL_RESULT_MARKER inspect_error = function_name == "inspect_variable" and inspect_error_marker is _INTERNAL_RESULT_MARKER label_data = additional_props.get("security_label") @@ -3216,13 +3226,14 @@ def _extract_content_label( embedded_label = _parse_content_label( label_map, source="embedded", - allow_principals=authoritative_label, + allow_principals=authoritative_label or validated_principals, ) if authoritative_label: return embedded_label combined_label = combine_labels(fallback_label, embedded_label) if ( - combined_label.confidentiality == ConfidentialityLabel.USER_IDENTITY + not validated_principals + and combined_label.confidentiality == ConfidentialityLabel.USER_IDENTITY and fallback_label.confidentiality == ConfidentialityLabel.USER_IDENTITY ): try: @@ -4711,9 +4722,7 @@ def _validate_service_continuation( return bound_identity = self._service_continuation_identity(state) state_is_authoritative = ( - continuation_identity is not None - and restored_context_label - and bound_identity == continuation_identity + continuation_identity is not None and restored_context_label and bound_identity == continuation_identity ) verified_sources = ( self._verified_service_history_sources(agent, session, context, continuation_identity) @@ -4774,9 +4783,7 @@ async def before_run( "SecureAgentConfig with message_labeler must be registered as a context provider." ) from exc if providers[config_index + 1 :]: - raise ValueError( - "SecureAgentConfig must be the last context provider when message_labeler is set." - ) + raise ValueError("SecureAgentConfig must be the last context provider when message_labeler is set.") provider_source_ids = { provider.source_id for provider in providers[:config_index] @@ -5927,6 +5934,7 @@ def _stamp_mcp_content_labels( continue props = item.additional_properties or {} props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + props.pop(_VALIDATED_SECURITY_LABEL_PRINCIPALS, None) props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) security_meta = props.pop(_MCP_RESULT_SECURITY_META_KEY, None) server_meta = props.pop(_MCP_RESULT_META_KEY, None) @@ -5963,6 +5971,11 @@ def _stamp_mcp_content_labels( props[_AUTHORITATIVE_SECURITY_LABEL] = _INTERNAL_RESULT_MARKER else: label = combine_labels(local_label, dynamic) + if ( + dynamic.confidentiality == ConfidentialityLabel.USER_IDENTITY + and PRINCIPAL_METADATA_KEY in label.metadata + ): + props[_VALIDATED_SECURITY_LABEL_PRINCIPALS] = _INTERNAL_RESULT_MARKER props["security_label"] = label.to_dict() item.additional_properties = props return contents_list @@ -5975,6 +5988,7 @@ def _strip_mcp_authority_markers(contents: str | list[Content]) -> str | list[Co for item in contents: props = item.additional_properties or {} props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + props.pop(_VALIDATED_SECURITY_LABEL_PRINCIPALS, None) props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) item.additional_properties = props return contents @@ -6001,6 +6015,7 @@ def _stamp_parsed_mcp_content_labels( props.pop(_MCP_RESULT_META_KEY, None) props.pop(_MCP_RESULT_SECURITY_META_KEY, None) props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + props.pop(_VALIDATED_SECURITY_LABEL_PRINCIPALS, None) props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) if security_meta is not None: props[_MCP_RESULT_SECURITY_META_KEY] = security_meta @@ -6050,6 +6065,7 @@ def _stamp_mcp_error_carrier_label( stamped_item = stamped[0] stamped_properties = dict(stamped_item.additional_properties) stamped_properties.pop(_AUTHORITATIVE_SECURITY_LABEL, None) + stamped_properties.pop(_VALIDATED_SECURITY_LABEL_PRINCIPALS, None) stamped_properties.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) raw_carrier.item_additional_properties = { **raw_carrier.item_additional_properties, @@ -6072,7 +6088,15 @@ def _current_mcp_local_label(func_tool: FunctionTool, default_integrity: Integri confidentiality = ConfidentialityLabel(props.get("confidentiality", ConfidentialityLabel.PUBLIC.value)) except (TypeError, ValueError): confidentiality = ConfidentialityLabel.PRIVATE - return ContentLabel(integrity=integrity, confidentiality=confidentiality) + metadata: dict[str, Any] | None = None + if confidentiality == ConfidentialityLabel.USER_IDENTITY: + try: + principals = _canonical_principals(props.get(PRINCIPAL_METADATA_KEY), source="local MCP policy") + except ValueError: + pass + else: + metadata = {PRINCIPAL_METADATA_KEY: _principal_list(principals)} + return ContentLabel(integrity=integrity, confidentiality=confidentiality, metadata=metadata) def _wrap_mcp_function_for_ifc(func_tool: FunctionTool, default_integrity: IntegrityLabel) -> None: @@ -6100,8 +6124,18 @@ async def _wrapped(*args: Any, **kwargs: Any) -> Any: None, ) + def has_matching_tracker() -> bool: + active_context = _current_context.get() + return ( + _current_middleware.get() is not None + and active_context is not None + and _current_function.get() is func_tool + and (invocation_context is None or active_context is invocation_context) + ) + def prepare_error_label() -> None: - if invocation_context is None: + active_middleware = _current_middleware.get() + if invocation_context is None or active_middleware is None or not has_matching_tracker(): return active_context = invocation_context raw_fallback_label = active_context.metadata.get(_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY) @@ -6112,8 +6146,7 @@ def prepare_error_label() -> None: fallback_label, trust_server_ifc=trust_server_ifc, ) - active_middleware = _current_middleware.get() - if error_label is None or active_middleware is None or _current_context.get() is not active_context: + if error_label is None: return raw_carrier = active_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) if not isinstance(raw_carrier, _FunctionResultCarrier): @@ -6137,7 +6170,7 @@ def commit_error_label() -> None: prepare_error_label() raise - retain_authority = _current_middleware.get() is not None + retain_authority = has_matching_tracker() if invocation_context is not None: raw_carrier = invocation_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) if isinstance(raw_carrier, _FunctionResultCarrier): diff --git a/python/packages/core/tests/core/test_mcp.py b/python/packages/core/tests/core/test_mcp.py index 7491f79c8bf..afa63a00d66 100644 --- a/python/packages/core/tests/core/test_mcp.py +++ b/python/packages/core/tests/core/test_mcp.py @@ -2399,6 +2399,252 @@ def identity_destination() -> str: assert executed is False +@pytest.mark.parametrize("use_result_parser", [False, True], ids=["builtin-parser", "function-parser"]) +@pytest.mark.parametrize("exhaust_budget", [False, True], ids=["available-budget", "exhausted-budget"]) +async def test_restriction_only_identity_ifc_preserves_principals_across_session_restore( + tmp_path: Path, + use_result_parser: bool, + exhaust_budget: bool, +) -> None: + from agent_framework.security import ( + PRINCIPAL_METADATA_KEY, + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + ) + + local_principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + server_principals = [{"tenant_id": "tenant-a", "user_id": "user-b"}] + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="identity-scoped result")], + _meta={ + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": server_principals, + } + }, + ) + tool = MCPTool(name="helper", max_host_payload_size_bytes=512) # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + budget = _FunctionResultPayloadBudget() + if exhaust_budget: + assert budget.reserve(512, 512) + tracker = LabelTrackingFunctionMiddleware() + session = AgentSession( + session_id=f"identity-principals-{'parser' if use_result_parser else 'builtin'}-" + f"{'exhausted' if exhaust_budget else 'available'}" + ) + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + result_parser=(lambda items: items[0].text) if use_result_parser else None, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + host_payload_budget=budget, + mcp_local_label=("trusted", "user_identity"), + mcp_local_principals=local_principals, + invocation_session=session, + trust_server_ifc=False, + ) + + expected_principals = [*local_principals, *server_principals] + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["metadata"][PRINCIPAL_METADATA_KEY] == expected_principals + assert tracker.get_context_label(session).metadata[PRINCIPAL_METADATA_KEY] == expected_principals + assert "_security_label_authoritative" not in function_result.items[0].additional_properties + assert "_security_label_validated_principals" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + + store = FileSessionStore(tmp_path / session.session_id, serialization_format="json") + await store.set(session.session_id, session) + restored = await store.get(session.session_id) + assert restored is not None + restored_tracker = LabelTrackingFunctionMiddleware() + restored_label = restored_tracker.get_context_label(restored) + assert restored_label.metadata[PRINCIPAL_METADATA_KEY] == expected_principals + + executed = False + + def local_identity_sink() -> str: + nonlocal executed + executed = True + return "sent" + + destination = FunctionTool( + name="local_identity_sink", + description="Identity-scoped destination for the local principal", + func=local_identity_sink, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: local_principals, + }, + ) + + with pytest.raises(MiddlewareTermination): + await _auto_invoke_function( + Content.from_function_call(call_id="destination-call", name=destination.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={destination.name: destination}, + invocation_session=restored, + middleware_pipeline=FunctionMiddlewarePipeline( + restored_tracker, + PolicyEnforcementFunctionMiddleware(), + ), + ) + + assert executed is False + + +async def test_restriction_only_identity_ifc_preserves_argument_restrictions() -> None: + from agent_framework.security import ( + PRINCIPAL_METADATA_KEY, + ConfidentialityLabel, + ContentLabel, + IntegrityLabel, + LabelTrackingFunctionMiddleware, + ) + + local_principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + server_principals = [{"tenant_id": "tenant-a", "user_id": "user-b"}] + argument_principals = [{"tenant_id": "tenant-a", "user_id": "user-c"}] + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="identity-scoped result")], + _meta={ + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": server_principals, + } + }, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + tracker = LabelTrackingFunctionMiddleware(auto_hide_untrusted=False) + variable_id = tracker.get_variable_store().store( + "identity-scoped argument", + ContentLabel( + integrity=IntegrityLabel.TRUSTED, + confidentiality=ConfidentialityLabel.USER_IDENTITY, + metadata={PRINCIPAL_METADATA_KEY: argument_principals}, + ), + ) + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + mcp_local_label=("trusted", "user_identity"), + mcp_local_principals=local_principals, + trust_server_ifc=False, + value=f"[{variable_id}]", + ) + + expected_principals = [*local_principals, *server_principals, *argument_principals] + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "user_identity" + assert result_label["metadata"][PRINCIPAL_METADATA_KEY] == expected_principals + context_label = tracker.get_context_label() + assert context_label.integrity == IntegrityLabel.TRUSTED + assert context_label.metadata[PRINCIPAL_METADATA_KEY] == expected_principals + + +@pytest.mark.parametrize("reuse_outer_context", [False, True], ids=["fresh-inner-context", "reused-outer-context"]) +@pytest.mark.parametrize( + ("server_ifc", "trust_server_ifc", "expected_integrity", "expected_confidentiality"), + [ + pytest.param( + {"integrity": "trusted"}, + False, + "untrusted", + "user_identity", + id="invalid-ifc", + ), + pytest.param( + {"integrity": "trusted", "confidentiality": "public"}, + True, + "trusted", + "private", + id="trusted-authoritative-ifc", + ), + ], +) +async def test_nested_direct_mcp_invocation_strips_unconsumed_authority_marker( + reuse_outer_context: bool, + server_ifc: dict[str, str], + trust_server_ifc: bool, + expected_integrity: str, + expected_confidentiality: str, +) -> None: + from agent_framework.security import IntegrityLabel, LabelTrackingFunctionMiddleware, _wrap_mcp_function_for_ifc + + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="nested result")], + _meta={"ifc": server_ifc}, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + inner_tool = FunctionTool( + name="inner_widget", + description="", + func=_make_mcp_tool_caller(tool, "inner_widget"), + input_model={"type": "object", "properties": {}}, + additional_properties={ + "_mcp_remote_name": "inner_widget", + "source_integrity": "trusted", + "confidentiality": "public", + "_mcp_trust_server_ifc": trust_server_ifc, + }, + ) + _wrap_mcp_function_for_ifc(inner_tool, IntegrityLabel.TRUSTED) + + async def invoke_nested(context: FunctionInvocationContext) -> list[Content]: + inner_context = context if reuse_outer_context else FunctionInvocationContext(function=inner_tool, arguments={}) + inner_result = await inner_tool.invoke(arguments={}, context=inner_context) + assert isinstance(inner_result, list) + assert "_security_label_authoritative" not in inner_result[0].additional_properties + assert "_security_label_validated_principals" not in inner_result[0].additional_properties + json.dumps([item.to_dict() for item in inner_result]) + return inner_result + + outer_tool = FunctionTool( + name="outer_tool", + description="Tracked tool that directly invokes an MCP function", + func=invoke_nested, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "confidentiality": "private", + }, + ) + tracker = LabelTrackingFunctionMiddleware(auto_hide_untrusted=False) + + function_result = await _auto_invoke_function( + Content.from_function_call(call_id="outer-call", name=outer_tool.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={outer_tool.name: outer_tool}, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + ) + + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == expected_integrity + assert result_label["confidentiality"] == expected_confidentiality + assert "_security_label_authoritative" not in function_result.items[0].additional_properties + assert "_security_label_validated_principals" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + + async def test_oversized_mcp_meta_is_omitted_from_host_and_model_items() -> None: mcp_result = types.CallToolResult( content=[types.TextContent(type="text", text="ok")], From 2381db5d43b096ea46f2c658645b2b737d328109 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Fri, 13 Nov 2026 09:08:13 +0100 Subject: [PATCH 5/7] Python: reuse IFC invocation authority --- python/packages/core/agent_framework/security.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/python/packages/core/agent_framework/security.py b/python/packages/core/agent_framework/security.py index bb555d208a5..d0f459cb6e8 100644 --- a/python/packages/core/agent_framework/security.py +++ b/python/packages/core/agent_framework/security.py @@ -2088,11 +2088,6 @@ def list_variables(self) -> list[str]: default=None, ) -_current_function: ContextVar[FunctionTool | None] = ContextVar( - "agent_framework_current_security_function", - default=None, -) - @experimental(feature_id=ExperimentalFeature.FIDES) class LabelTrackingFunctionMiddleware(FunctionMiddleware, _SecurityScopeBinding): @@ -2812,7 +2807,6 @@ async def process( scope_token = self._activate_security_scope(context) middleware_token = _current_middleware.set(self) context_token = _current_context.set(context) - function_token = _current_function.set(context.function) materialization_token: Token[tuple[Any, Callable[[Any], None], asyncio.Task[Any] | None] | None] | None = None try: function_name = context.function.name @@ -2917,7 +2911,6 @@ async def process( finally: if materialization_token is not None: _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT.reset(materialization_token) - _current_function.reset(function_token) _current_context.reset(context_token) _current_middleware.reset(middleware_token) self._active_security_scope.reset(scope_token) @@ -6126,10 +6119,13 @@ async def _wrapped(*args: Any, **kwargs: Any) -> Any: def has_matching_tracker() -> bool: active_context = _current_context.get() + if active_context is None: + return False + active_authority = active_context.metadata.get(_SECURITY_RESOLVED_AUTHORITY_CONTEXT_KEY) return ( _current_middleware.get() is not None - and active_context is not None - and _current_function.get() is func_tool + and isinstance(active_authority, _SecurityInvocationAuthority) + and active_authority.function is func_tool and (invocation_context is None or active_context is invocation_context) ) From 1e53250252f1991906d29629249b65d0fc0f23f8 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Fri, 13 Nov 2026 11:08:25 +0100 Subject: [PATCH 6/7] refactor MCP IFC result handling --- python/packages/core/AGENTS.md | 1 + python/packages/core/agent_framework/_mcp.py | 145 ++++-- .../packages/core/agent_framework/_skills.py | 123 ++++- .../packages/core/agent_framework/_tools.py | 115 ++++- .../packages/core/agent_framework/security.py | 485 +++++++++++++----- python/packages/core/tests/core/test_mcp.py | 309 ++++++++++- .../core/tests/core/test_mcp_skills.py | 470 ++++++++++++++++- python/packages/core/tests/test_security.py | 192 ++++--- .../_execute_code_tool.py | 1 + .../hyperlight/test_hyperlight_codeact.py | 1 + .../_execute_code_tool.py | 1 + .../monty/tests/monty/test_monty_codeact.py | 1 + .../security/FIDES_DEVELOPER_GUIDE.md | 39 +- python/samples/02-agents/security/README.md | 9 +- .../02-agents/security/github_mcp_example.py | 30 +- 15 files changed, 1612 insertions(+), 310 deletions(-) diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index 441a4dc6801..e6fa66d8221 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -228,6 +228,7 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID - **`SkillsProvider`** - Context provider (extends `ContextProvider`) that discovers file-based skills from `SKILL.md` files and/or accepts code-defined `Skill` instances. Follows progressive disclosure: advertise → load → read resources / run scripts. By default all three tools it exposes (`load_skill`, `read_skill_resource`, `run_skill_script`) are registered with `approval_mode="always_require"`, so every skill operation needs approval. To run unattended, pass one of the static auto-approval rules to `ToolApprovalMiddleware` (via `auto_approval_rules`): `SkillsProvider.read_only_tools_auto_approval_rule` approves only the read-only tools (`load_skill`, `read_skill_resource`) while still prompting for `run_skill_script`, and `SkillsProvider.all_tools_auto_approval_rule` approves every skill tool including script execution. Both rules reject any call carrying a `server_label` so they stay scoped to this provider's local tools and never auto-approve a same-named hosted tool. Alternatively, for trusted skills, the constructor / `from_paths` kwargs `disable_load_skill_approval`, `disable_read_skill_resource_approval`, and `disable_run_skill_script_approval` (all default `False`) opt individual tools out of approval entirely by registering them with `approval_mode="never_require"` (the auto-approval rules only apply to tools that still require approval). The tool names are also exposed as class constants (`LOAD_SKILL_TOOL_NAME`, `READ_SKILL_RESOURCE_TOOL_NAME`, `RUN_SKILL_SCRIPT_TOOL_NAME`). - **`FileSkillsSource`** - `SkillsSource` that discovers file-based skills by scanning configured root paths for `SKILL.md`. The **configured root paths define the trust boundary** and are used as given (a root may itself be a symlink); everything discovered *below* a root is link-checked and fails closed. `_discover_skill_directories` rejects any entry that is a symbolic link, junction, or other reparse point (via the shared `agent_framework._filesystem.is_link_or_reparse_point` helper) before descending into it, and rejects a directory whose `SKILL.md` is itself such a link — otherwise a link planted under a root would be adopted as the skill root, and since every later guard treats the skill root as the boundary and only inspects segments below it, the link itself would never be inspected. Resource and script discovery apply the same rule per path segment via `_has_link_or_reparse_point_in_path`; source-discovered resources and scripts retain a `_SkillPathScope` pairing their configured root with their skill directory, and repeat containment, regular-file, and link checks immediately before reading or execution — scanning every segment from the configured root down to the file, so a skill directory (or any directory between it and the root) swapped for a link after discovery is rejected too. An `OSError` while inspecting an entry is treated as unsafe (skip / reject), never as "safe". - **`MCPSkillsSource`** - `SkillsSource` that discovers Agent Skills served over MCP by reading the well-known `skill://index.json` (SEP-2640). Index entries are dispatched by their `type` (case-insensitive): `skill-md` entries become one `MCPSkill` each (its `SKILL.md` body and sibling resources are fetched on demand via `resources/read`), and `archive` entries are downloaded as a single ZIP blob and unpacked **entirely in memory** (via the private `_ArchiveEntryLoader`) into a `FileSkill` whose `SKILL.md` body drives it and whose sibling files (matching the resource extensions, within the search depth) become in-memory `InlineSkillResource` resources. **Nothing is written to disk** — there are no temporary directories to create, own, or prune (this is a deliberate divergence from .NET, which extracts ZIP archives to disk; it removes the temp-dir leak and the dangerous prune-of-unowned-subdirs footgun). Entries whose type has no handler (e.g. `mcp-resource-template`) are skipped. **MCP-delivered scripts are never runnable**: the loader emits no `SkillScript`s, so a bundled script can at most surface as a readable resource (and only if it matches the resource extensions — `.py` is not a default resource extension). The archive `SKILL.md` frontmatter `name` must match the advertised index-entry `name` or the skill is skipped. ZIP extraction is hardened: a `..` path-traversal ("zip-slip") member name raises via `_normalize_archive_member_name` and aborts the whole skill (like the file-count/size limits), and file-count / uncompressed-size (`_read_member_with_limit`) / download-size limits are enforced. Archive behavior is configured with `archive_*` constructor kwargs (`archive_resource_extensions`, `archive_resource_search_depth`, `archive_max_file_count`, `archive_max_size_bytes`, `archive_max_uncompressed_size_bytes`) — Python uses plain kwargs, not a `*Options` object as in .NET. A non-"resource not found" error while downloading an archive propagates (so a failed `CachingSkillsSource` refresh does not overwrite a cached list with a partial result). Unlike .NET's `AgentMcpSkillsSourceOptions.RefreshInterval`, this source has no built-in refresh interval; wrap it in `CachingSkillsSource(..., refresh_interval=...)` for caching/refresh. This is a port of .NET PR #6631; the `FileSkillsSource` `script_extensions`/`resource_extensions` kwargs default to the built-in tuples and treat `None` as "use defaults" and an empty tuple as "discover none" (an empty tuple previously fell back to defaults). `FoundryToolbox.as_skills_provider()` forwards matching `archive_*` kwargs to this source. +- **MCP Skills IFC** - Direct `MCPSkillsSource(...)` construction preserves its existing unlabeled behavior. `SecureMCPToolProxy.skills_source()` injects an operation-scoped result adapter so each lazy `SKILL.md`, sibling resource, or archive read applies that read's retained `_meta.ifc` only after the built-in FunctionTool's final parser. Index metadata never labels later reads, and archive members inherit only the archive download's label. - **`SkillsSource` decorators** - Skill sources are composable: `SkillsSource` is the abstract base, with concrete sources (`InMemorySkillsSource`, `FileSkillsSource`, `MCPSkillsSource`) and decorators that wrap an inner source — `AggregatingSkillsSource` (concatenate several sources), `FilteringSkillsSource` (predicate filter), `DeduplicatingSkillsSource` (first-wins by name), and `CachingSkillsSource` (cache the inner source's skills list). `DelegatingSkillsSource` is the abstract base for decorators. **`get_skills` takes a `SkillsSourceContext`**: every source/decorator implements `async def get_skills(self, context: SkillsSourceContext) -> list[Skill]` and forwards `context` to inner sources. `SkillsSourceContext` (frozen) carries the invoking `agent` (`SupportsAgentRun`) and optional `session` (`AgentSession | None`); `SkillsProvider` builds it from `before_run`'s `agent`/`session` and passes it into the pipeline. `FilteringSkillsSource`'s predicate is context-aware: `Callable[[Skill, SkillsSourceContext], bool]` (port of .NET #6797). **Default caching is applied only to the built-in, context-independent leaf sources**: for the `Skill` / sequence-of-skills / `from_paths` constructors, `SkillsProvider` builds `DeduplicatingSkillsSource(CachingSkillsSource())` so expensive filesystem/network discovery runs once. A **caller-supplied `SkillsSource` is used as-is — never auto-wrapped in caching or deduplication** — because auto-caching a context-aware caller source in a single shared bucket would replay the first invocation's skills for later `SkillsSourceContext`s and leak skills across agents/tenants (matches .NET, whose custom-source constructor also adds no caching/dedup). Callers who want caching on a custom pipeline compose `CachingSkillsSource(inner, cache_isolation_key_selector=...)` themselves. `disable_caching=True` only affects the built-in leaf caching (it has no effect on a caller-supplied source, which is never cached). `CachingSkillsSource` shares a single in-flight fetch across concurrent callers (per cache key) and does not update its cache on a failed fetch, so the next call retries (an initial failure leaves the cache empty; a refresh failure keeps the previously cached list). By default all callers share one cache bucket; pass `cache_isolation_key_selector=Callable[[SkillsSourceContext], str | None]` to cache separately per key (e.g. per agent name) for context-aware inner sources — the key should be low-cardinality and stable, and returning `None` (or leaving the selector `None`) uses the shared bucket. By default a cached list never expires; pass `refresh_interval=timedelta(...)` (port of .NET `CachingAgentSkillsSourceOptions.RefreshInterval`) to treat a cached list as stale once it is older than the interval so the next call re-queries the inner source (useful when an inner source such as `MCPSkillsSource` changes over the process lifetime; a zero/negative interval makes every result immediately stale, and a failed refresh keeps the prior list and retries). Freshness is measured with a monotonic clock (`time.monotonic()`). `SkillsProvider.__init__` / `from_paths` expose a `cache_refresh_interval` kwarg that is threaded into the built-in `CachingSkillsSource` (it has no effect on a caller-supplied source or when `disable_caching=True`). **`MCPSkillsSource` and `MCPSkill` accept exactly one of `client` (a fixed, already-entered high-level `Client` or deprecated caller-owned `ClientSession`) or the compatibility-named `session_provider` (`Callable[[], Client | ClientSession]`, resolved on every fetch); providing both/neither raises `ValueError`.** The source borrows the supplied connection and never enters or closes it. Use `session_provider` when an owner replaces its connection over time, so cached `MCPSkill`s keep fetching through the current normalized connection without reading `MCPTool.session`. - **MCP archive digests** - `MCPSkillsSource` verifies each non-null archive `digest` against the decoded ZIP bytes after the download-size guard and before extraction. The accepted form is `sha256:` followed by 64 lowercase hexadecimal characters. Omitted/null digests remain supported; malformed values (including non-string JSON), unsupported algorithms, and mismatches warn and skip only that archive. A successful `CachingSkillsSource` refresh therefore replaces its list without rejected archives; transport errors still propagate and leave the stored cache unchanged. Verification does not apply to lazy `skill-md` entries or their supporting resources. A digest only proves consistency with the index, not that the server or skill content is trustworthy. diff --git a/python/packages/core/agent_framework/_mcp.py b/python/packages/core/agent_framework/_mcp.py index 59f406213a5..67046efc169 100644 --- a/python/packages/core/agent_framework/_mcp.py +++ b/python/packages/core/agent_framework/_mcp.py @@ -244,8 +244,18 @@ class MCPSpecificApproval(TypedDict, total=False): }) # object is a reference to the owner of the headers, so we keep track which headers belong to which tool _mcp_call_headers: ContextVar[tuple[object, dict[str, str]] | None] = ContextVar("_mcp_call_headers") -_mcp_tool_runtime_context: ContextVar[tuple[object, Mapping[str, Any]] | None] = ContextVar( - "_mcp_tool_runtime_context", default=None + + +@dataclass(frozen=True) +class _MCPToolRuntimeContext: + owner: object + runtime_kwargs: Mapping[str, Any] + result_capture: _MCPResultCapture | None = None + + +_mcp_tool_runtime_context: ContextVar[_MCPToolRuntimeContext | None] = ContextVar( + "_mcp_tool_runtime_context", + default=None, ) _MCP_HEADER_OWNER_EXTENSION = "agent_framework.mcp_header_owner" _MCP_INJECTED_HEADER_KEYS_EXTENSION = "agent_framework.mcp_injected_header_keys" @@ -280,13 +290,42 @@ class _MCPDiscoveryRestart(Exception): """Restart staged discovery when its connection is replaced.""" +def _retain_mcp_result_security_meta(mcp_type: Any) -> dict[str, Any] | None: + """Retain bounded, JSON-safe MCP IFC metadata independently of generic payload budgets.""" + raw_meta = getattr(mcp_type, "meta", None) + if not isinstance(raw_meta, Mapping) or "ifc" not in raw_meta: + return None + + raw_meta_mapping = cast(Mapping[str, Any], raw_meta) + raw_security_meta: dict[str, Any] = {"ifc": raw_meta_mapping["ifc"]} + if _json_size_exceeds(raw_security_meta, _MAX_MCP_SECURITY_META_SIZE_BYTES): + logger.warning("MCP result _meta.ifc exceeds the independent security metadata limit.") + return {"retained": False} + + try: + copied = cast( + dict[str, Any], + to_jsonable_python(raw_security_meta, fallback=str), + ) + except (TypeError, ValueError): + logger.warning("MCP result _meta.ifc could not be retained safely.") + return {"retained": False} + + if len(json.dumps(copied).encode("utf-8")) > _MAX_MCP_SECURITY_META_SIZE_BYTES: + logger.warning("MCP result _meta.ifc exceeds the independent security metadata limit.") + return {"retained": False} + + return {"retained": True, "meta": copied} + + @dataclass -class _MCPHostPayloadCapture: +class _MCPResultCapture: """Collect one generated MCP result without affecting its public return shape.""" max_size_bytes: int | None aggregate_budget: _FunctionResultPayloadBudget | None apply_server_meta_to_model_items: bool + retain_generic_payload: bool = True host_payload: dict[str, Any] | None = None meta: dict[str, Any] | None = None security_meta: dict[str, Any] | None = None @@ -299,34 +338,7 @@ def prepare_security_meta(self, mcp_type: Any) -> dict[str, Any] | None: if self.security_meta_prepared: return self.security_meta self.security_meta_prepared = True - - raw_meta = getattr(mcp_type, "meta", None) - if not isinstance(raw_meta, Mapping) or "ifc" not in raw_meta: - return None - - raw_meta_mapping = cast(Mapping[str, Any], raw_meta) - raw_security_meta: dict[str, Any] = {"ifc": raw_meta_mapping["ifc"]} - if _json_size_exceeds(raw_security_meta, _MAX_MCP_SECURITY_META_SIZE_BYTES): - logger.warning("MCP result _meta.ifc exceeds the independent security metadata limit.") - self.security_meta = {"retained": False} - return self.security_meta - - try: - copied = cast( - dict[str, Any], - to_jsonable_python(raw_security_meta, fallback=str), - ) - except (TypeError, ValueError): - logger.warning("MCP result _meta.ifc could not be retained safely.") - self.security_meta = {"retained": False} - return self.security_meta - - if len(json.dumps(copied).encode("utf-8")) > _MAX_MCP_SECURITY_META_SIZE_BYTES: - logger.warning("MCP result _meta.ifc exceeds the independent security metadata limit.") - self.security_meta = {"retained": False} - return self.security_meta - - self.security_meta = {"retained": True, "meta": copied} + self.security_meta = _retain_mcp_result_security_meta(mcp_type) return self.security_meta def prepare_meta(self, mcp_type: Any) -> dict[str, Any] | None: @@ -358,6 +370,8 @@ def record(self, mcp_type: Any) -> None: return self.recorded = True self.prepare_security_meta(mcp_type) + if not self.retain_generic_payload: + return self.prepare_meta(mcp_type) effective_limit = self.max_size_bytes @@ -421,12 +435,6 @@ def prepare_model_result(self, parsed: str | list[Content]) -> list[Content]: return items -_mcp_host_payload_capture: ContextVar[_MCPHostPayloadCapture | None] = ContextVar( - "_mcp_host_payload_capture", - default=None, -) - - class _EncodedSizeBudget: """Track JSON bytes and abort as soon as an untrusted value exceeds its budget.""" @@ -593,8 +601,13 @@ def _mcp_tool_result_meta( return meta -def _capture_mcp_tool_result(mcp_type: Any) -> None: - capture = _mcp_host_payload_capture.get() +def _capture_mcp_result(owner: object, mcp_type: Any) -> None: + runtime_context = _mcp_tool_runtime_context.get() + capture = ( + runtime_context.result_capture + if runtime_context is not None and runtime_context.owner is owner + else None + ) if capture is not None: capture.record(mcp_type) @@ -1034,19 +1047,23 @@ async def _call_tool_with_runtime_kwargs( else: call_kwargs.pop("_meta", None) raw_budget = ctx.metadata.get(_FUNCTION_RESULT_PAYLOAD_BUDGET_CONTEXT_KEY) - capture = _MCPHostPayloadCapture( + capture = _MCPResultCapture( max_size_bytes=mcp_tool.max_host_payload_size_bytes, aggregate_budget=raw_budget if isinstance(raw_budget, _FunctionResultPayloadBudget) else None, apply_server_meta_to_model_items=mcp_tool.parse_tool_results is None, ) - token = _mcp_host_payload_capture.set(capture) - runtime_token = _mcp_tool_runtime_context.set((mcp_tool, dict(ctx.kwargs))) + runtime_token = _mcp_tool_runtime_context.set( + _MCPToolRuntimeContext( + owner=mcp_tool, + runtime_kwargs=dict(ctx.kwargs), + result_capture=capture, + ) + ) try: parsed = await mcp_tool.call_tool(remote_tool_name, **call_kwargs) return capture.prepare_model_result(parsed) finally: _mcp_tool_runtime_context.reset(runtime_token) - _mcp_host_payload_capture.reset(token) ctx.metadata[_FUNCTION_RESULT_CARRIER_CONTEXT_KEY] = capture.to_carrier() return _call_tool_with_runtime_kwargs @@ -1062,11 +1079,29 @@ async def _call_prompt_with_runtime_kwargs( ctx: FunctionInvocationContext, **kwargs: Any, ) -> str: - return await mcp_tool._call_prompt_with_runtime_kwargs( # pyright: ignore[reportPrivateUsage] - remote_prompt_name, - kwargs, - ctx.kwargs, + raw_budget = ctx.metadata.get(_FUNCTION_RESULT_PAYLOAD_BUDGET_CONTEXT_KEY) + capture = _MCPResultCapture( + max_size_bytes=mcp_tool.max_host_payload_size_bytes, + aggregate_budget=raw_budget if isinstance(raw_budget, _FunctionResultPayloadBudget) else None, + apply_server_meta_to_model_items=False, + retain_generic_payload=False, ) + runtime_token = _mcp_tool_runtime_context.set( + _MCPToolRuntimeContext( + owner=mcp_tool, + runtime_kwargs=dict(ctx.kwargs), + result_capture=capture, + ) + ) + try: + return await mcp_tool._call_prompt_with_runtime_kwargs( # pyright: ignore[reportPrivateUsage] + remote_prompt_name, + kwargs, + ctx.kwargs, + ) + finally: + _mcp_tool_runtime_context.reset(runtime_token) + ctx.metadata[_FUNCTION_RESULT_CARRIER_CONTEXT_KEY] = capture.to_carrier() return _call_prompt_with_runtime_kwargs @@ -1504,7 +1539,12 @@ def _parse_tool_result_from_mcp( """ from mcp import types - capture = _mcp_host_payload_capture.get() + runtime_context = _mcp_tool_runtime_context.get() + capture = ( + runtime_context.result_capture + if runtime_context is not None and runtime_context.owner is self + else None + ) if capture is not None: capture.prepare_security_meta(mcp_type) meta = capture.prepare_meta(mcp_type) @@ -3781,7 +3821,7 @@ async def _call_tool_with_retries( span_error_recorded = False try: result = await self._invoke_tool(tool_name, kwargs, trace_context) - _capture_mcp_tool_result(result) + _capture_mcp_result(self, result) if result.is_error: parsed = parser(result) text = ( @@ -3939,6 +3979,7 @@ async def get_prompt(self, prompt_name: str, **kwargs: Any) -> str: close_generation = self._close_generation try: prompt_result = await self._invoke_prompt(prompt_name, kwargs) + _capture_mcp_result(self, prompt_result) return parser(prompt_result) except ClosedResourceError as cl_ex: if attempt == 0: @@ -5174,7 +5215,11 @@ async def call_tool(self, tool_name: str, **kwargs: Any) -> str | list[Content]: A list of Content items representing the tool output. """ runtime_context = _mcp_tool_runtime_context.get() - header_kwargs = runtime_context[1] if runtime_context is not None and runtime_context[0] is self else kwargs + header_kwargs = ( + runtime_context.runtime_kwargs + if runtime_context is not None and runtime_context.owner is self + else kwargs + ) headers = self._effective_headers(header_kwargs) with self._http_headers(headers, header_kwargs): return await super().call_tool(tool_name, **kwargs) diff --git a/python/packages/core/agent_framework/_skills.py b/python/packages/core/agent_framework/_skills.py index 4fd42e7ddf5..841c4858e89 100644 --- a/python/packages/core/agent_framework/_skills.py +++ b/python/packages/core/agent_framework/_skills.py @@ -96,6 +96,7 @@ _FUNCTION_RESULT_CARRIER_CONTEXT_KEY, # pyright: ignore[reportPrivateUsage] ApprovalMode, FunctionTool, + _FunctionResultAdapter, # pyright: ignore[reportPrivateUsage] _FunctionResultCarrier, # pyright: ignore[reportPrivateUsage] ) from ._types import SKILL_CONTEXT_NAME_KEY @@ -2106,6 +2107,8 @@ def _contains_surrogate_code_points(value: str) -> bool: # region SkillsProvider _TSkillsProvider = TypeVar("_TSkillsProvider", bound="SkillsProvider") +_SkillResultAdapter: TypeAlias = _FunctionResultAdapter +_SkillResultAdapterFactory: TypeAlias = Callable[["ReadResourceResult"], _SkillResultAdapter | None] class SkillsProvider(ContextProvider): @@ -2896,17 +2899,37 @@ def _find_skill(skills: Sequence[Skill], name: str) -> Skill | None: return next((s for s in skills if s.frontmatter.name.lower() == name_lower), None) @staticmethod - def _record_skill_context(context: FunctionInvocationContext | None, skill: Skill) -> None: + def _record_skill_context( + context: FunctionInvocationContext | None, + skill: Skill, + result_adapter: _SkillResultAdapter | None = None, + ) -> None: """Attach the resolved skill identity without changing model-facing output.""" - if context is not None: - carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) - if isinstance(carrier, _FunctionResultCarrier): - carrier.additional_properties[SKILL_CONTEXT_NAME_KEY] = skill.frontmatter.name - else: - context.metadata[_FUNCTION_RESULT_CARRIER_CONTEXT_KEY] = _FunctionResultCarrier( - additional_properties={SKILL_CONTEXT_NAME_KEY: skill.frontmatter.name}, - item_additional_properties={}, - ) + if context is None: + return + + carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if not isinstance(carrier, _FunctionResultCarrier): + carrier = _FunctionResultCarrier( + additional_properties={}, + item_additional_properties={}, + ) + context.metadata[_FUNCTION_RESULT_CARRIER_CONTEXT_KEY] = carrier + + carrier.additional_properties[SKILL_CONTEXT_NAME_KEY] = skill.frontmatter.name + if result_adapter is not None: + carrier.result_adapter = result_adapter + + @staticmethod + def _read_result_adapter( + skill: Skill, + resource: SkillResource | None = None, + ) -> _SkillResultAdapter | None: + if resource is not None: + resource_adapter = getattr(resource, "_result_adapter", None) + if resource_adapter is not None: + return cast(_SkillResultAdapter | None, resource_adapter) + return cast(_SkillResultAdapter | None, getattr(skill, "_result_adapter", None)) async def _load_skill( self, @@ -2941,7 +2964,7 @@ async def _load_skill( logger.info("Loading skill: %s", skill_name) content = await skill.get_content() - self._record_skill_context(context, skill) + self._record_skill_context(context, skill, self._read_result_adapter(skill)) return content async def _run_skill_script( @@ -3062,7 +3085,7 @@ async def _read_skill_resource( logger.exception("Failed to read resource '%s' from skill '%s'", resource_name, skill_name) raise - self._record_skill_context(context, skill) + self._record_skill_context(context, skill, self._read_result_adapter(skill, resource)) return result @@ -4702,15 +4725,23 @@ class MCPSkillResource(SkillResource): extracts text or binary content from the result. """ - def __init__(self, *, name: str, result: ReadResourceResult) -> None: + def __init__( + self, + *, + name: str, + result: ReadResourceResult, + _result_adapter_factory: _SkillResultAdapterFactory | None = None, + ) -> None: """Initialize an MCPSkillResource. Args: name: The resource name (e.g. a relative path or identifier). result: The result returned by the MCP server's ``resources/read`` request. + _result_adapter_factory: Private factory for adapting the built-in tool result. """ super().__init__(name=name) self._result = result + self._result_adapter = _result_adapter_factory(result) if _result_adapter_factory is not None else None async def read(self, **kwargs: Any) -> Any: """Read the resource content. @@ -4785,6 +4816,7 @@ def __init__( client: Client | ClientSession | None = None, *, session_provider: Callable[[], Client | ClientSession] | None = None, + _result_adapter_factory: _SkillResultAdapterFactory | None = None, ) -> None: """Initialize an MCPSkill. @@ -4804,6 +4836,8 @@ def __init__( high-level Client or low-level ClientSession, resolved on every fetch. Use it when the owner may replace the underlying connection; MCPSkill borrows each returned connection and never enters or closes it. + _result_adapter_factory: Private factory for adapting each successful + MCP resource read at the built-in skill tool boundary. Raises: ValueError: If both or neither of *client* and *session_provider* are @@ -4813,7 +4847,9 @@ def __init__( self._skill_md_uri = skill_md_uri self._skill_root_uri = self._compute_skill_root_uri(skill_md_uri) self._connection_provider = _resolve_mcp_connection_provider(client, session_provider) + self._result_adapter_factory = _result_adapter_factory self._content: str | None = None + self._result_adapter: _SkillResultAdapter | None = None @property def frontmatter(self) -> SkillFrontmatter: @@ -4840,7 +4876,9 @@ async def get_content(self) -> str: text = _mcp_join_text(result) if not text: raise ValueError(f"The MCP server returned no text content for SKILL.md resource '{self._skill_md_uri}'.") + result_adapter = self._result_adapter_factory(result) if self._result_adapter_factory is not None else None self._content = text + self._result_adapter = result_adapter return text async def get_resource(self, name: str) -> SkillResource | None: @@ -4873,7 +4911,11 @@ async def get_resource(self, name: str) -> SkillResource | None: return None raise - return MCPSkillResource(name=name, result=result) + return MCPSkillResource( + name=name, + result=result, + _result_adapter_factory=self._result_adapter_factory, + ) @staticmethod def _validate_resource_name(name: str) -> str | None: @@ -5145,8 +5187,10 @@ def __init__( max_file_count: int, max_size_bytes: int, max_uncompressed_size_bytes: int, + result_adapter_factory: _SkillResultAdapterFactory | None, ) -> None: self._connection_provider = connection_provider + self._result_adapter_factory = result_adapter_factory self._resource_extensions: tuple[str, ...] = ( resource_extensions if resource_extensions is not None else DEFAULT_RESOURCE_EXTENSIONS ) @@ -5181,8 +5225,8 @@ async def load(self, entries: list[_McpSkillIndexEntry], context: SkillsSourceCo if downloaded is None: continue - data, mime_type = downloaded - skill = self._build_skill(entry, data, mime_type) + data, mime_type, result = downloaded + skill = self._build_skill(entry, data, mime_type, result) if skill is None: continue @@ -5199,7 +5243,7 @@ async def load(self, entries: list[_McpSkillIndexEntry], context: SkillsSourceCo return skills - async def _download(self, entry: _McpSkillIndexEntry) -> tuple[bytes, str | None] | None: + async def _download(self, entry: _McpSkillIndexEntry) -> tuple[bytes, str | None, ReadResourceResult] | None: """Download and decode the binary content of a skill's archive resource. Only "resource not found" MCP errors are swallowed (the skill is skipped); @@ -5209,9 +5253,9 @@ async def _download(self, entry: _McpSkillIndexEntry) -> tuple[bytes, str | None would otherwise overwrite a previously cached list with a partial result. Returns: - A ``(data, mime_type)`` tuple, or ``None`` when the resource is not found, - contains no binary content, is empty, exceeds the configured size limit, - or has an invalid or mismatched digest. + A ``(data, mime_type, result)`` tuple, or ``None`` when the + resource is not found, contains no binary content, is empty, exceeds + the configured size limit, or has an invalid or mismatched digest. Raises: Exception: Any error other than a "resource not found" MCP error raised @@ -5247,7 +5291,7 @@ async def _download(self, entry: _McpSkillIndexEntry) -> tuple[bytes, str | None if entry.digest is not None and not self._verify_digest(entry, data): return None - return data, mime_type + return data, mime_type, result @staticmethod def _verify_digest(entry: _McpSkillIndexEntry, data: bytes) -> bool: @@ -5266,7 +5310,13 @@ def _verify_digest(entry: _McpSkillIndexEntry, data: bytes) -> bool: return True - def _build_skill(self, entry: _McpSkillIndexEntry, data: bytes, mime_type: str | None) -> FileSkill | None: + def _build_skill( + self, + entry: _McpSkillIndexEntry, + data: bytes, + mime_type: str | None, + result: ReadResourceResult, + ) -> FileSkill | None: """Detect the format of and unpack one archive entry into an in-memory :class:`FileSkill`. Returns: @@ -5289,9 +5339,14 @@ def _build_skill(self, entry: _McpSkillIndexEntry, data: bytes, mime_type: str | logger.warning("Failed to extract archive for skill '%s'.", entry.name, exc_info=True) return None - return self._skill_from_files(entry, files) + return self._skill_from_files(entry, files, result) - def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) -> FileSkill | None: + def _skill_from_files( + self, + entry: _McpSkillIndexEntry, + files: dict[str, bytes], + result: ReadResourceResult, + ) -> FileSkill | None: """Assemble an in-memory :class:`FileSkill` from the archive's extracted files.""" try: skill_md_key = self._find_skill_md(files) @@ -5330,7 +5385,7 @@ def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) # ``path`` records the archive's origin URL; it is informational only, as the # skill and its resources are served entirely from memory (no filesystem access). try: - return FileSkill( + skill = FileSkill( frontmatter=frontmatter, content=content, path=cast(str, entry.url), @@ -5340,6 +5395,9 @@ def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) except ValueError as exc: logger.warning("Skipping skill '%s': %s", entry.name, exc) return None + if self._result_adapter_factory is not None: + setattr(skill, "_result_adapter", self._result_adapter_factory(result)) # ruff: ignore[set-attr-with-constant] + return skill @staticmethod def _find_skill_md(files: dict[str, bytes]) -> str | None: @@ -5489,6 +5547,7 @@ def __init__( client: Client | ClientSession | None = None, *, session_provider: Callable[[], Client | ClientSession] | None = None, + _result_adapter_factory: _SkillResultAdapterFactory | None = None, archive_resource_extensions: tuple[str, ...] | None = None, archive_resource_search_depth: int = DEFAULT_SEARCH_DEPTH, archive_max_file_count: int = _DEFAULT_ARCHIVE_MAX_FILE_COUNT, @@ -5512,6 +5571,8 @@ def __init__( a replacement connection without reading ``MCPTool.session``. MCPSkillsSource borrows every returned connection and never enters or closes it. + _result_adapter_factory: Private factory for adapting successful + MCP resource reads at the built-in skill tool boundary. archive_resource_extensions: Allowed file extensions for resources discovered in ``archive``-type skills. When ``None`` (the default), the file-source default set (``.md``, ``.json``, ``.yaml``, ``.yml``, ``.csv``, ``.xml``, @@ -5530,10 +5591,10 @@ def __init__( guard). Defaults to ``1 MB``. An archive that exceeds the limit is skipped. Raises: - ValueError: If both or neither of *client* and *session_provider* are - provided. + ValueError: If both or neither of *client* and *session_provider* are provided. """ self._connection_provider = _resolve_mcp_connection_provider(client, session_provider) + self._result_adapter_factory = _result_adapter_factory self._archive_loader = _ArchiveEntryLoader( self._connection_provider, resource_extensions=archive_resource_extensions, @@ -5541,6 +5602,7 @@ def __init__( max_file_count=archive_max_file_count, max_size_bytes=archive_max_size_bytes, max_uncompressed_size_bytes=archive_max_uncompressed_size_bytes, + result_adapter_factory=_result_adapter_factory, ) async def get_skills(self, context: SkillsSourceContext) -> list[Skill]: @@ -5663,7 +5725,12 @@ def _try_create_skill(self, entry: _McpSkillIndexEntry) -> MCPSkill | None: logger.debug("Skipping entry '%s': invalid metadata: %s", entry.name, ex) return None - return MCPSkill(frontmatter=fm, skill_md_uri=entry.url, session_provider=self._current_connection_source) + return MCPSkill( + frontmatter=fm, + skill_md_uri=entry.url, + session_provider=self._current_connection_source, + _result_adapter_factory=self._result_adapter_factory, + ) # endregion diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index a7ef502c187..9a1cd189298 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -325,14 +325,50 @@ class _FunctionResultCarrier: additional_properties: dict[str, Any] item_additional_properties: dict[str, Any] private_metadata: dict[str, Any] = field(default_factory=dict[str, Any]) - parsed_result_postprocessor: Callable[[list[Content]], list[Content]] | None = None - parser_exception_handler: Callable[[], None] | None = None + result_adapter: _FunctionResultAdapter | None = None error_result_finalizer: Callable[[], None] | None = None exclusive_outer_keys: frozenset[str] = frozenset() exclusive_item_keys: frozenset[str] = frozenset() result_already_parsed: bool = False +class _FunctionResultAdapter(typing.Protocol): + """Private operation-scoped result hook for integration-owned metadata.""" + + def postprocess( + self, + contents: list[Content], + context: FunctionInvocationContext, + function: FunctionTool, + ) -> list[Content]: ... + + def handle_error( + self, + context: FunctionInvocationContext, + function: FunctionTool, + ) -> None: ... + + +class _FunctionResultPostprocessor(typing.Protocol): + """Private final-result hook that cannot be replaced by a user parser.""" + + def before_invoke(self, context: FunctionInvocationContext | None) -> None: ... + + def postprocess( + self, + contents: list[Content], + context: FunctionInvocationContext | None, + ) -> list[Content]: ... + + def postprocess_raw( + self, + result: Any, + context: FunctionInvocationContext | None, + ) -> Any: ... + + def handle_error(self, context: FunctionInvocationContext | None) -> None: ... + + class _FunctionResultPayloadBudget: """Bound retained Host payloads across one function-invocation request.""" @@ -684,6 +720,7 @@ class WeatherArgs(BaseModel): "_input_schema", "_schema_supplied", "_invoke_sync_on_event_loop", + "_result_postprocessor", } # A tool that ``BaseAgent.as_tool()`` made keeps pointing at its agent when copied, as its function does. _SHALLOW_COPY_FIELDS: ClassVar[set[str]] = {"raw_representation", "_wrapped_agent"} @@ -808,6 +845,7 @@ def __init__( self._invocation_duration_histogram = _default_histogram() self.type: Literal["function_tool"] = "function_tool" self.result_parser = result_parser + self._result_postprocessor: _FunctionResultPostprocessor | None = None def _discover_injected_parameters(self) -> None: """Inspect the wrapped function for runtime injection parameters.""" @@ -1247,12 +1285,26 @@ async def invoke( if self._context_parameter_name is not None and effective_context is not None: call_kwargs[self._context_parameter_name] = effective_context + if effective_context is not None: + carrier = effective_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if isinstance(carrier, _FunctionResultCarrier): + carrier.result_adapter = None + if self._result_postprocessor is not None: + self._result_postprocessor.before_invoke(effective_context) + if not OBSERVABILITY_SETTINGS.ENABLED: logger.info(f"Function name: {self.name}") logger.debug(f"Function arguments: {observable_kwargs}") - with _suspend_security_argument_materialization(): - result = await self._invoke_function(call_kwargs) + try: + with _suspend_security_argument_materialization(): + result = await self._invoke_function(call_kwargs) + except Exception: + if self._result_postprocessor is not None: + self._result_postprocessor.handle_error(effective_context) + raise if skip_parsing: + if self._result_postprocessor is not None: + result = self._result_postprocessor.postprocess_raw(result, effective_context) logger.info(f"Function {self.name} succeeded.") logger.debug(f"Function result: {type(result).__name__}") return result @@ -1268,13 +1320,17 @@ async def invoke( elif callable(configured_parser): try: parsed = configured_parser(result) - if isinstance(parsed, str): - parsed = [Content.from_text(parsed)] - if isinstance(carrier, _FunctionResultCarrier) and carrier.parsed_result_postprocessor is not None: - parsed = carrier.parsed_result_postprocessor(parsed) except Exception as exception: - if isinstance(carrier, _FunctionResultCarrier) and carrier.parser_exception_handler is not None: - carrier.parser_exception_handler() + if ( + isinstance(carrier, _FunctionResultCarrier) + and carrier.result_adapter is not None + and effective_context is not None + ): + result_adapter = carrier.result_adapter + carrier.result_adapter = None + result_adapter.handle_error(effective_context, self) + if self._result_postprocessor is not None: + self._result_postprocessor.handle_error(effective_context) self.invocation_exception_count += 1 if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: logger.error(f"Function {self.name}: result parser failed. Error: {exception}") @@ -1289,6 +1345,16 @@ async def invoke( parsed = [Content.from_text(str(result))] if isinstance(parsed, str): parsed = [Content.from_text(parsed)] + if self._result_postprocessor is not None: + parsed = self._result_postprocessor.postprocess(parsed, effective_context) + if ( + isinstance(carrier, _FunctionResultCarrier) + and carrier.result_adapter is not None + and effective_context is not None + ): + result_adapter = carrier.result_adapter + carrier.result_adapter = None + parsed = result_adapter.postprocess(parsed, effective_context, self) logger.info(f"Function {self.name} succeeded.") if parsed: types = [item.type for item in parsed] @@ -1341,6 +1407,8 @@ async def invoke( end_time_stamp = perf_counter() except Exception as exception: end_time_stamp = perf_counter() + if self._result_postprocessor is not None: + self._result_postprocessor.handle_error(effective_context) metric_attributes[OtelAttr.ERROR_TYPE] = type(exception).__name__ capture_exception(span=span, exception=exception, timestamp=time_ns()) if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: @@ -1350,6 +1418,8 @@ async def invoke( raise else: if skip_parsing: + if self._result_postprocessor is not None: + result = self._result_postprocessor.postprocess_raw(result, effective_context) logger.info(f"Function {self.name} succeeded.") if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: result_str = str(result) @@ -1369,16 +1439,17 @@ async def invoke( elif callable(configured_parser): try: parsed = configured_parser(result) - if isinstance(parsed, str): - parsed = [Content.from_text(parsed)] + except Exception as exception: if ( isinstance(carrier, _FunctionResultCarrier) - and carrier.parsed_result_postprocessor is not None + and carrier.result_adapter is not None + and effective_context is not None ): - parsed = carrier.parsed_result_postprocessor(parsed) - except Exception as exception: - if isinstance(carrier, _FunctionResultCarrier) and carrier.parser_exception_handler is not None: - carrier.parser_exception_handler() + result_adapter = carrier.result_adapter + carrier.result_adapter = None + result_adapter.handle_error(effective_context, self) + if self._result_postprocessor is not None: + self._result_postprocessor.handle_error(effective_context) self.invocation_exception_count += 1 metric_attributes[OtelAttr.ERROR_TYPE] = type(exception).__name__ if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: @@ -1397,6 +1468,16 @@ async def invoke( parsed = [Content.from_text(str(result))] if isinstance(parsed, str): parsed = [Content.from_text(parsed)] + if self._result_postprocessor is not None: + parsed = self._result_postprocessor.postprocess(parsed, effective_context) + if ( + isinstance(carrier, _FunctionResultCarrier) + and carrier.result_adapter is not None + and effective_context is not None + ): + result_adapter = carrier.result_adapter + carrier.result_adapter = None + parsed = result_adapter.postprocess(parsed, effective_context, self) logger.info(f"Function {self.name} succeeded.") if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: result_str = "\n".join(c.text or "" for c in parsed if c.type == "text") or str(parsed) diff --git a/python/packages/core/agent_framework/security.py b/python/packages/core/agent_framework/security.py index d0f459cb6e8..09c68f92d7c 100644 --- a/python/packages/core/agent_framework/security.py +++ b/python/packages/core/agent_framework/security.py @@ -24,6 +24,7 @@ import re import time import uuid +import warnings from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence from contextvars import ContextVar, Token from copy import copy, deepcopy @@ -31,7 +32,7 @@ from datetime import datetime, timedelta from difflib import get_close_matches from enum import Enum -from typing import TYPE_CHECKING, Annotated, Any, NoReturn, cast +from typing import TYPE_CHECKING, Annotated, Any, Literal, NoReturn, cast from weakref import WeakKeyDictionary from pydantic import BaseModel, Field @@ -78,6 +79,7 @@ if TYPE_CHECKING: from ._clients import SupportsChatGetResponse from ._mcp import MCPTool + from ._skills import SkillsSource __all__ = [ "PRINCIPAL_METADATA_KEY", @@ -140,6 +142,7 @@ _SECURITY_MATERIALIZED_AUTHORITY_CONTEXT_KEY = "_agent_framework_core_security_materialized_authority" _SECURITY_RESOLVED_AUTHORITY_CONTEXT_KEY = "_agent_framework_core_security_resolved_authority" _SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY = "_agent_framework_core_security_result_fallback_label" +_MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY = "_agent_framework_core_mcp_ifc_policy_snapshots" _TOOL_POLICY_ACCEPTS_UNTRUSTED_KEY = "accepts_untrusted" _TOOL_POLICY_CONFIDENTIALITY_KEY = "confidentiality" _TOOL_POLICY_MAX_ALLOWED_CONFIDENTIALITY_KEY = "max_allowed_confidentiality" @@ -5687,6 +5690,32 @@ def get_security_tools() -> list[FunctionTool]: # Written only from local application configuration. MCP result metadata is # attached to Content instances and cannot mutate FunctionTool properties. _MCP_TRUST_SERVER_IFC_KEY = "_mcp_trust_server_ifc" +_MCP_SERVER_IFC_POLICY_KEY = "_mcp_server_ifc_policy" +_MCPServerIFCPolicy = Literal["ignore", "restrict", "authoritative"] +_MCP_SERVER_IFC_POLICIES = frozenset({"ignore", "restrict", "authoritative"}) + + +def _normalize_mcp_server_ifc_policy( + server_ifc_policy: _MCPServerIFCPolicy, + trust_server_ifc: bool | None, + *, + stacklevel: int, +) -> _MCPServerIFCPolicy: + """Validate the policy and translate the deprecated boolean alias.""" + if server_ifc_policy not in _MCP_SERVER_IFC_POLICIES: + raise ValueError( + "server_ifc_policy must be 'ignore', 'restrict', or 'authoritative', " + f"got {server_ifc_policy!r}." + ) + if trust_server_ifc is None: + return server_ifc_policy + warnings.warn( + "trust_server_ifc is deprecated; use server_ifc_policy='authoritative' when True " + "or server_ifc_policy='restrict' when False.", + DeprecationWarning, + stacklevel=stacklevel, + ) + return "authoritative" if trust_server_ifc else "restrict" def _map_mcp_annotations_to_labels( @@ -5730,7 +5759,7 @@ def _apply_mcp_security_label_to_function( default_integrity: IntegrityLabel, annotation_overrides: Mapping[str, tuple[IntegrityLabel, ConfidentialityLabel | None]] | None, mark_write_tools_as_sinks: bool, - trust_server_ifc: bool, + server_ifc_policy: _MCPServerIFCPolicy, ) -> None: """Apply one local MCP security policy to a remote function.""" properties = function.additional_properties @@ -5757,7 +5786,8 @@ def _apply_mcp_security_label_to_function( else: properties.pop("max_allowed_confidentiality", None) properties["accepts_untrusted"] = accepts_untrusted - properties[_MCP_TRUST_SERVER_IFC_KEY] = trust_server_ifc + properties[_MCP_SERVER_IFC_POLICY_KEY] = server_ifc_policy + properties[_MCP_TRUST_SERVER_IFC_KEY] = server_ifc_policy == "authoritative" _wrap_mcp_function_for_ifc(function, default_integrity) logger.info( @@ -5777,7 +5807,8 @@ async def apply_mcp_security_labels( # ruff: ignore[unused-async] default_integrity: IntegrityLabel = IntegrityLabel.UNTRUSTED, annotation_overrides: dict[str, tuple[IntegrityLabel, ConfidentialityLabel | None]] | None = None, mark_write_tools_as_sinks: bool = True, - trust_server_ifc: bool = False, + server_ifc_policy: _MCPServerIFCPolicy = "restrict", + trust_server_ifc: bool | None = None, ) -> None: """Auto-assign FIDES security labels to every tool loaded from an MCP server. @@ -5790,10 +5821,15 @@ async def apply_mcp_security_labels( # ruff: ignore[unused-async] Currently hidden progressive-disclosure tools are included. Server annotations cannot relax local policy. Use ``annotation_overrides`` - for explicit local per-tool static policy. Server result ``_meta.ifc`` is - also restriction-only unless ``trust_server_ifc=True`` is configured - locally, in which case a complete valid server label is authoritative for - that result. ToolAnnotations remain non-authoritative in both modes. + for explicit local per-tool static policy. ``server_ifc_policy`` controls + result ``_meta.ifc``: ``"ignore"`` uses local policy only, ``"restrict"`` + combines server labels with the local baseline so they can only add + restrictions, and ``"authoritative"`` accepts a complete valid server + label as authoritative. The integrity baseline comes from + ``default_integrity`` or ``annotation_overrides``; because it is written + as explicit ``FunctionTool`` policy, it takes precedence over + :class:`SecureAgentConfig`'s ``default_integrity`` for these MCP results. + ToolAnnotations remain non-authoritative in every mode. Call this **after** the ``MCPTool`` is connected (tools already loaded). Use :class:`SecureMCPToolProxy` to keep the same policy bound to functions @@ -5802,8 +5838,10 @@ async def apply_mcp_security_labels( # ruff: ignore[unused-async] Args: mcp_tool: A connected ``MCPTool`` instance (``MCPStdioTool``, ``MCPStreamableHTTPTool``). - default_integrity: Integrity label to assign when the server provides - no annotations. Defaults to ``UNTRUSTED`` (conservative). + default_integrity: Local integrity baseline for MCP results when no + override or stricter annotation applies. Defaults to ``UNTRUSTED`` + (conservative). This becomes explicit tool policy and therefore + takes precedence over ``SecureAgentConfig.default_integrity``. annotation_overrides: Optional per-tool-name overrides. Keys are *remote* MCP tool names (as the server exposes them). Values are ``(IntegrityLabel, ConfidentialityLabel | None)`` tuples that @@ -5813,13 +5851,17 @@ async def apply_mcp_security_labels( # ruff: ignore[unused-async] independently authorizing that policy for the other server's tools. mark_write_tools_as_sinks: When ``True`` (default), apply the annotation-derived ``max_allowed_confidentiality=PUBLIC`` cap. - trust_server_ifc: Whether complete, valid server ``_meta.ifc`` labels - are authoritative for tool results. Defaults to ``False``, which - combines remote labels with current local policy so they can only - add restrictions. + server_ifc_policy: How to handle server ``_meta.ifc`` labels. Defaults + to ``"restrict"``, which combines the server label with the local + MCP baseline. Use ``"ignore"`` for local policy only or + ``"authoritative"`` for an authenticated label authority. + trust_server_ifc: Deprecated boolean alias. ``True`` maps to + ``server_ifc_policy="authoritative"`` and ``False`` maps to + ``server_ifc_policy="restrict"``. Raises: RuntimeError: If the ``MCPTool`` is not connected. + ValueError: If ``server_ifc_policy`` is invalid. Examples: .. code-block:: python @@ -5832,6 +5874,11 @@ async def apply_mcp_security_labels( # ruff: ignore[unused-async] context_providers=[SecureAgentConfig(chat_client=client)], ) """ + effective_server_ifc_policy = _normalize_mcp_server_ifc_policy( + server_ifc_policy, + trust_server_ifc, + stacklevel=2, + ) if not getattr(mcp_tool, "is_connected", False): raise RuntimeError( "MCPTool is not connected. Call connect() or use 'async with' before applying security labels." @@ -5851,7 +5898,7 @@ async def apply_mcp_security_labels( # ruff: ignore[unused-async] default_integrity=default_integrity, annotation_overrides=annotation_overrides, mark_write_tools_as_sinks=mark_write_tools_as_sinks, - trust_server_ifc=trust_server_ifc, + server_ifc_policy=effective_server_ifc_policy, ) @@ -5992,13 +6039,26 @@ def _stamp_parsed_mcp_content_labels( contents: list[Content], local_label: ContentLabel, *, - trust_server_ifc: bool, + server_ifc_policy: _MCPServerIFCPolicy, retain_authority: bool, ) -> list[Content]: """Reapply retained MCP IFC after a function-level result parser.""" + trust_server_ifc = server_ifc_policy == "authoritative" raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) if not isinstance(raw_carrier, _FunctionResultCarrier): - return contents + if server_ifc_policy == "ignore": + contents = [copy(item) for item in contents] + for item in contents: + item.additional_properties = dict(item.additional_properties) + item.additional_properties.pop(_MCP_RESULT_META_KEY, None) + item.additional_properties.pop(_MCP_RESULT_SECURITY_META_KEY, None) + stamped = cast( + list[Content], + _stamp_mcp_content_labels(contents, local_label, trust_server_ifc=trust_server_ifc), + ) + if not retain_authority: + _strip_mcp_authority_markers(stamped) + return stamped security_meta = raw_carrier.private_metadata.get(_MCP_RESULT_SECURITY_META_KEY) prepared: list[Content] = [] @@ -6010,7 +6070,7 @@ def _stamp_parsed_mcp_content_labels( props.pop(_AUTHORITATIVE_SECURITY_LABEL, None) props.pop(_VALIDATED_SECURITY_LABEL_PRINCIPALS, None) props.pop(_LEGACY_AUTHORITATIVE_CONFIDENTIALITY, None) - if security_meta is not None: + if server_ifc_policy != "ignore" and security_meta is not None: props[_MCP_RESULT_SECURITY_META_KEY] = security_meta updated_item.additional_properties = props prepared.append(updated_item) @@ -6029,14 +6089,19 @@ def _stamp_mcp_error_carrier_label( local_label: ContentLabel, fallback_label: ContentLabel, *, - trust_server_ifc: bool, + server_ifc_policy: _MCPServerIFCPolicy, ) -> ContentLabel | None: """Apply retained MCP IFC to a generic function-error result carrier.""" raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) if not isinstance(raw_carrier, _FunctionResultCarrier): return None - security_meta = raw_carrier.private_metadata.get(_MCP_RESULT_SECURITY_META_KEY) + security_meta = ( + None + if server_ifc_policy == "ignore" + else raw_carrier.private_metadata.get(_MCP_RESULT_SECURITY_META_KEY) + ) + trust_server_ifc = server_ifc_policy == "authoritative" probe = Content.from_text("") valid_server_ifc = False if security_meta is not None: @@ -6046,7 +6111,11 @@ def _stamp_mcp_error_carrier_label( if security_meta_mapping.get("retained") is True: valid_server_ifc = _label_from_mcp_meta(security_meta_mapping.get("meta")) is not None effective_local_label = ( - fallback_label if security_meta is None or (valid_server_ifc and not trust_server_ifc) else local_label + fallback_label + if server_ifc_policy == "ignore" + or security_meta is None + or (valid_server_ifc and server_ifc_policy == "restrict") + else local_label ) stamped = cast( list[Content], @@ -6092,107 +6161,202 @@ def _current_mcp_local_label(func_tool: FunctionTool, default_integrity: Integri return ContentLabel(integrity=integrity, confidentiality=confidentiality, metadata=metadata) -def _wrap_mcp_function_for_ifc(func_tool: FunctionTool, default_integrity: IntegrityLabel) -> None: - """Replace ``func_tool.func`` with a wrapper that stamps IFC labels on results. - - The wrapper preserves the original signature and binding behaviour - (FunctionTool already cached ``_context_parameter_name`` from the - original callable) and merely post-processes the returned - ``list[Content]``. ``str`` returns are left untouched because there are - no per-item containers to stamp. - """ - original = func_tool.func - if original is None or getattr(original, "_ifc_wrapped", False): +def _track_mcp_error_label( + context: FunctionInvocationContext, + func_tool: FunctionTool, + local_label: ContentLabel, + server_ifc_policy: _MCPServerIFCPolicy, +) -> None: + """Apply retained MCP IFC to a generic function error and its active tracker.""" + raw_fallback_label = context.metadata.get(_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY) + fallback_label = raw_fallback_label if isinstance(raw_fallback_label, ContentLabel) else local_label + error_label = _stamp_mcp_error_carrier_label( + context, + local_label, + fallback_label, + server_ifc_policy=server_ifc_policy, + ) + if error_label is None: + return + active_middleware = _current_middleware.get() + if active_middleware is None or not _has_matching_label_tracker(context, func_tool): + return + raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if not isinstance(raw_carrier, _FunctionResultCarrier): return + active_scope = active_middleware._scope # pyright: ignore[reportPrivateUsage] + + def commit_error_label() -> None: + context.metadata["result_label"] = error_label + active_middleware._update_context_label( # pyright: ignore[reportPrivateUsage] + error_label, + scope=active_scope, + ) - async def _wrapped(*args: Any, **kwargs: Any) -> Any: - import inspect as _inspect + raw_carrier.error_result_finalizer = commit_error_label - props = func_tool.additional_properties or {} - local_label = _current_mcp_local_label(func_tool, default_integrity) - trust_server_ifc = props.get(_MCP_TRUST_SERVER_IFC_KEY) is True - invocation_context = next( - (value for value in kwargs.values() if isinstance(value, FunctionInvocationContext)), - None, +def _has_matching_label_tracker( + context: FunctionInvocationContext | None, + func_tool: FunctionTool, +) -> bool: + """Return whether the active tracker owns this exact invocation.""" + if context is None: + return False + active_context = _current_context.get() + if active_context is None or active_context is not context or _current_middleware.get() is None: + return False + active_authority = active_context.metadata.get(_SECURITY_RESOLVED_AUTHORITY_CONTEXT_KEY) + return isinstance(active_authority, _SecurityInvocationAuthority) and active_authority.function is func_tool + + +class _MCPIFCResultPostprocessor: + """Apply retained MCP IFC after every FunctionTool result parsing path.""" + + def __init__(self, func_tool: FunctionTool, default_integrity: IntegrityLabel) -> None: + self._func_tool = func_tool + self._default_integrity = default_integrity + + def _current_policy(self) -> tuple[ContentLabel, _MCPServerIFCPolicy]: + props = self._func_tool.additional_properties or {} + raw_policy = props.get(_MCP_SERVER_IFC_POLICY_KEY) + server_ifc_policy: _MCPServerIFCPolicy = ( + cast(_MCPServerIFCPolicy, raw_policy) + if isinstance(raw_policy, str) and raw_policy in _MCP_SERVER_IFC_POLICIES + else "authoritative" + if props.get(_MCP_TRUST_SERVER_IFC_KEY) is True + else "restrict" + ) + return ( + _current_mcp_local_label(self._func_tool, self._default_integrity), + server_ifc_policy, ) - def has_matching_tracker() -> bool: - active_context = _current_context.get() - if active_context is None: - return False - active_authority = active_context.metadata.get(_SECURITY_RESOLVED_AUTHORITY_CONTEXT_KEY) - return ( - _current_middleware.get() is not None - and isinstance(active_authority, _SecurityInvocationAuthority) - and active_authority.function is func_tool - and (invocation_context is None or active_context is invocation_context) + def before_invoke(self, context: FunctionInvocationContext | None) -> None: + if context is None: + return + raw_snapshots = context.metadata.setdefault(_MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY, {}) + if isinstance(raw_snapshots, dict): + cast(dict[FunctionTool, tuple[ContentLabel, _MCPServerIFCPolicy]], raw_snapshots)[self._func_tool] = ( + self._current_policy() ) - def prepare_error_label() -> None: - active_middleware = _current_middleware.get() - if invocation_context is None or active_middleware is None or not has_matching_tracker(): - return - active_context = invocation_context - raw_fallback_label = active_context.metadata.get(_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY) - fallback_label = raw_fallback_label if isinstance(raw_fallback_label, ContentLabel) else local_label - error_label = _stamp_mcp_error_carrier_label( - active_context, - local_label, - fallback_label, - trust_server_ifc=trust_server_ifc, + def _policy(self, context: FunctionInvocationContext | None) -> tuple[ContentLabel, _MCPServerIFCPolicy]: + if context is None: + return self._current_policy() + raw_snapshots = context.metadata.get(_MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY) + if isinstance(raw_snapshots, dict): + snapshots = cast(dict[FunctionTool, tuple[ContentLabel, _MCPServerIFCPolicy]], raw_snapshots) + snapshot = snapshots.pop(self._func_tool, None) + if not snapshots: + context.metadata.pop(_MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY, None) + if snapshot is not None: + return snapshot + return self._current_policy() + + def postprocess( + self, + contents: list[Content], + context: FunctionInvocationContext | None, + ) -> list[Content]: + local_label, server_ifc_policy = self._policy(context) + if context is None: + if server_ifc_policy == "ignore": + contents = [copy(item) for item in contents] + for item in contents: + item.additional_properties = dict(item.additional_properties) + item.additional_properties.pop(_MCP_RESULT_META_KEY, None) + item.additional_properties.pop(_MCP_RESULT_SECURITY_META_KEY, None) + stamped = cast( + list[Content], + _stamp_mcp_content_labels( + contents, + local_label, + trust_server_ifc=server_ifc_policy == "authoritative", + ), ) - if error_label is None: - return - raw_carrier = active_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) - if not isinstance(raw_carrier, _FunctionResultCarrier): - return - active_scope = active_middleware._scope # pyright: ignore[reportPrivateUsage] + return cast(list[Content], _strip_mcp_authority_markers(stamped)) + return _stamp_parsed_mcp_content_labels( + context, + contents, + local_label, + server_ifc_policy=server_ifc_policy, + retain_authority=_has_matching_label_tracker(context, self._func_tool), + ) - def commit_error_label() -> None: - active_context.metadata["result_label"] = error_label - active_middleware._update_context_label( # pyright: ignore[reportPrivateUsage] - error_label, - scope=active_scope, - ) + def postprocess_raw( + self, + result: Any, + context: FunctionInvocationContext | None, + ) -> Any: + if not isinstance(result, list): + return result + return self.postprocess(cast(list[Content], result), context) - raw_carrier.error_result_finalizer = commit_error_label + def handle_error(self, context: FunctionInvocationContext | None) -> None: + if context is None: + return + local_label, server_ifc_policy = self._policy(context) + _track_mcp_error_label(context, self._func_tool, local_label, server_ifc_policy) - try: - res = original(*args, **kwargs) - if _inspect.isawaitable(res): - res = await res - except Exception: - prepare_error_label() - raise - retain_authority = has_matching_tracker() - if invocation_context is not None: - raw_carrier = invocation_context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) - if isinstance(raw_carrier, _FunctionResultCarrier): - - def postprocess_parsed_result(contents: list[Content]) -> list[Content]: - return _stamp_parsed_mcp_content_labels( - invocation_context, - contents, - local_label, - trust_server_ifc=trust_server_ifc, - retain_authority=retain_authority, - ) +class _MCPIFCSkillResultAdapter: + """Apply one MCP Skills resource label at the built-in FunctionTool boundary.""" - raw_carrier.parsed_result_postprocessor = postprocess_parsed_result - raw_carrier.parser_exception_handler = prepare_error_label + def __init__( + self, + security_meta: Any, + local_label: ContentLabel, + server_ifc_policy: _MCPServerIFCPolicy, + ) -> None: + self._security_meta = security_meta + self._local_label = local_label + self._server_ifc_policy: _MCPServerIFCPolicy = server_ifc_policy - stamped = cast( - str | list[Content], - _stamp_mcp_content_labels(res, local_label, trust_server_ifc=trust_server_ifc), + def _prepare_carrier(self, context: FunctionInvocationContext) -> None: + raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) + if not isinstance(raw_carrier, _FunctionResultCarrier): + return + if self._server_ifc_policy != "ignore" and self._security_meta is not None: + raw_carrier.private_metadata[_MCP_RESULT_SECURITY_META_KEY] = self._security_meta + else: + raw_carrier.private_metadata.pop(_MCP_RESULT_SECURITY_META_KEY, None) + + def postprocess( + self, + contents: list[Content], + context: FunctionInvocationContext, + function: FunctionTool, + ) -> list[Content]: + self._prepare_carrier(context) + return _stamp_parsed_mcp_content_labels( + context, + contents, + self._local_label, + server_ifc_policy=self._server_ifc_policy, + retain_authority=_has_matching_label_tracker(context, function), ) - if not retain_authority: - _strip_mcp_authority_markers(stamped) - return stamped - _wrapped._ifc_wrapped = True # type: ignore[attr-defined] - func_tool.func = _wrapped + def handle_error( + self, + context: FunctionInvocationContext, + function: FunctionTool, + ) -> None: + self._prepare_carrier(context) + _track_mcp_error_label( + context, + function, + self._local_label, + self._server_ifc_policy, + ) + + +def _wrap_mcp_function_for_ifc(func_tool: FunctionTool, default_integrity: IntegrityLabel) -> None: + """Install final MCP IFC processing without replacing a user result parser.""" + func_tool._result_postprocessor = _MCPIFCResultPostprocessor( # pyright: ignore[reportPrivateUsage] + func_tool, + default_integrity, + ) @experimental(feature_id=ExperimentalFeature.FIDES) @@ -6227,6 +6391,12 @@ class SecureMCPToolProxy: ) as proxy: agent = Agent(client=client, tools=proxy.tools, ...) + The same secured connection can supply MCP Skills with identical IFC + policy by passing :meth:`skills_source` to ``SkillsProvider``:: + + async with SecureMCPToolProxy(url="https://mcp.example.com/") as proxy: + skills = SkillsProvider(proxy.skills_source()) + The URL mode ensures the MCP server is called **locally** by your application (not by the model provider), so :class:`LabelTrackingFunctionMiddleware` and @@ -6250,17 +6420,20 @@ class SecureMCPToolProxy: *url* mode. Defaults to 100; ``None`` disables the limit. max_discovery_items: Maximum entries accepted independently for each tool or prompt catalog fetch in *url* mode. Defaults to 1,000; ``None`` disables the limit. - default_integrity: Default integrity for tools without annotations. + default_integrity: Local integrity baseline for MCP results. It becomes + explicit tool policy and therefore takes precedence over + ``SecureAgentConfig.default_integrity`` for these functions. annotation_overrides: Per-tool-name label overrides (keyed by remote MCP tool name), applied only to this proxy's MCP connection. The mapping is not bound to a server identity; reuse it for another connection only after independently authorizing that policy there. mark_write_tools_as_sinks: Whether to apply the annotation-derived PUBLIC confidentiality cap. - trust_server_ifc: Whether complete, valid server ``_meta.ifc`` labels - are authoritative for results. Defaults to ``False`` so remote - labels can only add restrictions. This does not grant authority to - server ToolAnnotations. + server_ifc_policy: How to handle server ``_meta.ifc`` labels: + ``"ignore"``, ``"restrict"`` (default, combined with the local + MCP baseline), or ``"authoritative"``. This does not grant + authority to server ToolAnnotations. + trust_server_ifc: Deprecated boolean alias for ``server_ifc_policy``. """ def __init__( @@ -6276,7 +6449,8 @@ def __init__( default_integrity: IntegrityLabel = IntegrityLabel.UNTRUSTED, annotation_overrides: dict[str, tuple[IntegrityLabel, ConfidentialityLabel | None]] | None = None, mark_write_tools_as_sinks: bool = True, - trust_server_ifc: bool = False, + server_ifc_policy: _MCPServerIFCPolicy = "restrict", + trust_server_ifc: bool | None = None, ) -> None: """Initialize a secure proxy for an MCP tool or MCP URL endpoint. @@ -6297,21 +6471,26 @@ def __init__( ``url`` mode. Defaults to 100; ``None`` disables the limit. max_discovery_items: Maximum entries accepted independently for each tool or prompt catalog fetch in ``url`` mode. Defaults to 1,000; ``None`` disables the limit. - default_integrity: Default integrity for tools without annotations. - Defaults to ``IntegrityLabel.UNTRUSTED``. + default_integrity: Local integrity baseline for MCP results. + Defaults to ``IntegrityLabel.UNTRUSTED``. This becomes + explicit tool policy and therefore takes precedence over + ``SecureAgentConfig.default_integrity``. annotation_overrides: Per-tool-name label overrides keyed by remote MCP tool name, applied only to this proxy's MCP connection. The mapping is not bound to a server identity; reuse it for another connection only after independently authorizing that policy there. mark_write_tools_as_sinks: Whether to apply the annotation-derived PUBLIC confidentiality cap. Defaults to ``True``. - trust_server_ifc: Whether complete, valid server ``_meta.ifc`` - labels are authoritative for results. Defaults to ``False``; - ToolAnnotations remain restriction-only hints regardless of - this setting. + server_ifc_policy: How to handle server ``_meta.ifc`` labels. + Defaults to ``"restrict"``, which combines the server label + with the local MCP baseline. Use ``"ignore"`` for local policy + only or ``"authoritative"`` for an authenticated label + authority. ToolAnnotations remain restriction-only hints. + trust_server_ifc: Deprecated boolean alias. ``True`` maps to + ``"authoritative"`` and ``False`` maps to ``"restrict"``. Raises: - ValueError: If both ``mcp_tool`` and ``url`` are provided, or if neither is provided. + ValueError: If tool/URL selection or ``server_ifc_policy`` is invalid. """ if mcp_tool is not None and url is not None: raise ValueError("Provide either 'mcp_tool' or 'url', not both.") @@ -6337,7 +6516,11 @@ def __init__( self._default_integrity = default_integrity self._annotation_overrides = annotation_overrides self._mark_write_tools_as_sinks = mark_write_tools_as_sinks - self._trust_server_ifc = trust_server_ifc + self._server_ifc_policy: _MCPServerIFCPolicy = _normalize_mcp_server_ifc_policy( + server_ifc_policy, + trust_server_ifc, + stacklevel=2, + ) self._function_load_callback = self._apply_function_labels # -- Async context manager -- @@ -6440,8 +6623,68 @@ def mcp_tool(self) -> Any: """Access the underlying ``MCPTool`` instance.""" return self._mcp_tool + def skills_source(self, **archive_options: Any) -> SkillsSource: + """Create an MCP Skills source using this proxy's connection and IFC policy. + + The source resolves the proxy's current MCP connection for every + discovery and resource read, so it follows framework-owned reconnects. + Skill content and resources use the same ``default_integrity`` and + ``server_ifc_policy`` as MCP tools and prompts. Direct + :class:`MCPSkillsSource` construction remains unlabeled. + + Keyword Args: + archive_options: Archive-related ``MCPSkillsSource`` options such + as ``archive_resource_extensions`` and size limits. Connection + and result-adapter options are owned by this proxy. + + Returns: + A configured ``MCPSkillsSource`` for use with ``SkillsProvider``. + + Raises: + TypeError: If a caller tries to replace proxy-owned connection or + result-adapter options. + RuntimeError: When the source is read while the proxy is disconnected. + """ + from ._mcp import _retain_mcp_result_security_meta # pyright: ignore[reportPrivateUsage] + from ._skills import MCPSkillsSource + + reserved = {"client", "session_provider", "_result_adapter_factory"} + invalid = reserved.intersection(archive_options) + if invalid: + names = ", ".join(sorted(invalid)) + raise TypeError(f"skills_source() owns these option(s): {names}.") + + local_label = ContentLabel( + integrity=self._default_integrity, + confidentiality=ConfidentialityLabel.PUBLIC, + ) + server_ifc_policy = self._server_ifc_policy + + def result_adapter_factory(result: Any) -> _MCPIFCSkillResultAdapter: + return _MCPIFCSkillResultAdapter( + _retain_mcp_result_security_meta(result), + local_label, + server_ifc_policy, + ) + + return MCPSkillsSource( + session_provider=self._current_skills_connection, + _result_adapter_factory=result_adapter_factory, + **archive_options, + ) + # -- Internal -- + def _current_skills_connection(self) -> Any: + connection = self._mcp_tool._connection # pyright: ignore[reportPrivateUsage] + if connection is None: + raise RuntimeError("SecureMCPToolProxy must be connected before reading MCP Skills.") + if connection.client is not None: + return connection.client + if connection.session is not None: + return connection.session + raise RuntimeError("The active MCP connection cannot read Skills resources.") + def _bind_function_load_callback(self) -> bool: current = self._mcp_tool._function_load_callback # pyright: ignore[reportPrivateUsage] if current is self._function_load_callback: @@ -6465,7 +6708,7 @@ def _apply_function_labels(self, function: FunctionTool, annotations: Any) -> No default_integrity=self._default_integrity, annotation_overrides=self._annotation_overrides, mark_write_tools_as_sinks=self._mark_write_tools_as_sinks, - trust_server_ifc=self._trust_server_ifc, + server_ifc_policy=self._server_ifc_policy, ) async def _apply_labels(self) -> None: @@ -6474,5 +6717,5 @@ async def _apply_labels(self) -> None: default_integrity=self._default_integrity, annotation_overrides=self._annotation_overrides, mark_write_tools_as_sinks=self._mark_write_tools_as_sinks, - trust_server_ifc=self._trust_server_ifc, + server_ifc_policy=self._server_ifc_policy, ) diff --git a/python/packages/core/tests/core/test_mcp.py b/python/packages/core/tests/core/test_mcp.py index afa63a00d66..6a7789ff20f 100644 --- a/python/packages/core/tests/core/test_mcp.py +++ b/python/packages/core/tests/core/test_mcp.py @@ -49,13 +49,18 @@ MCPSpecificApproval, MCPTool, _build_prefixed_mcp_name, + _capture_mcp_result, _ClientMCPConnection, _describe_error, _get_input_model_from_mcp_prompt, _json_size_exceeds, + _make_mcp_prompt_caller, _make_mcp_tool_caller, _mcp_tool_result_host_payload, _mcp_tool_result_meta, + _mcp_tool_runtime_context, + _MCPResultCapture, + _MCPToolRuntimeContext, _normalize_additional_tool_argument_names, _normalize_mcp_name, _should_propagate_cancelled_error, @@ -291,6 +296,52 @@ async def _call_generated_mcp_tool( ) +async def _call_generated_mcp_prompt( + tool: MCPTool, + prompt_name: str, + *, + result_parser: Any = None, + middleware_pipeline: FunctionMiddlewarePipeline | None = None, + mcp_local_label: tuple[str, str] | None = None, + trust_server_ifc: bool = False, + server_ifc_policy: str | None = None, + include_detailed_errors: bool = False, + **kwargs: Any, +) -> Content: + function_kwargs: dict[str, Any] = {} + if result_parser is not None: + function_kwargs["result_parser"] = result_parser + function = FunctionTool( + name=prompt_name, + description="", + func=_make_mcp_prompt_caller(tool, prompt_name), + input_model={"type": "object", "properties": {name: {} for name in kwargs}}, + additional_properties={"_mcp_remote_name": prompt_name}, + **function_kwargs, + ) + if mcp_local_label is not None: + from agent_framework.security import IntegrityLabel, _wrap_mcp_function_for_ifc + + source_integrity, confidentiality = mcp_local_label + assert function.additional_properties is not None + function.additional_properties.update({ + "source_integrity": source_integrity, + "confidentiality": confidentiality, + "_mcp_trust_server_ifc": trust_server_ifc, + }) + if server_ifc_policy is not None: + function.additional_properties["_mcp_server_ifc_policy"] = server_ifc_policy + _wrap_mcp_function_for_ifc(function, IntegrityLabel(source_integrity)) + return await _auto_invoke_function( + Content.from_function_call(call_id=f"call-{prompt_name}", name=prompt_name, arguments=kwargs), + config=normalize_function_invocation_configuration({ + "include_detailed_errors": include_detailed_errors, + }), + tool_map={prompt_name: function}, + middleware_pipeline=middleware_pipeline, + ) + + def _reset_progressive_mcp_warning_state() -> None: _WARNED_FEATURES.discard((ExperimentalWarning, ExperimentalFeature.PROGRESSIVE_TOOLS.value)) @@ -1683,6 +1734,38 @@ def fail_if_captured(*_args: Any, **_kwargs: Any) -> Any: await tool.call_tool("widget") +def test_mcp_result_capture_is_scoped_to_its_owner() -> None: + owner = object() + capture = _MCPResultCapture( + max_size_bytes=1024, + aggregate_budget=None, + apply_server_meta_to_model_items=False, + ) + result = types.CallToolResult( + content=[types.TextContent(type="text", text="private")], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + token = _mcp_tool_runtime_context.set( + _MCPToolRuntimeContext( + owner=owner, + runtime_kwargs={}, + result_capture=capture, + ) + ) + try: + _capture_mcp_result(object(), result) + assert capture.recorded is False + + _capture_mcp_result(owner, result) + assert capture.recorded is True + assert capture.security_meta == { + "retained": True, + "meta": {"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + } + finally: + _mcp_tool_runtime_context.reset(token) + + async def test_function_tool_result_parser_cannot_discard_mcp_host_payload() -> None: mcp_result = types.CallToolResult( content=[types.TextContent(type="text", text="server projection")], @@ -1834,10 +1917,9 @@ async def test_exhausted_aggregate_budget_preserves_ifc_security_label() -> None assert "_meta" not in function_result.additional_properties assert function_result.items is not None - assert function_result.items[0].additional_properties["security_label"] == { - "integrity": "trusted", - "confidentiality": "private", - } + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "private" assert "_mcp_tool_result_security_meta" not in function_result.items[0].additional_properties @@ -1870,10 +1952,9 @@ async def test_function_result_parser_preserves_exhausted_budget_ifc_label() -> assert function_result.result == "private result" assert function_result.items is not None - assert function_result.items[0].additional_properties["security_label"] == { - "integrity": "trusted", - "confidentiality": "private", - } + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "private" assert tracker.get_context_label().confidentiality.value == "private" assert "_security_label_authoritative" not in function_result.items[0].additional_properties json.dumps(function_result.to_dict()) @@ -1911,13 +1992,225 @@ def fail_with_result(items: list[Content]) -> str: ) assert "private parser detail" in function_result.result + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "private" + assert tracker.get_context_label().confidentiality.value == "private" + assert "_security_label_authoritative" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + + +async def test_mcp_parser_failure_without_tracker_returns_serializable_labeled_error() -> None: + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="private parser detail")], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + tool = MCPTool(name="helper", parse_tool_results=_raise_result_parser) # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + + function_result = await _call_generated_mcp_tool( + tool, + "widget", + mcp_local_label=("trusted", "public"), + include_detailed_errors=True, + ) + assert function_result.items is not None assert function_result.items[0].additional_properties["security_label"] == { "integrity": "trusted", "confidentiality": "private", } + assert "_security_label_authoritative" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + + +async def test_function_result_parser_assigned_after_mcp_ifc_setup_preserves_label() -> None: + from agent_framework.security import IntegrityLabel, LabelTrackingFunctionMiddleware, _wrap_mcp_function_for_ifc + + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="private result")], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + function = FunctionTool( + name="widget", + description="", + func=_make_mcp_tool_caller(tool, "widget"), + input_model={"type": "object", "properties": {}}, + additional_properties={ + "_mcp_remote_name": "widget", + "source_integrity": "trusted", + "confidentiality": "public", + "_mcp_trust_server_ifc": False, + }, + ) + _wrap_mcp_function_for_ifc(function, IntegrityLabel.TRUSTED) + function.result_parser = lambda items: items[0].text + tracker = LabelTrackingFunctionMiddleware() + + function_result = await _auto_invoke_function( + Content.from_function_call(call_id="call-widget", name="widget", arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={"widget": function}, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + ) + + assert function_result.result == "private result" + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "private" + + +@pytest.mark.parametrize("custom_parsers", [False, True], ids=["default-parsers", "custom-parsers"]) +async def test_generated_mcp_prompt_applies_ifc_after_all_parsers(custom_parsers: bool) -> None: + from agent_framework.security import LabelTrackingFunctionMiddleware + + prompt_result = types.GetPromptResult( + description="Generated prompt", + messages=[ + types.PromptMessage( + role="user", + content=types.TextContent(type="text", text="server prompt"), + ) + ], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="helper", + parse_prompt_results=(lambda _: "MCP prompt projection") if custom_parsers else None, + ) + mock_session = Mock() + tool.session = mock_session + mock_session.get_prompt = AsyncMock(return_value=prompt_result) + tracker = LabelTrackingFunctionMiddleware() + + function_result = await _call_generated_mcp_prompt( + tool, + "summary", + result_parser=(lambda result: f"FunctionTool projection: {result}") if custom_parsers else None, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + mcp_local_label=("trusted", "public"), + ) + + assert function_result.items is not None + assert function_result.items[0].text == ( + "FunctionTool projection: MCP prompt projection" if custom_parsers else "server prompt" + ) + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "private" assert tracker.get_context_label().confidentiality.value == "private" assert "_security_label_authoritative" not in function_result.items[0].additional_properties + assert "_mcp_tool_result_security_meta" not in function_result.items[0].additional_properties + json.dumps(function_result.to_dict()) + + +async def test_generated_mcp_prompt_invalid_identity_ifc_fails_closed() -> None: + prompt_result = types.GetPromptResult( + messages=[ + types.PromptMessage( + role="user", + content=types.TextContent(type="text", text="identity prompt"), + ) + ], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "user_identity"}}, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.get_prompt = AsyncMock(return_value=prompt_result) + + function_result = await _call_generated_mcp_prompt( + tool, + "summary", + mcp_local_label=("trusted", "public"), + ) + + assert function_result.items is not None + assert function_result.items[0].additional_properties["security_label"] == { + "integrity": "untrusted", + "confidentiality": "user_identity", + "metadata": {"source": "invalid_mcp_ifc"}, + } + json.dumps(function_result.to_dict()) + + +async def test_generated_mcp_prompt_can_ignore_server_ifc() -> None: + prompt_result = types.GetPromptResult( + messages=[ + types.PromptMessage( + role="user", + content=types.TextContent(type="text", text="server prompt"), + ) + ], + _meta={"ifc": {"integrity": "untrusted", "confidentiality": "private"}}, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.get_prompt = AsyncMock(return_value=prompt_result) + + function_result = await _call_generated_mcp_prompt( + tool, + "summary", + mcp_local_label=("trusted", "public"), + server_ifc_policy="ignore", + ) + + assert function_result.items is not None + assert function_result.items[0].additional_properties["security_label"] == { + "integrity": "trusted", + "confidentiality": "public", + } + + +async def test_generated_mcp_prompt_parser_failure_preserves_ifc_label() -> None: + from agent_framework.security import LabelTrackingFunctionMiddleware + + prompt_result = types.GetPromptResult( + messages=[ + types.PromptMessage( + role="user", + content=types.TextContent(type="text", text="private prompt detail"), + ) + ], + _meta={"ifc": {"integrity": "trusted", "confidentiality": "private"}}, + ) + + def fail_with_prompt(result: types.GetPromptResult) -> str: + content = cast(types.TextContent, result.messages[0].content) + raise ValueError(f"prompt parser rejected {content.text}") + + tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="helper", + parse_prompt_results=fail_with_prompt, + ) + mock_session = Mock() + tool.session = mock_session + mock_session.get_prompt = AsyncMock(return_value=prompt_result) + tracker = LabelTrackingFunctionMiddleware() + + function_result = await _call_generated_mcp_prompt( + tool, + "summary", + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + mcp_local_label=("trusted", "public"), + include_detailed_errors=True, + ) + + assert "private prompt detail" in function_result.result + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["integrity"] == "trusted" + assert result_label["confidentiality"] == "private" + assert tracker.get_context_label().confidentiality.value == "private" json.dumps(function_result.to_dict()) diff --git a/python/packages/core/tests/core/test_mcp_skills.py b/python/packages/core/tests/core/test_mcp_skills.py index 4b8bf6994d4..0d78f547bd9 100644 --- a/python/packages/core/tests/core/test_mcp_skills.py +++ b/python/packages/core/tests/core/test_mcp_skills.py @@ -4,6 +4,7 @@ from __future__ import annotations +import asyncio import base64 import hashlib import io @@ -25,8 +26,20 @@ TextResourceContents, ) -from agent_framework import CachingSkillsSource, MCPSkill, MCPSkillResource, MCPSkillsSource, SkillsSourceContext -from agent_framework._skills import _fully_unquote, _parse_mcp_skill_index +from agent_framework import ( + CachingSkillsSource, + FileSkill, + InlineSkill, + MCPSkill, + MCPSkillResource, + MCPSkillsSource, + SkillFrontmatter, + SkillsProvider, + SkillsSourceContext, +) +from agent_framework._middleware import FunctionInvocationContext +from agent_framework._skills import InlineSkillResource, _fully_unquote, _parse_mcp_skill_index +from agent_framework._tools import _finalize_function_result # pyright: ignore[reportPrivateUsage] from .conftest import MockAgent @@ -60,20 +73,45 @@ ], }) - -def _make_text_result(text: str, uri: str = "skill://test") -> ReadResourceResult: +_PRIVATE_IFC_META = {"ifc": {"integrity": "trusted", "confidentiality": "private"}} +_IGNORED_IFC_LABEL = {"integrity": "untrusted", "confidentiality": "public"} +_RESTRICTED_IFC_LABEL = {"integrity": "untrusted", "confidentiality": "private"} +_AUTHORITATIVE_IFC_LABEL = {"integrity": "trusted", "confidentiality": "private"} +_SERVER_IFC_POLICY_CASES = [ + pytest.param("ignore", _IGNORED_IFC_LABEL, id="ignore"), + pytest.param("restrict", _RESTRICTED_IFC_LABEL, id="restrict"), + pytest.param("authoritative", _AUTHORITATIVE_IFC_LABEL, id="authoritative"), +] +_SERVER_IFC_POLICY_CASES_WITH_DEFAULT = [ + pytest.param(None, _RESTRICTED_IFC_LABEL, id="restrict-default"), + *_SERVER_IFC_POLICY_CASES, +] + + +def _make_text_result( + text: str, + uri: str = "skill://test", + *, + meta: Mapping[str, Any] | None = None, +) -> ReadResourceResult: """Create a ReadResourceResult with a single TextResourceContents.""" - return ReadResourceResult(contents=[TextResourceContents(uri=uri, text=text, mime_type="text/markdown")]) + return ReadResourceResult( + contents=[TextResourceContents(uri=uri, text=text, mime_type="text/markdown")], + _meta=dict(meta) if meta is not None else None, + ) def _make_blob_result( data: bytes, uri: str = "skill://test", mime_type: str = "application/octet-stream", + *, + meta: Mapping[str, Any] | None = None, ) -> ReadResourceResult: """Create a ReadResourceResult with a single BlobResourceContents.""" return ReadResourceResult( - contents=[BlobResourceContents(uri=uri, blob=base64.b64encode(data).decode(), mime_type=mime_type)] + contents=[BlobResourceContents(uri=uri, blob=base64.b64encode(data).decode(), mime_type=mime_type)], + _meta=dict(meta) if meta is not None else None, ) @@ -117,6 +155,50 @@ async def _read_resource(uri: str) -> ReadResourceResult: return client +async def _create_skill_tools(source: Any) -> dict[str, Any]: + """Create the built-in skill tools for a source.""" + provider = SkillsProvider(source) + _, _, tools = await provider._create_context(_SOURCE_CTX) # pyright: ignore[reportPrivateUsage] + return {tool.name: tool for tool in tools} + + +async def _invoke_skill_tool(tool: Any, **arguments: Any) -> list[Any]: + """Invoke one built-in skill tool through its FunctionTool boundary.""" + context = FunctionInvocationContext(function=tool, arguments={}) + result = await tool.invoke(arguments=arguments, context=context) + assert isinstance(result, list) + return result + + +def _secure_skills_source( + client: Any, + *, + server_ifc_policy: Any | None = None, +) -> MCPSkillsSource: + """Create an MCP Skills source through SecureMCPToolProxy.""" + from agent_framework._mcp import MCPTool + from agent_framework.security import SecureMCPToolProxy + + mcp_tool = MCPTool(name="skills", session=client) # type: ignore[abstract] # ty: ignore[call-non-callable] + proxy = ( + SecureMCPToolProxy(mcp_tool) + if server_ifc_policy is None + else SecureMCPToolProxy(mcp_tool, server_ifc_policy=server_ifc_policy) + ) + source = proxy.skills_source() + assert isinstance(source, MCPSkillsSource) + return source + + +def _assert_ifc_label(result: list[Any], expected_label: Mapping[str, Any]) -> None: + """Assert the expected IFC label was applied without leaking private markers.""" + properties = result[0].additional_properties + assert properties["security_label"] == expected_label + assert "_mcp_tool_result_security_meta" not in properties + assert "_security_label_authoritative" not in properties + assert "_security_label_validated_principals" not in properties + + @pytest.fixture(autouse=True) def _clear_resource_name_decode_cache() -> Iterator[None]: _fully_unquote.cache_clear() @@ -1120,6 +1202,382 @@ def _archive_client(index_json: str, archive_url: str, archive_bytes: bytes, mim }) +# --------------------------------------------------------------------------- +# MCP skill IFC tests +# --------------------------------------------------------------------------- + + +class TestMCPSkillsIFC: + """Tests for SecureMCPToolProxy's operation-scoped skill result adapters.""" + + async def test_proxy_source_requires_an_active_connection(self) -> None: + from agent_framework._mcp import MCPTool + from agent_framework.security import SecureMCPToolProxy + + proxy = SecureMCPToolProxy(MCPTool(name="skills")) # type: ignore[abstract] # ty: ignore[call-non-callable] + + with pytest.raises(RuntimeError, match="must be connected"): + await proxy.skills_source().get_skills(_SOURCE_CTX) + + def test_proxy_source_rejects_connection_overrides(self) -> None: + from agent_framework._mcp import MCPTool + from agent_framework.security import SecureMCPToolProxy + + client = _make_client() + proxy = SecureMCPToolProxy( + MCPTool(name="skills", session=client) # type: ignore[abstract] # ty: ignore[call-non-callable] + ) + + with pytest.raises(TypeError, match="skills_source.*owns"): + proxy.skills_source(client=client) + + async def test_proxy_source_follows_replaced_connection(self) -> None: + from agent_framework._mcp import MCPTool + from agent_framework.security import SecureMCPToolProxy + + old_client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + }) + new_client = _make_client(**{ + "skill://unit-converter/SKILL.md": _make_text_result( + "# New\nnew body", + uri="skill://unit-converter/SKILL.md", + meta=_PRIVATE_IFC_META, + ), + }) + mcp_tool = MCPTool( # type: ignore[abstract] # ty: ignore[call-non-callable] + name="skills", + session=old_client, + ) + proxy = SecureMCPToolProxy(mcp_tool) + skills = await proxy.skills_source().get_skills(_SOURCE_CTX) + + with pytest.warns(DeprecationWarning, match="MCPTool.session"): + mcp_tool.session = new_client + tools = await _create_skill_tools(skills) + result = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + + assert result[0].text == "# New\nnew body" + _assert_ifc_label(result, _RESTRICTED_IFC_LABEL) + + def test_invalid_server_ifc_policy_is_rejected(self) -> None: + invalid_policy: Any = "invalid" + with pytest.raises(ValueError, match="server_ifc_policy"): + _secure_skills_source(_make_client(), server_ifc_policy=invalid_policy) + + @pytest.mark.parametrize(("server_ifc_policy", "expected_label"), _SERVER_IFC_POLICY_CASES_WITH_DEFAULT) + async def test_skill_md_ifc_applies_to_load_and_cached_load( + self, + server_ifc_policy: Any | None, + expected_label: dict[str, str], + ) -> None: + skill_uri = "skill://unit-converter/SKILL.md" + client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + skill_uri: _make_text_result(SAMPLE_SKILL_MD, uri=skill_uri, meta=_PRIVATE_IFC_META), + }) + source = ( + _secure_skills_source(client) + if server_ifc_policy is None + else _secure_skills_source(client, server_ifc_policy=server_ifc_policy) + ) + tools = await _create_skill_tools(source) + + first = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + second = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + + assert first[0].text == SAMPLE_SKILL_MD + assert second[0].text == SAMPLE_SKILL_MD + _assert_ifc_label(first, expected_label) + _assert_ifc_label(second, expected_label) + assert client.read_resource.await_args_list == [ + call("skill://index.json"), + call(skill_uri), + ] + + async def test_skill_adapter_runs_after_custom_result_parser(self) -> None: + skill_uri = "skill://unit-converter/SKILL.md" + client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + skill_uri: _make_text_result(SAMPLE_SKILL_MD, uri=skill_uri, meta=_PRIVATE_IFC_META), + }) + tools = await _create_skill_tools(_secure_skills_source(client)) + tools["load_skill"].result_parser = lambda _: "projected instructions" + + result = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + + assert result[0].text == "projected instructions" + _assert_ifc_label(result, _RESTRICTED_IFC_LABEL) + + @pytest.mark.parametrize(("server_ifc_policy", "expected_label"), _SERVER_IFC_POLICY_CASES) + async def test_sibling_resource_ifc_applies_to_read_resource( + self, + server_ifc_policy: Any, + expected_label: dict[str, str], + ) -> None: + resource_uri = "skill://unit-converter/references/checklist.md" + client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + resource_uri: _make_text_result("private checklist", uri=resource_uri, meta=_PRIVATE_IFC_META), + }) + tools = await _create_skill_tools(_secure_skills_source(client, server_ifc_policy=server_ifc_policy)) + + result = await _invoke_skill_tool( + tools["read_skill_resource"], + skill_name="unit-converter", + resource_name="references/checklist.md", + ) + + assert result[0].text == "private checklist" + _assert_ifc_label(result, expected_label) + + async def test_sibling_resource_does_not_inherit_cached_skill_adapter(self) -> None: + skill_uri = "skill://unit-converter/SKILL.md" + resource_uri = "skill://unit-converter/references/public.md" + client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + skill_uri: _make_text_result(SAMPLE_SKILL_MD, uri=skill_uri, meta=_PRIVATE_IFC_META), + resource_uri: _make_text_result("public resource", uri=resource_uri), + }) + tools = await _create_skill_tools(_secure_skills_source(client, server_ifc_policy="authoritative")) + + manifest = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + resource = await _invoke_skill_tool( + tools["read_skill_resource"], + skill_name="unit-converter", + resource_name="references/public.md", + ) + + _assert_ifc_label(manifest, _AUTHORITATIVE_IFC_LABEL) + _assert_ifc_label(resource, _IGNORED_IFC_LABEL) + + @pytest.mark.parametrize(("server_ifc_policy", "expected_label"), _SERVER_IFC_POLICY_CASES) + async def test_archive_ifc_applies_to_manifest_and_extracted_resource( + self, + server_ifc_policy: Any, + expected_label: dict[str, str], + ) -> None: + archive_uri = "skill://archives/packaged-skill.zip" + archive = _make_zip({ + "SKILL.md": ARCHIVE_SKILL_MD.encode(), + "references/private.md": b"private archive resource", + }) + client = _make_client(**{ + "skill://index.json": _make_text_result( + _make_archive_index("packaged-skill", archive_uri), + uri="skill://index.json", + ), + archive_uri: _make_blob_result( + archive, + uri=archive_uri, + mime_type="application/zip", + meta=_PRIVATE_IFC_META, + ), + }) + tools = await _create_skill_tools(_secure_skills_source(client, server_ifc_policy=server_ifc_policy)) + + manifest = await _invoke_skill_tool(tools["load_skill"], skill_name="packaged-skill") + resource = await _invoke_skill_tool( + tools["read_skill_resource"], + skill_name="packaged-skill", + resource_name="references/private.md", + ) + + assert "Instructions from an archive." in manifest[0].text + assert resource[0].text == "private archive resource" + _assert_ifc_label(manifest, expected_label) + _assert_ifc_label(resource, expected_label) + + async def test_index_ifc_is_not_inherited_by_skill_md(self) -> None: + client = _make_client(**{ + "skill://index.json": _make_text_result( + SAMPLE_SKILL_INDEX, + uri="skill://index.json", + meta=_PRIVATE_IFC_META, + ), + "skill://unit-converter/SKILL.md": _make_text_result(SAMPLE_SKILL_MD), + }) + tools = await _create_skill_tools(_secure_skills_source(client, server_ifc_policy="authoritative")) + + result = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + + assert result[0].text == SAMPLE_SKILL_MD + _assert_ifc_label(result, _IGNORED_IFC_LABEL) + + @pytest.mark.parametrize( + "meta", + [ + {"ifc": {"integrity": "trusted"}}, + { + "ifc": { + "integrity": "trusted", + "confidentiality": "private", + "padding": "x" * 5000, + } + }, + ], + ids=["malformed", "oversized"], + ) + async def test_invalid_ifc_fails_closed(self, meta: dict[str, Any]) -> None: + skill_uri = "skill://unit-converter/SKILL.md" + client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + skill_uri: _make_text_result(SAMPLE_SKILL_MD, uri=skill_uri, meta=meta), + }) + tools = await _create_skill_tools(_secure_skills_source(client)) + + result = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + + assert result[0].additional_properties["security_label"] == { + "integrity": "untrusted", + "confidentiality": "user_identity", + "metadata": {"source": "invalid_mcp_ifc"}, + } + assert "_mcp_tool_result_security_meta" not in result[0].additional_properties + assert "_security_label_authoritative" not in result[0].additional_properties + + async def test_plain_mcp_source_remains_unlabeled(self) -> None: + skill_uri = "skill://unit-converter/SKILL.md" + client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + skill_uri: _make_text_result(SAMPLE_SKILL_MD, uri=skill_uri, meta=_PRIVATE_IFC_META), + }) + tools = await _create_skill_tools(MCPSkillsSource(client=client)) + + result = await _invoke_skill_tool(tools["load_skill"], skill_name="unit-converter") + + assert result[0].text == SAMPLE_SKILL_MD + assert result[0].additional_properties == {} + + @pytest.mark.parametrize("enable_instrumentation", [False, True], indirect=True) + @pytest.mark.usefixtures("span_exporter") + async def test_adapter_does_not_leak_after_result_parser_error(self) -> None: + resource_uri = "skill://unit-converter/references/private.md" + client = _make_client(**{ + "skill://index.json": _make_text_result(SAMPLE_SKILL_INDEX, uri="skill://index.json"), + resource_uri: _make_text_result("private resource", uri=resource_uri, meta=_PRIVATE_IFC_META), + }) + mcp_skill = (await _secure_skills_source(client).get_skills(_SOURCE_CTX))[0] + inline = InlineSkill( + frontmatter=SkillFrontmatter(name="inline-skill", description="Inline test skill."), + instructions="Inline instructions.", + resources=[InlineSkillResource(name="reference.md", content="inline resource")], + ) + tools = await _create_skill_tools([mcp_skill, inline]) + read_tool = tools["read_skill_resource"] + context = FunctionInvocationContext(function=read_tool, arguments={}) + + def fail_parser(value: Any) -> str: + raise ValueError(f"parser failed: {value}") + + read_tool.result_parser = fail_parser + with pytest.raises(ValueError, match="parser failed") as exc_info: + await read_tool.invoke( + arguments={ + "skill_name": "unit-converter", + "resource_name": "references/private.md", + }, + context=context, + ) + error_result = _finalize_function_result( + call_id="call-1", + result=f"Error: {exc_info.value}", + exception=str(exc_info.value), + context=context, + ) + + assert error_result.items is not None + assert "private resource" in error_result.result + assert error_result.items[0].additional_properties["security_label"] == _RESTRICTED_IFC_LABEL + json.dumps(error_result.to_dict()) + + read_tool.result_parser = None + result = await read_tool.invoke( + arguments={ + "skill_name": "inline-skill", + "resource_name": "reference.md", + }, + context=context, + ) + + assert isinstance(result, list) + assert result[0].text == "inline resource" + assert result[0].additional_properties == {} + + async def test_concurrent_resource_reads_keep_adapters_isolated(self) -> None: + first_uri = "skill://unit-converter/references/first.md" + second_uri = "skill://unit-converter/references/second.md" + responses = { + first_uri: _make_text_result("first", uri=first_uri, meta=_PRIVATE_IFC_META), + second_uri: _make_text_result( + "second", + uri=second_uri, + meta={"ifc": {"integrity": "untrusted", "confidentiality": "public"}}, + ), + } + client = AsyncMock() + started: set[str] = set() + both_started = asyncio.Event() + + async def read_resource(uri: str) -> ReadResourceResult: + uri_str = str(uri) + if uri_str == "skill://index.json": + return _make_text_result(SAMPLE_SKILL_INDEX, uri=uri_str) + started.add(uri_str) + if len(started) == 2: + both_started.set() + await asyncio.wait_for(both_started.wait(), timeout=1) + return responses[uri_str] + + client.read_resource = AsyncMock(side_effect=read_resource) + tools = await _create_skill_tools(_secure_skills_source(client, server_ifc_policy="authoritative")) + + first, second = await asyncio.gather( + _invoke_skill_tool( + tools["read_skill_resource"], + skill_name="unit-converter", + resource_name="references/first.md", + ), + _invoke_skill_tool( + tools["read_skill_resource"], + skill_name="unit-converter", + resource_name="references/second.md", + ), + ) + + assert first[0].text == "first" + assert second[0].text == "second" + _assert_ifc_label(first, _AUTHORITATIVE_IFC_LABEL) + _assert_ifc_label(second, _IGNORED_IFC_LABEL) + + async def test_local_inline_and_file_skill_outputs_remain_unchanged(self) -> None: + inline = InlineSkill( + frontmatter=SkillFrontmatter(name="inline-skill", description="Inline test skill."), + instructions="Inline instructions.", + resources=[InlineSkillResource(name="reference.md", content="inline resource")], + ) + file_skill = FileSkill( + frontmatter=SkillFrontmatter(name="file-skill", description="File test skill."), + content="# File instructions", + path="file-skill", + resources=[InlineSkillResource(name="reference.md", content="file resource")], + ) + tools = await _create_skill_tools([inline, file_skill]) + + for skill, expected_resource in ((inline, "inline resource"), (file_skill, "file resource")): + manifest = await _invoke_skill_tool(tools["load_skill"], skill_name=skill.frontmatter.name) + resource = await _invoke_skill_tool( + tools["read_skill_resource"], + skill_name=skill.frontmatter.name, + resource_name="reference.md", + ) + + assert manifest[0].text == await skill.get_content() + assert manifest[0].additional_properties == {} + assert resource[0].text == expected_resource + assert resource[0].additional_properties == {} + + # --------------------------------------------------------------------------- # Archive skill discovery tests (through MCPSkillsSource) # --------------------------------------------------------------------------- diff --git a/python/packages/core/tests/test_security.py b/python/packages/core/tests/test_security.py index be49c4fa6db..3565db2df90 100644 --- a/python/packages/core/tests/test_security.py +++ b/python/packages/core/tests/test_security.py @@ -8622,9 +8622,7 @@ async def fake_call(**kwargs: Any) -> list[Content]: }, ) _wrap_mcp_function_for_ifc(function, IntegrityLabel.TRUSTED) - assert function.func is not None - - result = await function.func() + result = await _invoke_mcp_function(function) assert result[0].additional_properties["security_label"] == { "integrity": "untrusted", @@ -8687,8 +8685,7 @@ async def fake_call(**kwargs): }, ) _wrap_mcp_function_for_ifc(func_tool, IntegrityLabel.UNTRUSTED) - assert func_tool.func is not None - result = await func_tool.func() + result = await _invoke_mcp_function(func_tool) assert isinstance(result, list) assert result[0].additional_properties["security_label"] == { "integrity": "untrusted", @@ -8714,8 +8711,7 @@ async def fake_call(**kwargs): }, ) _wrap_mcp_function_for_ifc(func_tool, IntegrityLabel.UNTRUSTED) - assert func_tool.func is not None - result = await func_tool.func() + result = await _invoke_mcp_function(func_tool) assert result[0].additional_properties["security_label"] == { "integrity": "untrusted", "confidentiality": "public", @@ -8749,8 +8745,7 @@ async def fake_call(**kwargs): }, ) _wrap_mcp_function_for_ifc(func_tool, IntegrityLabel.UNTRUSTED) - assert func_tool.func is not None - result = await func_tool.func() + result = await _invoke_mcp_function(func_tool) assert result[0].additional_properties["security_label"] == { "integrity": "untrusted", "confidentiality": confidentiality.value, @@ -8778,9 +8773,7 @@ async def fake_call(**kwargs: Any) -> list[Content]: }, ) _wrap_mcp_function_for_ifc(func_tool, IntegrityLabel.UNTRUSTED) - assert func_tool.func is not None - - result = await func_tool.func() + result = await _invoke_mcp_function(func_tool) assert result[0].additional_properties["security_label"] == { "integrity": "trusted", @@ -8809,8 +8802,7 @@ async def test_wrap_mcp_function_reads_refreshed_local_policy_at_invocation(self await proxy.refresh_labels() assert props["source_integrity"] == "untrusted" assert mcp_tool.load_tools.await_count == 2 # type: ignore[union-attr] - assert function.func is not None - result = await function.func() + result = await _invoke_mcp_function(function) assert result[0].additional_properties["security_label"] == { "integrity": "untrusted", @@ -8880,22 +8872,30 @@ async def fake_call(**kwargs: Any) -> list[Content]: additional_properties={"_mcp_remote_name": "remote_tool", **start_properties}, ) _wrap_mcp_function_for_ifc(function, IntegrityLabel.UNTRUSTED) - assert function.func is not None - - first_call = asyncio.create_task(function.func()) + first_call = asyncio.create_task(_invoke_mcp_function(function)) await call_started.wait() assert function.additional_properties is not None function.additional_properties.update(refreshed_properties) release_call.set() first_result = await first_call - second_result = await function.func() + second_result = await _invoke_mcp_function(function) assert first_result[0].additional_properties["security_label"] == first_label assert second_result[0].additional_properties["security_label"] == second_label - @pytest.mark.parametrize("trust_server_ifc", [False, True], ids=["default", "trusted"]) - async def test_apply_mcp_security_labels_configures_result_authority(self, trust_server_ifc: bool): + @pytest.mark.parametrize( + ("server_ifc_policy", "expected_label"), + [ + pytest.param("restrict", {"integrity": "untrusted", "confidentiality": "private"}, id="restrict"), + pytest.param("authoritative", {"integrity": "trusted", "confidentiality": "public"}, id="authoritative"), + ], + ) + async def test_apply_mcp_security_labels_configures_result_authority( + self, + server_ifc_policy: Literal["restrict", "authoritative"], + expected_label: dict[str, str], + ): from agent_framework.security import apply_mcp_security_labels annotations = SimpleNamespace(read_only_hint=True, open_world_hint=False) @@ -8905,26 +8905,70 @@ async def test_apply_mcp_security_labels_configures_result_authority(self, trust } mcp_tool, function = _make_connected_mcp_tool_for_ifc(annotations=annotations, server_meta=server_meta) - if trust_server_ifc: - await apply_mcp_security_labels(mcp_tool, trust_server_ifc=True) - else: - await apply_mcp_security_labels(mcp_tool) + await apply_mcp_security_labels(mcp_tool, server_ifc_policy=server_ifc_policy) props = function.additional_properties assert props is not None assert props["source_integrity"] == "untrusted" assert props["max_allowed_confidentiality"] == "public" assert props["accepts_untrusted"] is False - assert props["_mcp_trust_server_ifc"] is trust_server_ifc - assert function.func is not None - result = await function.func() - expected_label = ( - {"integrity": "trusted", "confidentiality": "public"} - if trust_server_ifc - else {"integrity": "untrusted", "confidentiality": "private"} - ) + assert props["_mcp_server_ifc_policy"] == server_ifc_policy + assert props["_mcp_trust_server_ifc"] is (server_ifc_policy == "authoritative") + result = await _invoke_mcp_function(function) assert result[0].additional_properties["security_label"] == expected_label + async def test_apply_mcp_security_labels_can_ignore_server_ifc(self) -> None: + from agent_framework.security import apply_mcp_security_labels + + annotations = SimpleNamespace(read_only_hint=True, open_world_hint=False) + server_meta = {"ifc": {"integrity": "untrusted", "confidentiality": "private"}} + mcp_tool, function = _make_connected_mcp_tool_for_ifc( + annotations=annotations, + server_meta=server_meta, + confidentiality=ConfidentialityLabel.PUBLIC, + ) + + await apply_mcp_security_labels( + mcp_tool, + default_integrity=IntegrityLabel.TRUSTED, + server_ifc_policy="ignore", + ) + + result = await _invoke_mcp_function(function) + assert result[0].additional_properties["security_label"] == { + "integrity": "trusted", + "confidentiality": "public", + } + + @pytest.mark.parametrize( + ("trust_server_ifc", "expected_policy"), + [(False, "restrict"), (True, "authoritative")], + ) + async def test_apply_mcp_security_labels_deprecated_trust_alias( + self, + trust_server_ifc: bool, + expected_policy: str, + ) -> None: + from agent_framework.security import apply_mcp_security_labels + + annotations = SimpleNamespace(read_only_hint=True, open_world_hint=False) + mcp_tool, function = _make_connected_mcp_tool_for_ifc(annotations=annotations, server_meta={}) + + with pytest.warns(DeprecationWarning, match="trust_server_ifc is deprecated"): + await apply_mcp_security_labels(mcp_tool, trust_server_ifc=trust_server_ifc) + + assert function.additional_properties is not None + assert function.additional_properties["_mcp_server_ifc_policy"] == expected_policy + + async def test_apply_mcp_security_labels_rejects_invalid_server_ifc_policy(self) -> None: + from agent_framework.security import apply_mcp_security_labels + + annotations = SimpleNamespace(read_only_hint=True, open_world_hint=False) + mcp_tool, _ = _make_connected_mcp_tool_for_ifc(annotations=annotations, server_meta={}) + + with pytest.raises(ValueError, match="server_ifc_policy"): + await apply_mcp_security_labels(mcp_tool, server_ifc_policy=cast(Any, "invalid")) + async def test_apply_mcp_security_labels_uses_loaded_annotation_snapshot(self) -> None: from agent_framework._mcp import _ClientMCPConnection from agent_framework.security import apply_mcp_security_labels @@ -8950,14 +8994,12 @@ async def test_framework_stamped_mcp_label_remains_authoritative_through_trackin annotations=annotations, server_meta=server_meta, ) - await apply_mcp_security_labels(mcp_tool, trust_server_ifc=True) - wrapped = function.func - assert wrapped is not None + await apply_mcp_security_labels(mcp_tool, server_ifc_policy="authoritative") tracker = LabelTrackingFunctionMiddleware() context = FunctionInvocationContext(function=function, arguments={}) async def next_fn() -> None: - context.result = await wrapped() + context.result = await function.invoke(arguments={}, context=context, skip_parsing=True) await tracker.process(context, next_fn) @@ -8973,33 +9015,45 @@ async def test_apply_mcp_security_labels_reconfigures_existing_wrapper_authority server_meta = {"ifc": {"integrity": "trusted", "confidentiality": "public"}} mcp_tool, function = _make_connected_mcp_tool_for_ifc(annotations=annotations, server_meta=server_meta) await apply_mcp_security_labels(mcp_tool) - wrapped = function.func + original = function.func props = function.additional_properties assert props is not None assert props["max_allowed_confidentiality"] == "public" - await apply_mcp_security_labels(mcp_tool, mark_write_tools_as_sinks=False, trust_server_ifc=True) + await apply_mcp_security_labels( + mcp_tool, + mark_write_tools_as_sinks=False, + server_ifc_policy="authoritative", + ) - assert function.func is wrapped + assert function.func is original assert "max_allowed_confidentiality" not in props - assert function.func is not None - result = await function.func() + assert props["_mcp_server_ifc_policy"] == "authoritative" + result = await _invoke_mcp_function(function) assert result[0].additional_properties["security_label"] == { "integrity": "trusted", "confidentiality": "public", } - @pytest.mark.parametrize("trust_server_ifc", [False, True], ids=["default", "trusted"]) - async def test_secure_mcp_proxy_configures_result_authority(self, trust_server_ifc: bool): + @pytest.mark.parametrize( + ("server_ifc_policy", "expected_label"), + [ + pytest.param("restrict", {"integrity": "untrusted", "confidentiality": "private"}, id="restrict"), + pytest.param("authoritative", {"integrity": "trusted", "confidentiality": "public"}, id="authoritative"), + ], + ) + async def test_secure_mcp_proxy_configures_result_authority( + self, + server_ifc_policy: Literal["restrict", "authoritative"], + expected_label: dict[str, str], + ): from agent_framework.security import SecureMCPToolProxy annotations = SimpleNamespace(read_only_hint=True, open_world_hint=False) server_meta = {"ifc": {"integrity": "trusted", "confidentiality": "public"}} mcp_tool, function = _make_connected_mcp_tool_for_ifc(annotations=annotations, server_meta=server_meta) mcp_tool.load_tools = AsyncMock() # type: ignore[method-assign] - proxy = ( - SecureMCPToolProxy(mcp_tool, trust_server_ifc=True) if trust_server_ifc else SecureMCPToolProxy(mcp_tool) - ) + proxy = SecureMCPToolProxy(mcp_tool, server_ifc_policy=server_ifc_policy) await proxy.refresh_labels() @@ -9008,16 +9062,28 @@ async def test_secure_mcp_proxy_configures_result_authority(self, trust_server_i assert props["source_integrity"] == "untrusted" assert props["max_allowed_confidentiality"] == "public" assert props["accepts_untrusted"] is False - assert props["_mcp_trust_server_ifc"] is trust_server_ifc - assert function.func is not None - result = await function.func() - expected_label = ( - {"integrity": "trusted", "confidentiality": "public"} - if trust_server_ifc - else {"integrity": "untrusted", "confidentiality": "private"} - ) + assert props["_mcp_server_ifc_policy"] == server_ifc_policy + assert props["_mcp_trust_server_ifc"] is (server_ifc_policy == "authoritative") + result = await _invoke_mcp_function(function) assert result[0].additional_properties["security_label"] == expected_label + @pytest.mark.parametrize( + ("trust_server_ifc", "expected_policy"), + [(False, "restrict"), (True, "authoritative")], + ) + def test_secure_mcp_proxy_deprecated_trust_alias( + self, + trust_server_ifc: bool, + expected_policy: str, + ) -> None: + from agent_framework.security import SecureMCPToolProxy + + mcp_tool = _make_connected_mcp_discovery_tool() + with pytest.warns(DeprecationWarning, match="trust_server_ifc is deprecated"): + proxy = SecureMCPToolProxy(mcp_tool, trust_server_ifc=trust_server_ifc) + + assert proxy._server_ifc_policy == expected_policy # pyright: ignore[reportPrivateUsage] + async def test_secure_mcp_proxy_refresh_respects_disabled_tool_loading(self) -> None: from agent_framework.security import SecureMCPToolProxy @@ -9067,8 +9133,9 @@ async def test_secure_mcp_proxy_labels_notification_reload_before_publication(se assert late_function.additional_properties["source_integrity"] == "untrusted" assert late_function.additional_properties["max_allowed_confidentiality"] == "public" assert late_function.additional_properties["accepts_untrusted"] is False + assert late_function.additional_properties["_mcp_server_ifc_policy"] == "restrict" assert late_function.additional_properties["_mcp_trust_server_ifc"] is False - assert getattr(late_function.func, "_ifc_wrapped", False) is True + assert getattr(late_function, "_result_postprocessor", None) is not None context = FunctionInvocationContext(function=late_function, arguments={}) context.metadata["context_label"] = ContentLabel(confidentiality=ConfidentialityLabel.PRIVATE) @@ -9112,7 +9179,7 @@ async def test_secure_mcp_proxy_labels_progressive_hidden_function_before_exposu assert hidden_function.additional_properties is not None assert hidden_function.additional_properties["source_integrity"] == "untrusted" assert hidden_function.additional_properties["max_allowed_confidentiality"] == "public" - assert getattr(hidden_function.func, "_ifc_wrapped", False) is True + assert getattr(hidden_function, "_result_postprocessor", None) is not None load_function = next(function for function in mcp_tool.functions if function.name == "load_tool") context = FunctionInvocationContext( @@ -9156,7 +9223,7 @@ async def test_secure_mcp_proxy_applies_local_policy_to_later_tool(self): proxy = SecureMCPToolProxy( mcp_tool, annotation_overrides={"later_tool": (IntegrityLabel.TRUSTED, ConfidentialityLabel.PRIVATE)}, - trust_server_ifc=True, + server_ifc_policy="authoritative", ) await proxy.refresh_labels() await mcp_tool.load_tools() @@ -9165,6 +9232,7 @@ async def test_secure_mcp_proxy_applies_local_policy_to_later_tool(self): assert function.additional_properties is not None assert function.additional_properties["source_integrity"] == "trusted" assert function.additional_properties["max_allowed_confidentiality"] == "private" + assert function.additional_properties["_mcp_server_ifc_policy"] == "authoritative" assert function.additional_properties["_mcp_trust_server_ifc"] is True result = await _invoke_mcp_function(function) assert result[0].additional_properties["security_label"] == { @@ -9266,7 +9334,7 @@ async def test_plain_mcp_tool_remains_unlabeled(self): "_mcp_normalized_name": "plain_tool", "_mcp_is_tool": True, } - assert getattr(function.func, "_ifc_wrapped", False) is False + assert getattr(function, "_result_postprocessor", None) is None result = await _invoke_mcp_function(function) assert result[0].additional_properties["_meta"] == { "ifc": {"integrity": "trusted", "confidentiality": "private"} @@ -9291,8 +9359,7 @@ async def fake_call(**kwargs): }, ) _wrap_mcp_function_for_ifc(func_tool, IntegrityLabel.UNTRUSTED) - assert func_tool.func is not None - result = await func_tool.func() + result = await _invoke_mcp_function(func_tool) assert result == "plain string result" async def test_wrap_mcp_function_is_idempotent(self): @@ -9312,10 +9379,11 @@ async def fake_call(**kwargs): "_mcp_remote_name": "remote_tool", }, ) + original = func_tool.func _wrap_mcp_function_for_ifc(func_tool, IntegrityLabel.UNTRUSTED) - wrapped_once = func_tool.func _wrap_mcp_function_for_ifc(func_tool, IntegrityLabel.UNTRUSTED) - assert func_tool.func is wrapped_once + assert func_tool.func is original + assert getattr(func_tool, "_result_postprocessor", None) is not None async def _hide_session_value( diff --git a/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py b/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py index 94d946c2192..00fd6705635 100644 --- a/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py +++ b/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py @@ -47,6 +47,7 @@ "standing_guidance", "agent_framework.security.principals", "_agent_framework_internal_security_tool", + "_mcp_server_ifc_policy", "_mcp_trust_server_ifc", }) OUTPUT_FILE_RETRY_ATTEMPTS = 10 diff --git a/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py b/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py index 80f4da03aad..2ce5963c485 100644 --- a/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py +++ b/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py @@ -528,6 +528,7 @@ def test_execute_code_tool_updates_approval_with_managed_tools() -> None: {"standing_guidance": []}, {"agent_framework.security.principals": []}, {"_agent_framework_internal_security_tool": object()}, + {"_mcp_server_ifc_policy": "restrict"}, {"_mcp_trust_server_ifc": False}, ], ) diff --git a/python/packages/monty/agent_framework_monty/_execute_code_tool.py b/python/packages/monty/agent_framework_monty/_execute_code_tool.py index 0cb4923d230..c806c8258a2 100644 --- a/python/packages/monty/agent_framework_monty/_execute_code_tool.py +++ b/python/packages/monty/agent_framework_monty/_execute_code_tool.py @@ -49,6 +49,7 @@ "standing_guidance", "agent_framework.security.principals", "_agent_framework_internal_security_tool", + "_mcp_server_ifc_policy", "_mcp_trust_server_ifc", }) diff --git a/python/packages/monty/tests/monty/test_monty_codeact.py b/python/packages/monty/tests/monty/test_monty_codeact.py index 94e2a2a314f..9bb3a9270b5 100644 --- a/python/packages/monty/tests/monty/test_monty_codeact.py +++ b/python/packages/monty/tests/monty/test_monty_codeact.py @@ -279,6 +279,7 @@ def test_tool_construction_defaults() -> None: {"standing_guidance": []}, {"agent_framework.security.principals": []}, {"_agent_framework_internal_security_tool": object()}, + {"_mcp_server_ifc_policy": "restrict"}, {"_mcp_trust_server_ifc": False}, ], ) diff --git a/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md b/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md index 0780197dcfe..52c66a87a5b 100644 --- a/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md +++ b/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md @@ -590,15 +590,35 @@ async def run_secure_github_mcp(github_pat: str, endpoint: str) -> None: - Per-result label mapping from `_meta.ifc` into FIDES `security_label`; by default, remote labels are combined with local policy and can only add restrictions -Set `trust_server_ifc=True` only when the MCP server is an authenticated authority for result labels. In that mode, -a complete valid `_meta.ifc` label is authoritative for that result, including permitted relaxation of the local -fallback. Missing, partial, or malformed labels still use current local policy. This opt-in does not make -ToolAnnotations authoritative: `readOnlyHint` and `openWorldHint` remain restriction-only hints. +Choose how result `_meta.ifc` is handled with `server_ifc_policy`: ```python -secure_mcp = SecureMCPToolProxy(url="https://trusted.example.com/mcp/", trust_server_ifc=True) +secure_mcp = SecureMCPToolProxy( + url="https://trusted.example.com/mcp/", + server_ifc_policy="authoritative", +) +``` + +- `"ignore"` uses local policy only. +- `"restrict"` (the default) lets valid server labels add restrictions but never relax local policy. +- `"authoritative"` accepts a complete valid server label as authoritative, including permitted relaxation of the + local fallback. Use it only when the MCP server is an authenticated label authority. + +Missing labels use local policy. Partial, malformed, oversized, or unretainable labels fail closed when server IFC is +processed. This setting does not make ToolAnnotations authoritative: `readOnlyHint` and `openWorldHint` remain +restriction-only hints. +The deprecated `trust_server_ifc=True` and `False` values map to `"authoritative"` and `"restrict"` respectively. + +Use the same proxy for MCP Skills so each `resources/read` result keeps its own IFC label: + +```python +async with SecureMCPToolProxy(url="https://trusted.example.com/mcp/") as secure_mcp: + skills_provider = SkillsProvider(secure_mcp.skills_source()) ``` +Pass `skills_provider` in the agent's `context_providers`. Direct `MCPSkillsSource(...)` construction does not apply +FIDES labels. + `annotation_overrides` supplies explicit local policy keyed by remote MCP tool name. It applies only to the `MCPTool` passed to `apply_mcp_security_labels`, or the connection wrapped by `SecureMCPToolProxy`; the mapping itself is not bound to a server identity. Reusing a mapping for another connection applies its overrides to @@ -609,10 +629,11 @@ reusing it; a shared tool name does not establish shared trust. 1. Prefer `async with SecureMCPToolProxy(...)` so connection and label application happen together. 2. Pass `secure_mcp.tools` into `Agent(..., tools=...)`. -3. Use `context_providers=[SecureAgentConfig(...)]` instead of manual security wiring. -4. Keep `auto_hide_untrusted=True` unless you have a very specific reason to expose untrusted content. -5. If write-like actions are blocked, inspect `config.get_audit_log(session)` first. -6. Leave `trust_server_ifc=False` unless the connected server is explicitly trusted to label result data. +3. For MCP Skills, create `SkillsProvider(secure_mcp.skills_source())`. +4. Use `context_providers=[SecureAgentConfig(...)]` instead of manual security wiring. +5. Keep `auto_hide_untrusted=True` unless you have a very specific reason to expose untrusted content. +6. If write-like actions are blocked, inspect `config.get_audit_log(session)` first. +7. Leave `server_ifc_policy="restrict"` unless the connected server is explicitly trusted as a label authority. ### 7. Security Tools diff --git a/python/samples/02-agents/security/README.md b/python/samples/02-agents/security/README.md index 1afbfeb35d3..1c25a04b718 100644 --- a/python/samples/02-agents/security/README.md +++ b/python/samples/02-agents/security/README.md @@ -12,7 +12,7 @@ security model, middleware behavior, and API reference. | `email_security_example.py` | Prompt injection defense | `SecureAgentConfig`, Foundry-backed email handling, `quarantined_llm`, and approval on policy violations | | `repo_confidentiality_example.py` | Data exfiltration prevention | Confidentiality labels, Foundry-backed repository access, `max_allowed_confidentiality`, and approval before leaking private data | | `user_identity_security_example.py` | Principal-bound identity data | Canonical tenant/user principals, identity-scoped sources and destinations, and allowed versus blocked flows | -| `github_mcp_example.py` | Remote MCP URL with local FIDES enforcement | `SecureMCPToolProxy(url=...)`, direct GitHub MCP access, tool auto-labeling, and post-tool-call policy enforcement | +| `github_mcp_example.py` | Remote MCP URL with local FIDES enforcement | `SecureMCPToolProxy(url=...)`, IFC policy selection, secured MCP tools and Skills, and post-result policy enforcement | | `provider_message_labeling_example.py` | Central provider-message labeling | `SecureAgentConfig.message_labeler` classifies messages from existing history, memory, and context providers | ## Prerequisites @@ -114,7 +114,10 @@ This sample connects directly to `https://api.githubcopilot.com/mcp/` through `MCPStreamableHTTPTool`, then wraps the MCP client in `SecureMCPToolProxy` so FIDES middleware can inspect tool results and enforce policy locally. The `X-MCP-Features: ifc_labels` header is passed to opt in to server-side IFC label -emission in tool result `_meta`. +emission in result `_meta`. The same proxy supplies +`SkillsProvider(secure_github.skills_source())`, so MCP Skills resource reads +use the same IFC policy. Servers without `skill://index.json` contribute no +skills. Run it with: @@ -128,6 +131,8 @@ uv run samples/02-agents/security/github_mcp_example.py --devui --debug What to look for: - MCP tools are auto-labeled from remote annotations +- MCP Skills retain per-read IFC labels through `secure_github.skills_source()` +- `server_ifc_policy="restrict"` lets server IFC add restrictions without relaxing local policy - Untrusted tool output is tracked by FIDES label middleware - Attack-mode write attempts can trigger policy enforcement or approval diff --git a/python/samples/02-agents/security/github_mcp_example.py b/python/samples/02-agents/security/github_mcp_example.py index a8c7d5a1a35..57b4244b9eb 100644 --- a/python/samples/02-agents/security/github_mcp_example.py +++ b/python/samples/02-agents/security/github_mcp_example.py @@ -6,10 +6,13 @@ (`https://api.githubcopilot.com/mcp/`) while enforcing IFC/FIDES security locally in your process. -The key idea: wrap the remote MCP URL with `SecureMCPToolProxy(...)` so the MCP -tools run locally. This lets the security middleware inspect tool results, apply -IFC labels, hide untrusted content, and enforce policies before the agent uses -any tool data. The agent is then served through DevUI for interactive use. +The key idea: wrap the remote MCP URL with `SecureMCPToolProxy(...)` so MCP +tools and MCP Skills use the same local IFC policy. This lets the security +middleware inspect results, apply IFC labels, hide untrusted content, and +enforce policies before the agent uses server data. +``server_ifc_policy="restrict"`` lets server labels add restrictions without +granting them authority to relax local policy. The agent is then served through +DevUI for interactive use. Prerequisites (environment variables): - GITHUB_PAT: GitHub Personal Access Token (required) @@ -29,9 +32,9 @@ from pathlib import Path import uvicorn -from agent_framework import Agent +from agent_framework import Agent, SkillsProvider from agent_framework.foundry import FoundryChatClient -from agent_framework.security import SecureAgentConfig, SecureMCPToolProxy +from agent_framework.security import IntegrityLabel, SecureAgentConfig, SecureMCPToolProxy from agent_framework_devui._server import DevServer from azure.identity import AzureCliCredential from dotenv import load_dotenv @@ -70,10 +73,23 @@ async def main() -> None: headers={"Authorization": f"Bearer {github_pat}", **MCP_HEADERS}, name="GitHub", description="GitHub MCP server over Streamable HTTP", + # This is the local MCP result baseline. It is explicit tool + # policy, so it takes precedence over SecureAgentConfig's + # default_integrity for these MCP functions. + default_integrity=IntegrityLabel.UNTRUSTED, + # "ignore": local policy only; "restrict": server labels may only + # add restrictions to the local baseline; "authoritative": trust + # complete server labels. + server_ifc_policy="restrict", ) ) print(f"Connected to MCP URL: {MCP_URL} ({len(secure_github.tools)} tools loaded)") + # Reuse the secured connection for MCP Skills. Each SKILL.md, resource, + # or archive read applies its own _meta.ifc label after final parsing. + # A server without skill://index.json simply contributes no skills. + skills_provider = SkillsProvider(secure_github.skills_source()) + # SecureAgentConfig is a context provider that applies the IFC/FIDES policy: # hide untrusted content, enforce policies, and require approval on violations. config = SecureAgentConfig( @@ -89,7 +105,7 @@ async def main() -> None: name="GitHubSecureMcpUrlAgent", instructions=_AGENT_INSTRUCTIONS, tools=secure_github.tools, - context_providers=[config], + context_providers=[skills_provider, config], ) ) From 4b600f453a245239bcf856e4c8ae9b715bfdb9b5 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Fri, 13 Nov 2026 12:05:38 +0100 Subject: [PATCH 7/7] fix MCP IFC review findings --- .../packages/core/agent_framework/_tools.py | 60 +++-- .../packages/core/agent_framework/security.py | 148 ++++++++-- python/packages/core/tests/core/test_mcp.py | 252 ++++++++++++++++++ python/packages/hyperlight/README.md | 25 +- .../_execute_code_tool.py | 14 +- .../agent_framework_hyperlight/_provider.py | 5 + .../hyperlight/test_hyperlight_codeact.py | 28 ++ python/packages/monty/AGENTS.md | 4 + python/packages/monty/README.md | 25 +- .../_execute_code_tool.py | 13 +- .../monty/agent_framework_monty/_provider.py | 5 + .../monty/tests/monty/test_monty_codeact.py | 26 ++ .../security/FIDES_DEVELOPER_GUIDE.md | 31 ++- 13 files changed, 570 insertions(+), 66 deletions(-) diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 9a1cd189298..07402194e28 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -340,33 +340,49 @@ def postprocess( contents: list[Content], context: FunctionInvocationContext, function: FunctionTool, - ) -> list[Content]: ... + ) -> list[Content]: + raise NotImplementedError def handle_error( self, context: FunctionInvocationContext, function: FunctionTool, - ) -> None: ... + ) -> None: + pass class _FunctionResultPostprocessor(typing.Protocol): """Private final-result hook that cannot be replaced by a user parser.""" - def before_invoke(self, context: FunctionInvocationContext | None) -> None: ... + def before_invoke( + self, + context: FunctionInvocationContext | None, + function: FunctionTool, + ) -> None: + pass def postprocess( self, contents: list[Content], context: FunctionInvocationContext | None, - ) -> list[Content]: ... + function: FunctionTool, + ) -> list[Content]: + raise NotImplementedError def postprocess_raw( self, result: Any, context: FunctionInvocationContext | None, - ) -> Any: ... + function: FunctionTool, + ) -> Any: + pass - def handle_error(self, context: FunctionInvocationContext | None) -> None: ... + def handle_error( + self, + context: FunctionInvocationContext | None, + function: FunctionTool, + ) -> None: + pass class _FunctionResultPayloadBudget: @@ -414,6 +430,11 @@ class _SkipParsingSentinel: request the raw value on a per-call basis by passing ``skip_parsing=True`` to :meth:`FunctionTool.invoke`. + Raw invocation bypasses operation-scoped adapters that depend on normalized + ``Content`` items. Scalar values therefore do not gain per-item security labels. + A tool's private final-result hook may still process raw values it explicitly + supports, such as an existing ``list[Content]``. + Use the module-level ``SKIP_PARSING`` singleton — do not instantiate this class. """ @@ -1194,14 +1215,19 @@ async def invoke( ``skip_parsing=True`` per call. Either way the wrapped function's raw value is returned. This is intended for callers (e.g. sandboxed runtimes) that consume the value from Python directly and would otherwise undo the - ``Content`` wrapping. + ``Content`` wrapping. Operation-scoped adapters that run after ``Content`` + normalization are bypassed, so scalar raw values do not gain per-item + security labels. Private final-result hooks may still process compatible + raw values such as an existing ``list[Content]``. Keyword Args: arguments: A mapping or model instance containing the arguments for the function. context: Explicit function invocation context carrying runtime kwargs. tool_call_id: Optional tool call identifier used for telemetry and tracing. skip_parsing: When ``True``, bypass parsing and return the wrapped function's - raw value instead of a ``list[Content]``. Defaults to ``False``. + raw value instead of a ``list[Content]``. This also bypasses + operation-scoped adapters that require normalized content. Defaults + to ``False``. kwargs: Direct function argument values. When provided, every keyword must match a declared tool parameter. Runtime data must be passed via ``context``. @@ -1290,7 +1316,7 @@ async def invoke( if isinstance(carrier, _FunctionResultCarrier): carrier.result_adapter = None if self._result_postprocessor is not None: - self._result_postprocessor.before_invoke(effective_context) + self._result_postprocessor.before_invoke(effective_context, self) if not OBSERVABILITY_SETTINGS.ENABLED: logger.info(f"Function name: {self.name}") @@ -1300,11 +1326,11 @@ async def invoke( result = await self._invoke_function(call_kwargs) except Exception: if self._result_postprocessor is not None: - self._result_postprocessor.handle_error(effective_context) + self._result_postprocessor.handle_error(effective_context, self) raise if skip_parsing: if self._result_postprocessor is not None: - result = self._result_postprocessor.postprocess_raw(result, effective_context) + result = self._result_postprocessor.postprocess_raw(result, effective_context, self) logger.info(f"Function {self.name} succeeded.") logger.debug(f"Function result: {type(result).__name__}") return result @@ -1330,7 +1356,7 @@ async def invoke( carrier.result_adapter = None result_adapter.handle_error(effective_context, self) if self._result_postprocessor is not None: - self._result_postprocessor.handle_error(effective_context) + self._result_postprocessor.handle_error(effective_context, self) self.invocation_exception_count += 1 if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: logger.error(f"Function {self.name}: result parser failed. Error: {exception}") @@ -1346,7 +1372,7 @@ async def invoke( if isinstance(parsed, str): parsed = [Content.from_text(parsed)] if self._result_postprocessor is not None: - parsed = self._result_postprocessor.postprocess(parsed, effective_context) + parsed = self._result_postprocessor.postprocess(parsed, effective_context, self) if ( isinstance(carrier, _FunctionResultCarrier) and carrier.result_adapter is not None @@ -1408,7 +1434,7 @@ async def invoke( except Exception as exception: end_time_stamp = perf_counter() if self._result_postprocessor is not None: - self._result_postprocessor.handle_error(effective_context) + self._result_postprocessor.handle_error(effective_context, self) metric_attributes[OtelAttr.ERROR_TYPE] = type(exception).__name__ capture_exception(span=span, exception=exception, timestamp=time_ns()) if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: @@ -1419,7 +1445,7 @@ async def invoke( else: if skip_parsing: if self._result_postprocessor is not None: - result = self._result_postprocessor.postprocess_raw(result, effective_context) + result = self._result_postprocessor.postprocess_raw(result, effective_context, self) logger.info(f"Function {self.name} succeeded.") if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: result_str = str(result) @@ -1449,7 +1475,7 @@ async def invoke( carrier.result_adapter = None result_adapter.handle_error(effective_context, self) if self._result_postprocessor is not None: - self._result_postprocessor.handle_error(effective_context) + self._result_postprocessor.handle_error(effective_context, self) self.invocation_exception_count += 1 metric_attributes[OtelAttr.ERROR_TYPE] = type(exception).__name__ if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED: @@ -1469,7 +1495,7 @@ async def invoke( if isinstance(parsed, str): parsed = [Content.from_text(parsed)] if self._result_postprocessor is not None: - parsed = self._result_postprocessor.postprocess(parsed, effective_context) + parsed = self._result_postprocessor.postprocess(parsed, effective_context, self) if ( isinstance(carrier, _FunctionResultCarrier) and carrier.result_adapter is not None diff --git a/python/packages/core/agent_framework/security.py b/python/packages/core/agent_framework/security.py index 09c68f92d7c..7922eab1be5 100644 --- a/python/packages/core/agent_framework/security.py +++ b/python/packages/core/agent_framework/security.py @@ -142,6 +142,7 @@ _SECURITY_MATERIALIZED_AUTHORITY_CONTEXT_KEY = "_agent_framework_core_security_materialized_authority" _SECURITY_RESOLVED_AUTHORITY_CONTEXT_KEY = "_agent_framework_core_security_resolved_authority" _SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY = "_agent_framework_core_security_result_fallback_label" +_SECURITY_NESTED_RESULT_RESTRICTION_CONTEXT_KEY = "_agent_framework_core_security_nested_result_restriction" _MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY = "_agent_framework_core_mcp_ifc_policy_snapshots" _TOOL_POLICY_ACCEPTS_UNTRUSTED_KEY = "accepts_untrusted" _TOOL_POLICY_CONFIDENTIALITY_KEY = "confidentiality" @@ -2893,6 +2894,7 @@ async def process( context.metadata["context_label"] = context_label context.metadata["argument_label"] = argument_label context.metadata[_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY] = fallback_label + context.metadata.pop(_SECURITY_NESTED_RESULT_RESTRICTION_CONTEXT_KEY, None) context.metadata["effective_invocation_label"] = combine_labels(context_label, argument_label) materialization_token = _SECURITY_ARGUMENT_MATERIALIZATION_CONTEXT.set(( @@ -2944,6 +2946,10 @@ def _label_result( captured before call_next() so a tool body cannot inject or alter it at runtime. None if the tool declared none. """ + nested_restriction = context.metadata.pop(_SECURITY_NESTED_RESULT_RESTRICTION_CONTEXT_KEY, None) + if isinstance(nested_restriction, ContentLabel): + fallback_label = combine_labels(fallback_label, nested_restriction) + standing_guidance_items = self._standing_guidance_items(standing_guidance, fallback_label) if context.result is None: @@ -6021,6 +6027,68 @@ def _stamp_mcp_content_labels( return contents_list +def _validated_principal_restriction(label: ContentLabel) -> ContentLabel | None: + """Return the confidentiality-only restriction for validated identity principals.""" + if label.confidentiality != ConfidentialityLabel.USER_IDENTITY: + return None + try: + principals = _canonical_principals( + label.metadata.get(PRINCIPAL_METADATA_KEY), + source="validated nested MCP label", + ) + except ValueError: + return None + return ContentLabel( + integrity=IntegrityLabel.TRUSTED, + confidentiality=ConfidentialityLabel.USER_IDENTITY, + metadata={PRINCIPAL_METADATA_KEY: _principal_list(principals)}, + ) + + +def _record_nested_mcp_principal_restriction( + label: ContentLabel, + function: FunctionTool, +) -> None: + """Carry validated nested MCP principals into the owning outer invocation.""" + active_context = _current_context.get() + active_middleware = _current_middleware.get() + if active_context is None or active_middleware is None: + return + active_authority = active_context.metadata.get(_SECURITY_RESOLVED_AUTHORITY_CONTEXT_KEY) + if not isinstance(active_authority, _SecurityInvocationAuthority) or active_authority.function is function: + return + restriction = _validated_principal_restriction(label) + if restriction is None: + return + existing = active_context.metadata.get(_SECURITY_NESTED_RESULT_RESTRICTION_CONTEXT_KEY) + if isinstance(existing, ContentLabel): + restriction = combine_labels(existing, restriction) + active_context.metadata[_SECURITY_NESTED_RESULT_RESTRICTION_CONTEXT_KEY] = restriction + + +def _record_nested_mcp_content_restrictions( + contents: list[Content], + function: FunctionTool, +) -> None: + """Record only framework-validated identity restrictions before marker cleanup.""" + for item in contents: + props = item.additional_properties or {} + if props.get(_VALIDATED_SECURITY_LABEL_PRINCIPALS) is not _INTERNAL_RESULT_MARKER: + continue + label_data = props.get("security_label") + if not isinstance(label_data, MutableMapping): + continue + try: + label = _parse_content_label( + cast(MutableMapping[str, Any], label_data), + source="nested MCP result", + allow_principals=True, + ) + except (TypeError, ValueError): + continue + _record_nested_mcp_principal_restriction(label, function) + + def _strip_mcp_authority_markers(contents: str | list[Content]) -> str | list[Content]: """Remove private authority markers when no tracking middleware can consume them.""" if not isinstance(contents, list): @@ -6038,6 +6106,7 @@ def _stamp_parsed_mcp_content_labels( context: FunctionInvocationContext, contents: list[Content], local_label: ContentLabel, + function: FunctionTool, *, server_ifc_policy: _MCPServerIFCPolicy, retain_authority: bool, @@ -6057,6 +6126,7 @@ def _stamp_parsed_mcp_content_labels( _stamp_mcp_content_labels(contents, local_label, trust_server_ifc=trust_server_ifc), ) if not retain_authority: + _record_nested_mcp_content_restrictions(stamped, function) _strip_mcp_authority_markers(stamped) return stamped @@ -6080,6 +6150,7 @@ def _stamp_parsed_mcp_content_labels( _stamp_mcp_content_labels(prepared, local_label, trust_server_ifc=trust_server_ifc), ) if not retain_authority: + _record_nested_mcp_content_restrictions(stamped, function) _strip_mcp_authority_markers(stamped) return stamped @@ -6090,11 +6161,11 @@ def _stamp_mcp_error_carrier_label( fallback_label: ContentLabel, *, server_ifc_policy: _MCPServerIFCPolicy, -) -> ContentLabel | None: +) -> tuple[ContentLabel | None, bool]: """Apply retained MCP IFC to a generic function-error result carrier.""" raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) if not isinstance(raw_carrier, _FunctionResultCarrier): - return None + return None, False security_meta = ( None @@ -6103,13 +6174,15 @@ def _stamp_mcp_error_carrier_label( ) trust_server_ifc = server_ifc_policy == "authoritative" probe = Content.from_text("") + server_label: ContentLabel | None = None valid_server_ifc = False if security_meta is not None: probe.additional_properties[_MCP_RESULT_SECURITY_META_KEY] = security_meta if isinstance(security_meta, Mapping): security_meta_mapping = cast(Mapping[str, Any], security_meta) if security_meta_mapping.get("retained") is True: - valid_server_ifc = _label_from_mcp_meta(security_meta_mapping.get("meta")) is not None + server_label = _label_from_mcp_meta(security_meta_mapping.get("meta")) + valid_server_ifc = server_label is not None effective_local_label = ( fallback_label if server_ifc_policy == "ignore" @@ -6122,7 +6195,7 @@ def _stamp_mcp_error_carrier_label( _stamp_mcp_content_labels([probe], effective_local_label, trust_server_ifc=trust_server_ifc), ) if not stamped: - return None + return None, False stamped_item = stamped[0] stamped_properties = dict(stamped_item.additional_properties) @@ -6135,8 +6208,11 @@ def _stamp_mcp_error_carrier_label( } label_data = stamped_properties.get("security_label") if not isinstance(label_data, MutableMapping): - return None - return ContentLabel.from_dict(cast(MutableMapping[str, Any], label_data)) + return None, False + return ( + ContentLabel.from_dict(cast(MutableMapping[str, Any], label_data)), + server_label is not None and server_label.confidentiality == ConfidentialityLabel.USER_IDENTITY, + ) def _current_mcp_local_label(func_tool: FunctionTool, default_integrity: IntegrityLabel) -> ContentLabel: @@ -6170,7 +6246,7 @@ def _track_mcp_error_label( """Apply retained MCP IFC to a generic function error and its active tracker.""" raw_fallback_label = context.metadata.get(_SECURITY_RESULT_FALLBACK_LABEL_CONTEXT_KEY) fallback_label = raw_fallback_label if isinstance(raw_fallback_label, ContentLabel) else local_label - error_label = _stamp_mcp_error_carrier_label( + error_label, validated_principals = _stamp_mcp_error_carrier_label( context, local_label, fallback_label, @@ -6179,7 +6255,11 @@ def _track_mcp_error_label( if error_label is None: return active_middleware = _current_middleware.get() - if active_middleware is None or not _has_matching_label_tracker(context, func_tool): + if active_middleware is None: + return + if not _has_matching_label_tracker(context, func_tool): + if validated_principals: + _record_nested_mcp_principal_restriction(error_label, func_tool) return raw_carrier = context.metadata.get(_FUNCTION_RESULT_CARRIER_CONTEXT_KEY) if not isinstance(raw_carrier, _FunctionResultCarrier): @@ -6213,12 +6293,11 @@ def _has_matching_label_tracker( class _MCPIFCResultPostprocessor: """Apply retained MCP IFC after every FunctionTool result parsing path.""" - def __init__(self, func_tool: FunctionTool, default_integrity: IntegrityLabel) -> None: - self._func_tool = func_tool + def __init__(self, default_integrity: IntegrityLabel) -> None: self._default_integrity = default_integrity - def _current_policy(self) -> tuple[ContentLabel, _MCPServerIFCPolicy]: - props = self._func_tool.additional_properties or {} + def _current_policy(self, function: FunctionTool) -> tuple[ContentLabel, _MCPServerIFCPolicy]: + props = function.additional_properties or {} raw_policy = props.get(_MCP_SERVER_IFC_POLICY_KEY) server_ifc_policy: _MCPServerIFCPolicy = ( cast(_MCPServerIFCPolicy, raw_policy) @@ -6228,38 +6307,47 @@ def _current_policy(self) -> tuple[ContentLabel, _MCPServerIFCPolicy]: else "restrict" ) return ( - _current_mcp_local_label(self._func_tool, self._default_integrity), + _current_mcp_local_label(function, self._default_integrity), server_ifc_policy, ) - def before_invoke(self, context: FunctionInvocationContext | None) -> None: + def before_invoke( + self, + context: FunctionInvocationContext | None, + function: FunctionTool, + ) -> None: if context is None: return raw_snapshots = context.metadata.setdefault(_MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY, {}) if isinstance(raw_snapshots, dict): - cast(dict[FunctionTool, tuple[ContentLabel, _MCPServerIFCPolicy]], raw_snapshots)[self._func_tool] = ( - self._current_policy() + cast(dict[FunctionTool, tuple[ContentLabel, _MCPServerIFCPolicy]], raw_snapshots)[function] = ( + self._current_policy(function) ) - def _policy(self, context: FunctionInvocationContext | None) -> tuple[ContentLabel, _MCPServerIFCPolicy]: + def _policy( + self, + context: FunctionInvocationContext | None, + function: FunctionTool, + ) -> tuple[ContentLabel, _MCPServerIFCPolicy]: if context is None: - return self._current_policy() + return self._current_policy(function) raw_snapshots = context.metadata.get(_MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY) if isinstance(raw_snapshots, dict): snapshots = cast(dict[FunctionTool, tuple[ContentLabel, _MCPServerIFCPolicy]], raw_snapshots) - snapshot = snapshots.pop(self._func_tool, None) + snapshot = snapshots.pop(function, None) if not snapshots: context.metadata.pop(_MCP_IFC_POLICY_SNAPSHOTS_CONTEXT_KEY, None) if snapshot is not None: return snapshot - return self._current_policy() + return self._current_policy(function) def postprocess( self, contents: list[Content], context: FunctionInvocationContext | None, + function: FunctionTool, ) -> list[Content]: - local_label, server_ifc_policy = self._policy(context) + local_label, server_ifc_policy = self._policy(context, function) if context is None: if server_ifc_policy == "ignore": contents = [copy(item) for item in contents] @@ -6280,24 +6368,30 @@ def postprocess( context, contents, local_label, + function, server_ifc_policy=server_ifc_policy, - retain_authority=_has_matching_label_tracker(context, self._func_tool), + retain_authority=_has_matching_label_tracker(context, function), ) def postprocess_raw( self, result: Any, context: FunctionInvocationContext | None, + function: FunctionTool, ) -> Any: if not isinstance(result, list): return result - return self.postprocess(cast(list[Content], result), context) + return self.postprocess(cast(list[Content], result), context, function) - def handle_error(self, context: FunctionInvocationContext | None) -> None: + def handle_error( + self, + context: FunctionInvocationContext | None, + function: FunctionTool, + ) -> None: if context is None: return - local_label, server_ifc_policy = self._policy(context) - _track_mcp_error_label(context, self._func_tool, local_label, server_ifc_policy) + local_label, server_ifc_policy = self._policy(context, function) + _track_mcp_error_label(context, function, local_label, server_ifc_policy) class _MCPIFCSkillResultAdapter: @@ -6333,6 +6427,7 @@ def postprocess( context, contents, self._local_label, + function, server_ifc_policy=self._server_ifc_policy, retain_authority=_has_matching_label_tracker(context, function), ) @@ -6354,7 +6449,6 @@ def handle_error( def _wrap_mcp_function_for_ifc(func_tool: FunctionTool, default_integrity: IntegrityLabel) -> None: """Install final MCP IFC processing without replacing a user result parser.""" func_tool._result_postprocessor = _MCPIFCResultPostprocessor( # pyright: ignore[reportPrivateUsage] - func_tool, default_integrity, ) diff --git a/python/packages/core/tests/core/test_mcp.py b/python/packages/core/tests/core/test_mcp.py index 6a7789ff20f..ca2a47f333f 100644 --- a/python/packages/core/tests/core/test_mcp.py +++ b/python/packages/core/tests/core/test_mcp.py @@ -11,6 +11,7 @@ from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping from contextlib import AbstractAsyncContextManager, _AsyncGeneratorContextManager # type: ignore from contextvars import ContextVar +from copy import copy from pathlib import Path from textwrap import dedent from types import SimpleNamespace, TracebackType @@ -2938,6 +2939,257 @@ async def invoke_nested(context: FunctionInvocationContext) -> list[Content]: json.dumps(function_result.to_dict()) +@pytest.mark.parametrize("reuse_outer_context", [False, True], ids=["fresh-inner-context", "reused-outer-context"]) +@pytest.mark.parametrize("auto_hide_untrusted", [False, True], ids=["visible", "hidden"]) +async def test_nested_restriction_only_identity_ifc_preserves_server_principal( + reuse_outer_context: bool, + auto_hide_untrusted: bool, +) -> None: + from agent_framework.security import ( + PRINCIPAL_METADATA_KEY, + IntegrityLabel, + LabelTrackingFunctionMiddleware, + PolicyEnforcementFunctionMiddleware, + _wrap_mcp_function_for_ifc, + ) + + local_principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + server_principals = [{"tenant_id": "tenant-a", "user_id": "user-b"}] + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="identity-scoped nested result")], + _meta={ + "ifc": { + "integrity": "untrusted", + "confidentiality": "user_identity", + "principals": server_principals, + } + }, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + inner_tool = FunctionTool( + name="inner_widget", + description="", + func=_make_mcp_tool_caller(tool, "inner_widget"), + input_model={"type": "object", "properties": {}}, + additional_properties={ + "_mcp_remote_name": "inner_widget", + "source_integrity": "trusted", + "confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: local_principals, + "_mcp_server_ifc_policy": "restrict", + }, + ) + _wrap_mcp_function_for_ifc(inner_tool, IntegrityLabel.TRUSTED) + + async def invoke_nested(context: FunctionInvocationContext) -> list[Content]: + inner_context = context if reuse_outer_context else FunctionInvocationContext(function=inner_tool, arguments={}) + inner_result = await inner_tool.invoke(arguments={}, context=inner_context) + assert isinstance(inner_result, list) + assert "_security_label_validated_principals" not in inner_result[0].additional_properties + json.dumps([item.to_dict() for item in inner_result]) + return inner_result + + outer_tool = FunctionTool( + name="outer_tool", + description="Tracked tool that directly invokes an MCP function", + func=invoke_nested, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: local_principals, + }, + ) + tracker = LabelTrackingFunctionMiddleware(auto_hide_untrusted=auto_hide_untrusted) + function_result = await _auto_invoke_function( + Content.from_function_call(call_id="outer-call", name=outer_tool.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={outer_tool.name: outer_tool}, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + ) + + assert function_result.items is not None + expected_principals = [*local_principals, *server_principals] + if auto_hide_untrusted: + hidden = function_result.items[0] + assert hidden.text is not None + variable_id = cast(str, json.loads(hidden.text)["variable_id"]) + _, stored_label = tracker.get_variable_store().retrieve(variable_id) + assert stored_label.metadata[PRINCIPAL_METADATA_KEY] == expected_principals + assert tracker.get_context_label().integrity == IntegrityLabel.TRUSTED + else: + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["metadata"][PRINCIPAL_METADATA_KEY] == expected_principals + assert tracker.get_context_label().integrity == IntegrityLabel.UNTRUSTED + + assert tracker.get_context_label().metadata[PRINCIPAL_METADATA_KEY] == expected_principals + + executed = False + + def local_identity_sink() -> str: + nonlocal executed + executed = True + return "sent" + + destination = FunctionTool( + name="local_identity_sink", + description="Identity-scoped destination for the local principal", + func=local_identity_sink, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "max_allowed_confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: local_principals, + }, + ) + + with pytest.raises(MiddlewareTermination): + await _auto_invoke_function( + Content.from_function_call(call_id="destination-call", name=destination.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={destination.name: destination}, + middleware_pipeline=FunctionMiddlewarePipeline( + tracker, + PolicyEnforcementFunctionMiddleware(), + ), + ) + + assert executed is False + + +@pytest.mark.parametrize("reuse_outer_context", [False, True], ids=["fresh-inner-context", "reused-outer-context"]) +async def test_nested_mcp_parser_error_preserves_server_principal(reuse_outer_context: bool) -> None: + from agent_framework.security import ( + PRINCIPAL_METADATA_KEY, + IntegrityLabel, + LabelTrackingFunctionMiddleware, + _wrap_mcp_function_for_ifc, + ) + + local_principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + server_principals = [{"tenant_id": "tenant-a", "user_id": "user-b"}] + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="identity-scoped parser detail")], + _meta={ + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": server_principals, + } + }, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + + def fail_parser(_: Any) -> str: + raise ValueError("parser failed") + + inner_tool = FunctionTool( + name="inner_widget", + description="", + func=_make_mcp_tool_caller(tool, "inner_widget"), + result_parser=fail_parser, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "_mcp_remote_name": "inner_widget", + "source_integrity": "trusted", + "confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: local_principals, + "_mcp_server_ifc_policy": "restrict", + }, + ) + _wrap_mcp_function_for_ifc(inner_tool, IntegrityLabel.TRUSTED) + + async def invoke_nested(context: FunctionInvocationContext) -> str: + inner_context = context if reuse_outer_context else FunctionInvocationContext(function=inner_tool, arguments={}) + with pytest.raises(ValueError, match="parser failed"): + await inner_tool.invoke(arguments={}, context=inner_context) + return "caught parser failure" + + outer_tool = FunctionTool( + name="outer_tool", + description="Tracked tool that catches an MCP parser failure", + func=invoke_nested, + input_model={"type": "object", "properties": {}}, + additional_properties={ + "source_integrity": "trusted", + "confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: local_principals, + }, + ) + tracker = LabelTrackingFunctionMiddleware(auto_hide_untrusted=False) + function_result = await _auto_invoke_function( + Content.from_function_call(call_id="outer-call", name=outer_tool.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={outer_tool.name: outer_tool}, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + ) + + expected_principals = [*local_principals, *server_principals] + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["metadata"][PRINCIPAL_METADATA_KEY] == expected_principals + assert tracker.get_context_label().metadata[PRINCIPAL_METADATA_KEY] == expected_principals + + +async def test_copied_mcp_tool_uses_copy_as_result_authority_owner() -> None: + from agent_framework.security import ( + PRINCIPAL_METADATA_KEY, + IntegrityLabel, + LabelTrackingFunctionMiddleware, + _wrap_mcp_function_for_ifc, + ) + + local_principals = [{"tenant_id": "tenant-a", "user_id": "user-a"}] + server_principals = [{"tenant_id": "tenant-a", "user_id": "user-b"}] + mcp_result = types.CallToolResult( + content=[types.TextContent(type="text", text="copied tool result")], + _meta={ + "ifc": { + "integrity": "trusted", + "confidentiality": "user_identity", + "principals": server_principals, + } + }, + ) + tool = MCPTool(name="helper") # type: ignore[abstract] # ty: ignore[call-non-callable] + mock_session = Mock() + tool.session = mock_session + mock_session.call_tool = AsyncMock(return_value=mcp_result) + original = FunctionTool( + name="widget", + description="", + func=_make_mcp_tool_caller(tool, "widget"), + input_model={"type": "object", "properties": {}}, + additional_properties={ + "_mcp_remote_name": "widget", + "source_integrity": "trusted", + "confidentiality": "user_identity", + PRINCIPAL_METADATA_KEY: local_principals, + "_mcp_server_ifc_policy": "restrict", + }, + ) + _wrap_mcp_function_for_ifc(original, IntegrityLabel.TRUSTED) + copied = copy(original) + tracker = LabelTrackingFunctionMiddleware(auto_hide_untrusted=False) + + function_result = await _auto_invoke_function( + Content.from_function_call(call_id="copied-call", name=copied.name, arguments={}), + config=normalize_function_invocation_configuration(None), + tool_map={copied.name: copied}, + middleware_pipeline=FunctionMiddlewarePipeline(tracker), + ) + + assert function_result.items is not None + result_label = function_result.items[0].additional_properties["security_label"] + assert result_label["metadata"][PRINCIPAL_METADATA_KEY] == [*local_principals, *server_principals] + + async def test_oversized_mcp_meta_is_omitted_from_host_and_model_items() -> None: mcp_result = types.CallToolResult( content=[types.TextContent(type="text", text="ok")], diff --git a/python/packages/hyperlight/README.md b/python/packages/hyperlight/README.md index f6c2333a30d..c9057605b83 100644 --- a/python/packages/hyperlight/README.md +++ b/python/packages/hyperlight/README.md @@ -5,20 +5,33 @@ Hyperlight-backed CodeAct integrations for Microsoft Agent Framework. ## FIDES compatibility > [!WARNING] -> **FIDES integration is not supported with CodeAct providers.** Host-tool calls -> made inside generated code bypass the agent's function middleware, so FIDES -> policy enforcement and label tracking do not apply to those nested calls or -> intermediate code values. Checks on the outer `execute_code` invocation do not -> enforce the policies of individual tools called inside it. +> **Granular FIDES integration is not supported with CodeAct providers.** CodeAct +> combines many tool calls inside one generated-code execution and consumes native +> values with `skip_parsing=True`. Nested calls therefore bypass the normalized +> `Content` boundary and function middleware where FIDES labels and policies apply. > > Registering tools with recognized FIDES `additional_properties` logs a warning, > but does not block execution. This is a best-effort diagnostic: FIDES also uses > defaults for unannotated tools, so no warning does not imply support or safety. > Keep tools that require FIDES as direct agent tools, not Hyperlight-managed tools, > and enforce authorization and destination restrictions inside host functions. -> Sandbox isolation does not supply FIDES enforcement. +> Sandbox isolation does not supply FIDES enforcement. For coarse-grained handling, +> pass `additional_properties` to `HyperlightCodeActProvider` or +> `HyperlightExecuteCodeTool`; those properties label the complete outer +> `execute_code` result, not nested results, intermediate values, or prior side +> effects. > See the [FIDES guide](../../samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md). +```python +codeact = HyperlightCodeActProvider( + tools=[search, fetch], + additional_properties={ + "source_integrity": "untrusted", + "confidentiality": "private", + }, +) +``` + ## Error diagnostics Host tool callbacks expose a generic `RuntimeError("Host tool execution failed.")` diff --git a/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py b/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py index 00fd6705635..f2079b61f55 100644 --- a/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py +++ b/python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py @@ -15,7 +15,7 @@ from collections.abc import Callable, Iterator, Sequence from concurrent.futures import ThreadPoolExecutor from contextlib import suppress -from copy import copy +from copy import copy, deepcopy from dataclasses import dataclass from pathlib import Path, PurePosixPath from tempfile import TemporaryDirectory @@ -1370,6 +1370,8 @@ def _make_sandbox_callback(tool_obj: FunctionTool, *, include_detailed_errors: b def _callback(**kwargs: Any) -> Any: async def _invoke() -> Any: + # CodeAct needs native values inside generated code. This deliberately + # bypasses adapters that attach labels after Content normalization. return await sandbox_tool.invoke(arguments=kwargs, skip_parsing=True) # FunctionTool.invoke() is async. The real Hyperlight backend invokes @@ -1680,7 +1682,8 @@ def _warn_unsupported_fides_tools( logger.warning( "FIDES is not supported with CodeAct providers. Metadata on tool '%s' will not be enforced " "through function middleware for calls made inside generated code. " - "Keep FIDES-dependent tools as direct agent tools.", + "Keep FIDES-dependent tools as direct agent tools, or label the outer execute_code result " + "with CodeAct additional_properties for coarse-grained handling.", tool_obj.name, ) @@ -1696,6 +1699,10 @@ class HyperlightExecuteCodeTool(FunctionTool): """Execute Python code inside a Hyperlight sandbox. Keyword Args: + additional_properties: Metadata applied only to the outer ``execute_code`` + FunctionTool. The mapping is deep-copied at construction and for each + run snapshot. It can define one coarse FIDES policy for the complete + CodeAct result; it does not label or enforce nested host-tool calls. tool_description_format: Parameter documentation in ``.description``: ``"compact"`` (default) or ``"json"``, globally or mapped by exact, case-sensitive tool name. Missing names use compact format. Schemas that cannot be represented faithfully in compact form use JSON Schema. @@ -1711,6 +1718,7 @@ def __init__( self, *, tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]] | None = None, + additional_properties: dict[str, Any] | None = None, tool_description_format: _ToolDescriptionFormat = "compact", include_detailed_errors: bool = False, approval_mode: ApprovalMode | None = None, @@ -1743,6 +1751,7 @@ def __init__( approval_mode="never_require", func=self._run_code, input_model=EXECUTE_CODE_INPUT_SCHEMA, + additional_properties=deepcopy(additional_properties), ) self._state_lock = threading.RLock() self._tool_description_format: _NormalizedToolDescriptionFormat = normalized_description_format @@ -1925,6 +1934,7 @@ def create_run_tool(self) -> HyperlightExecuteCodeTool: return HyperlightExecuteCodeTool( _fides_warned_metadata=warned_metadata, tools=tools, + additional_properties=deepcopy(self.additional_properties), tool_description_format=self._tool_description_format, approval_mode=self._default_approval_mode, include_detailed_errors=self._include_detailed_errors, diff --git a/python/packages/hyperlight/agent_framework_hyperlight/_provider.py b/python/packages/hyperlight/agent_framework_hyperlight/_provider.py index bfb76daf88a..c8eb0e40d24 100644 --- a/python/packages/hyperlight/agent_framework_hyperlight/_provider.py +++ b/python/packages/hyperlight/agent_framework_hyperlight/_provider.py @@ -26,6 +26,9 @@ class HyperlightCodeActProvider(ContextProvider): """Inject a Hyperlight-backed CodeAct surface using provider-owned tools. Keyword Args: + additional_properties: Metadata applied only to the outer ``execute_code`` + FunctionTool. Use it for one coarse FIDES policy over the complete + CodeAct result; nested host-tool calls remain outside FIDES tracking. tool_description_format: Parameter documentation in the injected tool's ``.description``: ``"compact"`` (default) or ``"json"``, globally or mapped by exact, case-sensitive tool name. Missing names use compact format; rich schemas fall back to full JSON Schema. @@ -43,6 +46,7 @@ def __init__( source_id: str = DEFAULT_SOURCE_ID, *, tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]] | None = None, + additional_properties: dict[str, Any] | None = None, tool_description_format: _ToolDescriptionFormat = "compact", include_detailed_errors: bool = False, approval_mode: ApprovalMode | None = None, @@ -61,6 +65,7 @@ def __init__( super().__init__(source_id) self._execute_code_tool = HyperlightExecuteCodeTool( tools=tools, + additional_properties=additional_properties, tool_description_format=tool_description_format, include_detailed_errors=include_detailed_errors, approval_mode=approval_mode, diff --git a/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py b/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py index 2ce5963c485..2e2ae63a77d 100644 --- a/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py +++ b/python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py @@ -515,6 +515,34 @@ def test_execute_code_tool_updates_approval_with_managed_tools() -> None: assert execute_code.approval_mode == "always_require" +@pytest.mark.parametrize("entry_point", [HyperlightExecuteCodeTool, HyperlightCodeActProvider]) +def test_execute_code_additional_properties_are_isolated_across_run_snapshots( + entry_point: type[HyperlightExecuteCodeTool] | type[HyperlightCodeActProvider], +) -> None: + properties: dict[str, Any] = { + "source_integrity": "untrusted", + "confidentiality": "user_identity", + "agent_framework.security.principals": [{"tenant_id": "tenant-a", "user_id": "user-a"}], + } + codeact = entry_point(additional_properties=properties, _registry=_FakeRuntime()) + template = codeact if isinstance(codeact, HyperlightExecuteCodeTool) else codeact._execute_code_tool + + properties["agent_framework.security.principals"][0]["user_id"] = "mutated-input" + assert template.additional_properties is not None + assert template.additional_properties["agent_framework.security.principals"][0]["user_id"] == "user-a" + + run_tool = template.create_run_tool() + template.additional_properties["agent_framework.security.principals"][0]["user_id"] = "mutated-template" + + assert run_tool.additional_properties is not None + assert run_tool.additional_properties["source_integrity"] == "untrusted" + assert run_tool.additional_properties["agent_framework.security.principals"] == [ + {"tenant_id": "tenant-a", "user_id": "user-a"} + ] + + _close_execute_code_registry(template) + + @pytest.mark.parametrize("entry_point", [HyperlightExecuteCodeTool, HyperlightCodeActProvider]) @pytest.mark.parametrize("register_later", [False, True]) @pytest.mark.parametrize( diff --git a/python/packages/monty/AGENTS.md b/python/packages/monty/AGENTS.md index 8ad4c8bf8b9..2a46a15d7fc 100644 --- a/python/packages/monty/AGENTS.md +++ b/python/packages/monty/AGENTS.md @@ -30,6 +30,10 @@ from agent_framework.monty import ( `MontyCodeActProvider` and `MontyExecuteCodeTool` both accept: - `tools` — host tool callables / `FunctionTool`s +- `additional_properties` — metadata copied onto the outer `execute_code` + FunctionTool and each run snapshot. It can define one coarse FIDES policy + for the complete CodeAct result; it does not enforce nested host-tool calls + or intermediate values. - `approval_mode` — `"never_require"` (default) or `"always_require"` - `workspace_root` — host directory auto-mounted at `/input` (mirrors `HyperlightCodeActProvider.workspace_root`) diff --git a/python/packages/monty/README.md b/python/packages/monty/README.md index bcf6c3fcfc3..00a1aca155b 100644 --- a/python/packages/monty/README.md +++ b/python/packages/monty/README.md @@ -9,19 +9,32 @@ Monty-backed CodeAct integrations for Microsoft Agent Framework. ## FIDES compatibility > [!WARNING] -> **FIDES integration is not supported with CodeAct providers.** Host-tool calls -> made inside generated code bypass the agent's function middleware, so FIDES -> policy enforcement and label tracking do not apply to those nested calls or -> intermediate code values. Checks on the outer `execute_code` invocation do not -> enforce the policies of individual tools called inside it. +> **Granular FIDES integration is not supported with CodeAct providers.** CodeAct +> combines many tool calls inside one generated-code execution and consumes native +> values with `skip_parsing=True`. Nested calls therefore bypass the normalized +> `Content` boundary and function middleware where FIDES labels and policies apply. > > Registering tools with recognized FIDES `additional_properties` logs a warning, > but does not block execution. This is a best-effort diagnostic: FIDES also uses > defaults for unannotated tools, so no warning does not imply support or safety. > Keep tools that require FIDES as direct agent tools, not Monty-managed tools, and -> enforce authorization and destination restrictions inside host functions. +> enforce authorization and destination restrictions inside host functions. For +> coarse-grained handling, pass `additional_properties` to +> `MontyCodeActProvider` or `MontyExecuteCodeTool`; those properties label the +> complete outer `execute_code` result, not nested results, intermediate values, +> or prior side effects. > See the [FIDES guide](../../samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md). +```python +codeact = MontyCodeActProvider( + tools=[search, fetch], + additional_properties={ + "source_integrity": "untrusted", + "confidentiality": "private", + }, +) +``` + ## Error diagnostics Host tool failures raise a generic `RuntimeError("Host tool execution failed.")` diff --git a/python/packages/monty/agent_framework_monty/_execute_code_tool.py b/python/packages/monty/agent_framework_monty/_execute_code_tool.py index c806c8258a2..2b39efa5af6 100644 --- a/python/packages/monty/agent_framework_monty/_execute_code_tool.py +++ b/python/packages/monty/agent_framework_monty/_execute_code_tool.py @@ -18,6 +18,7 @@ import os import stat from collections.abc import Callable, Iterator, Sequence +from copy import deepcopy from functools import partial from pathlib import Path, PurePosixPath from typing import Any, cast @@ -191,6 +192,8 @@ def _make_tool_callback(tool_obj: FunctionTool) -> Callable[..., Any]: Returns the raw native value (no ``Content`` wrapping) so the Monty interpreter receives real Python objects. ``FunctionTool.invoke`` accepts direct keyword arguments and handles both sync and async underlying functions internally. + The raw path deliberately bypasses adapters that attach labels after + ``Content`` normalization. """ return partial(tool_obj.invoke, skip_parsing=True) @@ -217,7 +220,8 @@ def _warn_unsupported_fides_tools( logger.warning( "FIDES is not supported with CodeAct providers. Metadata on tool '%s' will not be enforced " "through function middleware for calls made inside generated code. " - "Keep FIDES-dependent tools as direct agent tools.", + "Keep FIDES-dependent tools as direct agent tools, or label the outer execute_code result " + "with CodeAct additional_properties for coarse-grained handling.", tool_obj.name, ) @@ -263,6 +267,10 @@ class MontyExecuteCodeTool(FunctionTool): loop, so no internal locking is needed. Keyword Args: + additional_properties: Metadata applied only to the outer ``execute_code`` + FunctionTool. The mapping is deep-copied at construction and for each + run snapshot. It can define one coarse FIDES policy for the complete + CodeAct result; it does not label or enforce nested host-tool calls. include_detailed_errors: Include host exception types/messages and execution error details. Defaults to ``False``. Enable only for a trusted channel; diagnostics can contain secrets. This setting is independent of the outer client's error and sensitive-logging settings. @@ -272,6 +280,7 @@ def __init__( self, *, tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]] | None = None, + additional_properties: dict[str, Any] | None = None, approval_mode: ApprovalMode | None = None, workspace_root: str | Path | None = None, file_mounts: FileMountInput | Sequence[FileMountInput] | None = None, @@ -288,6 +297,7 @@ def __init__( approval_mode="never_require", func=self._run_code, input_model=EXECUTE_CODE_INPUT_SCHEMA, + additional_properties=deepcopy(additional_properties), ) self._default_approval_mode: ApprovalMode = approval_mode or "never_require" self._include_detailed_errors = include_detailed_errors @@ -418,6 +428,7 @@ def create_run_tool(self) -> MontyExecuteCodeTool: return MontyExecuteCodeTool( _fides_warned_metadata=self._fides_warned_metadata, tools=tools, + additional_properties=deepcopy(self.additional_properties), approval_mode=self._default_approval_mode, workspace_root=self._workspace_root, file_mounts=list(self._file_mounts.values()) or None, diff --git a/python/packages/monty/agent_framework_monty/_provider.py b/python/packages/monty/agent_framework_monty/_provider.py index 4b4a79fb90d..af482c7535c 100644 --- a/python/packages/monty/agent_framework_monty/_provider.py +++ b/python/packages/monty/agent_framework_monty/_provider.py @@ -33,6 +33,9 @@ class MontyCodeActProvider(ContextProvider): retaining entries for tools registered later. Keyword Args: + additional_properties: Metadata applied only to the outer ``execute_code`` + FunctionTool. Use it for one coarse FIDES policy over the complete + CodeAct result; nested host-tool calls remain outside FIDES tracking. include_detailed_errors: Expose host exception and execution diagnostics only for a trusted channel. Defaults to ``False`` and is independent of outer-client error/logging settings. """ @@ -44,6 +47,7 @@ def __init__( source_id: str = DEFAULT_SOURCE_ID, *, tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]] | None = None, + additional_properties: dict[str, Any] | None = None, approval_mode: ApprovalMode | None = None, workspace_root: str | Path | None = None, file_mounts: FileMountInput | Sequence[FileMountInput] | None = None, @@ -54,6 +58,7 @@ def __init__( super().__init__(source_id) self._execute_code_tool = MontyExecuteCodeTool( tools=tools, + additional_properties=additional_properties, approval_mode=approval_mode, workspace_root=workspace_root, file_mounts=file_mounts, diff --git a/python/packages/monty/tests/monty/test_monty_codeact.py b/python/packages/monty/tests/monty/test_monty_codeact.py index 9bb3a9270b5..15bc113065e 100644 --- a/python/packages/monty/tests/monty/test_monty_codeact.py +++ b/python/packages/monty/tests/monty/test_monty_codeact.py @@ -266,6 +266,32 @@ def test_tool_construction_defaults() -> None: assert monty_tool.get_tools() == [] +@pytest.mark.parametrize("entry_point", [MontyExecuteCodeTool, MontyCodeActProvider]) +def test_execute_code_additional_properties_are_isolated_across_run_snapshots( + entry_point: type[MontyExecuteCodeTool] | type[MontyCodeActProvider], +) -> None: + properties: dict[str, Any] = { + "source_integrity": "untrusted", + "confidentiality": "user_identity", + "agent_framework.security.principals": [{"tenant_id": "tenant-a", "user_id": "user-a"}], + } + codeact = entry_point(additional_properties=properties) + template = codeact if isinstance(codeact, MontyExecuteCodeTool) else codeact._execute_code_tool + + properties["agent_framework.security.principals"][0]["user_id"] = "mutated-input" + assert template.additional_properties is not None + assert template.additional_properties["agent_framework.security.principals"][0]["user_id"] == "user-a" + + run_tool = template.create_run_tool() + template.additional_properties["agent_framework.security.principals"][0]["user_id"] = "mutated-template" + + assert run_tool.additional_properties is not None + assert run_tool.additional_properties["source_integrity"] == "untrusted" + assert run_tool.additional_properties["agent_framework.security.principals"] == [ + {"tenant_id": "tenant-a", "user_id": "user-a"} + ] + + @pytest.mark.parametrize("entry_point", [MontyExecuteCodeTool, MontyCodeActProvider]) @pytest.mark.parametrize("register_later", [False, True]) @pytest.mark.parametrize( diff --git a/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md b/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md index 52c66a87a5b..a56a2e5ce3d 100644 --- a/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md +++ b/python/samples/02-agents/security/FIDES_DEVELOPER_GUIDE.md @@ -5,19 +5,36 @@ > [!WARNING] > **Combining FIDES with CodeAct providers is currently unsupported**, including > [Monty](../../../packages/monty/README.md) and -> [Hyperlight](../../../packages/hyperlight/README.md). FIDES's per-tool guarantees -> apply to invocations routed through its function middleware. Host-tool calls -> inside generated code bypass that middleware; nested calls and intermediate -> code values do not receive its policy enforcement or label tracking. Checking -> the outer `execute_code` invocation does not enforce the policies of individual -> tools called inside it, and sandbox isolation does not supply FIDES enforcement. +> [Hyperlight](../../../packages/hyperlight/README.md). CodeAct is optimized for +> combining many tool calls inside one generated-code execution and consumes +> native tool values with `skip_parsing=True`. That bypasses the normalized +> `Content` boundary where operation-scoped FIDES labels are attached. FIDES +> instead depends on granular inspection, labeling, and enforcement for each +> function result. Nested calls and intermediate code values therefore do not +> receive its policy enforcement or label tracking. > > CodeAct logs a warning for recognized FIDES tool metadata, but this is diagnostic > only: execution is not blocked, and defaults can apply to unannotated tools. > No warning does not imply support or safety. Keep tools that require FIDES as > direct agent tools rather than CodeAct-managed tools, or disable CodeAct for > workflows requiring those guarantees. Host functions must independently enforce -> authorization and destination restrictions. +> authorization and destination restrictions. If one coarse policy for the +> complete CodeAct output is sufficient, set `additional_properties` on the +> CodeAct provider or execute-code tool: +> +> ```python +> codeact = MontyCodeActProvider( +> tools=[search, fetch], +> additional_properties={ +> "source_integrity": "untrusted", +> "confidentiality": "private", +> }, +> ) +> ``` +> +> FIDES then labels the outer `execute_code` result as a whole. It still does +> not inspect nested tool results, intermediate values, or side effects that +> happen before the outer result exists. ## Context Provider Pattern with SecureAgentConfig!