Skip to content

Commit d721ff1

Browse files
🐛 fix(activation): escape batch quote() against injection (#3250)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 087a2ef commit d721ff1

6 files changed

Lines changed: 234 additions & 32 deletions

File tree

‎docs/changelog/3250.bugfix.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Fix ``activate.bat`` running arbitrary commands from a crafted ``--prompt``, ``VIRTUALENV_PROMPT``, or config file
2+
value.

‎src/virtualenv/activation/batch/__init__.py‎

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,47 @@
11
from __future__ import annotations
22

3+
import logging
34
import os
4-
from typing import TYPE_CHECKING
5+
from typing import TYPE_CHECKING, Final
56

67
from virtualenv.activation.via_template import ViaTemplateActivator
8+
from virtualenv.util.text import collapse_line_boundaries
79

810
if TYPE_CHECKING:
911
from collections.abc import Iterator
12+
from pathlib import Path
1013

1114
from python_discovery import PythonInfo
1215

1316
from virtualenv.create.creator import Creator
1417

18+
LOGGER = logging.getLogger(__name__)
19+
20+
# cmd.exe's own command-line parser looks for these regardless of surrounding quotes: confirmed on a
21+
# real Windows runner that `@set "VAR=x & cmd"` still runs `cmd` as a second statement even though the
22+
# whole VAR=value expression is quoted. `(` and `)` are not in this set - confirmed on the same runner
23+
# that `@set "VAR=C:\Program Files (x86)\..."` round-trips unchanged, since parentheses are only special
24+
# to cmd.exe as block delimiters in control-flow syntax (if/for), not as bare characters in a value. `!`
25+
# is only live when the caller already has delayed expansion enabled (`setlocal enabledelayedexpansion`,
26+
# `cmd /V:ON`) - not cmd.exe's default, but confirmed on a real runner that a prompt like `foo!SECRET!`
27+
# then substitutes the actual value of an existing SECRET variable into the prompt, so it is neutered
28+
# unconditionally rather than only when that mode happens to be on.
29+
_CMD_OPERATORS: Final[tuple[str, ...]] = ("&", "|", "<", ">", "^", "!", '"')
30+
31+
# Of _CMD_OPERATORS, only `&` can actually occur in a real Windows path: `|`, `<`, `>` and `"` are
32+
# already illegal in Windows filenames, and a literal `^` is silently dropped by cmd.exe itself even
33+
# with no help from quote(), confirmed on a real Windows runner - never exploitable, just a value that
34+
# reads one character short. `&` is different: quote() can neuter it in free text like the prompt, but
35+
# doing that to a path would silently point activate.bat at a directory that does not exist. There is no
36+
# way to represent it here and no way to fake the path, so refuse instead.
37+
_PATH_UNSAFE_CHARS: Final[tuple[str, ...]] = ("&",)
38+
39+
_PATH_REPLACEMENT_NAMES: Final[dict[str, str]] = {
40+
"__VIRTUAL_ENV__": "the destination directory",
41+
"__TCL_LIBRARY__": "the interpreter's Tcl library path",
42+
"__TK_LIBRARY__": "the interpreter's Tk library path",
43+
}
44+
1545

1646
class BatchActivator(ViaTemplateActivator):
1747
@classmethod
@@ -23,16 +53,47 @@ def templates(self) -> Iterator[str]:
2353
yield "deactivate.bat"
2454
yield "pydoc.bat"
2555

56+
def generate(self, creator: Creator) -> list[Path]:
57+
values = super().replacements(creator, creator.bin_dir)
58+
problems = [reason for key in _PATH_REPLACEMENT_NAMES if (reason := _unsafe_path_reason(key, values[key]))]
59+
if problems:
60+
for problem in problems:
61+
LOGGER.warning("skipping batch activation scripts: %s", problem)
62+
return []
63+
return super().generate(creator)
64+
2665
@staticmethod
2766
def quote(string: str) -> str:
28-
return string
67+
"""Make a value safe to sit inside ``@set "VAR=value"``.
68+
69+
Batch has no escape for a double quote in this context either: it always closes the quoted string, and whatever
70+
follows on the line runs as live cmd.exe syntax. A raw line boundary is worse - batch is line-oriented
71+
regardless of quote state, so it starts a brand-new statement instead of staying inside the value. None of these
72+
can be represented literally here, so replace them with a space. ``%`` still triggers variable expansion inside
73+
the quotes, but doubling it to ``%%`` is a real, in-file escape that keeps the literal character.
74+
75+
"""
76+
string = string.replace("%", "%%")
77+
for operator in _CMD_OPERATORS:
78+
string = string.replace(operator, " ")
79+
return collapse_line_boundaries(string)
2980

3081
def instantiate_template(self, replacements: dict[str, str], template: str, creator: Creator) -> str:
3182
# ensure the text has all newlines as \r\n - required by batch
3283
base = super().instantiate_template(replacements, template, creator)
3384
return base.replace(os.linesep, "\n").replace("\n", os.linesep)
3485

3586

87+
def _unsafe_path_reason(key: str, value: str) -> str | None:
88+
found = sorted({char for char in value if char in _PATH_UNSAFE_CHARS})
89+
if not found:
90+
return None
91+
return (
92+
f"{_PATH_REPLACEMENT_NAMES[key]} ({value!r}) contains {''.join(found)!r}, and cmd.exe has no way "
93+
f'to keep that literal inside the @set "VAR=value" lines activate.bat relies on'
94+
)
95+
96+
3697
__all__ = [
3798
"BatchActivator",
3899
]

‎src/virtualenv/create/pyenv_cfg.py‎

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,29 +3,15 @@
33
import logging
44
import os
55
from collections import OrderedDict
6-
from typing import TYPE_CHECKING, Final
6+
from typing import TYPE_CHECKING
7+
8+
from virtualenv.util.text import collapse_line_boundaries
79

810
if TYPE_CHECKING:
911
from pathlib import Path
1012

1113
LOGGER = logging.getLogger(__name__)
1214

13-
# pyvenv.cfg is a line-based format with no escape syntax, so a value carrying any character that
14-
# str.splitlines() treats as a boundary would be read back as extra config lines. These are exactly
15-
# the boundaries splitlines() recognizes, per the Python string documentation.
16-
_LINE_BOUNDARIES: Final[tuple[str, ...]] = (
17-
"\n",
18-
"\r",
19-
"\v",
20-
"\f",
21-
"\x1c",
22-
"\x1d",
23-
"\x1e",
24-
"\x85",
25-
chr(0x2028), # line separator
26-
chr(0x2029), # paragraph separator
27-
)
28-
2915

3016
class PyEnvCfg:
3117
def __init__(self, content: OrderedDict[str, str], path: Path) -> None:
@@ -64,7 +50,7 @@ def write(self) -> None:
6450
normalized_value = f'"{value}"'
6551
else:
6652
normalized_value = os.path.abspath(value) if value and os.path.exists(value) else value
67-
line = f"{_one_line(key)} = {_one_line(normalized_value)}"
53+
line = f"{collapse_line_boundaries(key)} = {collapse_line_boundaries(normalized_value)}"
6854
LOGGER.debug("\t%s", line)
6955
text += line
7056
text += "\n"
@@ -91,13 +77,6 @@ def __repr__(self) -> str:
9177
return f"{self.__class__.__name__}(path={self.path})"
9278

9379

94-
def _one_line(text: str) -> str:
95-
"""Collapse line boundaries so a value can never be read back as extra config lines."""
96-
for boundary in _LINE_BOUNDARIES:
97-
text = text.replace(boundary, " ")
98-
return text
99-
100-
10180
__all__ = [
10281
"PyEnvCfg",
10382
]

‎src/virtualenv/util/text.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
"""Shared text-safety helpers for values written into line-based formats."""
2+
3+
from __future__ import annotations
4+
5+
from typing import Final
6+
7+
# A line-based format with no escape syntax reads any character str.splitlines() treats as a
8+
# boundary back as an extra line - or, for a script, runs it as one. This is the exact boundary
9+
# set splitlines() recognizes, per the Python string documentation.
10+
_LINE_BOUNDARIES: Final[tuple[str, ...]] = (
11+
"\n",
12+
"\r",
13+
"\v",
14+
"\f",
15+
"\x1c",
16+
"\x1d",
17+
"\x1e",
18+
"\x85",
19+
chr(0x2028), # line separator
20+
chr(0x2029), # paragraph separator
21+
)
22+
23+
24+
def collapse_line_boundaries(text: str) -> str:
25+
"""Replace every line-boundary character with a space so text can never become extra lines."""
26+
for boundary in _LINE_BOUNDARIES:
27+
text = text.replace(boundary, " ")
28+
return text
29+
30+
31+
__all__ = [
32+
"collapse_line_boundaries",
33+
]

‎tests/property/test_batch_quote.py‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
r"""Property tests for BatchActivator.quote().
2+
3+
``@set "VAR=value"`` is the only place a value from ``--prompt`` (or any other replacement) reaches cmd.exe, and cmd.exe
4+
treats several characters as live syntax there regardless of the surrounding quotes - confirmed on a real Windows runner
5+
while fixing the ``activate.bat`` injection this closes. The invariant that matters is that none of those characters can
6+
survive ``quote()``.
7+
8+
``(`` and ``)`` are deliberately not in that set: also confirmed on a real Windows runner, they round-trip unchanged
9+
through the same construct, since cmd.exe only treats them as special when they delimit a control-flow block (``if``,
10+
``for``), not as bare characters in a value. Neutering them anyway would corrupt a destination path under the extremely
11+
common ``C:\Program Files (x86)\...``.
12+
13+
"""
14+
15+
from __future__ import annotations
16+
17+
import pytest
18+
from hypothesis import example, given
19+
from hypothesis import strategies as st
20+
21+
from virtualenv.activation.batch import BatchActivator
22+
23+
pytestmark = pytest.mark.property
24+
25+
# Confirmed live syntax inside @set "VAR=value" on a real Windows runner, independently of this fix's
26+
# own implementation - this is not just re-asserting quote()'s source. `!` only turns live when the
27+
# caller already has delayed expansion enabled, but a crafted prompt then leaks the value of whatever
28+
# variable it names, confirmed the same way.
29+
DANGEROUS = '"&|<>^!'
30+
SAFE_IN_THIS_CONTEXT = "()"
31+
LINE_BOUNDARIES = "\n\r\v\f\x1c\x1d\x1e\x85" + chr(0x2028) + chr(0x2029)
32+
33+
# Lone surrogates are excluded: cmd.exe scripts are read as text, and the same limit applies to the
34+
# pyvenv.cfg property tests for the same reason.
35+
values = st.text(st.characters(blacklist_categories=("Cs",), max_codepoint=0x2100))
36+
37+
38+
@given(value=values)
39+
@example('x" & type nul > pwned.marker & "') # the confirmed exploit payload
40+
@example("x^& type nul ^> pwned.marker ^& ") # caret-escaped: still live outside a quoted context
41+
@example("x\n@type nul > pwned.marker\n@rem ") # newline: a full extra statement, not just a breakout
42+
@example('a"&type nul>pwned.marker&"b')
43+
@example("foo!SECRET!bar") # delayed-expansion variable substitution, confirmed under cmd /V:ON
44+
def test_quote_strips_every_dangerous_character(value: str) -> None:
45+
quoted = BatchActivator.quote(value)
46+
47+
assert not (set(quoted) & set(DANGEROUS))
48+
assert not (set(quoted) & set(LINE_BOUNDARIES))
49+
50+
51+
@given(value=st.text(st.sampled_from(SAFE_IN_THIS_CONTEXT), min_size=1))
52+
@example("(x86)") # the shape that shows up in every 32-bit "Program Files (x86)" install
53+
def test_quote_leaves_parentheses_untouched(value: str) -> None:
54+
assert BatchActivator.quote(value) == value
55+
56+
57+
@given(value=values)
58+
def test_quote_keeps_percent_literal_and_balanced(value: str) -> None:
59+
"""Every ``%`` must survive doubled, never as a lone character that triggers expansion."""
60+
quoted = BatchActivator.quote(value)
61+
62+
assert quoted.replace("%%", "").count("%") == 0
63+
64+
65+
@given(value=values)
66+
@example('x" & type nul > pwned.marker & "')
67+
def test_embedding_in_the_set_statement_stays_one_well_formed_line(value: str) -> None:
68+
"""The exact shape the template uses: a single ``@set "VAR=value"`` statement."""
69+
rendered = f'@set "VIRTUAL_ENV_PROMPT={BatchActivator.quote(value)}"'
70+
71+
assert rendered.count("\n") == 0
72+
assert rendered.count('"') == 2

‎tests/unit/activation/test_batch.py‎

Lines changed: 60 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,31 @@
11
from __future__ import annotations
22

3+
import sys
34
from argparse import Namespace
45

56
import pytest
67

78
from virtualenv.activation import BatchActivator
9+
from virtualenv.info import IS_WIN
10+
11+
12+
@pytest.fixture(scope="session")
13+
def special_char_name():
14+
"""The shared tests/conftest.py fixture, minus &: cmd.exe cannot represent that one at all."""
15+
base = "'\";e-$ èрт🚒♞中片-j"
16+
if IS_WIN:
17+
base = base.replace('"', "").replace(";", "")
18+
encoding = "ascii" if IS_WIN else sys.getfilesystemencoding()
19+
result = ""
20+
for char in base:
21+
try:
22+
trip = char.encode(encoding, errors="strict").decode(encoding)
23+
if char == trip:
24+
result += char
25+
except ValueError: # ruff:ignore[try-except-in-loop]
26+
continue
27+
assert result
28+
return result
829

930

1031
def test_batch_pydoc_bat_quoting(tmp_path) -> None:
@@ -91,9 +112,38 @@ def __init__(self, dest) -> None:
91112
assert '@if NOT ""=="" @set "TK_LIBRARY="' in activate_content
92113

93114

94-
@pytest.mark.usefixtures("activation_python")
115+
def test_batch_skips_destination_with_ampersand(tmp_path, caplog) -> None:
116+
"""An `&` in the destination can never be represented, so generation must skip it, not guess."""
117+
118+
class MockInterpreter:
119+
os = "nt"
120+
tcl_lib = None
121+
tk_lib = None
122+
123+
class MockCreator:
124+
def __init__(self, dest) -> None:
125+
self.dest = dest
126+
self.bin_dir = dest / "Scripts"
127+
self.bin_dir.mkdir(parents=True)
128+
self.interpreter = MockInterpreter()
129+
self.pyenv_cfg = {}
130+
self.env_name = "test-env"
131+
132+
creator = MockCreator(tmp_path / "weird&dest")
133+
activator = BatchActivator(Namespace(prompt=None))
134+
135+
generated = activator.generate(creator)
136+
137+
assert generated == []
138+
assert list(creator.bin_dir.iterdir()) == []
139+
assert "skipping batch activation scripts" in caplog.text
140+
assert "&" in caplog.text
141+
142+
95143
@pytest.mark.parametrize("activations", [1, 2], ids=["activate_once", "activate_twice"])
96-
def test_batch(activation_tester_class, activation_tester, tmp_path, activations) -> None:
144+
def test_batch(activation_python, activation_tester_class, activation_tester, tmp_path, activations) -> None:
145+
if not (activation_python.creator.bin_dir / "activate.bat").exists():
146+
pytest.skip("cmd.exe cannot represent this destination, batch activation was skipped on purpose")
97147
version_script = tmp_path / "version.bat"
98148
version_script.write_text("ver", encoding="utf-8")
99149

@@ -126,8 +176,9 @@ def print_prompt(self) -> str:
126176
activation_tester(Batch)
127177

128178

129-
@pytest.mark.usefixtures("activation_python")
130-
def test_batch_output(activation_tester_class, activation_tester, tmp_path) -> None:
179+
def test_batch_output(activation_python, activation_tester_class, activation_tester, tmp_path) -> None:
180+
if not (activation_python.creator.bin_dir / "activate.bat").exists():
181+
pytest.skip("cmd.exe cannot represent this destination, batch activation was skipped on purpose")
131182
version_script = tmp_path / "version.bat"
132183
version_script.write_text("ver", encoding="utf-8")
133184

@@ -142,7 +193,11 @@ def __init__(self, session) -> None:
142193
self.unix_line_ending = False
143194

144195
def _get_test_lines(self, activate_script):
145-
"""Build intermediary script which will be then called. In the script just activate environment, call echo to get current echo setting, and then deactivate. This ensures that echo setting is preserved and no unwanted output appears."""
196+
"""Build an intermediary script that activates, echoes the current echo setting, then deactivates.
197+
198+
This is what proves echo state survives activation and deactivation without leaking unwanted output.
199+
200+
"""
146201
intermediary_script_path = str(tmp_path / "intermediary.bat")
147202
activate_script_quoted = self.quote(str(activate_script))
148203
return [

0 commit comments

Comments
 (0)