code_execution_env.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. """Child-process environment for execute_code: env scrubbing, interpreter and cwd resolution.
  2. Both the per-call remote path and the local session kernel build their child
  3. env through ``_build_child_env`` so the security rules (secret scrubbing,
  4. PYTHONPATH hygiene, UTF-8 forcing, TZ) cannot drift between them.
  5. """
  6. import logging
  7. import os
  8. import platform
  9. import subprocess
  10. import sys
  11. from typing import Dict
  12. # Logger name kept as the origin module's so existing log expectations hold.
  13. logger = logging.getLogger("tools.code_execution_tool")
  14. _IS_WINDOWS = platform.system() == "Windows"
  15. # Scrub order: secret-substring block first; whatever is left must match a safe
  16. # prefix, the exact-name HERMES_ allowlist, or (Windows) an OS-essential name.
  17. # The broad "HERMES_" prefix is deliberately NOT safe — it leaked config vars
  18. # without a secret substring (HERMES_BASE_URL, HERMES_KANBAN_DB, *_WEBHOOK).
  19. # HERMES_RPC_SOCKET / HERMES_RPC_DIR / TZ / HOME are injected after scrubbing.
  20. _SAFE_ENV_PREFIXES = ("PATH", "HOME", "USER", "LANG", "LC_", "TERM", "TMPDIR", "TMP", "TEMP", "SHELL",
  21. "LOGNAME", "XDG_", "PYTHONPATH", "VIRTUAL_ENV", "CONDA")
  22. # "PASS" is intentionally absent: it false-positives on BYPASS_CACHE /
  23. # COMPASS_DIR / PASSENGER_HOST while PASSWORD/PASSWD already cover credentials.
  24. _SECRET_SUBSTRINGS = ("KEY", "TOKEN", "SECRET", "PASSWORD", "CREDENTIAL", "PASSWD", "AUTH", "DSN",
  25. "WEBHOOK", "CREDS", "BEARER", "APIKEY", "COOKIE")
  26. def is_secret_env_name(name: str) -> bool:
  27. """The credential-name policy, shared with a local session's client environment (``agent.session_client_env``)."""
  28. return any(s in name.upper() for s in _SECRET_SUBSTRINGS)
  29. # Non-secret runtime-location flags that repo-root modules a sandbox script
  30. # imports may read at import time. HERMES_DELEGATED_CHILD_CONTEXT must ride
  31. # along or a child that imports Hermes code loses the Kanban mutation guard
  32. # while still inheriting HERMES_HOME.
  33. _HERMES_CHILD_ALLOWED = frozenset({
  34. "HERMES_HOME", "HERMES_PROFILE", "HERMES_CONFIG", "HERMES_ENV", "HERMES_DELEGATED_CHILD_CONTEXT",
  35. })
  36. # Windows-only: without these the CRT itself fails — socket.socket() raises
  37. # WinError 10106 (Winsock can't find mswsock.dll) and subprocess can't resolve
  38. # cmd.exe. Well-known OS paths, not secrets; the substring block still runs.
  39. _WINDOWS_ESSENTIAL_ENV_VARS = frozenset({
  40. "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT", "OS",
  41. "PROCESSOR_ARCHITECTURE", "NUMBER_OF_PROCESSORS", "PUBLIC", "ALLUSERSPROFILE",
  42. "PROGRAMDATA", "PROGRAMFILES", "PROGRAMFILES(X86)", "PROGRAMW6432",
  43. "APPDATA", "LOCALAPPDATA", "USERPROFILE", "USERDOMAIN", "USERNAME",
  44. "HOMEDRIVE", "HOMEPATH", "COMPUTERNAME",
  45. })
  46. def _scrub_child_env(source_env, is_passthrough=None, is_windows=None, toolchain=frozenset()):
  47. """Produce the scrubbed child-process env for execute_code.
  48. Rules, in order: (1) passthrough vars (skill/config-declared) resolve
  49. through the active profile secret scope — an absent scoped value is
  50. omitted; (2) secret-substring names are blocked; (3) safe prefixes pass,
  51. as do a local session's client ``toolchain`` names (NVM_DIR, GOPATH...);
  52. (4) operational HERMES_* pass by exact name; (5) on Windows the
  53. OS-essential allowlist passes by exact name.
  54. """
  55. try:
  56. from tools.env_passthrough import is_env_passthrough, resolve_passthrough_value, scoped_passthrough_additions
  57. except Exception:
  58. is_env_passthrough = lambda _: False
  59. resolve_passthrough_value = lambda _name, _fallback: None
  60. scoped_passthrough_additions = lambda _present: {}
  61. if is_passthrough is None:
  62. is_passthrough = is_env_passthrough
  63. if is_windows is None:
  64. is_windows = _IS_WINDOWS
  65. scrubbed = {}
  66. # Non-secret HERMES_* vars no allowlist admits are dropped on purpose; a script importing a
  67. # repo module that reads one would see it silently unset — log the drop, point at the opt-in.
  68. _dropped_hermes = []
  69. for k, v in source_env.items():
  70. if is_passthrough(k):
  71. resolved = resolve_passthrough_value(k, v)
  72. if resolved is not None:
  73. scrubbed[k] = resolved
  74. continue
  75. if is_secret_env_name(k):
  76. continue
  77. if (any(k.startswith(p) for p in _SAFE_ENV_PREFIXES) or k in toolchain
  78. or k in _HERMES_CHILD_ALLOWED
  79. or (is_windows and k.upper() in _WINDOWS_ESSENTIAL_ENV_VARS)):
  80. scrubbed[k] = v
  81. elif k.startswith("HERMES_"):
  82. _dropped_hermes.append(k)
  83. # Declared names only the bound profile scope holds (a routed profile's own .env / sources
  84. # never enter the process env) — the loop above sees only names ``source_env`` carries.
  85. scrubbed.update((k, v) for k, v in scoped_passthrough_additions(scrubbed).items() if is_passthrough(k))
  86. if _dropped_hermes:
  87. logger.debug(
  88. "execute_code: dropped %d non-allowlisted HERMES_* var(s) from the "
  89. "sandbox child env (%s). This is intentional hardening (#27303); if "
  90. "a sandbox script legitimately needs one, declare it via "
  91. "env_passthrough in the skill/config so it passes by explicit opt-in.",
  92. len(_dropped_hermes), ", ".join(sorted(_dropped_hermes)),
  93. )
  94. # delegate_task children are marked by a ContextVar, not os.environ, and the sandbox crosses
  95. # a process boundary: strip dispatcher-owned Kanban vars AFTER the scrub so an explicit
  96. # passthrough cannot re-grant a delegated child the parent's board mutation capability.
  97. from agent.delegation_context import (
  98. DELEGATED_CHILD_ENV_MARKER, delegated_child_subprocess_env,
  99. )
  100. scoped = delegated_child_subprocess_env(source_env)
  101. # Preserve location only when carrying the descendant fence, not for arbitrary
  102. # non-allowlisted HERMES_* values in otherwise ordinary execution environments.
  103. if scoped.get(DELEGATED_CHILD_ENV_MARKER):
  104. for key in (DELEGATED_CHILD_ENV_MARKER, "HERMES_KANBAN_DB", "HERMES_KANBAN_BOARD"):
  105. if key in scoped:
  106. scrubbed[key] = scoped[key]
  107. return delegated_child_subprocess_env(scrubbed)
  108. def _build_child_env(*, rpc_endpoint: str, rpc_token: str, tmpdir: str,
  109. child_python: str) -> dict[str, str]:
  110. """Build the scrubbed child environment both execution paths share."""
  111. from hermes_constants import apply_scratch_tmp_env, apply_subprocess_home_env, get_hermes_home_override
  112. from agent.session_client_env import tool_env, toolchain_environ
  113. # A local session's client toolchain replaces the daemon's PATH / venv, then the whole scrub (secret
  114. # names, delegated-child restrictions) runs over the merged environment.
  115. child_env = _scrub_child_env(toolchain_environ(), toolchain=frozenset(tool_env()))
  116. child_env["HERMES_RPC_SOCKET"] = rpc_endpoint
  117. child_env["HERMES_RPC_TOKEN"] = rpc_token
  118. child_env["PYTHONDONTWRITEBYTECODE"] = "1"
  119. # Force UTF-8 stdio and default file encoding: on Windows sys.stdout is bound to the console
  120. # code page (cp1252) and print("→") raises; harmless under a C/POSIX locale (containers).
  121. child_env["PYTHONIOENCODING"] = "utf-8"
  122. child_env["PYTHONUTF8"] = "1"
  123. # Only TZ reaches the child; HERMES_TIMEZONE is an internal setting (and under the multiplexed
  124. # gateway holds only the default profile's value — hermes_time resolves the routed profile's).
  125. from hermes_time import get_timezone_name
  126. _tz_name = get_timezone_name()
  127. # Windows CPython does not support IANA names in TZ. Leaving TZ unset
  128. # preserves the OS-configured local timezone for the child process.
  129. if _tz_name and not _IS_WINDOWS:
  130. child_env["TZ"] = _tz_name
  131. child_env.pop("HERMES_TIMEZONE", None)
  132. apply_subprocess_home_env(child_env)
  133. # Multiplexed gateway/Desktop (#110303): the server process env carries the machine-default
  134. # HERMES_HOME, but this turn runs under a per-profile override (ContextVar bound per turn).
  135. # The scrub above passed the stale default through; rewrite it so skill scripts see the
  136. # active profile's home — the same per-turn rewrite apply_subprocess_home_env does for HOME.
  137. # No override (dedicated per-profile process) → leave the inherited value untouched.
  138. _home_override = get_hermes_home_override()
  139. if _home_override:
  140. child_env["HERMES_HOME"] = _home_override
  141. apply_scratch_tmp_env(child_env) # TMPDIR follows the routed home, like HOME does
  142. # PYTHONPATH: the staging dir (hermes_tools.py) must always be importable even when project
  143. # mode changes CWD. Hermes's root is added ONLY when the child runs in Hermes's Python env —
  144. # exposing Hermes's site-packages to an external interpreter can mix incompatible compiled
  145. # extensions (3.12 NumPy under a 3.9 venv). Inherited Hermes-owned entries are stripped first.
  146. # Before re-injecting PYTHONPATH, strip Hermes-owned entries that leaked through _scrub_child_env
  147. # (PYTHONPATH is in _SAFE_ENV_PREFIXES so it passes the scrub). External project interpreters
  148. # must not inherit Hermes dependencies (#74817). PM's own interpreter, however, can be a
  149. # bare bundled Python whose dependencies live in the selected generation, not sys.prefix.
  150. from tools.environments.local_pythonpath import (
  151. _strip_hermes_owned_pythonpath, _validated_runtime_venv, _same_path,
  152. )
  153. _runtime_path = None
  154. if child_python == sys.executable:
  155. runtime_venv = _validated_runtime_venv(child_env)
  156. if runtime_venv is not None:
  157. from pathlib import Path
  158. from pm.environments import site_packages
  159. candidate = site_packages(runtime_venv)
  160. # Restore only a dependency path the launcher actually supplied, not a newly
  161. # selected generation that this still-running interpreter has never loaded.
  162. if any(_same_path(Path(entry), candidate)
  163. for entry in child_env.get("PYTHONPATH", "").split(os.pathsep) if entry):
  164. _runtime_path = str(candidate)
  165. _strip_hermes_owned_pythonpath(child_env)
  166. _existing_pp = child_env.get("PYTHONPATH", "")
  167. _pp_parts = [tmpdir]
  168. if _runtime_path is not None:
  169. _pp_parts.append(_runtime_path)
  170. if _uses_hermes_python_environment(child_python):
  171. _pp_parts.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
  172. elif child_python not in _external_env_logged:
  173. # Surface once per interpreter so "import hermes_constants fails" is diagnosable.
  174. _external_env_logged.add(child_python)
  175. logger.info("execute_code: child interpreter %s is outside the Hermes "
  176. "environment; hermes root omitted from PYTHONPATH", child_python)
  177. if _existing_pp:
  178. _pp_parts.append(_existing_pp)
  179. child_env["PYTHONPATH"] = os.pathsep.join(_pp_parts)
  180. return child_env
  181. # Interpreter-probe caches: success-only dicts (FIFO-evicted at the cap) rather than lru_cache —
  182. # a transient probe failure (fork pressure, 5s timeout) must not stick for the process lifetime.
  183. _PROBE_CACHE_MAX = 32
  184. _usable_python_cache: dict = {}
  185. _python_prefix_cache: dict = {}
  186. # Interpreter paths already reported as outside the Hermes environment.
  187. _external_env_logged: set = set()
  188. def _cache_probe_result(cache: dict, key: str, value):
  189. """Insert into a bounded probe cache, FIFO-evicting at the cap."""
  190. if len(cache) >= _PROBE_CACHE_MAX:
  191. cache.pop(next(iter(cache)))
  192. cache[key] = value
  193. def _probe_python(python_path: str, code: str, *, text: bool = False):
  194. """Run ``python_path -c code``; None if missing, unspawnable, or past the 5s timeout."""
  195. try:
  196. from agent.delegation_context import delegated_child_subprocess_env
  197. return subprocess.run(
  198. [python_path, "-c", code], timeout=5, capture_output=True, text=text,
  199. creationflags=subprocess.CREATE_NO_WINDOW if _IS_WINDOWS else 0,
  200. stdin=subprocess.DEVNULL, env=delegated_child_subprocess_env(),
  201. check=False,
  202. )
  203. except (OSError, subprocess.TimeoutExpired, subprocess.SubprocessError):
  204. return None
  205. def _is_usable_python(python_path: str) -> bool:
  206. """Whether the interpreter is Python 3.8+ (what the RPC stubs need); success cached, failure retried."""
  207. cached = _usable_python_cache.get(python_path)
  208. if cached is not None:
  209. return cached
  210. result = _probe_python(python_path, "import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)")
  211. if result is None:
  212. return False
  213. usable = result.returncode == 0
  214. _cache_probe_result(_usable_python_cache, python_path, usable)
  215. return usable
  216. def _python_environment_prefix(python_path: str) -> str:
  217. """Resolved ``sys.prefix`` reported by *python_path* ("" on failure; failures are not cached)."""
  218. cached = _python_prefix_cache.get(python_path)
  219. if cached is not None:
  220. return cached
  221. result = _probe_python(python_path, "import sys; print(sys.prefix)", text=True)
  222. if result is not None and result.returncode == 0 and result.stdout.strip():
  223. prefix = os.path.realpath(result.stdout.strip())
  224. _cache_probe_result(_python_prefix_cache, python_path, prefix)
  225. return prefix
  226. return ""
  227. def _uses_hermes_python_environment(python_path: str) -> bool:
  228. """Whether *python_path* belongs to Hermes's active Python environment. Short-circuits when
  229. it IS the running interpreter (by path or realpath — covers ``uv run`` venvs) so no probe
  230. runs on the default strict path and a flaky probe can never drop the hermes root."""
  231. if python_path == sys.executable or os.path.realpath(python_path) == os.path.realpath(sys.executable):
  232. return True
  233. return _python_environment_prefix(python_path) == os.path.realpath(sys.prefix)
  234. def _resolve_child_python(mode: str) -> str:
  235. """Child interpreter: ``sys.executable`` in strict mode; in project mode the active
  236. VIRTUAL_ENV/CONDA_PREFIX python if it exists and passes the 3.8+ probe, else ``sys.executable``."""
  237. if mode != "project":
  238. return sys.executable
  239. from agent.session_client_env import toolchain_environ
  240. environ = toolchain_environ() # a local session's: its client's venv/conda, not the daemon's
  241. subdir, exe_names = ("Scripts", ("python.exe", "python3.exe")) if _IS_WINDOWS else ("bin", ("python", "python3"))
  242. for var in ("VIRTUAL_ENV", "CONDA_PREFIX"):
  243. root = environ.get(var, "").strip()
  244. for exe in exe_names if root else ():
  245. candidate = os.path.join(root, subdir, exe)
  246. if not (os.path.isfile(candidate) and os.access(candidate, os.X_OK)):
  247. continue
  248. if _is_usable_python(candidate):
  249. return candidate
  250. logger.info("execute_code: skipping %s=%s (Python version < 3.8 or broken). "
  251. "Using sys.executable instead.", var, candidate)
  252. return sys.executable
  253. return sys.executable
  254. def _resolve_child_cwd(mode: str, staging_dir: str, task_id: str = "") -> str:
  255. """Child cwd. Strict: the staging dir. Project mirrors the terminal/file-tool ladder so every
  256. file-writing path agrees: session cwd record (`cd` state) → registered ``session.cwd.set``
  257. override → TERMINAL_CWD → os.getcwd() → staging dir (never Popen on a missing cwd).
  258. (#56047)
  259. """
  260. if mode != "project":
  261. return staging_dir
  262. if task_id:
  263. try:
  264. from tools.terminal_tool import get_session_cwd
  265. recorded = get_session_cwd(task_id)
  266. except Exception:
  267. recorded = None
  268. if recorded and os.path.isdir(recorded):
  269. return recorded
  270. try:
  271. from tools.file_tools_paths import _registered_task_cwd_override
  272. session_cwd = _registered_task_cwd_override(task_id)
  273. except Exception:
  274. session_cwd = None
  275. if session_cwd and os.path.isdir(session_cwd):
  276. return session_cwd
  277. from agent.runtime_cwd import scope_terminal_cwd
  278. raw = scope_terminal_cwd().strip()
  279. for candidate in (os.path.expanduser(raw) if raw else "", os.getcwd()):
  280. if candidate and os.path.isdir(candidate):
  281. return candidate
  282. return staging_dir