From 574c89cd3fcac0b1f6729bddccf763c7f63d6d3c Mon Sep 17 00:00:00 2001 From: westey <164392973+westey-m@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:09:26 +0000 Subject: [PATCH 1/4] Improve docker shell path validation --- python/packages/tools/README.md | 40 ++- .../agent_framework_tools/shell/_docker.py | 59 ++--- .../agent_framework_tools/shell/_resolve.py | 134 +++++++--- .../agent_framework_tools/shell/_tool.py | 23 +- .../tools/tests/test_docker_shell_tool.py | 247 +++++++----------- .../tools/tests/test_local_shell_tool.py | 52 +++- .../tools/tests/test_shell_resolve.py | 194 ++++++++++---- 7 files changed, 444 insertions(+), 305 deletions(-) diff --git a/python/packages/tools/README.md b/python/packages/tools/README.md index 14585e8ca95..fd26a2ab28e 100644 --- a/python/packages/tools/README.md +++ b/python/packages/tools/README.md @@ -111,7 +111,9 @@ output (`stdout`) and error output (`stderr`): from agent_framework.tools import DockerShellTool, LocalShellTool local_shell = LocalShellTool(max_stdout_bytes=16 * 1024, max_stderr_bytes=4 * 1024) -docker_shell = DockerShellTool(max_stdout_bytes=16 * 1024, max_stderr_bytes=4 * 1024) +docker_shell = DockerShellTool( + docker_binary="/usr/bin/docker", max_stdout_bytes=16 * 1024, max_stderr_bytes=4 * 1024 +) ``` These settings limit retained output, not how much a command may produce. @@ -126,13 +128,27 @@ are not stopped solely because either output allowance is exceeded. - **Linux / macOS**: `/bin/bash --noprofile --norc` (falls back to `/bin/sh`). - Override via the `shell=` constructor argument or the `AGENT_FRAMEWORK_SHELL` environment variable. -- **Windows executable lookup**: a bare executable name (the default `pwsh` or - `powershell`, a bare `shell=` or `AGENT_FRAMEWORK_SHELL` value, and the - `docker_binary` of `DockerShellTool`) is looked up only in the fully - qualified entries of `PATH`. The current directory and relative `PATH` - entries are never searched. Pass an absolute path to select a specific - executable. A path, like a `PATH` match, shows only that the file exists, not - that it can be trusted, so keep `PATH` and the directories on it protected. +- **Full paths required**: `shell=`, `AGENT_FRAMEWORK_SHELL`, and the + `docker_binary` of `DockerShellTool` must be full paths, such as + `/usr/bin/zsh` or `C:\Program Files\PowerShell\7\pwsh.exe`. On Windows the + path must also include the file extension. Short names (`zsh`) and relative + paths (`bin/zsh`, `.\pwsh.exe`) are rejected, because they could pick up a + file in the current directory. +- **Default shell lookup**: the Windows default (`pwsh.exe`, then + `powershell.exe`) is looked up only in the fully qualified entries of + `PATH`. The current directory and relative `PATH` entries are never + searched. +- **Shell `PATH`**: before the shell starts, empty and relative entries (such + as `.` or `bin`) are removed from its `PATH`, so commands it runs are never + looked up in the current directory. On Windows, + `NoDefaultCurrentDirectoryInExePath=1` is also set, so `cmd.exe` runs a + program from the working directory only when the command gives its relative + path (for example `.\tool`). On Linux and macOS, `LocalShellTool` raises + `ValueError` if no full directory path is left in `PATH` (for example + `clean_env=True` without a `PATH` in `env`), because an empty or missing + `PATH` would search the current directory. This can't be turned off. +- A path, like a `PATH` match, shows only that the file exists, not that it can + be trusted, so keep `PATH` and the directories on it protected. ## `ShellEnvironmentProvider` — context provider @@ -182,6 +198,7 @@ from agent_framework.tools import DockerShellTool async def main() -> None: async with DockerShellTool( + docker_binary="/usr/bin/docker", # full path to the container runtime image="mcr.microsoft.com/azurelinux/base/core:3.0", approval_mode="never_require", # container is the boundary ) as shell: @@ -201,8 +218,11 @@ Defaults applied to every container: - `--memory 512m`, `--pids-limit 256`, ephemeral `tmpfs /tmp`. To expose a host directory, pass `host_workdir="/path"` (mounted -read-only by default; `mount_readonly=False` to allow writes). Swap the -container runtime with `docker_binary="podman"`. +read-only by default; `mount_readonly=False` to allow writes). +`docker_binary` is required and must be the full path to the container +runtime (for example `docker_binary="/usr/bin/podman"` to use Podman). On +Windows include the extension, for example +`C:\Program Files\Docker\Docker\resources\bin\docker.exe`. Applications that must pass additional Docker options can use `unsafe_extra_run_args`. These trusted setup options are appended verbatim diff --git a/python/packages/tools/agent_framework_tools/shell/_docker.py b/python/packages/tools/agent_framework_tools/shell/_docker.py index 1fbe3609758..7f7c1955d4e 100644 --- a/python/packages/tools/agent_framework_tools/shell/_docker.py +++ b/python/packages/tools/agent_framework_tools/shell/_docker.py @@ -46,7 +46,6 @@ import logging import os import secrets -import shutil import subprocess # ruff:ignore[suspicious-subprocess-import] # nosec B404 - running shell commands is the whole point of this tool import time from collections.abc import Callable, Mapping, Sequence @@ -59,7 +58,7 @@ from .._feature_usage import FeatureIndex from ._capture import _ProcessOutput # pyright: ignore[reportPrivateUsage] - shared shell capture from ._policy import ShellPolicy, ShellRequest -from ._resolve import resolve_executable +from ._resolve import require_full_path from ._session import ShellSession from ._truncate import _validate_output_limit # pyright: ignore[reportPrivateUsage] - shared limit validation from ._types import ( @@ -92,17 +91,19 @@ class DockerNotAvailableError(RuntimeError): """Raised when the configured docker binary cannot be reached.""" -def is_docker_available(binary: str = "docker") -> bool: - """Return ``True`` if ``binary`` is on PATH and the daemon responds. +def is_docker_available(binary: str) -> bool: + """Return ``True`` if the container runtime at ``binary`` exists and its daemon responds. - On Windows, a bare ``binary`` is looked up only in the fully qualified entries of ``PATH``. The - current directory is never searched. + Args: + binary: Full path to the ``docker`` (or compatible, such as ``podman``) executable. On + Windows it must include the file extension. A short name or relative path returns + ``False`` because it could be resolved from the current directory. """ try: - binary = resolve_executable(binary) - except FileNotFoundError: + require_full_path(binary, source="binary") + except ValueError: return False - if shutil.which(binary) is None: + if not os.path.isfile(binary): return False try: out = subprocess.run( # ruff:ignore[subprocess-without-shell-equals-true] # nosec B603 - argv is built from trusted binary name @@ -240,6 +241,12 @@ class DockerShellTool: docstring for more. Args: + docker_binary: Required full path to the ``docker`` (or compatible, + such as ``podman``) executable, for example ``"/usr/bin/docker"``. + On Windows it must also include the file extension (``.exe``). + Short names and relative paths are rejected because they could be + resolved from the current directory. A path shows only that the + file is there, not that it can be trusted. image: OCI image to run. Defaults to a small Microsoft-maintained base image. Override with anything that includes ``bash`` and (for persistent mode) ``sleep``. @@ -287,11 +294,6 @@ class DockerShellTool: with the default isolation flags and a trusted runtime — is the intended boundary rather than approval. on_command: Audit hook fired for every allowed command. - docker_binary: Override (e.g. ``"podman"``). On Windows, a bare name is - looked up only in the fully qualified entries of ``PATH``; the current - directory is never searched. Pass an absolute path to select a specific - executable. A path, like a ``PATH`` match, shows only that the file - exists, not that it can be trusted. shell: Shell binary to invoke inside the container. Defaults to ``"bash"``; pass ``"sh"`` for minimal images such as Alpine that don't ship bash. Anything else must be present on @@ -301,6 +303,7 @@ class DockerShellTool: def __init__( self, *, + docker_binary: str, image: str = DEFAULT_IMAGE, container_name: str | None = None, mode: ShellMode = "persistent", @@ -320,7 +323,6 @@ def __init__( max_stderr_bytes: int = 64 * 1024, approval_mode: Literal["always_require", "never_require"] = "always_require", on_command: Callable[[str], None] | None = None, - docker_binary: str = "docker", shell: str = "bash", ) -> None: _validate_output_limit(max_stdout_bytes, name="max_stdout_bytes") @@ -348,10 +350,9 @@ def __init__( self._max_stderr_bytes = max_stderr_bytes self._approval_mode: Literal["always_require", "never_require"] = approval_mode self._on_command = on_command - self._binary = docker_binary + self._binary = require_full_path(docker_binary, source="docker_binary") self._shell = shell - self._resolved_binary: str | None = None self._session: ShellSession | None = None self._container_started = False self._lifecycle_lock: asyncio.Lock | None = None @@ -361,23 +362,13 @@ def _get_lifecycle_lock(self) -> asyncio.Lock: self._lifecycle_lock = asyncio.Lock() return self._lifecycle_lock - def _runtime_path(self) -> str: - """Return the container runtime to launch, resolved once for this instance. - - Resolving once keeps every launch of one instance on the same executable, so the runtime that - started a container is also the one that stops it. - """ - if self._resolved_binary is None: - self._resolved_binary = resolve_executable(self._binary) - return self._resolved_binary - # ------------------------------------------------------------------ lifecycle async def start(self) -> None: """Pull/start the container and (if persistent) the inner shell session. Raises: - FileNotFoundError: If the container runtime executable cannot be found. + FileNotFoundError: If the container runtime executable does not exist. """ # Stateless mode never uses the long-lived container — every call goes # through ``docker run --rm`` — so start()/close() are no-ops. @@ -391,7 +382,7 @@ async def start(self) -> None: await self._start_container() self._container_started = True argv = build_exec_argv( - binary=self._runtime_path(), + binary=self._binary, container_name=self._container_name, interactive=True, shell=self._shell, # nosec B604 - 'shell' is the binary name kwarg, not subprocess shell=True @@ -467,7 +458,7 @@ async def _run_stateless(self, command: str, *, timeout: float | None) -> ShellR """Run a single command in a fresh ``docker run --rm`` container.""" per_call_name = f"af-shell-{secrets.token_hex(6)}" argv = [ - self._runtime_path(), + self._binary, "run", "--rm", "-i", @@ -538,7 +529,7 @@ async def _terminate_stateless(self, proc: asyncio.subprocess.Process, name: str # Stopping the local client alone does not stop its container. try: killer = await asyncio.create_subprocess_exec( - self._runtime_path(), + self._binary, "kill", "--signal", "KILL", @@ -562,7 +553,7 @@ async def _terminate_stateless(self, proc: asyncio.subprocess.Process, name: str if not kill_ok: logger.warning("docker kill of %s did not succeed; attempting docker rm -f", name) reaper = await asyncio.create_subprocess_exec( - self._runtime_path(), + self._binary, "rm", "-f", name, @@ -598,7 +589,7 @@ async def _terminate_stateless(self, proc: asyncio.subprocess.Process, name: str async def _start_container(self) -> None: argv = build_run_argv( - binary=self._runtime_path(), + binary=self._binary, image=self._image, container_name=self._container_name, user=self._user, @@ -634,7 +625,7 @@ async def _stop_container(self) -> None: async def _attempt(timeout: float) -> tuple[int | None, str]: """Run a single ``docker rm -f`` attempt. Returns (rc, stderr).""" proc = await asyncio.create_subprocess_exec( - self._runtime_path(), + self._binary, "rm", "-f", self._container_name, diff --git a/python/packages/tools/agent_framework_tools/shell/_resolve.py b/python/packages/tools/agent_framework_tools/shell/_resolve.py index 513f4b1f216..e28b9e7fa10 100644 --- a/python/packages/tools/agent_framework_tools/shell/_resolve.py +++ b/python/packages/tools/agent_framework_tools/shell/_resolve.py @@ -6,17 +6,18 @@ import ntpath import os -import shutil +import posixpath import sys -from collections.abc import Sequence +from collections.abc import Mapping, Sequence from ._types import ShellExecutionError _ENV_OVERRIDE = "AGENT_FRAMEWORK_SHELL" +_NO_CURRENT_DIRECTORY_SEARCH = "NoDefaultCurrentDirectoryInExePath" def _is_fully_qualified(path: str) -> bool: - """Return whether ``path`` names a fixed location that does not depend on the current directory.""" + """Return whether the Windows ``path`` names a fixed location that does not depend on the current directory.""" drive, rest = ntpath.splitdrive(path) if drive.replace("/", "\\").startswith("\\\\"): # A UNC or device root such as \\server\share is complete without a trailing separator. @@ -27,62 +28,107 @@ def _is_fully_qualified(path: str) -> bool: def find_executable(name: str) -> str | None: """Find a bare executable name in the fully qualified entries of ``PATH``. - The search follows Windows naming rules and never uses the current directory. Windows starts a - bare name from the current directory of the host process before it reads ``PATH``, and - :func:`shutil.which` puts that directory first too, so a file in that directory could replace the - intended executable. Empty, relative, drive-relative, and drive-less rooted ``PATH`` entries - depend on the current directory, so they are skipped. + The current directory is never searched. Empty and relative ``PATH`` entries (and, on Windows, + drive-relative and drive-less rooted entries) depend on the current directory, so they are + skipped. :func:`shutil.which` does not skip them, and on Windows it puts the current directory + first, so a file planted there could replace the intended executable. Args: - name: A bare file name. ``.exe`` is added when it has no extension, as Windows does. + name: A bare file name. On Windows only ``.exe`` files are found; ``.exe`` is added when the + name has no extension. Returns: The absolute path of the first match, or ``None`` when no fully qualified ``PATH`` entry holds the file. A match shows only that the file exists there, not who owns it or whether it can be trusted. """ - candidate = name if ntpath.splitext(name)[1] else f"{name}.exe" - # PATH entries are sometimes quoted; Windows tools differ in whether they strip the quotes. - for raw_entry in os.environ.get("PATH", "").split(ntpath.pathsep): - entry = raw_entry.strip().strip('"') - if not _is_fully_qualified(entry): + if sys.platform == "win32": + extension = ntpath.splitext(name)[1] + if extension and extension.lower() != ".exe": + return None + candidate = name if extension else f"{name}.exe" + # PATH entries are sometimes quoted; Windows tools differ in whether they strip the quotes. + for raw_entry in os.environ.get("PATH", "").split(ntpath.pathsep): + entry = raw_entry.strip().strip('"') + if not _is_fully_qualified(entry): + continue + path = ntpath.join(entry, candidate) + if os.path.isfile(path): + return path + return None + + for entry in os.environ.get("PATH", "").split(posixpath.pathsep): + if not posixpath.isabs(entry): continue - path = ntpath.join(entry, candidate) - if os.path.isfile(path): + path = posixpath.join(entry, name) + if os.path.isfile(path) and os.access(path, os.X_OK): return path return None -def resolve_executable(name: str) -> str: - """Return ``name`` in a form that can be launched without searching the current directory. +def require_full_path(value: str, *, source: str) -> str: + """Return ``value`` if it is a full path to an executable, otherwise raise. - On Windows a bare name is replaced by the path that :func:`find_executable` returns. Every other - value is returned unchanged: names with a directory or a drive are an explicit choice of the caller, - and other platforms do not search the current directory for bare names. + Short names and relative paths are rejected because they can be resolved from the current + directory. On Windows the path must also end in a file extension such as ``.exe``. The file is + not checked for existence; a missing file fails when it is launched. Args: - name: The executable name or path that the caller configured. + value: The executable path that the caller configured. + source: Where the value came from, used in the error message. + + Raises: + ValueError: When ``value`` is not a full path (or, on Windows, has no file extension). + """ + if sys.platform == "win32": + if not _is_fully_qualified(value) or not ntpath.splitext(value)[1]: + raise ValueError( + f"{source} must be a full path to the executable including its extension, " + rf"for example 'C:\Program Files\PowerShell\7\pwsh.exe'; got {value!r}." + ) + return value + if not posixpath.isabs(value): + raise ValueError(f"{source} must be a full path to the executable, for example '/usr/bin/zsh'; got {value!r}.") + return value + + +def restrict_executable_search(env: Mapping[str, str]) -> dict[str, str]: + """Return a copy of ``env`` whose ``PATH`` only searches fully qualified directories. + + Empty and relative ``PATH`` entries are removed so commands run by the shell are never looked up + in the current directory. On Windows the ``PATH`` key is matched without regard to case, and + ``NoDefaultCurrentDirectoryInExePath`` is set so ``cmd.exe`` does not search the current + directory first. Raises: - FileNotFoundError: On Windows, when a bare name is not found in the fully qualified ``PATH`` - entries. The bare name is never used as a fallback. + ValueError: On Linux and macOS, when ``PATH`` is missing or has no fully qualified entry left. + POSIX shells search the current directory when ``PATH`` is empty, and ``bash`` falls back + to a built-in search path that can include it when ``PATH`` is missing. """ - if sys.platform != "win32" or ntpath.dirname(name) or ntpath.splitdrive(name)[0]: - return name - found = find_executable(name) - if found is None: - raise FileNotFoundError( - f"Executable {name!r} was not found in the fully qualified entries of PATH. " - "The current directory and relative PATH entries are not searched." + result = dict(env) + if sys.platform == "win32": + for key in [key for key in result if key.upper() == "PATH"]: + entries = result[key].split(ntpath.pathsep) + result[key] = ntpath.pathsep.join(e for e in entries if _is_fully_qualified(e.strip().strip('"'))) + result[_NO_CURRENT_DIRECTORY_SEARCH] = "1" + return result + + kept = [e for e in result.get("PATH", "").split(posixpath.pathsep) if posixpath.isabs(e)] + if not kept: + raise ValueError( + "The shell's PATH must contain at least one full directory path, such as '/usr/bin'. " + "Empty and relative PATH entries are removed, and an empty or missing PATH would search " + "the current directory. Set PATH in env (required when clean_env=True)." ) - return found + result["PATH"] = posixpath.pathsep.join(kept) + return result -def _qualify_shell(parts: list[str]) -> list[str]: - """Resolve the executable of an explicit shell override.""" +def _qualify_shell(parts: list[str], *, source: str) -> list[str]: + """Check that the executable of an explicit shell override is a full path.""" try: - return [resolve_executable(parts[0]), *parts[1:]] - except FileNotFoundError as exc: + return [require_full_path(parts[0], source=source), *parts[1:]] + except ValueError as exc: raise ShellExecutionError(str(exc)) from exc @@ -96,9 +142,11 @@ def resolve_shell(shell: str | Sequence[str] | None, *, interactive: bool) -> li 2. ``AGENT_FRAMEWORK_SHELL`` environment variable. 3. Platform default. - On Windows, a bare shell name (the default or an override) is resolved from the fully - qualified entries of ``PATH``; the current directory is never searched. Names that contain - a directory or a drive are used as given. + An override (``shell`` or ``AGENT_FRAMEWORK_SHELL``) must name the shell by its full path; on + Windows it must also include the file extension. Short names and relative paths are rejected + because they could be resolved from the current directory. The Windows default (``pwsh.exe``, + then ``powershell.exe``) and the last POSIX fallback (``sh``) are looked up only in the fully + qualified entries of ``PATH``. When ``interactive=False`` (stateless mode), the returned argv is guaranteed to end with a ``-c`` (POSIX) or ``-Command`` (PowerShell) @@ -124,7 +172,7 @@ def resolve_shell(shell: str | Sequence[str] | None, *, interactive: bool) -> li parts = list(shell) if not parts: raise ShellExecutionError("shell override must not be empty") - parts = _qualify_shell(parts) + parts = _qualify_shell(parts, source="shell") return parts if interactive else _ensure_command_flag(parts) env_override = os.environ.get(_ENV_OVERRIDE) @@ -133,7 +181,7 @@ def resolve_shell(shell: str | Sequence[str] | None, *, interactive: bool) -> li parts = shlex.split(env_override) if parts: - parts = _qualify_shell(parts) + parts = _qualify_shell(parts, source=_ENV_OVERRIDE) return parts if interactive else _ensure_command_flag(parts) if sys.platform == "win32": @@ -152,8 +200,8 @@ def resolve_shell(shell: str | Sequence[str] | None, *, interactive: bool) -> li if interactive: return [candidate, "--noprofile", "--norc"] if candidate.endswith("bash") else [candidate] return [candidate, "-c"] - # Last-ditch fallback: let PATH resolve 'sh'. - sh = shutil.which("sh") + # Last-ditch fallback: look up 'sh' in the fully qualified PATH entries. + sh = find_executable("sh") if sh is None: raise ShellExecutionError(f"No POSIX shell found on PATH. Set {_ENV_OVERRIDE} to override.") return [sh] if interactive else [sh, "-c"] diff --git a/python/packages/tools/agent_framework_tools/shell/_tool.py b/python/packages/tools/agent_framework_tools/shell/_tool.py index 85a61e7acb0..c18310985ad 100644 --- a/python/packages/tools/agent_framework_tools/shell/_tool.py +++ b/python/packages/tools/agent_framework_tools/shell/_tool.py @@ -17,7 +17,7 @@ from .._feature_usage import FeatureIndex from ._executor import run_stateless from ._policy import ShellPolicy, ShellRequest -from ._resolve import is_powershell, resolve_shell +from ._resolve import is_powershell, resolve_shell, restrict_executable_search from ._session import ShellSession from ._truncate import _validate_output_limit # pyright: ignore[reportPrivateUsage] - shared limit validation from ._types import ( @@ -127,6 +127,17 @@ class LocalShellTool: variables are exported before the session is used. clean_env: When ``True``, do **not** inherit ``os.environ``; only the variables supplied in ``env`` are visible to commands. + + In every case, empty and relative ``PATH`` entries are removed + from the shell's environment so commands are never looked up in + the current directory. On Windows + ``NoDefaultCurrentDirectoryInExePath=1`` is also set, so + ``cmd.exe`` runs a program from the working directory only when + the command includes its relative path. On Linux and macOS a + :class:`ValueError` is raised when no full directory path is left + in ``PATH`` (for example ``clean_env=True`` without a ``PATH`` in + ``env``), because an empty or missing ``PATH`` would search the + current directory. policy: Policy applied before approval. Defaults to an empty :class:`ShellPolicy()` which allows every command; supply explicit ``denylist``/``allowlist`` patterns to filter. The @@ -195,14 +206,8 @@ def __init__( self._approval_mode: Literal["always_require", "never_require"] = approval_mode self._on_command = on_command - merged_env: dict[str, str] | None - if env is None and not clean_env: - merged_env = None # inherit - elif clean_env: - merged_env = dict(env) if env is not None else {} - else: - merged_env = {**os.environ, **dict(env or {})} - self._env = merged_env + merged_env = dict(env or {}) if clean_env else {**os.environ, **dict(env or {})} + self._env = restrict_executable_search(merged_env) self._interactive_argv = resolve_shell(self._shell_override, interactive=True) self._stateless_argv = resolve_shell(self._shell_override, interactive=False) diff --git a/python/packages/tools/tests/test_docker_shell_tool.py b/python/packages/tools/tests/test_docker_shell_tool.py index 7b2bd52c273..b998455a3a8 100644 --- a/python/packages/tools/tests/test_docker_shell_tool.py +++ b/python/packages/tools/tests/test_docker_shell_tool.py @@ -15,12 +15,12 @@ import subprocess import sys from collections.abc import Callable, Iterable, Sequence +from pathlib import Path from typing import TypeAlias, cast from unittest.mock import AsyncMock, MagicMock, patch import pytest -import agent_framework_tools.shell._docker as docker_module from agent_framework_tools._feature_usage import FeatureIndex from agent_framework_tools.shell import ( DockerNotAvailableError, @@ -31,29 +31,18 @@ is_docker_available, ) from agent_framework_tools.shell._docker import build_exec_argv, build_run_argv -from agent_framework_tools.shell._resolve import resolve_executable +from agent_framework_tools.shell._resolve import find_executable _CommunicateOutcome: TypeAlias = tuple[bytes, bytes] | BaseException _WaitOutcome: TypeAlias = int | None | BaseException _FakeWindowsHost: TypeAlias = Callable[[str, Iterable[str]], None] -_RUNTIME_DIR = r"C:\Runtimes" -_DOCKER_EXE = rf"{_RUNTIME_DIR}\docker.exe" +_DOCKER = r"C:\Runtimes\docker.exe" if sys.platform == "win32" else "/usr/bin/docker" +_PODMAN = r"C:\Runtimes\podman.exe" if sys.platform == "win32" else "/usr/bin/podman" +_HOST_DOCKER = find_executable("docker") _CREATE_PROCESS = "agent_framework_tools.shell._docker.asyncio.create_subprocess_exec" -@pytest.fixture(autouse=True) -def _pin_runtime_lookup(monkeypatch: pytest.MonkeyPatch) -> None: - """Keep the launch tests independent of the container runtimes installed on the host.""" - monkeypatch.setattr(docker_module, "resolve_executable", lambda name: name) - - -@pytest.fixture -def real_runtime_lookup(monkeypatch: pytest.MonkeyPatch) -> None: - """Use the real executable lookup for tests that check how the runtime is resolved.""" - monkeypatch.setattr(docker_module, "resolve_executable", resolve_executable) - - class _FakeProcess: def __init__( self, @@ -102,11 +91,11 @@ def kill(self) -> None: def _docker_image_available(image: str) -> bool: - if not is_docker_available(): + if _HOST_DOCKER is None or not is_docker_available(_HOST_DOCKER): return False try: result = subprocess.run( - ["docker", "image", "inspect", image], + [_HOST_DOCKER, "image", "inspect", image], capture_output=True, check=False, timeout=5.0, @@ -242,12 +231,12 @@ def test_build_exec_argv_interactive(): @pytest.mark.parametrize("token", [None, 42]) def test_dockershell_rejects_non_string_unsafe_extra_run_args(token): with pytest.raises(ValueError, match="unsafe_extra_run_args contains a non-string token"): - DockerShellTool(unsafe_extra_run_args=[token]) # type: ignore[list-item] + DockerShellTool(docker_binary=_DOCKER, unsafe_extra_run_args=[token]) # type: ignore[list-item] def test_dockershell_snapshots_unsafe_extra_run_args(): unsafe = ["--network", "host"] - unsafe_tool = DockerShellTool(unsafe_extra_run_args=unsafe) + unsafe_tool = DockerShellTool(docker_binary=_DOCKER, unsafe_extra_run_args=unsafe) unsafe.append("--privileged") assert unsafe_tool._unsafe_extra_run_args == ("--network", "host") @@ -262,32 +251,32 @@ def test_build_exec_argv_non_interactive_appends_dash_c(): def test_docker_shell_tool_validates_mode(): with pytest.raises(ValueError, match="mode must be"): - DockerShellTool(mode="bogus") # type: ignore[arg-type] # ty: ignore[invalid-argument-type] + DockerShellTool(docker_binary=_DOCKER, mode="bogus") # type: ignore[arg-type] # ty: ignore[invalid-argument-type] def test_docker_shell_tool_does_not_require_acknowledge_unsafe(): """The container is the boundary; never_require should NOT raise.""" # No exception means the security model is trusting the sandbox, as # advertised in the docstring. - DockerShellTool(approval_mode="never_require") + DockerShellTool(docker_binary=_DOCKER, approval_mode="never_require") def test_docker_shell_tool_generates_unique_container_names(): - a = DockerShellTool() - b = DockerShellTool() + a = DockerShellTool(docker_binary=_DOCKER) + b = DockerShellTool(docker_binary=_DOCKER) assert a._container_name != b._container_name assert a._container_name.startswith("af-shell-") def test_docker_shell_tool_implements_shell_executor_protocol(): - tool = DockerShellTool() + tool = DockerShellTool(docker_binary=_DOCKER) assert isinstance(tool, ShellExecutor) def test_as_function_carries_shell_kind(): from agent_framework._tools import SHELL_TOOL_KIND_VALUE - fn = DockerShellTool().as_function() + fn = DockerShellTool(docker_binary=_DOCKER).as_function() # Approval mode flows through; tool is tagged as a shell tool. assert ( getattr(fn, "additional_properties", {}).get("kind") == SHELL_TOOL_KIND_VALUE @@ -303,7 +292,7 @@ async def test_as_function_preserves_structured_shell_result() -> None: exit_code=7, duration_ms=25, ) - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") with patch.object(tool, "run", AsyncMock(return_value=shell_result)): function = tool.as_function() @@ -326,7 +315,7 @@ async def test_as_function_preserves_structured_shell_result() -> None: async def test_start_and_close_are_noops_in_stateless_mode() -> None: - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") with ( patch.object(tool, "_start_container", AsyncMock()) as start_container, @@ -340,7 +329,7 @@ async def test_start_and_close_are_noops_in_stateless_mode() -> None: async def test_start_creates_and_reuses_persistent_session() -> None: - tool = DockerShellTool(docker_binary="podman", shell="sh", max_stdout_bytes=1024, max_stderr_bytes=2048) + tool = DockerShellTool(docker_binary=_PODMAN, shell="sh", max_stdout_bytes=1024, max_stderr_bytes=2048) session = AsyncMock() with ( @@ -352,7 +341,7 @@ async def test_start_creates_and_reuses_persistent_session() -> None: start_container.assert_awaited_once() shell_session.assert_called_once_with( - ["podman", "exec", "-i", tool._container_name, "sh"], + [_PODMAN, "exec", "-i", tool._container_name, "sh"], workdir=None, env=None, max_stdout_bytes=1024, @@ -362,7 +351,7 @@ async def test_start_creates_and_reuses_persistent_session() -> None: async def test_start_container_passes_unsafe_extra_run_args_verbatim() -> None: - tool = DockerShellTool(unsafe_extra_run_args=("--network", "host")) + tool = DockerShellTool(docker_binary=_DOCKER, unsafe_extra_run_args=("--network", "host")) proc = _FakeProcess(returncode=0) with patch( @@ -377,7 +366,7 @@ async def test_start_container_passes_unsafe_extra_run_args_verbatim() -> None: async def test_close_terminates_session_and_container() -> None: - tool = DockerShellTool() + tool = DockerShellTool(docker_binary=_DOCKER) tool._container_started = True session = AsyncMock() tool._session = session @@ -393,7 +382,8 @@ async def test_close_terminates_session_and_container() -> None: async def test_run_rejects_denied_commands() -> None: tool = DockerShellTool( - policy=MagicMock(evaluate=MagicMock(return_value=MagicMock(decision="deny", reason="blocked"))) + docker_binary=_DOCKER, + policy=MagicMock(evaluate=MagicMock(return_value=MagicMock(decision="deny", reason="blocked"))), ) with pytest.raises(ShellCommandError, match="blocked"): @@ -406,7 +396,7 @@ async def test_run_logs_audit_hook_failures_and_executes_persistent_command( def broken_hook(command: str) -> None: raise RuntimeError(f"boom:{command}") - tool = DockerShellTool(on_command=broken_hook) + tool = DockerShellTool(docker_binary=_DOCKER, on_command=broken_hook) tool._session = AsyncMock(run=AsyncMock(return_value=ShellResult("", "", 0, 1))) result = await tool.run("echo hi") @@ -417,14 +407,14 @@ def broken_hook(command: str) -> None: async def test_run_raises_if_start_did_not_create_persistent_session() -> None: - tool = DockerShellTool() + tool = DockerShellTool(docker_binary=_DOCKER) with patch.object(tool, "start", AsyncMock()), pytest.raises(RuntimeError, match="session failed to start"): await tool.run("echo hi") async def test_run_dispatches_to_private_stateless_runner() -> None: - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") expected = ShellResult(stdout="ok", stderr="", exit_code=0, duration_ms=1) with ( @@ -440,8 +430,8 @@ async def test_run_dispatches_to_private_stateless_runner() -> None: async def test_run_stateless_builds_expected_argv() -> None: tool = DockerShellTool( + docker_binary=_PODMAN, mode="stateless", - docker_binary="podman", image="alpine:3", shell="sh", host_workdir="/repo", @@ -459,7 +449,7 @@ async def test_run_stateless_builds_expected_argv() -> None: assert create_proc.await_args is not None argv = create_proc.await_args.args - assert argv[:4] == ("podman", "run", "--rm", "-i") + assert argv[:4] == (_PODMAN, "run", "--rm", "-i") assert "-v" in argv assert "/repo:/workspace:rw" in argv assert "AF_TEST=1" in argv @@ -487,7 +477,9 @@ def checked_append(self: _OutputBuffer, data: bytes) -> None: observed.append(retained) monkeypatch.setattr(_OutputBuffer, "append", checked_append) - tool = DockerShellTool(mode="stateless", max_stdout_bytes=max_stdout_bytes, max_stderr_bytes=max_stderr_bytes) + tool = DockerShellTool( + docker_binary=_DOCKER, mode="stateless", max_stdout_bytes=max_stdout_bytes, max_stderr_bytes=max_stderr_bytes + ) proc = _FakeProcess(communicate_results=[(b"a" * 65536, b"b" * 65536)]) with patch("agent_framework_tools.shell._docker.asyncio.create_subprocess_exec", AsyncMock(return_value=proc)): result = await tool.run("unused") @@ -499,7 +491,7 @@ def checked_append(self: _OutputBuffer, data: bytes) -> None: @pytest.mark.parametrize("failure", ["cancel", "reader"]) async def test_docker_stateless_failure_stops_container_and_local_client(failure: str) -> None: - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") proc = _FakeProcess(returncode=None) killer = _FakeProcess() waiting = asyncio.Event() @@ -539,13 +531,14 @@ async def wait() -> int: def test_docker_rejects_invalid_output_limit_before_execution(cap: int, stream: str) -> None: with pytest.raises(ValueError, match=f"max_{stream}_bytes must be positive"): DockerShellTool( + docker_binary=_DOCKER, max_stdout_bytes=cap if stream == "stdout" else 1024, max_stderr_bytes=cap if stream == "stderr" else 1024, ) async def test_docker_cleanup_reader_failure_stops_cleanup_process() -> None: - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") proc = _FakeProcess(returncode=None, wait_results=[asyncio.TimeoutError()]) killer = _FakeProcess(returncode=1) reaper = _FakeProcess(returncode=None) @@ -563,7 +556,7 @@ async def test_docker_cleanup_reader_failure_stops_cleanup_process() -> None: @pytest.mark.parametrize("cleanup_command", ["kill", "rm"]) async def test_docker_cancellation_stops_cleanup_process(cleanup_command: str) -> None: - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") proc = _FakeProcess(returncode=None, wait_results=[asyncio.TimeoutError()]) cleanup = _FakeProcess(returncode=None) waiting = asyncio.Event() @@ -591,6 +584,7 @@ async def wait() -> int: async def test_run_stateless_places_unsafe_extra_args_after_isolation_defaults() -> None: tool = DockerShellTool( + docker_binary=_DOCKER, mode="stateless", image="alpine:3", shell="sh", @@ -616,6 +610,7 @@ async def test_run_stateless_places_unsafe_extra_args_after_isolation_defaults() async def test_run_stateless_passes_unsafe_extra_run_args_verbatim() -> None: tool = DockerShellTool( + docker_binary=_DOCKER, mode="stateless", image="alpine:3", shell="sh", @@ -636,7 +631,7 @@ async def test_run_stateless_passes_unsafe_extra_run_args_verbatim() -> None: async def test_run_stateless_timeout_reaps_container_when_kill_fails() -> None: - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") command_proc = _FakeProcess( returncode=137, communicate_results=[asyncio.TimeoutError(), (b"after-timeout", b"stderr")], @@ -657,7 +652,7 @@ async def test_run_stateless_timeout_reaps_container_when_kill_fails() -> None: async def test_run_stateless_timeout_handles_kill_and_reaper_timeouts() -> None: - tool = DockerShellTool(mode="stateless") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") command_proc = _FakeProcess( returncode=None, communicate_results=[asyncio.TimeoutError(), RuntimeError("drain failed")], @@ -680,7 +675,7 @@ async def test_run_stateless_timeout_handles_kill_and_reaper_timeouts() -> None: async def test_start_container_success_logs_container_id(caplog: pytest.LogCaptureFixture) -> None: - tool = DockerShellTool() + tool = DockerShellTool(docker_binary=_DOCKER) proc = _FakeProcess(returncode=0, communicate_results=[(b"abcdef1234567890\n", b"")]) with ( @@ -693,7 +688,7 @@ async def test_start_container_success_logs_container_id(caplog: pytest.LogCaptu async def test_start_container_raises_when_runtime_fails() -> None: - tool = DockerShellTool() + tool = DockerShellTool(docker_binary=_DOCKER) proc = _FakeProcess(returncode=7, communicate_results=[(b"", b"daemon unavailable")]) with ( @@ -704,7 +699,7 @@ async def test_start_container_raises_when_runtime_fails() -> None: async def test_stop_container_returns_after_first_success() -> None: - tool = DockerShellTool() + tool = DockerShellTool(docker_binary=_DOCKER) proc = _FakeProcess(returncode=0, communicate_results=[(b"", b"")]) with patch("agent_framework_tools.shell._docker.asyncio.create_subprocess_exec", AsyncMock(return_value=proc)): @@ -712,7 +707,7 @@ async def test_stop_container_returns_after_first_success() -> None: async def test_stop_container_retries_when_first_attempt_fails() -> None: - tool = DockerShellTool() + tool = DockerShellTool(docker_binary=_DOCKER) first = _FakeProcess(returncode=1, communicate_results=[(b"", b"still running")]) second = _FakeProcess(returncode=2, communicate_results=[(b"", b"still running")]) @@ -726,7 +721,7 @@ async def test_stop_container_retries_when_first_attempt_fails() -> None: async def test_as_function_surfaces_command_errors() -> None: - tool = DockerShellTool(mode="persistent") + tool = DockerShellTool(docker_binary=_DOCKER, mode="persistent") with patch.object(tool, "run", AsyncMock(side_effect=ShellCommandError("blocked"))): function = tool.as_function() @@ -737,14 +732,32 @@ async def test_as_function_surfaces_command_errors() -> None: assert "persistent session" in function.description -# --------------------------------------------------------------------- executable lookup +# --------------------------------------------------------------------- runtime path + + +@pytest.mark.parametrize("docker_binary", ["docker", "podman", "bin/docker", "./docker"]) +def test_docker_binary_must_be_a_full_path_on_posix(monkeypatch: pytest.MonkeyPatch, docker_binary: str) -> None: + monkeypatch.setattr(sys, "platform", "linux") + + with pytest.raises(ValueError, match="docker_binary must be a full path"): + DockerShellTool(docker_binary=docker_binary) -async def test_persistent_lifecycle_launches_only_the_qualified_runtime_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None +@pytest.mark.parametrize( + "docker_binary", + ["docker", "docker.exe", r"bin\docker.exe", r".\docker.exe", "C:docker.exe", r"\docker.exe", r"C:\Runtimes\docker"], +) +def test_docker_binary_must_be_a_full_path_with_an_extension_on_windows( + fake_windows_host: _FakeWindowsHost, docker_binary: str ) -> None: - fake_windows_host(f".;{_RUNTIME_DIR}", {_DOCKER_EXE, r".\docker.exe", "docker.exe"}) - tool = DockerShellTool() + fake_windows_host(r"C:\Runtimes", {r"C:\Runtimes\docker.exe", r".\docker.exe", "docker.exe"}) + + with pytest.raises(ValueError, match="docker_binary must be a full path"): + DockerShellTool(docker_binary=docker_binary) + + +async def test_persistent_lifecycle_launches_the_configured_runtime() -> None: + tool = DockerShellTool(docker_binary=_DOCKER) started = _FakeProcess(returncode=0, communicate_results=[(b"abcdef123456\n", b"")]) stopped = _FakeProcess(returncode=0, communicate_results=[(b"", b"")]) @@ -755,29 +768,12 @@ async def test_persistent_lifecycle_launches_only_the_qualified_runtime_on_windo await tool.start() await tool.close() - assert [call.args[:2] for call in create_proc.await_args_list] == [(_DOCKER_EXE, "run"), (_DOCKER_EXE, "rm")] - assert shell_session.call_args.args[0][:2] == [_DOCKER_EXE, "exec"] + assert [call.args[:2] for call in create_proc.await_args_list] == [(_DOCKER, "run"), (_DOCKER, "rm")] + assert shell_session.call_args.args[0][:2] == [_DOCKER, "exec"] -async def test_stateless_run_launches_the_qualified_runtime_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None -) -> None: - fake_windows_host(f".;{_RUNTIME_DIR}", {_DOCKER_EXE, r".\docker.exe", "docker.exe"}) - tool = DockerShellTool(mode="stateless") - proc = _FakeProcess(returncode=0, communicate_results=[(b"", b"")]) - - with patch(_CREATE_PROCESS, AsyncMock(return_value=proc)) as create_proc: - await tool._run_stateless("echo hi", timeout=5.0) - - assert create_proc.await_args is not None - assert create_proc.await_args.args[:2] == (_DOCKER_EXE, "run") - - -async def test_stateless_cleanup_launches_the_qualified_runtime_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None -) -> None: - fake_windows_host(f".;{_RUNTIME_DIR}", {_DOCKER_EXE, r".\docker.exe", "docker.exe"}) - tool = DockerShellTool(mode="stateless") +async def test_stateless_cleanup_launches_the_configured_runtime() -> None: + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless") victim = _FakeProcess(returncode=None) killer = _FakeProcess(returncode=1) reaper = _FakeProcess(returncode=0) @@ -785,93 +781,38 @@ async def test_stateless_cleanup_launches_the_qualified_runtime_on_windows( with patch(_CREATE_PROCESS, AsyncMock(side_effect=[killer, reaper])) as create_proc: await tool._terminate_stateless(cast(asyncio.subprocess.Process, victim), "af-shell-test") - assert [call.args[:2] for call in create_proc.await_args_list] == [(_DOCKER_EXE, "kill"), (_DOCKER_EXE, "rm")] + assert [call.args[:2] for call in create_proc.await_args_list] == [(_DOCKER, "kill"), (_DOCKER, "rm")] assert victim.killed -async def test_launch_is_refused_when_the_runtime_exists_only_in_the_current_directory_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None -) -> None: - fake_windows_host(f".;{_RUNTIME_DIR}", {r".\docker.exe", "docker.exe"}) - persistent = DockerShellTool() - stateless = DockerShellTool(mode="stateless") - - with patch(_CREATE_PROCESS, AsyncMock()) as create_proc: - with pytest.raises(FileNotFoundError, match="'docker'"): - await persistent.start() - with pytest.raises(FileNotFoundError, match="'docker'"): - await stateless.run("echo hi") - - create_proc.assert_not_awaited() - - -async def test_container_is_stopped_with_the_runtime_that_started_it_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None -) -> None: - fake_windows_host(_RUNTIME_DIR, {_DOCKER_EXE}) - tool = DockerShellTool() - started = _FakeProcess(returncode=0, communicate_results=[(b"abcdef123456\n", b"")]) - stopped = _FakeProcess(returncode=0, communicate_results=[(b"", b"")]) - - with ( - patch(_CREATE_PROCESS, AsyncMock(side_effect=[started, stopped])) as create_proc, - patch("agent_framework_tools.shell._docker.ShellSession", return_value=AsyncMock()), - ): - await tool.start() - fake_windows_host(r"C:\Other", {r"C:\Other\docker.exe"}) - await tool.close() - - assert [call.args[0] for call in create_proc.await_args_list] == [_DOCKER_EXE, _DOCKER_EXE] - - -async def test_explicit_runtime_path_is_launched_unchanged_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None -) -> None: - fake_windows_host(_RUNTIME_DIR, {_DOCKER_EXE}) - tool = DockerShellTool(mode="stateless", docker_binary=r"C:\Custom\podman.exe") - proc = _FakeProcess(returncode=0, communicate_results=[(b"", b"")]) - - with patch(_CREATE_PROCESS, AsyncMock(return_value=proc)) as create_proc: - await tool._run_stateless("echo hi", timeout=5.0) - - assert create_proc.await_args is not None - assert create_proc.await_args.args[0] == r"C:\Custom\podman.exe" - +def test_is_docker_available_runs_the_given_runtime(tmp_path: Path) -> None: + runtime = tmp_path / "docker.exe" + runtime.write_text("") + completed = subprocess.CompletedProcess(args=[], returncode=0, stdout=b"27.0.1\n", stderr=b"") -async def test_run_stateless_uses_the_configured_binary_unchanged_on_other_platforms( - real_runtime_lookup: None, monkeypatch: pytest.MonkeyPatch -) -> None: - tool = DockerShellTool(mode="stateless", docker_binary="podman") - proc = _FakeProcess(returncode=0, communicate_results=[(b"", b"")]) - monkeypatch.setattr(sys, "platform", "linux") + with patch("agent_framework_tools.shell._docker.subprocess.run", return_value=completed) as run: + assert is_docker_available(str(runtime)) is True - with patch(_CREATE_PROCESS, AsyncMock(return_value=proc)) as create_proc: - await tool._run_stateless("echo hi", timeout=5.0) + assert run.call_args.args[0][0] == str(runtime) - assert create_proc.await_args is not None - assert create_proc.await_args.args[0] == "podman" - -def test_is_docker_available_uses_the_qualified_runtime_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None, monkeypatch: pytest.MonkeyPatch +@pytest.mark.parametrize("binary", ["docker", "docker.exe", "./docker.exe"]) +def test_is_docker_available_is_false_for_a_short_name_or_relative_path( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, binary: str ) -> None: - fake_windows_host(f".;{_RUNTIME_DIR}", {_DOCKER_EXE, r".\docker.exe", "docker.exe"}) - monkeypatch.setattr(docker_module.shutil, "which", lambda name: name) - completed = subprocess.CompletedProcess(args=[], returncode=0, stdout=b"27.0.1\n", stderr=b"") - - with patch("agent_framework_tools.shell._docker.subprocess.run", return_value=completed) as run: - assert is_docker_available() is True + (tmp_path / "docker").write_text("") + (tmp_path / "docker.exe").write_text("") + monkeypatch.chdir(tmp_path) - assert run.call_args.args[0][0] == _DOCKER_EXE + with patch("agent_framework_tools.shell._docker.subprocess.run") as run: + assert is_docker_available(binary) is False + run.assert_not_called() -def test_is_docker_available_is_false_when_the_runtime_exists_only_in_the_current_directory_on_windows( - fake_windows_host: _FakeWindowsHost, real_runtime_lookup: None -) -> None: - fake_windows_host(f".;{_RUNTIME_DIR}", {r".\docker.exe", "docker.exe"}) +def test_is_docker_available_is_false_when_the_runtime_does_not_exist(tmp_path: Path) -> None: with patch("agent_framework_tools.shell._docker.subprocess.run") as run: - assert is_docker_available() is False + assert is_docker_available(str(tmp_path / "docker.exe")) is False run.assert_not_called() @@ -881,7 +822,7 @@ def test_is_docker_available_is_false_when_the_runtime_exists_only_in_the_curren @_skip_if_no_linux_docker async def test_docker_persistent_session_preserves_state(): - async with DockerShellTool(image="alpine:3", shell="sh", network="none") as shell: + async with DockerShellTool(docker_binary=_HOST_DOCKER, image="alpine:3", shell="sh", network="none") as shell: r1 = await shell.run("export AF_X=hello") assert r1.exit_code == 0 r2 = await shell.run("echo $AF_X") @@ -891,7 +832,7 @@ async def test_docker_persistent_session_preserves_state(): @_skip_if_no_linux_docker async def test_docker_stateless_each_command_isolated(): - shell = DockerShellTool(mode="stateless", image="alpine:3", shell="sh", network="none") + shell = DockerShellTool(docker_binary=_HOST_DOCKER, mode="stateless", image="alpine:3", shell="sh", network="none") r1 = await shell.run("export AF_X=hello") assert r1 is not None # noqa: S101 r2 = await shell.run('echo "${AF_X:-unset}"') @@ -900,7 +841,7 @@ async def test_docker_stateless_each_command_isolated(): @_skip_if_no_linux_docker async def test_docker_no_network_by_default(): - async with DockerShellTool(image="alpine:3", shell="sh") as shell: + async with DockerShellTool(docker_binary=_HOST_DOCKER, image="alpine:3", shell="sh") as shell: # busybox wget against a host that should be unreachable with --network none r = await shell.run("wget -q -T 2 -O- http://example.com || echo NOACCESS") assert "NOACCESS" in r.stdout @@ -916,7 +857,7 @@ async def test_run_stateless_sets_stdin_to_devnull() -> None: This test asserts the spawn is given stdin=DEVNULL by inspecting the asyncio.create_subprocess_exec call. """ - tool = DockerShellTool(mode="stateless", image="alpine:3", shell="sh") + tool = DockerShellTool(docker_binary=_DOCKER, mode="stateless", image="alpine:3", shell="sh") proc = _FakeProcess(returncode=0, communicate_results=[(b"", b"")]) with patch( diff --git a/python/packages/tools/tests/test_local_shell_tool.py b/python/packages/tools/tests/test_local_shell_tool.py index b7040f310cb..77f84c11428 100644 --- a/python/packages/tools/tests/test_local_shell_tool.py +++ b/python/packages/tools/tests/test_local_shell_tool.py @@ -31,7 +31,7 @@ from agent_framework_tools.shell._truncate import _OutputBuffer from agent_framework_tools.shell._types import ShellMode -_TEST_SHELL = "/opt/agent-framework-test-shell" +_TEST_SHELL = r"C:\agent-framework\test-shell.exe" if sys.platform == "win32" else "/opt/agent-framework-test-shell" _APPROVED_COMMAND = "printf '%s' approved-value" _ALTERNATE_COMMAND = "printf '%s' alternate-value" _POWERSHELL = shutil.which("pwsh") or (shutil.which("powershell") if sys.platform == "win32" else None) @@ -547,14 +547,58 @@ def test_local_shell_tool_handles_mode_and_environment_variants(monkeypatch: pyt mode="stateless", approval_mode="never_require", acknowledge_unsafe=True, - env={"ONLY": "2"}, + env={"ONLY": "2", "PATH": os.environ["PATH"]}, clean_env=True, ) assert inherited._env is not None assert inherited._env["INHERITED"] == "yes" assert inherited._env["EXTRA"] == "1" - assert clean._env == {"ONLY": "2"} + assert clean._env["ONLY"] == "2" + assert "INHERITED" not in clean._env + + +@pytest.mark.skipif(sys.platform == "win32", reason="POSIX PATH search") +@pytest.mark.parametrize("mode", ["stateless", "persistent"]) +@pytest.mark.parametrize( + ("env", "clean_env"), + [({"PATH": "."}, False), ({"PATH": "bin"}, False), ({"PATH": ""}, False), ({"ONLY": "1"}, True)], +) +def test_shell_path_without_full_directories_is_rejected(mode: ShellMode, env: dict[str, str], clean_env: bool) -> None: + with pytest.raises(ValueError, match="at least one full directory path"): + LocalShellTool(mode=mode, env=env, clean_env=clean_env, approval_mode="never_require", acknowledge_unsafe=True) + + +@pytest.mark.skipif(sys.platform == "win32", reason="POSIX PATH search") +@pytest.mark.parametrize("mode", ["stateless", "persistent"]) +@pytest.mark.parametrize("path_source", ["env", "inherited"]) +async def test_relative_path_entries_are_not_searched_by_the_shell( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, mode: ShellMode, path_source: str +) -> None: + workdir = tmp_path / "repo" + workdir.mkdir() + marker = tmp_path / "planted-ran" + planted = workdir / "af-planted-tool" + planted.write_text(f"#!/bin/sh\ntouch {shlex.quote(str(marker))}\n") + planted.chmod(0o755) + unsafe_path = os.pathsep.join(["", ".", os.environ.get("PATH", "")]) + env: dict[str, str] | None = None + if path_source == "env": + env = {"PATH": unsafe_path} + else: + monkeypatch.setenv("PATH", unsafe_path) + + async with LocalShellTool( + mode=mode, + workdir=workdir, + env=env, + approval_mode="never_require", + acknowledge_unsafe=True, + ) as tool: + result = await tool.run("af-planted-tool") + + assert result.exit_code != 0 + assert not marker.exists() async def test_local_shell_tool_stateless_start_is_noop() -> None: @@ -585,7 +629,7 @@ async def test_local_shell_tool_as_function_returns_policy_errors() -> None: def test_local_shell_tool_reanchors_powershell_paths() -> None: tool = LocalShellTool( mode="persistent", - shell="/usr/bin/pwsh", + shell=r"C:\Program Files\PowerShell\7\pwsh.exe" if sys.platform == "win32" else "/usr/bin/pwsh", workdir="C:\\repo", approval_mode="never_require", acknowledge_unsafe=True, diff --git a/python/packages/tools/tests/test_shell_resolve.py b/python/packages/tools/tests/test_shell_resolve.py index b8c727e49b3..2afaac59414 100644 --- a/python/packages/tools/tests/test_shell_resolve.py +++ b/python/packages/tools/tests/test_shell_resolve.py @@ -1,5 +1,6 @@ # Copyright (c) Microsoft. All rights reserved. +import os import sys from collections.abc import Callable, Iterable from pathlib import Path @@ -12,8 +13,9 @@ _ensure_command_flag, find_executable, is_powershell, - resolve_executable, + require_full_path, resolve_shell, + restrict_executable_search, ) _FakeWindowsHost: TypeAlias = Callable[[str, Iterable[str]], None] @@ -23,6 +25,12 @@ _WINDOWS_POWERSHELL = r"C:\Windows\System32\WindowsPowerShell\v1.0" +@pytest.fixture +def posix_host(monkeypatch: pytest.MonkeyPatch) -> None: + """Make the process look like a POSIX host so POSIX paths are accepted on every platform.""" + monkeypatch.setattr(sys, "platform", "linux") + + def test_empty_string_shell_override_rejected() -> None: with pytest.raises(ShellExecutionError, match="must not be empty"): resolve_shell("", interactive=True) @@ -38,7 +46,7 @@ def test_empty_sequence_shell_override_rejected() -> None: resolve_shell([], interactive=True) -def test_resolve_shell_prefers_environment_override(monkeypatch: pytest.MonkeyPatch) -> None: +def test_resolve_shell_prefers_environment_override(posix_host: None, monkeypatch: pytest.MonkeyPatch) -> None: monkeypatch.setenv("AGENT_FRAMEWORK_SHELL", "/custom/pwsh -NoProfile") assert resolve_shell(None, interactive=False) == ["/custom/pwsh", "-NoProfile", "-Command"] @@ -79,40 +87,56 @@ def test_resolve_shell_windows_default_ignores_executables_in_the_current_direct resolve_shell(None, interactive=False) -def test_resolve_shell_windows_resolves_bare_overrides( - fake_windows_host: _FakeWindowsHost, monkeypatch: pytest.MonkeyPatch +@pytest.mark.parametrize( + "shell", + [ + "pwsh", + "pwsh.exe", + r".\pwsh.exe", + r"bin\pwsh.exe", + "C:pwsh.exe", + r"\pwsh.exe", + rf"{_POWERSHELL_7}\pwsh", + "/opt/pwsh", + ], +) +def test_resolve_shell_windows_rejects_overrides_that_are_not_full_paths_with_an_extension( + fake_windows_host: _FakeWindowsHost, monkeypatch: pytest.MonkeyPatch, shell: str ) -> None: + # The file exists in every searched location, so only the path form decides the result. + fake_windows_host(f".;{_POWERSHELL_7}", {rf"{_POWERSHELL_7}\pwsh.exe", r".\pwsh.exe", "pwsh.exe"}) monkeypatch.delenv("AGENT_FRAMEWORK_SHELL", raising=False) - fake_windows_host(f"{_POWERSHELL_7};{_TRUSTED_BIN}", {rf"{_POWERSHELL_7}\pwsh.exe", rf"{_TRUSTED_BIN}\bash.exe"}) - assert resolve_shell("pwsh -NoProfile", interactive=True) == [rf"{_POWERSHELL_7}\pwsh.exe", "-NoProfile"] - assert resolve_shell(["bash", "--norc"], interactive=True) == [rf"{_TRUSTED_BIN}\bash.exe", "--norc"] - monkeypatch.setenv("AGENT_FRAMEWORK_SHELL", "bash") - assert resolve_shell(None, interactive=False) == [rf"{_TRUSTED_BIN}\bash.exe", "-c"] + with pytest.raises(ShellExecutionError, match="shell must be a full path"): + resolve_shell(shell, interactive=True) + with pytest.raises(ShellExecutionError, match="shell must be a full path"): + resolve_shell([shell, "-NoProfile"], interactive=True) + monkeypatch.setenv("AGENT_FRAMEWORK_SHELL", shell) + with pytest.raises(ShellExecutionError, match="AGENT_FRAMEWORK_SHELL must be a full path"): + resolve_shell(None, interactive=True) -def test_resolve_shell_windows_rejects_a_bare_override_found_only_in_the_current_directory( - fake_windows_host: _FakeWindowsHost, monkeypatch: pytest.MonkeyPatch +@pytest.mark.parametrize("shell", ["zsh", "bin/zsh", "./zsh", "../zsh"]) +def test_resolve_shell_posix_rejects_overrides_that_are_not_full_paths( + posix_host: None, monkeypatch: pytest.MonkeyPatch, shell: str ) -> None: monkeypatch.delenv("AGENT_FRAMEWORK_SHELL", raising=False) - fake_windows_host(f".;{_TRUSTED_BIN}", {r".\bash.exe", "bash.exe"}) - with pytest.raises(ShellExecutionError, match="'bash'"): - resolve_shell("bash", interactive=True) - monkeypatch.setenv("AGENT_FRAMEWORK_SHELL", "bash") - with pytest.raises(ShellExecutionError, match="'bash'"): - resolve_shell(None, interactive=True) + with pytest.raises(ShellExecutionError, match="shell must be a full path"): + resolve_shell(shell, interactive=False) + monkeypatch.setenv("AGENT_FRAMEWORK_SHELL", f"{shell} -l") + with pytest.raises(ShellExecutionError, match="AGENT_FRAMEWORK_SHELL must be a full path"): + resolve_shell(None, interactive=False) @pytest.mark.parametrize( "shell", [ [rf"{_POWERSHELL_7}\pwsh.exe", "-NoProfile"], - [r".\pwsh.exe"], - ["/opt/pwsh"], + [r"\\server\share\pwsh.exe"], ], ) -def test_resolve_shell_windows_keeps_explicit_paths(fake_windows_host: _FakeWindowsHost, shell: list[str]) -> None: +def test_resolve_shell_windows_keeps_full_paths(fake_windows_host: _FakeWindowsHost, shell: list[str]) -> None: fake_windows_host(_TRUSTED_BIN, set()) assert resolve_shell(shell, interactive=True) == shell @@ -160,12 +184,19 @@ def test_find_executable_returns_the_first_match_in_path_order(fake_windows_host @pytest.mark.parametrize( ("name", "expected"), - [("pwsh", None), ("pwsh.exe", None), ("pwsh.cmd", rf"{_TRUSTED_BIN}\pwsh.cmd")], + [ + ("pwsh", rf"{_TRUSTED_BIN}\pwsh.exe"), + ("pwsh.exe", rf"{_TRUSTED_BIN}\pwsh.exe"), + ("pwsh.cmd", None), + ("pwsh.bat", None), + ], ) -def test_find_executable_adds_exe_only_to_names_without_an_extension( +def test_find_executable_finds_only_exe_files_on_windows( fake_windows_host: _FakeWindowsHost, name: str, expected: str | None ) -> None: - fake_windows_host(_TRUSTED_BIN, {rf"{_TRUSTED_BIN}\pwsh.cmd"}) + fake_windows_host( + _TRUSTED_BIN, {rf"{_TRUSTED_BIN}\pwsh.exe", rf"{_TRUSTED_BIN}\pwsh.cmd", rf"{_TRUSTED_BIN}\pwsh.bat"} + ) assert find_executable(name) == expected @@ -196,38 +227,97 @@ def test_find_executable_accepts_unc_share_roots_without_a_trailing_separator( assert find_executable("docker") == expected -@pytest.mark.parametrize( - "name", - [ - r"C:\tools\docker.exe", - r"\\server\share\docker.exe", - r".\docker.exe", - r"bin\docker.exe", - "C:docker.exe", - r"\docker.exe", - "/usr/bin/docker", - ], -) -def test_resolve_executable_returns_names_with_a_directory_or_drive_unchanged( - fake_windows_host: _FakeWindowsHost, name: str +@pytest.mark.parametrize("value", [r"C:\tools\docker.exe", r"\\server\share\docker.exe", "//server/share/docker.exe"]) +def test_require_full_path_accepts_full_paths_with_an_extension_on_windows( + fake_windows_host: _FakeWindowsHost, value: str ) -> None: fake_windows_host(_TRUSTED_BIN, set()) - assert resolve_executable(name) == name + assert require_full_path(value, source="docker_binary") == value + + +@pytest.mark.parametrize("value", ["/usr/bin/docker", "/usr/local/bin/podman"]) +def test_require_full_path_accepts_absolute_paths_on_posix(posix_host: None, value: str) -> None: + # The file is not required to exist; a missing file fails when it is launched. + assert require_full_path(value, source="docker_binary") == value + + +@pytest.mark.skipif(sys.platform == "win32", reason="POSIX executable lookup") +def test_find_executable_skips_empty_and_relative_path_entries_on_posix( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + workdir = tmp_path / "repo" + trusted = tmp_path / "trusted" + for directory in (workdir, workdir / "bin", trusted): + directory.mkdir() + tool = directory / "git" + tool.write_text("#!/bin/sh\n") + tool.chmod(0o755) + monkeypatch.chdir(workdir) + monkeypatch.setenv("PATH", os.pathsep.join(["", ".", "bin", str(trusted)])) + + assert find_executable("git") == str(trusted / "git") + + +@pytest.mark.skipif(sys.platform == "win32", reason="POSIX executable lookup") +def test_find_executable_skips_files_that_are_not_executable_on_posix( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + (tmp_path / "git").write_text("") + monkeypatch.setenv("PATH", str(tmp_path)) + assert find_executable("git") is None -def test_resolve_executable_never_falls_back_to_the_bare_name_on_windows(fake_windows_host: _FakeWindowsHost) -> None: - fake_windows_host(f".;{_TRUSTED_BIN}", {r".\docker.exe", "docker.exe"}) - with pytest.raises(FileNotFoundError, match="'docker'"): - resolve_executable("docker") +def test_restrict_executable_search_keeps_only_absolute_path_entries_on_posix(posix_host: None) -> None: + env = {"PATH": ":.:bin:/usr/bin:../tools:/opt/tools", "HOME": "/home/user"} + + restricted = restrict_executable_search(env) + + assert restricted == {"PATH": "/usr/bin:/opt/tools", "HOME": "/home/user"} + assert env["PATH"] == ":.:bin:/usr/bin:../tools:/opt/tools" + + +def test_restrict_executable_search_cleans_every_path_key_on_windows(fake_windows_host: _FakeWindowsHost) -> None: + fake_windows_host(_TRUSTED_BIN, set()) + env = { + "Path": r'.;;bin;C:dir;\dir;C:\Windows;"C:\Program Files\Tools";\\server\share', + "PATH": rf".;{_TRUSTED_BIN}", + "OTHER": "1", + } + + assert restrict_executable_search(env) == { + "Path": r'C:\Windows;"C:\Program Files\Tools";\\server\share', + "PATH": _TRUSTED_BIN, + "OTHER": "1", + "NoDefaultCurrentDirectoryInExePath": "1", + } -def test_resolve_executable_returns_names_unchanged_on_other_platforms(monkeypatch: pytest.MonkeyPatch) -> None: +def test_restrict_executable_search_sets_the_current_directory_switch_only_on_windows( + fake_windows_host: _FakeWindowsHost, monkeypatch: pytest.MonkeyPatch +) -> None: monkeypatch.setattr(sys, "platform", "linux") - monkeypatch.setenv("PATH", "") + assert restrict_executable_search({"PATH": "/usr/bin"}) == {"PATH": "/usr/bin"} + + fake_windows_host(_TRUSTED_BIN, set()) + assert restrict_executable_search({}) == {"NoDefaultCurrentDirectoryInExePath": "1"} + + +@pytest.mark.parametrize("env", [{}, {"PATH": ""}, {"PATH": "."}, {"PATH": ".:bin:"}]) +def test_restrict_executable_search_rejects_a_path_without_full_directories_on_posix( + posix_host: None, env: dict[str, str] +) -> None: + with pytest.raises(ValueError, match="at least one full directory path"): + restrict_executable_search(env) + + +def test_restrict_executable_search_allows_a_path_without_full_directories_on_windows( + fake_windows_host: _FakeWindowsHost, +) -> None: + fake_windows_host(_TRUSTED_BIN, set()) - assert resolve_executable("docker") == "docker" + assert restrict_executable_search({"PATH": r".;bin"}) == {"PATH": "", "NoDefaultCurrentDirectoryInExePath": "1"} def test_resolve_shell_posix_fallbacks(monkeypatch: pytest.MonkeyPatch) -> None: @@ -238,10 +328,10 @@ def test_resolve_shell_posix_fallbacks(monkeypatch: pytest.MonkeyPatch) -> None: assert resolve_shell(None, interactive=False) == ["/bin/sh", "-c"] monkeypatch.setattr(resolve_module.os.path, "exists", lambda candidate: False) - monkeypatch.setattr(resolve_module.shutil, "which", lambda name: "/usr/local/bin/sh" if name == "sh" else None) + monkeypatch.setattr(resolve_module, "find_executable", lambda name: "/usr/local/bin/sh" if name == "sh" else None) assert resolve_shell(None, interactive=True) == ["/usr/local/bin/sh"] - monkeypatch.setattr(resolve_module.shutil, "which", lambda name: None) + monkeypatch.setattr(resolve_module, "find_executable", lambda name: None) with pytest.raises(ShellExecutionError, match="No POSIX shell found"): resolve_shell(None, interactive=False) @@ -251,30 +341,30 @@ def test_is_powershell_and_command_flag_helpers() -> None: assert _ensure_command_flag([]) == [] -def test_stateless_appends_dash_c_for_posix_shell_without_flag() -> None: +def test_stateless_appends_dash_c_for_posix_shell_without_flag(posix_host: None) -> None: argv = resolve_shell("/bin/bash", interactive=False) assert argv == ["/bin/bash", "-c"] -def test_stateless_appends_dash_c_for_pwsh_without_flag() -> None: +def test_stateless_appends_dash_c_for_pwsh_without_flag(posix_host: None) -> None: argv = resolve_shell("/usr/bin/pwsh -NoProfile", interactive=False) assert argv[-1] == "-Command" assert "pwsh" in argv[0] -def test_stateless_preserves_existing_dash_c_flag() -> None: +def test_stateless_preserves_existing_dash_c_flag(posix_host: None) -> None: argv = resolve_shell("/bin/bash -c", interactive=False) assert argv == ["/bin/bash", "-c"] -def test_stateless_preserves_existing_pwsh_command_flag() -> None: +def test_stateless_preserves_existing_pwsh_command_flag(posix_host: None) -> None: argv = resolve_shell("/opt/pwsh -NoProfile -Command", interactive=False) assert argv[-1] == "-Command" # No second -Command appended. assert argv.count("-Command") == 1 -def test_interactive_does_not_append_command_flag() -> None: +def test_interactive_does_not_append_command_flag(posix_host: None) -> None: argv = resolve_shell("/bin/bash --noprofile", interactive=True) assert "-c" not in argv From 19c39d96613d33d4afc508fbb29e5e353b5e7271 Mon Sep 17 00:00:00 2001 From: westey <164392973+westey-m@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:28:35 +0000 Subject: [PATCH 2/4] Address PR comments --- python/packages/tools/tests/test_local_shell_tool.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/packages/tools/tests/test_local_shell_tool.py b/python/packages/tools/tests/test_local_shell_tool.py index 77f84c11428..19b9723add6 100644 --- a/python/packages/tools/tests/test_local_shell_tool.py +++ b/python/packages/tools/tests/test_local_shell_tool.py @@ -629,7 +629,7 @@ async def test_local_shell_tool_as_function_returns_policy_errors() -> None: def test_local_shell_tool_reanchors_powershell_paths() -> None: tool = LocalShellTool( mode="persistent", - shell=r"C:\Program Files\PowerShell\7\pwsh.exe" if sys.platform == "win32" else "/usr/bin/pwsh", + shell=[r"C:\Program Files\PowerShell\7\pwsh.exe"] if sys.platform == "win32" else ["/usr/bin/pwsh"], workdir="C:\\repo", approval_mode="never_require", acknowledge_unsafe=True, From 7b8605ffb37186c169a19b6a80f35c2c338a26dc Mon Sep 17 00:00:00 2001 From: westey <164392973+westey-m@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:47:02 +0000 Subject: [PATCH 3/4] Fix build errors --- python/packages/tools/tests/test_docker_shell_tool.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/python/packages/tools/tests/test_docker_shell_tool.py b/python/packages/tools/tests/test_docker_shell_tool.py index b998455a3a8..81933b9ecfa 100644 --- a/python/packages/tools/tests/test_docker_shell_tool.py +++ b/python/packages/tools/tests/test_docker_shell_tool.py @@ -39,7 +39,7 @@ _DOCKER = r"C:\Runtimes\docker.exe" if sys.platform == "win32" else "/usr/bin/docker" _PODMAN = r"C:\Runtimes\podman.exe" if sys.platform == "win32" else "/usr/bin/podman" -_HOST_DOCKER = find_executable("docker") +_HOST_DOCKER = find_executable("docker") or "" _CREATE_PROCESS = "agent_framework_tools.shell._docker.asyncio.create_subprocess_exec" @@ -91,7 +91,7 @@ def kill(self) -> None: def _docker_image_available(image: str) -> bool: - if _HOST_DOCKER is None or not is_docker_available(_HOST_DOCKER): + if not _HOST_DOCKER or not is_docker_available(_HOST_DOCKER): return False try: result = subprocess.run( From 9a64a2504be155666c6061c0843a005ce4ac830f Mon Sep 17 00:00:00 2001 From: westey <164392973+westey-m@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:56:37 +0000 Subject: [PATCH 4/4] Address PR comments --- python/packages/tools/README.md | 5 +++- .../agent_framework_tools/shell/_resolve.py | 28 +++++++++++++------ .../agent_framework_tools/shell/_tool.py | 16 ++++++++--- .../tools/tests/test_local_shell_tool.py | 22 +++++++++++---- .../tools/tests/test_shell_resolve.py | 18 ++++++++++++ 5 files changed, 71 insertions(+), 18 deletions(-) diff --git a/python/packages/tools/README.md b/python/packages/tools/README.md index fd26a2ab28e..8d9154fd0af 100644 --- a/python/packages/tools/README.md +++ b/python/packages/tools/README.md @@ -133,7 +133,10 @@ are not stopped solely because either output allowance is exceeded. `/usr/bin/zsh` or `C:\Program Files\PowerShell\7\pwsh.exe`. On Windows the path must also include the file extension. Short names (`zsh`) and relative paths (`bin/zsh`, `.\pwsh.exe`) are rejected, because they could pick up a - file in the current directory. + file in the current directory. On Windows, wrap a path that contains spaces + in double quotes when passing it as a string, for example + `"C:\Program Files\PowerShell\7\pwsh.exe" -NoLogo`, or pass `shell=` as a + list. - **Default shell lookup**: the Windows default (`pwsh.exe`, then `powershell.exe`) is looked up only in the fully qualified entries of `PATH`. The current directory and relative `PATH` entries are never diff --git a/python/packages/tools/agent_framework_tools/shell/_resolve.py b/python/packages/tools/agent_framework_tools/shell/_resolve.py index e28b9e7fa10..7b65d39cae9 100644 --- a/python/packages/tools/agent_framework_tools/shell/_resolve.py +++ b/python/packages/tools/agent_framework_tools/shell/_resolve.py @@ -7,6 +7,7 @@ import ntpath import os import posixpath +import shlex import sys from collections.abc import Mapping, Sequence @@ -25,6 +26,20 @@ def _is_fully_qualified(path: str) -> bool: return bool(drive) and rest[:1] in ("\\", "/") +def _split_shell_string(value: str) -> list[str]: + """Split a shell override string into argv. + + On Windows, path separators are kept as written and a path that contains spaces must be wrapped in + double quotes, which are then removed. Elsewhere POSIX shell rules apply. + """ + if sys.platform == "win32": + return [ + part[1:-1] if len(part) >= 2 and part[0] == part[-1] == '"' else part + for part in shlex.split(value, posix=False) + ] + return shlex.split(value) + + def find_executable(name: str) -> str | None: """Find a bare executable name in the fully qualified entries of ``PATH``. @@ -137,8 +152,9 @@ def resolve_shell(shell: str | Sequence[str] | None, *, interactive: bool) -> li Priority: - 1. Explicit ``shell`` argument (string is split via shlex rules; sequence - is used verbatim). + 1. Explicit ``shell`` argument (a string is split into arguments; on + Windows a path with spaces must be in double quotes; a sequence is + used verbatim). 2. ``AGENT_FRAMEWORK_SHELL`` environment variable. 3. Platform default. @@ -163,9 +179,7 @@ def resolve_shell(shell: str | Sequence[str] | None, *, interactive: bool) -> li """ if shell is not None: if isinstance(shell, str): - import shlex - - parts = shlex.split(shell) + parts = _split_shell_string(shell) if not parts: raise ShellExecutionError("shell override must not be empty") else: @@ -177,9 +191,7 @@ def resolve_shell(shell: str | Sequence[str] | None, *, interactive: bool) -> li env_override = os.environ.get(_ENV_OVERRIDE) if env_override: - import shlex - - parts = shlex.split(env_override) + parts = _split_shell_string(env_override) if parts: parts = _qualify_shell(parts, source=_ENV_OVERRIDE) return parts if interactive else _ensure_command_flag(parts) diff --git a/python/packages/tools/agent_framework_tools/shell/_tool.py b/python/packages/tools/agent_framework_tools/shell/_tool.py index c18310985ad..3555b741fcb 100644 --- a/python/packages/tools/agent_framework_tools/shell/_tool.py +++ b/python/packages/tools/agent_framework_tools/shell/_tool.py @@ -206,8 +206,11 @@ def __init__( self._approval_mode: Literal["always_require", "never_require"] = approval_mode self._on_command = on_command - merged_env = dict(env or {}) if clean_env else {**os.environ, **dict(env or {})} - self._env = restrict_executable_search(merged_env) + self._env_overrides = dict(env or {}) + self._clean_env = clean_env + # Check PATH now so a bad configuration fails here; the environment used to start a shell is + # rebuilt at launch so later changes to os.environ are still inherited. + self._launch_env() self._interactive_argv = resolve_shell(self._shell_override, interactive=True) self._stateless_argv = resolve_shell(self._shell_override, interactive=False) @@ -222,6 +225,11 @@ def _get_session_lock(self) -> asyncio.Lock: # ------------------------------------------------------------------ lifecycle + def _launch_env(self) -> dict[str, str]: + """Build the environment for a new shell process, with ``PATH`` restricted to full directory paths.""" + base = {} if self._clean_env else dict(os.environ) + return restrict_executable_search({**base, **self._env_overrides}) + async def start(self) -> None: """Eagerly spawn the persistent session (no-op in stateless mode).""" if self._mode != "persistent": @@ -231,7 +239,7 @@ async def start(self) -> None: self._session = ShellSession( self._interactive_argv, workdir=self._workdir, - env=self._env, + env=self._launch_env(), max_stdout_bytes=self._max_stdout_bytes, max_stderr_bytes=self._max_stderr_bytes, ) @@ -297,7 +305,7 @@ async def run(self, command: str, *, timeout: float | None = None) -> ShellResul self._stateless_argv, command, workdir=self._workdir, - env=self._env, + env=self._launch_env(), timeout=effective_timeout, max_stdout_bytes=self._max_stdout_bytes, max_stderr_bytes=self._max_stderr_bytes, diff --git a/python/packages/tools/tests/test_local_shell_tool.py b/python/packages/tools/tests/test_local_shell_tool.py index 19b9723add6..4a57ff914d5 100644 --- a/python/packages/tools/tests/test_local_shell_tool.py +++ b/python/packages/tools/tests/test_local_shell_tool.py @@ -551,11 +551,23 @@ def test_local_shell_tool_handles_mode_and_environment_variants(monkeypatch: pyt clean_env=True, ) - assert inherited._env is not None - assert inherited._env["INHERITED"] == "yes" - assert inherited._env["EXTRA"] == "1" - assert clean._env["ONLY"] == "2" - assert "INHERITED" not in clean._env + inherited_env = inherited._launch_env() + clean_env = clean._launch_env() + assert inherited_env["INHERITED"] == "yes" + assert inherited_env["EXTRA"] == "1" + assert clean_env["ONLY"] == "2" + assert "INHERITED" not in clean_env + + +@pytest.mark.skipif(sys.platform == "win32", reason="POSIX shell syntax") +async def test_environment_changes_after_construction_are_inherited(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("AF_LATE_VALUE", raising=False) + tool = LocalShellTool(mode="stateless", approval_mode="never_require", acknowledge_unsafe=True) + monkeypatch.setenv("AF_LATE_VALUE", "late") + + result = await tool.run('echo "$AF_LATE_VALUE"') + + assert result.stdout.strip() == "late" @pytest.mark.skipif(sys.platform == "win32", reason="POSIX PATH search") diff --git a/python/packages/tools/tests/test_shell_resolve.py b/python/packages/tools/tests/test_shell_resolve.py index 2afaac59414..4af540c622d 100644 --- a/python/packages/tools/tests/test_shell_resolve.py +++ b/python/packages/tools/tests/test_shell_resolve.py @@ -142,6 +142,24 @@ def test_resolve_shell_windows_keeps_full_paths(fake_windows_host: _FakeWindowsH assert resolve_shell(shell, interactive=True) == shell +@pytest.mark.parametrize( + ("value", "expected"), + [ + (r"C:\Tools\pwsh.exe -NoLogo", [r"C:\Tools\pwsh.exe", "-NoLogo"]), + (rf'"{_POWERSHELL_7}\pwsh.exe" -NoLogo', [rf"{_POWERSHELL_7}\pwsh.exe", "-NoLogo"]), + ], +) +def test_resolve_shell_windows_keeps_backslashes_in_string_overrides( + fake_windows_host: _FakeWindowsHost, monkeypatch: pytest.MonkeyPatch, value: str, expected: list[str] +) -> None: + fake_windows_host(_TRUSTED_BIN, set()) + monkeypatch.delenv("AGENT_FRAMEWORK_SHELL", raising=False) + + assert resolve_shell(value, interactive=True) == expected + monkeypatch.setenv("AGENT_FRAMEWORK_SHELL", value) + assert resolve_shell(None, interactive=True) == expected + + def test_find_executable_searches_only_fully_qualified_path_entries(fake_windows_host: _FakeWindowsHost) -> None: fake_windows_host( rf".;;bin;C:;C:Tools;\rooted;{_TRUSTED_BIN}",