terminal_tool_guards.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383
  1. """Pre-execution guards for the terminal tool.
  2. Pure functions that decide whether a command may run at all: workdir
  3. validation, the foreground long-lived/background-operator guidance, the
  4. supervised-gateway lifecycle block, and the Windows self-repo git guard.
  5. Each ``*_block`` helper returns a finished JSON error string, or None when
  6. the command may proceed. Split out of tools/terminal_tool.py; the origin
  7. module re-imports every public helper so ``tools.terminal_tool.<name>``
  8. keeps resolving.
  9. """
  10. import json
  11. import logging
  12. import re
  13. import shlex
  14. import stat
  15. from pathlib import Path
  16. from typing import Any, Optional
  17. from tools.shell_heredoc import strip_inert_heredoc_bodies
  18. logger = logging.getLogger("tools.terminal_tool")
  19. # Workdir allowlist: Unicode alnum plus path/drive/UNC separators and common
  20. # punctuation; shell metacharacters stay rejected. Unicode is allowed on
  21. # purpose (e.g. CJK vault paths). Defense-in-depth — the cwd is also
  22. # shlex-quoted before reaching the shell.
  23. _WORKDIR_SAFE_ASCII_CHARS = frozenset('/\\:_-.~ +@=,')
  24. def _is_safe_workdir_char(ch: str) -> bool:
  25. if not ch or ord(ch) < 32 or ord(ch) == 127: # control chars / NUL
  26. return False
  27. return ch.isalnum() or ch in _WORKDIR_SAFE_ASCII_CHARS
  28. def _validate_workdir(workdir: str) -> str | None:
  29. """Error message if *workdir* has a disallowed character, else None.
  30. Allowlist rather than deny-list so novel metacharacters can't slip through."""
  31. for ch in workdir or "":
  32. if not _is_safe_workdir_char(ch):
  33. return (
  34. f"Blocked: workdir contains disallowed character {ch!r}. "
  35. "Use a simple filesystem path without shell metacharacters."
  36. )
  37. return None
  38. def _safe_command_preview(command: Any, limit: int = 200) -> str:
  39. """Return a log-safe preview for possibly-invalid command values."""
  40. if command is None:
  41. return "<None>"
  42. if isinstance(command, str):
  43. return command[:limit]
  44. try:
  45. return repr(command)[:limit]
  46. except Exception:
  47. return f"<{type(command).__name__}>"
  48. def _blocked_json(error: str, status: str) -> str:
  49. """The guard result envelope: exit_code 1 + *error* + *status*."""
  50. return json.dumps({"output": "", "exit_code": 1, "error": error, "status": status}, ensure_ascii=False)
  51. _SHELL_LEVEL_BACKGROUND_RE = re.compile(
  52. r"(?:^|[;&|]\s*|&&\s*|\|\|\s*|\$\(\s*)(?:nohup|disown|setsid)\b", re.IGNORECASE | re.MULTILINE
  53. )
  54. _INLINE_BACKGROUND_AMP_RE = re.compile(r"\s&\s")
  55. _TRAILING_BACKGROUND_AMP_RE = re.compile(r"\s&\s*(?:#.*)?$")
  56. def _strip_quotes(command: str) -> str:
  57. """Blank quoted / backtick content and provably-inert heredoc bodies so
  58. regex checks can't match keywords (nohup, setsid, '&') inside strings.
  59. Heredocs are masked FIRST: their delimiter may itself be quoted
  60. (``<<'EOF'``). ``strip_inert_heredoc_bodies`` is conservative — only a
  61. quoted, terminated delimiter on a simple opener fed to a known non-shell
  62. consumer is masked, so a real background operator can't hide in one.
  63. """
  64. result = strip_inert_heredoc_bodies(command)
  65. result = re.sub(r"'[^']*'", "''", result)
  66. result = re.sub(r'"(?:[^"\\]|\\.)*"', '""', result)
  67. return re.sub(r"`[^`]*`", "``", result)
  68. _LONG_LIVED_FOREGROUND_PATTERNS = tuple(re.compile(p, re.IGNORECASE) for p in (
  69. r"\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|watch)\b",
  70. r"\bdocker\s+compose\s+up\b",
  71. r"\bnext\s+dev\b",
  72. r"\bvite(?:\s|$)",
  73. r"\bnodemon\b",
  74. r"\buvicorn\b",
  75. r"\bgunicorn\b",
  76. r"\bpython(?:3)?\s+-m\s+http\.server\b",
  77. ))
  78. # Ordered (predicate on the unquoted command, guidance) — first hit wins.
  79. _FOREGROUND_GUIDANCE = (
  80. (
  81. _SHELL_LEVEL_BACKGROUND_RE.search,
  82. "Foreground command uses shell-level background wrappers (nohup/disown/setsid). "
  83. "Re-send WITHOUT the wrapper as terminal(command=\"<cmd>\", background=true, "
  84. "notify_on_complete=true) so Hermes tracks the process, then run readiness "
  85. "checks and tests in separate commands.",
  86. ),
  87. (
  88. lambda s: _INLINE_BACKGROUND_AMP_RE.search(s) or _TRAILING_BACKGROUND_AMP_RE.search(s),
  89. "Foreground command uses '&' backgrounding. Re-send WITHOUT the '&' as "
  90. "terminal(command=\"<cmd>\", background=true) — add notify_on_complete=true "
  91. "for bounded jobs — then run health checks and tests in follow-up terminal calls.",
  92. ),
  93. (
  94. lambda s: any(p.search(s) for p in _LONG_LIVED_FOREGROUND_PATTERNS),
  95. "This foreground command appears to start a long-lived server/watch process. "
  96. "Run it with background=true, verify readiness (health endpoint/log signal), "
  97. "then execute tests in a separate command.",
  98. ),
  99. )
  100. def _looks_like_help_or_version_command(command: str) -> bool:
  101. """Return True for informational invocations that should never be blocked."""
  102. normalized = " ".join(command.lower().split())
  103. return (
  104. " --help" in normalized
  105. or normalized.endswith(" -h")
  106. or " --version" in normalized
  107. or normalized.endswith(" -v")
  108. )
  109. def _foreground_background_guidance(command: str) -> str | None:
  110. """Guidance text when a foreground command looks long-lived or uses shell
  111. backgrounding (it should be a managed background session), else None."""
  112. if _looks_like_help_or_version_command(command):
  113. return None
  114. unquoted = _strip_quotes(command)
  115. return next((msg for hit, msg in _FOREGROUND_GUIDANCE if hit(unquoted)), None)
  116. # `&` spellings that are not backgrounding: and-lists, fd redirects (`2>&1`, `>&2`, `&>`, `&>>`,
  117. # `<&3`) and the stderr pipe `|&`.
  118. _NON_BACKGROUND_AMP_RE = re.compile(r"&&|\d*[<>]&(?:\d+|-)?|&>>?|\|&")
  119. _TRAILING_AMP_ONLY_RE = re.compile(r"\s&\s*$")
  120. # Executable substitutions run code the quote-masking cannot see into (`"$(sleep 9 & echo $!)"`
  121. # hides a second, untracked background job), so any spelling of one refuses the conversion. Raw
  122. # substring match on purpose: a false refusal is today's behaviour, a false conversion is not.
  123. _EXECUTABLE_SUBSTITUTION_MARKERS = ("$(", "`", "<(", ">(")
  124. def _strip_trailing_amp(command: str) -> str:
  125. """*command* minus its final `&` and the UNESCAPED whitespace right before it.
  126. A backslash-escaped space is part of the last argument (`trailing\\ ` is the word `trailing `),
  127. so trimming stops at the first whitespace byte preceded by an odd run of backslashes.
  128. """
  129. body = command.rstrip()[:-1]
  130. end = len(body)
  131. while end and body[end - 1].isspace():
  132. backslashes = len(body[:end - 1]) - len(body[:end - 1].rstrip("\\"))
  133. if backslashes % 2:
  134. break
  135. end -= 1
  136. return body[:end]
  137. def _approval_identity(command: str) -> tuple:
  138. """Everything the approval path keys a decision on for *command*: hardline verdict, the
  139. dangerous pattern key/description (what session/permanent approvals are stored under), the
  140. sudo-stdin floor, runtime self-delete, the user's deny rules and the permanent allowlist."""
  141. from agent.runtime_self_protection import command_deletes_runtime
  142. from tools.approval import _command_matches_permanent_allowlist, _match_user_deny_rule
  143. from tools.approval_detection import _check_sudo_stdin_guard, detect_dangerous_command, detect_hardline_command
  144. return (
  145. tuple(detect_hardline_command(command)),
  146. tuple(detect_dangerous_command(command)),
  147. tuple(_check_sudo_stdin_guard(command)),
  148. command_deletes_runtime(command),
  149. _match_user_deny_rule(command),
  150. bool(_command_matches_permanent_allowlist(command)),
  151. )
  152. def trailing_amp_background_command(command: str) -> str | None:
  153. """The command without its trailing `&` when that `&` is its ONLY backgrounding, else None.
  154. Only the unambiguous shape converts: one line, one and-or list or pipeline (`a && b | c &`
  155. backgrounds the whole list in bash, exactly what background=true runs), nothing after the
  156. `&`. Inline `a & b`, `;` sequences, multi-line scripts/heredocs, nohup/disown/setsid and any
  157. executable substitution (`$(...)`, backticks, `<(...)`/`>(...)`) keep the refusal: the tool
  158. cannot prove there is no other background job or that later commands don't depend on a
  159. readiness check. Quoted `&` (and inert heredoc bodies) never count. Conversion must leave
  160. the approval identity untouched, otherwise the refusal stands.
  161. """
  162. if not isinstance(command, str) or _looks_like_help_or_version_command(command):
  163. return None
  164. if any(marker in command for marker in _EXECUTABLE_SUBSTITUTION_MARKERS):
  165. return None
  166. unquoted = _strip_quotes(command)
  167. if not _TRAILING_AMP_ONLY_RE.search(unquoted) or not command.rstrip().endswith("&"):
  168. return None
  169. body = unquoted.rstrip()[:-1]
  170. if "\n" in body or "\r" in body or ";" in body or "#" in body or _SHELL_LEVEL_BACKGROUND_RE.search(body):
  171. return None
  172. if "&" in _NON_BACKGROUND_AMP_RE.sub("", body):
  173. return None
  174. stripped = _strip_trailing_amp(command)
  175. if not stripped.strip():
  176. return None
  177. # Approval runs on what executes (the stripped command). Some patterns key on the `&` itself
  178. # (`hermes gateway run &` = gateway outside its service manager), and approvals are stored per
  179. # pattern key, so a different key would let a pre-approval for another category pass.
  180. if _approval_identity(command) != _approval_identity(stripped):
  181. return None
  182. return stripped
  183. def _read_script_for_guard(env: Any, guard_cwd: str, script_path: str, max_bytes: int) -> Optional[str]:
  184. """Best-effort script read: host filesystem first, then a bounded
  185. ``env.execute('head -c ... < path')`` for remote backends. Binary content
  186. (NUL byte) is not a script: feeding it to the guard tokenizes machine code
  187. into bogus paths and crashes the scanner, so it yields None."""
  188. if env is None:
  189. return None
  190. try:
  191. local_path = Path(script_path).expanduser()
  192. if not local_path.is_absolute():
  193. local_path = Path(guard_cwd) / local_path
  194. if local_path.is_file():
  195. metadata = local_path.stat()
  196. if stat.S_ISREG(metadata.st_mode) and metadata.st_size <= max_bytes:
  197. data = local_path.read_bytes()
  198. if len(data) <= max_bytes:
  199. return None if b"\x00" in data else data.decode("utf-8", errors="replace")
  200. except Exception:
  201. pass
  202. # Remote backend: bound the read at the source with `head -c` so an
  203. # oversized binary never crosses the wire (an unbounded `cat` once
  204. # pinned the gateway's tool thread for 30+ min on a shlex scan). One
  205. # byte over budget is enough for lifecycle_guard to fail closed. The
  206. # `< path` redirect keeps leading-dash paths out of argv.
  207. try:
  208. result = env.execute(f"head -c {max_bytes + 1} < {shlex.quote(script_path)}")
  209. if result.get("returncode", -1) == 0:
  210. output = result.get("output", "")
  211. return None if output and "\x00" in output else output
  212. except Exception:
  213. pass
  214. return None
  215. def gateway_lifecycle_block(
  216. *,
  217. command: str,
  218. env: Any,
  219. env_type: str,
  220. cwd: str,
  221. workdir: Optional[str],
  222. session_key: str,
  223. ) -> Optional[str]:
  224. """Refuse gateway lifecycle commands issued from inside the supervised gateway.
  225. ``systemctl``/``launchctl``/``hermes gateway restart|stop|uninstall``
  226. targeting hermes-gateway would SIGTERM the gateway — and this very
  227. subprocess — before completing, so the service may never come back.
  228. Applies unconditionally (``force=True`` cannot bypass it). Gated on the
  229. SUPERVISED-gateway probe, not the raw ``_HERMES_GATEWAY`` marker: that
  230. marker leaks into every process that merely imports gateway.run (hermes
  231. serve, CLI, web server), which must still be able to restart the gateway;
  232. an unsupervised foreground ``hermes gateway run`` has no KeepAlive to turn
  233. a self-restart into a respawn loop, so it passes too.
  234. Returns the JSON error string when blocked, else None.
  235. """
  236. from tools.process_registry import _is_supervised_gateway_process
  237. from tools.terminal_tool import _resolve_command_cwd, get_session_cwd
  238. if not _is_supervised_gateway_process():
  239. return None
  240. from cron.lifecycle_guard import (
  241. _MAX_REFERENCED_SCRIPT_BYTES,
  242. HOST_INTERPRETER_KILL_REJECTION,
  243. contains_host_interpreter_kill,
  244. contains_launchctl_submit_command,
  245. lifecycle_scan_root_within_budget,
  246. scan_gateway_lifecycle,
  247. )
  248. # Keep the specific launchctl diagnostic when this optional pre-scan fits the
  249. # budget. The full fail-closed guard below still runs when it does not, so
  250. # oversized roots never reach shlex here.
  251. if lifecycle_scan_root_within_budget(command) and contains_launchctl_submit_command(command):
  252. return _blocked_json(
  253. "Blocked: launchctl submit/bootstrap is restricted inside a supervised "
  254. "gateway regardless of the job label, to prevent indirect gateway "
  255. "restart loops. This guard does not inspect the job's KeepAlive settings "
  256. "or determine whether it is independent of Hermes. Perform authorized "
  257. "LaunchAgent maintenance from a separate shell outside the gateway, "
  258. "not by switching launchctl verbs to bypass this rejection.",
  259. "error",
  260. )
  261. guard_cwd_base = get_session_cwd(session_key)
  262. if guard_cwd_base is None:
  263. guard_cwd_base = getattr(env, "cwd", None) or cwd
  264. guard_cwd = _resolve_command_cwd(
  265. workdir=workdir, default_cwd=guard_cwd_base, session_key=session_key, env_type=env_type,
  266. mounted_host=getattr(env, "host_cwd", None),
  267. env=env,
  268. )
  269. unsafe, refusal = scan_gateway_lifecycle(
  270. command,
  271. cwd=guard_cwd,
  272. read_remote_script=lambda p: _read_script_for_guard(env, guard_cwd, p, _MAX_REFERENCED_SCRIPT_BYTES),
  273. )
  274. if unsafe and refusal:
  275. # Not a lifecycle command: a script the command EXECUTES could not be scanned (budget,
  276. # size, device, live SQLite, cloud placeholder). Say so, or the model rewords and retries
  277. # the same command in a loop (#113944).
  278. return _blocked_json(
  279. f"Blocked: the lifecycle guard could not scan this command or referenced script: {refusal}. "
  280. "Nothing in the command is known to contain a gateway lifecycle command, but a "
  281. "script the command executes must be scannable (a regular text file under 1 MiB) "
  282. "before it can run inside the gateway process.",
  283. "error",
  284. )
  285. if unsafe:
  286. # Name the ownership-scoped route for image-name kills: the intent is almost always "stop
  287. # MY background job", and re-rolling the same over-broad spelling is what takes the gateway down.
  288. if lifecycle_scan_root_within_budget(command) and contains_host_interpreter_kill(command):
  289. return _blocked_json(HOST_INTERPRETER_KILL_REJECTION, "error")
  290. return _blocked_json(
  291. "Blocked: command or referenced script cannot restart, stop, or "
  292. "uninstall the gateway from inside the gateway process. The gateway would "
  293. "kill this command before it could complete (SIGTERM propagates "
  294. "to child processes). Run `hermes gateway restart` from a "
  295. "separate shell outside the running gateway.",
  296. "error",
  297. )
  298. return None
  299. def self_repo_block(
  300. *,
  301. command: str,
  302. cwd: str,
  303. workdir: Optional[str],
  304. session_key: str,
  305. ) -> Optional[str]:
  306. """Windows-only guard against git-mutating the checkout backing this interpreter.
  307. NTFS locks loaded module files, so rewriting the live checkout can corrupt
  308. the running process; POSIX keeps old inodes alive for open handles, so the
  309. guard is off there (``guard_active``). Local backend only — remote
  310. backends cannot reach that checkout. Returns the JSON error string when
  311. blocked, else None.
  312. """
  313. from tools.self_repo_guard import detect_self_repo_git_mutation, guard_active
  314. from tools.terminal_tool import _resolve_command_cwd
  315. if not guard_active():
  316. return None
  317. guard_cwd = _resolve_command_cwd(workdir=workdir, default_cwd=cwd, session_key=session_key)
  318. hit, msg = detect_self_repo_git_mutation(command, guard_cwd)
  319. if not hit:
  320. return None
  321. logger.warning("Blocked self-repo git mutation (command: %s)", _safe_command_preview(command))
  322. return _blocked_json(msg, "blocked")
  323. def locked_skill_block(*, command: str, cwd: str, workdir: Optional[str], session_key: str) -> Optional[str]:
  324. """Refuse commands that write into a skill the user locked, change the lock record, or run
  325. ``hermes curator unlock`` (see tools/skill_lock). Local backend only: a remote or container
  326. backend cannot reach this profile's skills dir. Returns the JSON error string when blocked."""
  327. from tools.skill_lock import command_refusal
  328. from tools.terminal_tool import _resolve_command_cwd
  329. guard_cwd = _resolve_command_cwd(workdir=workdir, default_cwd=cwd, session_key=session_key)
  330. reason = command_refusal(command, guard_cwd)
  331. if reason is None:
  332. return None
  333. logger.warning("Blocked write to a locked skill (command: %s)", _safe_command_preview(command))
  334. return _blocked_json(f"Blocked: {reason}", "blocked")