PurePath.match() incorrectly intercepts and breaks absolute shebangs #348

Activity

1. zooba commented on May 25, 2026

   

   zooba

   on May 25, 2026

   Member

   More actions

   Thanks for writing this up, it makes a lot more sense now and covers a legacy case that I wasn't aware of.

   We intentionally are treating shebangs as a compatibility for scripts written on POSIX machines, and deliberately not making py a generic executable launcher. So it should always prioritise properly installed and registered Python runtimes. Otherwise, py becomes a vector for malicious actors to launch arbitrary processes via a (hopefully) trusted executable, which we want to avoid.

   So treating any path ending in python as generic is by design, and if you want a different design then you need a tool other than the Python install manager. You can find this stated in the previous issue you linked.

   That said, when the name doesn't end in a known tag - such as _test - we shouldn't crash. Can you show the output of this crash? Failing to find a matching runtime isn't a crash, given the intended behaviour, but I think it's reasonable enough for this case to fall through to the "launch arbitrary executable" behaviour (which shows a warning and can/should be disabled).
2. mcexit commented on May 26, 2026

   

   mcexit

   on May 26, 2026

   Author

   More actions

   @zooba, thanks for taking the time to review this and for providing the context on the design goals! I completely agree that py shouldn’t be a silent vector for malicious actors, and prioritizing properly installed and registered Python runtimes makes perfect sense.

   To answer your question first, here is the exact crash output you requested. To demonstrate this, I am using an isolated environment created by uv, which drops its own unregistered executable at C:\Users\mcexit\AppData\Roaming\uv\tools\exampletool\Scripts\python.exe.

   If I rename that specific isolated executable to python_test.exe and update the script's absolute shebang to match (#!C:\Users\mcexit\AppData\Roaming\uv\tools\exampletool\Scripts\python_test.exe), here is what happens:

   > example.py --help
   [ERROR] No runtime installed that matches _test. Try running "py install _test".
   

   Because the string-slicing fallback (sh_cmd.name[6:-4]) assumes it's parsing a bare tag, it intercepts this explicit absolute path and crashes while looking for _test, which prevents it from falling through to the "launch arbitrary executable" behavior you mentioned.

   Regarding the routing logic, I want to clarify that this PR does not impact how pymanager handles registered global runtimes, nor does it aim to turn py into a generic executable launcher. It strictly addresses how pymanager handles explicit Windows absolute paths that point to local, unregistered virtual environments (like standard venvs or uv tools).

   Right now, because PurePath.match() evaluates from the right side of the string, an absolute path like #!C:\Users\mcexit\AppData\Roaming\uv\tools\exampletool\Scripts\python.exe evaluates to True when matching against the alias "python.exe". pymanager then intercepts the explicit path, discards the directory routing, and hijacks execution to the global Python environment (causing ModuleNotFoundErrors for isolated scripts).

   An interesting side effect of this alias-matching is that the current logic actually allows arbitrary executables to run safely through the fallback, while intercepting legitimate absolute paths to local Python environments. For example, if I rename that same python.exe executable to malware.exe and update the absolute shebang (#!C:\Users\mcexit\AppData\Roaming\uv\tools\exampletool\Scripts\malware.exe), it bypasses the PurePath.match() alias checks, correctly delegates to _find_on_path(), and executes with your intended warnings:

   > example.py --help
   [WARNING] A shebang 'C:\Users\mcexit\AppData\Roaming\uv\tools\exampletool\Scripts\malware.exe' was found but does not match any supported template (e.g. '/usr/bin/python'), so it will be treated as an arbitrary command.
   [WARNING] To prevent execution of programs that are not Python runtimes, set 'shebang_can_run_anything' to 'false' in your configuration file.
   Usage: example.py [input file list] [options]
   ...
   

   So currently, an unrecognized executable correctly falls through to your intended security warning block (governed by shebang_can_run_anything), but a perfectly valid absolute path to a local, isolated python.exe gets hijacked or crashes.

   This PR simply adds an is_name_only check so that alias extraction and wildcard string-slicing only apply to bare names like python3.14.exe or /usr/bin/env python. Explicit absolute paths containing directory separators will safely bypass the alias check, raise LookupError, and cleanly fall through to the native fallback logic (_parse_shebang), where they are properly subjected to your existing security checks before execution.

   Finally, regarding using another tool: since the Python 3.14 docs officially state that the legacy Python Launcher (py.exe) is deprecated and superseded by Python Install Manager (pymanager), users won't have another supported tool to fall back on for running standard venv and uv scripts natively on Windows. Merging this ensures pymanager correctly supports absolute paths to local environments while fully preserving your POSIX alias resolution and security goals.

   Let me know what you think! I'm happy to adjust the PR if you have a different approach in mind.
3. zooba commented on May 26, 2026

   

   zooba

   on May 26, 2026

   Member

   More actions

   a perfectly valid absolute path to a local, isolated python.exe

   This is the part that's outside of the design - shebangs are for selecting a registered interpreter, not an isolated one, no matter how valid the path is. The fallback to launch arbitrary paths is entirely to satisfy people transitioning (hence the warning and kill switch), and wasn't supported in the initial design at all.

   Basically, we don't want to launch any path that wasn't previously provided by the machine owner/user. That does argue for "compare the full path against all registered runtimes and allow it if it matches one", which we don't currently do (and perhaps we should), but it doesn't argue for bypassing the registrations (and then we get the same argument about /usr/bin/python potentially being a valid path on Windows, so we "shouldn't" interpret it as a template instead, and so we currently draw the line at "templates first, optional fallback if the template fails").

   So things I think we can do:

   • if the name matched python*.exe but the captured tag can't be found, fall back to treating it as a regular path (so fix the _test bug). Obviously if there is no tag, the default runtime will be chosen unconditionally, so this doesn't affect the "full path to python.exe" case
   • add a new config section as described in shebang backwards compatibility #307 that can map a shebang template (the argv[0]) to either a -V: option or a full executable path, where the latter is subject to shebang_can_run_anything and prints the same warning
   • treat all alias and executable paths as templates for properly installed runtimes (at highest priority, but then launches as if given the -V tag)

   Once that's done, if you want a shebang to launch an arbitrary runtime, then you can put the path into your config against itself and allow arbitrary paths and it'll run. If you want to avoid the warning, follow PEP 514 to register it properly (or activate the venv, and then it's automatically detected as the default runtime - launching unactivated venvs isn't supported, though it usually works).
4. zooba

   self-assigned this

   on Jun 2, 2026
5. zooba

   closed this as completedin 080ed44on Jun 4, 2026
6. StanFromIreland

   added a commit that references this issue on Jul 8, 2026

   Adds shebang_templates configuration for overriding shebangs. (python…

   ...

   This issue will close once commit 080ed44 is merged into the 'main' branch.

   080ed44