Skip to content

Python: [BREAKING] Improve shell path validation - #10318

Merged
westey (westey-m) merged 4 commits into
microsoft:mainfrom
westey-m:python-improve-path-validation
Nov 13, 2026
Merged

westey (westey-m) merged 4 commits into
microsoft:mainfrom
westey-m:python-improve-path-validation

Conversation

@westey-m

Copy link
Copy Markdown
Collaborator

Motivation & Context

LocalShellTool and DockerShellTool accepted program names such as bash, pwsh.exe or docker for the
shell, the AGENT_FRAMEWORK_SHELL environment variable and the container runtime, and looked them up using
every PATH entry, including relative ones like . or bin. The shell's own PATH kept those entries too.
This means the program that runs, and the tools the shell then starts, can depend on the folder the app is
started from, which makes the behavior hard to predict.

This change brings the Python shell tools in line with the .NET change in #10310: programs are given or found
by full path, and the shell's PATH only contains full directory paths, so results no longer depend on the
current folder.

Description & Review Guide

  • What are the major changes?
    • shell/_resolve.py:
      • find_executable(name) searches only fully qualified PATH entries. On Windows it only finds .exe
        files; on Linux/macOS the file must be executable.
      • New require_full_path(value, *, source): rejects values that are not full paths (on Windows, also
        values without an extension).
      • resolve_shell requires a full path for an explicit shell and for AGENT_FRAMEWORK_SHELL. The
        default lookup (pwsh / powershell on Windows, bash / sh elsewhere) uses find_executable.
      • New restrict_executable_search(env): removes empty and relative PATH entries. On Windows it also
        sets NoDefaultCurrentDirectoryInExePath=1. On Linux/macOS it raises ValueError when no full
        directory path is left in PATH (or PATH is missing), because the shell would otherwise fall back
        to searching the current folder.
    • LocalShellTool: the shell environment (both clean_env modes, stateless and persistent) goes through
      restrict_executable_search.
    • DockerShellTool: docker_binary is now a required keyword argument and must be a full path.
      is_docker_available(binary) now takes the runtime path.
    • README: updated examples and the Cross-OS notes.
    • Tests: new cases for full-path validation, find_executable, restrict_executable_search, and an
      end-to-end check that commands run in the shell don't use relative PATH entries (stateless and
      persistent).
  • What is the impact of these changes?
    • Breaking (pre-release package):
      • shell= and AGENT_FRAMEWORK_SHELL must be full paths, e.g. shell="/bin/zsh" or
        shell=r"C:\Program Files\PowerShell\7\pwsh.exe".

      • DockerShellTool needs docker_binary:

        # Before
        tool = DockerShellTool(image="python:3.12-slim")
        # After
        tool = DockerShellTool(docker_binary="/usr/bin/docker", image="python:3.12-slim")
      • On Linux/macOS, LocalShellTool(clean_env=True, ...) needs an env with a PATH that contains at
        least one full directory path, e.g. env={"PATH": "/usr/bin:/bin"}.

    • Commands run by the shell no longer find programs through empty/relative PATH entries. Use ./tool
      (or .\tool) to run a program from the working folder.
    • The default shell choice is unchanged when the usual shells are installed.
  • What do you want reviewers to focus on?
    • The validation rules in _resolve.py, especially the Linux/macOS error when PATH has no full
      directory path.
    • Making docker_binary required instead of looking it up.

Related Issue

Fixes #

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: implementation, tests, documentation, and this PR description.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

Copilot AI balanced review requested due to automatic review settings November 12, 2026 19:15
@agent-framework-automation agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible labels Nov 12, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The Windows test passes a shell path through POSIX-style parsing, causing construction to raise ShellExecutionError before the re-anchoring assertion; passing a one-element argv list would preserve the path.

1 open issue
What changed in this PR

This PR hardens Python shell executable lookup to align with the .NET path-validation changes, reducing dependence on the application's working directory.

Changes:

  • Requires full paths for local shell overrides and an explicit docker_binary runtime path.
  • Removes empty and relative entries from local shell PATH, rejecting unusable POSIX configurations.
  • Updates documentation and tests for validation, runtime launches, and restricted command lookup.
File Description
python/​packages/​tools/​tests/​test_shell_resolve.py Tests full-path validation and restricted executable lookup.
python/​packages/​tools/​tests/​test_local_shell_tool.py Tests environment restrictions in both execution modes.
python/​packages/​tools/​tests/​test_docker_shell_tool.py Updates runtime arguments and tests path validation.
python/​packages/​tools/​README.md Documents breaking changes and migration examples.
python/​packages/​tools/​agent_framework_tools/​shell/​_tool.py Restricts the local shell environment before execution.
python/​packages/​tools/​agent_framework_tools/​shell/​_resolve.py Implements full-path checks and PATH filtering.
python/​packages/​tools/​agent_framework_tools/​shell/​_docker.py Requires and consistently uses the configured runtime path.

Review effort: Balanced

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (2 commit(s)): 574c89cd3fca, 19c39d96613d
Model: gpt-5.6-sol

Overview

The change consistently validates explicit executable paths, filters ordinary relative PATH entries, and adds focused unit and end-to-end coverage across local and Docker-backed shells. Three residual gaps remain: native Windows environment overrides are corrupted before validation, inherited environments are unexpectedly frozen at construction, and Linux cwd aliases bypass the lexical absolute-path filter. Each can break or undermine the newly documented path contract.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (3 medium) across 2 files. Details are attached to the affected lines below.

Affected areas: python/packages/tools/agent_framework_tools/shell/_resolve.py, python/packages/tools/agent_framework_tools/shell/_tool.py

@westey-m
westey (westey-m) added this pull request to the merge queue Nov 13, 2026
Merged via the queue into microsoft:main with commit 7a166e7 Nov 13, 2026
51 checks passed
@westey-m
westey (westey-m) deleted the python-improve-path-validation branch November 13, 2026 09:54

This branch was successfully deployed

1 active deployment
github-app-auth — 9a64a250 Deployed Nov 12, 2026 by westey-m via add_label #27753
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants