lifecycle_guard.py 65 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293
  1. """Gateway lifecycle guard for cron job creation.
  2. A cron job that restarts/stops the gateway from inside the gateway (``hermes gateway restart``,
  3. ``launchctl kickstart ai.hermes.gateway``, ``systemctl restart hermes-gateway``) kills the process,
  4. the supervisor revives it, auto-resume re-runs the turn: a SIGTERM-respawn loop.
  5. ``cron.jobs.create_job`` rejects such specs on every creation path. Patterns are command-shaped —
  6. anchored on concrete command identifiers — so they cannot fire on prose. Defence-in-depth layer.
  7. """
  8. from __future__ import annotations
  9. import logging
  10. import os
  11. import re
  12. import shlex
  13. import stat
  14. import sys
  15. from pathlib import Path
  16. from typing import Callable, Iterator, Optional
  17. logger = logging.getLogger(__name__)
  18. class GatewayLifecycleBlocked(ValueError):
  19. """Raised when a cron job spec contains a gateway-lifecycle command."""
  20. # Shell-level command shapes that target the gateway lifecycle; each branch is anchored on a
  21. # concrete command identifier so it fires only on command-shaped strings, never prose.
  22. _GATEWAY_LIFECYCLE_PATTERN = re.compile(
  23. r"(?i)"
  24. # Branch A: destructive `hermes gateway` ops. `start` is excluded: starting from inside a
  25. # gateway is benign and a job may legitimately start a sibling profile. The lookbehind keeps
  26. # `hermes` from being a path component or word tail (`/docs/hermes gateway restart-notes.md`)
  27. # while every real command position (text start, whitespace, `;`/`&`/`|`, `$(`, backtick,
  28. # U+FFFD) still matches.
  29. # See #77173.
  30. # Windows spells the CLI with a launcher suffix (`hermes.exe`, npm-style `hermes.cmd`/`.ps1`);
  31. # same command, so the suffix is optional here.
  32. r"(?:(?<![/\w.\-])hermes(?:\.(?:exe|cmd|bat|com|ps1))?\s+gateway\s+(?:restart|stop|uninstall)\b)"
  33. # Branch B: launchctl ops anchored on a hermes-gateway label so unrelated hermes services stay
  34. # unblocked. `submit`/`bootstrap` register a NEW keepalive job wrapping an arbitrary helper (a
  35. # laundered restart); neutral-label submissions are caught by
  36. # `contains_launchctl_submit_command`. `bootout`/`remove`/`disable` are the
  37. # modern/legacy/durable forms of `unload`.
  38. # `submit` and `bootstrap` are included alongside the direct verbs (kickstart/etc.): `launchctl submit
  39. # -l ai.hermes.gateway-<suffix> -- <helper-script>` (or `launchctl bootstrap gui/<uid> <plist>`) creates
  40. # a NEW keepalive job wrapping an arbitrary helper, which is how a blocked direct restart/kill gets
  41. # laundered into a persistent restart loop instead (#62891) — same foot-gun, indirect shape.
  42. # Neutral-label submissions that dodge this text anchor are caught separately by
  43. # `contains_launchctl_submit_command` (execution-aware, label-independent). `bootout`/`remove`/`disable`
  44. # sit alongside `unload`: Apple deprecated load/unload in favour of bootstrap/bootout, so `bootout` is
  45. # the modern spelling of an already-listed verb, `remove` is its legacy sibling, and `disable` is what
  46. # makes an unload durable across boots. Omitting them left the bypassable approval layer
  47. # (tools/approval.py, skipped on force=True) as the only cover, while this hard block — documented as
  48. # "force=True cannot help here" — let them through (#80260).
  49. r"|(?:launchctl\s+(?:kickstart|unload|load|stop|restart|submit|bootstrap|bootout|remove|disable)\b[^\n]*\bhermes[.\-]?gateway)"
  50. # Branch C: systemctl ops on a hermes-gateway unit.
  51. r"|(?:systemctl\s+(?:-\S+\s+)*(?:restart|stop|start)\b[^\n]*\bhermes[.\-]?gateway)"
  52. # Branch D: pkill/kill of the gateway process, both token orders. Leading \b keeps "skill" from
  53. # matching as "kill".
  54. # `taskkill` / `Stop-Process` are the Windows spellings of the same operation; `\bp?kill\b`
  55. # cannot reach inside `taskkill`, so they are named outright. Service-control forms (`net stop`,
  56. # `sc stop`) presuppose a service install this guard has no evidence of and stay uncovered.
  57. r"|(?:\b(?:p?kill|taskkill|stop-process)\b[^\n]*\bhermes\b[^\n]*\bgateway)"
  58. r"|(?:\b(?:p?kill|taskkill|stop-process)\b[^\n]*\bgateway\b[^\n]*\bhermes)"
  59. )
  60. # Branch E: process killers whose TARGET is the interpreter image hosting the gateway. A supervised
  61. # gateway is literally `python.exe` / `python3.12` (`python -m hermes_cli.main gateway run`), so
  62. # `taskkill /F /IM python.exe`, `pkill -9 python3` or `killall python` carry no hermes/gateway token
  63. # yet terminate it (#113667). Token-aware rather than a line regex: option VALUES are never read as
  64. # targets (`pkill -u <user> chrome`), `-f` cmdline patterns are judged as patterns, and other image
  65. # names (`taskkill /F /IM chrome.exe`) stay available. Numeric-PID kills are out of scope:
  66. # the explicit PID / `proc_*` id IS the ownership-scoped route the rejection points to.
  67. _INTERPRETER_IMAGE_RE = re.compile(r"^pythonw?(?:\d+(?:\.\d+)*)?(?:\.exe)?$")
  68. _HOST_INTERPRETER_NAME = Path(sys.executable).name.lower() if sys.executable else ""
  69. _KILLER_VALUE_OPTIONS = {
  70. # procps pkill/pgrep options that consume the next token, so the value is never the pattern.
  71. "pkill": frozenset({
  72. "-g", "--pgroup", "-G", "--group", "-P", "--parent", "-s", "--session", "-t", "--terminal",
  73. "-u", "--euid", "-U", "--uid", "-F", "--pidfile", "--ns", "--nslist", "-d", "--delimiter",
  74. "--signal", "-O", "--older", "-r", "--runstates", "--cgroup", "-A", "--ignore-ancestors",
  75. }),
  76. "killall": frozenset({"-s", "--signal", "-u", "--user", "-o", "--older-than", "-y", "--younger-than",
  77. "-n", "--ns", "-Z", "--context"}),
  78. }
  79. _KILLER_VALUE_OPTIONS["pgrep"] = _KILLER_VALUE_OPTIONS["pkill"]
  80. _KILLER_VALUE_OPTIONS["pidof"] = frozenset({"-o", "--omit-pid", "-S", "--separator"})
  81. # Regex metacharacters a pkill/pgrep ERE may carry around the interpreter name (`^python3?$`, `python.*`).
  82. _ERE_TAIL = re.compile(r"[.*+?\\\[\](){}|].*$")
  83. _ERE_WILDCARD_ONLY = re.compile(r"^[.*+?$\s]*$")
  84. _NAME_KILLERS = frozenset({"pkill", "killall", "taskkill", "stop-process"})
  85. _NAME_ENUMERATORS = frozenset({"pgrep", "pidof", "get-process"})
  86. _KILL_VERB_RE = re.compile(r"(?i)\b(?:kill|taskkill|stop-process)\b")
  87. # A `-f` pattern that does not start with the interpreter reaches the gateway cmdline
  88. # (`python -m hermes_cli.main gateway run` / `hermes gateway run`) only through its own tokens;
  89. # an unrelated script that merely contains "hermes" (`hermes-polis/run.sh`, `my_hermes_bot.py`)
  90. # cannot match it. Same hermes+gateway pairing as Branch D, plus the module path.
  91. _GATEWAY_CMDLINE_TOKEN_RE = re.compile(r"(?i)hermes_cli|\bhermes\b[^\n]*\bgateway\b|\bgateway\b[^\n]*\bhermes\b")
  92. # Rejection text for Branch E, shared by every tool surface that runs the guard so the agent is
  93. # pointed at the ownership-scoped route (proc_* id / explicit PID) rather than the shell.
  94. HOST_INTERPRETER_KILL_REJECTION = (
  95. "Blocked: this command kills every process whose image/name matches the Python "
  96. "interpreter, which is the process hosting this gateway (and this command). "
  97. "Stop only the process you own instead: process(action=\"kill\", session_id=\"proc_…\") "
  98. "for a background job Hermes started, or kill/taskkill by its explicit PID."
  99. )
  100. def _is_interpreter_image(value: str, *, substring: bool = False) -> bool:
  101. """True when *value* (a process/image name, `*`-wildcard allowed) denotes the Python interpreter
  102. that hosts the gateway. *substring*: pkill/pgrep match an ERE anywhere in the name, so `py`
  103. reaches `python3` too."""
  104. name = value.strip().strip("\"'").lower().removesuffix(".exe")
  105. if not name:
  106. return False
  107. if name.endswith("*"):
  108. prefix = name.rstrip("*")
  109. return "python".startswith(prefix) or _HOST_INTERPRETER_NAME.startswith(prefix)
  110. if _INTERPRETER_IMAGE_RE.match(name) or name == _HOST_INTERPRETER_NAME.removesuffix(".exe"):
  111. return True
  112. return substring and len(name) >= 2 and "python".startswith(name)
  113. def _pattern_reaches_host_interpreter(pattern: str, *, full_cmdline: bool, exact: bool) -> bool:
  114. """pkill/pgrep/killall operand semantics: an ERE against the process NAME (or, with `-f`, the full
  115. command line). `python -m hermes_cli.main …` is the gateway's own cmdline, so a `-f` pattern
  116. that names the interpreter and then only wildcards or a `hermes` token reaches it, while
  117. `python mt_add.py` (a specific script) does not."""
  118. core = pattern.strip().strip("\"'").lstrip("^")
  119. core = core.removesuffix("$")
  120. head, _, rest = core.partition(" ") if full_cmdline else (core, "", "")
  121. # A literal interpreter name first (`python3.12`: the dot is a version separator, not an ERE
  122. # wildcard); only then read the head as an ERE with a metacharacter tail (`python3?`, `python.*`).
  123. match = None if _is_interpreter_image(head, substring=not exact) else _ERE_TAIL.search(head)
  124. if match:
  125. rest = head[match.start():] + " " + rest
  126. head = head[: match.start()]
  127. if not _is_interpreter_image(head, substring=not exact):
  128. return full_cmdline and bool(_GATEWAY_CMDLINE_TOKEN_RE.search(core))
  129. return not rest.strip() or bool(_ERE_WILDCARD_ONLY.match(rest)) or "hermes" in rest.lower()
  130. def _killer_targets_host_interpreter(name: str, args: list[str]) -> bool:
  131. """Whether killer/enumerator *name* with argv *args* would select the host interpreter."""
  132. if name in ("pkill", "pgrep", "killall", "pidof"):
  133. # pkill/pgrep: ERE anywhere in the name unless -x; killall: exact name unless -r; pidof: exact.
  134. exact = name == "pidof" or (name == "killall") != any(t in ("-r", "--regexp", "-x", "--exact") for t in args)
  135. full_cmdline = name in ("pkill", "pgrep") and any(t in ("-f", "--full") for t in args)
  136. operands: list[str] = []
  137. position = 0
  138. while position < len(args):
  139. token = args[position]
  140. if token == "--":
  141. operands += args[position + 1:]
  142. break
  143. if token in _KILLER_VALUE_OPTIONS[name]:
  144. position += 2
  145. continue
  146. if not token.startswith("-"):
  147. operands.append(token)
  148. position += 1
  149. return any(_pattern_reaches_host_interpreter(op, full_cmdline=full_cmdline, exact=exact) for op in operands)
  150. if name == "taskkill":
  151. for position, token in enumerate(args[:-1]):
  152. option = token.lower().lstrip("/-")
  153. value = args[position + 1]
  154. if option == "im" and _is_interpreter_image(value):
  155. return True
  156. if option == "fi":
  157. filter_match = re.match(r"(?i)\s*['\"]?imagename\s+eq\s+(\S+)", value)
  158. if filter_match and _is_interpreter_image(filter_match.group(1)):
  159. return True
  160. return False
  161. # Stop-Process / Get-Process: `-Name`/`-ProcessName` (also `-Name:value`), comma lists, positional
  162. # names for Get-Process.
  163. values: list[str] = []
  164. for position, token in enumerate(args):
  165. option, _, inline_value = token.partition(":")
  166. if option.lower() in ("-name", "-processname", "-n"):
  167. values.append(inline_value if inline_value else (args[position + 1] if position + 1 < len(args) else ""))
  168. elif name == "get-process" and not token.startswith("-") and (position == 0 or not args[position - 1].startswith("-")):
  169. values.append(token)
  170. return any(_is_interpreter_image(part) for value in values for part in value.split(","))
  171. def _segment_names_host_interpreter(tokens: list[str], killers: frozenset[str]) -> bool:
  172. """Whether a tokenized segment runs one of *killers* against the host interpreter. The
  173. executable is read at the wrapper-peeled position first, then at the first killer token anywhere
  174. in the segment (`xargs kill`, Python argv lists)."""
  175. index = _executed_command_index(tokens)
  176. candidates = [index] if index is not None else []
  177. candidates += [i for i, token in enumerate(tokens) if _executable_name(token).lower().removesuffix(".exe") in killers]
  178. for position in candidates:
  179. name = _executable_name(tokens[position]).lower().removesuffix(".exe")
  180. if name in killers and _killer_targets_host_interpreter(name, tokens[position + 1:]):
  181. return True
  182. return False
  183. def contains_host_interpreter_kill(text: str) -> bool:
  184. """Branch E entrypoint: a process killer aimed at the interpreter image hosting the gateway, or a
  185. name-derived PID feed into one (`pgrep python | xargs kill`, `kill $(pidof python3)`,
  186. `Get-Process python | Stop-Process`). Segment-tokenized, so quoted/spliced spellings and Python
  187. argv lists resolve the same way the shell resolves them."""
  188. normalized = _SHELL_LINE_CONTINUATION.sub(" ", text)
  189. kill_verb_present = bool(_KILL_VERB_RE.search(normalized))
  190. for segment in _iter_command_segments(normalized):
  191. joined = " ".join(segment)
  192. stripped = _ARGV_LIST_PUNCTUATION.sub(" ", joined)
  193. # Python argv lists (`subprocess.run(["taskkill", "/IM", "python.exe"])`) re-split only when
  194. # list punctuation was present, so a quoted `-f 'python my_script.py'` stays one operand.
  195. for tokens in ([segment, stripped.split()] if stripped != joined else [segment]):
  196. if _segment_names_host_interpreter(tokens, _NAME_KILLERS):
  197. return True
  198. if kill_verb_present and _segment_names_host_interpreter(tokens, _NAME_ENUMERATORS):
  199. return True
  200. return False
  201. # Every branch uses `[^\n]*` between verb and label so matches cannot span unrelated lines. A POSIX
  202. # backslash-newline continuation is therefore collapsed to a space before matching (as the shell
  203. # does) rather than loosening `[^\n]*`.
  204. # Every branch above uses `[^\n]*` between its verb and the gateway identifier so the match can't span
  205. # unrelated lines of a longer cron prompt/script, but that also means a real multi-line shell invocation
  206. # split across continuation lines (e.g. `launchctl submit \` / ` -l ai.hermes.gateway-... \` / ` -- ...`,
  207. # the exact reported shape in #62891) would otherwise slip past. Collapse continuations to a single space
  208. # before matching, mirroring what the shell itself does, rather than loosening `[^\n]*` and risking false
  209. # positives across genuinely separate lines.
  210. _SHELL_LINE_CONTINUATION = re.compile(r"\\\r?\n[ \t]*")
  211. # Python argv-list punctuation (`subprocess.run(["launchctl", "bootout", ...])`) separates exec'd
  212. # words with brackets/commas. Stripped only for the token-join re-scan, never from raw text.
  213. # See #68289.
  214. _ARGV_LIST_PUNCTUATION = re.compile(r"[\[\],]+")
  215. # Branch A2: `hermes -p <profile> gateway restart|stop` (also `--profile <name>` /
  216. # `--profile=<name>`). The selector breaks Branch A's adjacency. A sibling-profile restart is a
  217. # legitimate fleet operation, so the profile name is captured and blocked only when it equals the
  218. # profile running the guard. `start` stays excluded as in Branch A.
  219. # Unlike Branch A this form is NOT unconditionally self-targeting: issued from inside gateway `zeus`,
  220. # `hermes -p venus gateway restart` operates on a sibling profile's gateway and is a legitimate fleet
  221. # operation. The pattern captures the named profile so `contains_gateway_lifecycle_command` can block only
  222. # the self-targeting shape (named profile == the profile running the guard). See #78028.
  223. _PROFILE_FLAG_LIFECYCLE_PATTERN = re.compile(
  224. r"(?i)"
  225. r"hermes\s+"
  226. # Each flag has one parse: '-' plus its remainder, never two ways to split
  227. # '--'. A following flag cannot also be an optional value (#129281).
  228. # Possessive token/space runs avoid repartitioning whitespace on failure;
  229. # whole flag groups can still backtrack to expose the profile selector.
  230. # Do not cap the number of flags: that would silently allow long self-stops.
  231. r"(?:-\S++(?:\s++(?!-\S)\S++)?\s++)*"
  232. # The selector: exactly the shapes the CLI's `_apply_profile_override` accepts.
  233. r"(?:--profile=([^\s]+)|(?:-p|--profile)\s+([^\s]+))"
  234. # Any global flags between the selector and the subcommand.
  235. r"(?:\s++-\S++(?:\s++(?!-\S)\S++)?)*"
  236. r"\s+gateway\s+(?:restart|stop)"
  237. )
  238. # Branch B needs the label AFTER the verb in one `[^\n]*` span; a loop that builds the label in an
  239. # EARLIER `;`-segment (`label=${item%%:*}; launchctl bootout "gui/$uid/$label"`) leaves only
  240. # `$label` next to the verb. These verbs act on an EXISTING job, so the hermes-gateway label anchor
  241. # stays correct, but the check is "verb anywhere AND label anywhere".
  242. # No profile identity available: cannot prove self-targeting, so do not block — sibling restarts must stay
  243. # allowed (#78028).
  244. _LAUNCHCTL_LIFECYCLE_VERBS_RE = re.compile(
  245. r"(?i)\blaunchctl\s+(?:kickstart|unload|load|stop|restart|bootout|kill|disable|remove)\b"
  246. )
  247. _HERMES_GATEWAY_LABEL_RE = re.compile(r"(?i)\bhermes[.\-]?gateway\b")
  248. _SHELL_EXECUTABLES = frozenset({"sh", "bash", "dash", "ksh", "zsh"})
  249. _SHELL_OPTIONS_WITH_VALUES = frozenset({"-O", "+O", "-o", "+o"})
  250. _SHELL_COMMAND_FLAGS = {"-c", "--command"}
  251. _MAX_REFERENCED_SCRIPT_BYTES = 1024 * 1024
  252. _MAX_REFERENCED_SCRIPT_DEPTH = 8
  253. _CONTROL_CHARS = frozenset(";&|()")
  254. # Directory names directly under `Library` that mark a FileProvider-backed subtree: `Mobile
  255. # Documents` is iCloud Drive; `CloudStorage` hosts third-party providers (Dropbox, OneDrive, Google
  256. # Drive, ...).
  257. _CLOUD_PLACEHOLDER_MARKERS = frozenset({"Mobile Documents", "CloudStorage"})
  258. # Executables whose arguments are DATA (search patterns, SQL, log filters) and cannot execute their
  259. # argument text. Deliberately conservative: no `awk` (system()), no `sed` (`s///e`), no
  260. # `echo`/`printf` (routinely piped into a shell), no `mysql` (`\\!` and `system` escapes).
  261. _DATA_SINK_EXECUTABLES = frozenset(
  262. {"grep", "egrep", "fgrep", "rg", "ag", "ack", "journalctl", "sqlite3", "psql"}
  263. )
  264. # Argument shapes that smuggle execution back INTO a data sink (command/process substitution, psql
  265. # `\!`). Any hit disables masking for the whole segment — fail closed to the plain regex verdict.
  266. _UNSAFE_DATA_ARG_MARKERS = ("`", "$(", "<(", ">(", "\\!")
  267. # sqlite3 dot-commands (`.shell`, `.system`) also disable masking. Dot must be followed by a NAME
  268. # character so relative paths (`.`, `./x`) stay paths.
  269. _DOT_COMMAND_ARGUMENT = re.compile(r"^\.[A-Za-z]")
  270. # A data sink piped into a shell/interpreter can feed matched lines to execution; never mask it.
  271. _PIPE_TO_INTERPRETER = re.compile(
  272. r"\|\s*&?\s*(?:sudo\s+)?(?:sh|bash|dash|ksh|zsh|xargs|eval|source)\b"
  273. )
  274. # Bytes sniffed before reading a referenced file in full (see _BINARY_MAGICS).
  275. _BINARY_SNIFF_BYTES = 4096
  276. _ReadRemoteScriptFn = Callable[[str], Optional[str]]
  277. # Wrappers that hand execution to their argument tail: the real command sits further right, so a
  278. # first-token-only guard would let `sudo bash ~/restart.sh` / `sudo launchctl submit ...` walk past.
  279. # A guard that reads only the first token sees `sudo`/`env`/`nohup` and never inspects what they run, so
  280. # `sudo bash ~/restart.sh` walked past the same walk that stops `bash ~/restart.sh`, and `sudo launchctl
  281. # submit ...` past the label-independent submit block (#62891). `_PIPE_TO_INTERPRETER` above already reads
  282. # `sudo ` this way for the pipe case; this generalises that reading to the command position.
  283. _TRANSPARENT_COMMAND_PREFIXES = frozenset({
  284. "sudo", "doas", "env", "nohup", "setsid", "nice", "ionice", "stdbuf",
  285. "timeout", "exec", "command", "builtin", "eatmydata",
  286. # Privilege and namespace wrappers: options, then the command they run.
  287. "pkexec", "su", "runuser", "setpriv", "systemd-run", "nsenter", "unshare",
  288. })
  289. # Wrapper options that consume the NEXT token, so a value is never mistaken for the command.
  290. _TRANSPARENT_PREFIX_VALUE_OPTIONS = {
  291. "sudo": {"-u", "-g", "-U", "-C", "-p", "-r", "-t", "-T", "--user", "--group", "--prompt"},
  292. "doas": {"-u", "-C"},
  293. "env": {"-u", "--unset", "-S", "--split-string", "-C", "--chdir"},
  294. "nice": {"-n", "--adjustment"},
  295. "ionice": {"-c", "-n", "-p", "--class", "--classdata"},
  296. "stdbuf": {"-i", "-o", "-e", "--input", "--output", "--error"},
  297. "timeout": {"-s", "-k", "--signal", "--kill-after"},
  298. "pkexec": {"--user"},
  299. "su": {"-s", "--shell", "-g", "--group", "-G", "--supp-group"},
  300. "runuser": {"-u", "--user", "-s", "--shell", "-g", "--group", "-G", "--supp-group"},
  301. "setpriv": {"--reuid", "--regid", "--groups", "--inh-caps", "--ambient-caps", "--bounding-set",
  302. "--selinux-label", "--apparmor-profile"},
  303. "systemd-run": {"-u", "--unit", "-p", "--property", "-E", "--setenv", "--slice",
  304. "--description", "--uid", "--gid", "--on-calendar", "--service-type"},
  305. "nsenter": {"-t", "--target", "-S", "--setuid", "-G", "--setgid", "-r", "--root", "-w", "--wd"},
  306. "unshare": {"--map-user", "--map-group", "--setgroups", "-R", "--root", "-w", "--wd"},
  307. }
  308. # Wrapper options carrying a COMMAND STRING (shell source, re-scanned like `sh -c`); treating it as
  309. # an opaque value would hide whatever it runs (`env -S 'bash ~/restart.sh'`).
  310. _STRING_COMMAND_OPTIONS = {
  311. "env": ("-S", "--split-string"),
  312. "su": ("-c", "--command"),
  313. "runuser": ("-c", "--command"),
  314. }
  315. # Wrappers whose first non-option operand is a VALUE, not the command (`timeout 60 bash x.sh`).
  316. _TRANSPARENT_PREFIX_OPERANDS = {"timeout": 1}
  317. _ENV_ASSIGNMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
  318. # Bound the walk: a pathological token run must not spin here.
  319. _MAX_PREFIX_PEELS = 8
  320. _BINARY_MAGICS = (
  321. b"\x7fELF", # ELF — Linux/BSD executables and shared objects
  322. b"\xfe\xed\xfa\xce", # Mach-O 32-bit
  323. b"\xfe\xed\xfa\xcf", # Mach-O 64-bit
  324. b"\xce\xfa\xed\xfe", # Mach-O 32-bit, byte-swapped
  325. b"\xcf\xfa\xed\xfe", # Mach-O 64-bit, byte-swapped
  326. b"\xca\xfe\xba\xbe", # Mach-O universal ("fat") binary
  327. b"MZ", # PE/COFF — Windows .exe/.dll
  328. b"!<arch>", # static archive (.a)
  329. b"\x1f\x8b", # gzip
  330. b"PK\x03\x04", # zip (also .jar/.whl/.egg)
  331. )
  332. # --- profile identity -------------------------------------------------------------------------
  333. def _current_profile_name() -> Optional[str]:
  334. """Profile running the guard (``hermes_cli.profiles.current_profile_name``); ``None`` if none."""
  335. from hermes_cli.profiles import current_profile_name
  336. return current_profile_name()
  337. def _named_profile_is_current(named: str) -> bool:
  338. """True when *named* is the profile executing the guard. Without a profile identity
  339. self-targeting cannot be proven, so nothing is blocked (sibling restarts stay allowed)."""
  340. current = _current_profile_name()
  341. return bool(current) and named.strip().casefold() == current.strip().casefold()
  342. # --- direct string scans ----------------------------------------------------------------------
  343. def _contains_launchctl_gateway_lifecycle(normalized_text: str) -> bool:
  344. """Order-independent companion to Branch B — see the verbs regex comment."""
  345. return bool(_LAUNCHCTL_LIFECYCLE_VERBS_RE.search(normalized_text)) and bool(
  346. _HERMES_GATEWAY_LABEL_RE.search(normalized_text)
  347. )
  348. def contains_gateway_lifecycle_command(text: str) -> bool:
  349. """Return True if *text* contains a gateway lifecycle command pattern.
  350. Passes, in order: raw-text regex (the only pass that fires on inputs shlex cannot tokenize, e.g.
  351. Python source); profile-flag form; the same regex on each shell-tokenized segment with quotes/
  352. escapes resolved (closes splice bypasses like ``kick"start"`` / ``kick\\start``);
  353. order-independent launchctl pass. Single choke point for every recursion level of
  354. ``_contains_unsafe_gateway_action``.
  355. That second pass exists because a real shell resolves quote-splicing (``kick"start"``) and
  356. backslash-escaping (``kick\\start``) into one literal word — ``kickstart`` — before the command ever
  357. runs. The raw text still has the quote or backslash sitting between the verb's two halves, so the first
  358. pass alone lets a spliced verb reach ``launchctl``/``systemctl`` untouched while still executing as the
  359. blocked lifecycle command (#80269, reported against #80260's bootout parity fix). Tokenizing closes that
  360. gap while keeping the same gateway-label anchoring (``_GATEWAY_LIFECYCLE_PATTERN`` still requires a
  361. ``hermes``/``gateway`` token) — this function is the single choke point
  362. ``_contains_unsafe_gateway_action`` calls at every recursion level, so referenced-script and ``sh -c``
  363. payload scanning inherit the fix automatically.
  364. """
  365. if not text:
  366. return False
  367. # Provably inert heredoc bodies (quoted delimiter, data-sink consumer like `cat > f <<'EOF'`)
  368. # are documentation, not commands. The stripper fails open on ANY ambiguity (unquoted delimiter,
  369. # shell consumer, unterminated body), so executable heredocs are still scanned.
  370. # Heredoc bodies that are provably inert data (quoted delimiter, data-sink consumer like `cat > file
  371. # <<'EOF'`) are masked before scanning (#88336): a runbook line "a human can run: hermes gateway
  372. # restart" inside such a body is documentation, not a command this shell will execute.
  373. from tools.shell_heredoc import strip_inert_heredoc_bodies
  374. text = strip_inert_heredoc_bodies(text)
  375. normalized = _SHELL_LINE_CONTINUATION.sub(" ", text)
  376. if _GATEWAY_LIFECYCLE_PATTERN.search(normalized):
  377. return True
  378. # Profile-flag form: blocked only when the named profile IS the one running the guard.
  379. # Profile-flag form (#78028): `hermes -p <profile> gateway restart|stop` bypasses Branch A because the
  380. # selector sits between `hermes` and `gateway`. It is only the same foot-gun when the named profile IS
  381. # the profile running the guard — sibling-profile restarts are legitimate fleet operations and stay
  382. # allowed.
  383. profile_match = _PROFILE_FLAG_LIFECYCLE_PATTERN.search(normalized)
  384. if profile_match:
  385. named = profile_match.group(1) or profile_match.group(2)
  386. # Profile ids cannot contain quotes (`^[a-z0-9][a-z0-9_-]{0,63}$`), so a shell-quoted
  387. # `-p 'zeus'` compares equal to the bare name.
  388. if named and _named_profile_is_current(named.strip().strip("\"'")):
  389. return True
  390. # Token-aware pass. Tokens are also re-joined with Python argv-list punctuation stripped, since
  391. # `subprocess.run(["launchctl", "bootout", ...])` separates argv words with commas/brackets.
  392. # Token-aware second pass (#80269): re-run the pattern on shell-tokenized segments where quotes/escapes
  393. # are resolved, closing splice bypasses like `kick"start"`. Runs after the profile-flag check so both
  394. # passes apply independently.
  395. for segment in _iter_command_segments(normalized):
  396. joined = " ".join(segment)
  397. if joined and _GATEWAY_LIFECYCLE_PATTERN.search(joined):
  398. return True
  399. stripped = _ARGV_LIST_PUNCTUATION.sub(" ", joined)
  400. if stripped != joined and _GATEWAY_LIFECYCLE_PATTERN.search(stripped):
  401. return True
  402. # The label may be built in an earlier `;`-segment, so no pass above sees verb + label together.
  403. # Order-independent launchctl pass (#77083): a shell loop can build the gateway label from a variable
  404. # defined in an earlier `;`-separated segment (`label=${item%%:*}; launchctl bootout
  405. # "gui/$uid/$label"`), so neither the same-span regex nor same-segment tokenization sees verb and label
  406. # together. Check "verb anywhere AND label anywhere" instead.
  407. # Branch E (#113667): killers aimed at the interpreter image itself carry no hermes/gateway token.
  408. return _contains_launchctl_gateway_lifecycle(normalized) or contains_host_interpreter_kill(normalized)
  409. # Whole-walk work limits. The per-file cap and depth bound above limit one read, not the walk: a
  410. # command can reference arbitrarily many scripts, and the pure-Python shlex pass (quadratic on a
  411. # giant token) once held the GIL for minutes. These caps bound one whole walk and are charged
  412. # BEFORE any text reaches shlex. Exhaustion fails closed (an unscanned script could hide a
  413. # lifecycle command) and is logged at WARNING so an operator can tell it from a real block. Sizes
  414. # sit well above any legitimate wrapper graph; remote reads are a backend roundtrip each, so they
  415. # get a far tighter cap.
  416. # See #78398.
  417. _MAX_LIFECYCLE_SCAN_BYTES = _MAX_REFERENCED_SCRIPT_BYTES # 1 MiB across the walk
  418. _MAX_LIFECYCLE_SCAN_LINES = 16384
  419. _MAX_LIFECYCLE_SCAN_LINE_BYTES = 64 * 1024
  420. _MAX_LIFECYCLE_SCAN_PATHS = 1024
  421. _MAX_LIFECYCLE_SCAN_REMOTE_READS = 64
  422. class _LifecycleScanBudget:
  423. """Shared work budget for one complete referenced-script walk. ``refusal`` records why the walk
  424. failed closed for a reason other than a lifecycle command (budget, size, device, live SQLite,
  425. cloud placeholder) so the caller can tell the model the real reason (#113944)."""
  426. __slots__ = (
  427. "bytes_remaining",
  428. "lines_remaining",
  429. "paths_remaining",
  430. "refusal",
  431. "remote_reads_remaining",
  432. )
  433. def __init__(self) -> None:
  434. # Read the module constants at construction so tests/operators can lower them at runtime.
  435. self.bytes_remaining = _MAX_LIFECYCLE_SCAN_BYTES
  436. self.lines_remaining = _MAX_LIFECYCLE_SCAN_LINES
  437. self.paths_remaining = _MAX_LIFECYCLE_SCAN_PATHS
  438. self.remote_reads_remaining = _MAX_LIFECYCLE_SCAN_REMOTE_READS
  439. self.refusal: Optional[str] = None
  440. def charge_text(self, text: str) -> bool:
  441. """Charge *text* before tokenization; False when it does not fit."""
  442. # UTF-8 is >= one byte per code point, so the char count is a free lower bound.
  443. if len(text) > self.bytes_remaining:
  444. return False
  445. encoded = len(text.encode("utf-8", errors="replace"))
  446. if encoded > self.bytes_remaining:
  447. return False
  448. lines = text.count("\n") + 1
  449. if lines > self.lines_remaining:
  450. return False
  451. # One huge token is the quadratic shlex case; bound the longest physical line (chars, a
  452. # lower bound on bytes — tight enough for a DoS bound without a per-line encode).
  453. longest = max((len(line) for line in text.split("\n")), default=0)
  454. if longest > _MAX_LIFECYCLE_SCAN_LINE_BYTES:
  455. return False
  456. self.bytes_remaining -= encoded
  457. self.lines_remaining -= lines
  458. return True
  459. def charge_path(self) -> bool:
  460. """Charge one unique referenced path before any local/remote read."""
  461. if self.paths_remaining <= 0:
  462. return False
  463. self.paths_remaining -= 1
  464. return True
  465. def charge_remote_read(self) -> bool:
  466. """Charge one remote-backend read (a network roundtrip each)."""
  467. if self.remote_reads_remaining <= 0:
  468. return False
  469. self.remote_reads_remaining -= 1
  470. return True
  471. def _capped_read_limit(max_bytes: Optional[int]) -> int:
  472. """Per-read byte cap: never above the per-file cap, never negative. One definition so local and
  473. remote reads cannot diverge.
  474. See #76762, #77703.
  475. """
  476. if max_bytes is None:
  477. return _MAX_REFERENCED_SCRIPT_BYTES
  478. return min(_MAX_REFERENCED_SCRIPT_BYTES, max(0, int(max_bytes)))
  479. def lifecycle_scan_root_within_budget(text: str) -> bool:
  480. """Whether *text* may safely enter an optional tokenizer pass (``tools/terminal_tool.py`` gates
  481. its launchctl pre-scan on this). A FRESH budget, independent of the full guard's walk: the
  482. pre-scan may pass while the walk later exhausts, still fail-closed — only the friendlier
  483. launchctl diagnostic is lost. ``False`` is not a verdict: callers must still run the full guard."""
  484. try:
  485. return _LifecycleScanBudget().charge_text(text)
  486. except Exception:
  487. return False
  488. def _budget_exhausted(budget: _LifecycleScanBudget, what: str, depth: int) -> bool:
  489. logger.warning(
  490. "lifecycle guard scan budget exhausted (%s at depth %d); "
  491. "failing closed — see _MAX_LIFECYCLE_SCAN_* in cron/lifecycle_guard.py",
  492. what, depth,
  493. )
  494. budget.refusal = f"the scan budget was exhausted ({what} at depth {depth})"
  495. return True
  496. def _unreadable_reason(path: Path) -> str:
  497. """Name why an *executed* script failed closed without being scanned (live SQLite, device,
  498. oversized). Message-only: the fail-closed verdict itself came from the bounded reader."""
  499. from hermes_cli.sqlite_safe_read import has_live_connection
  500. if has_live_connection(path):
  501. return f"`{path}` is a SQLite database open in this gateway process"
  502. try:
  503. metadata = os.stat(path)
  504. except OSError:
  505. return f"`{path}` could not be read"
  506. if not stat.S_ISREG(metadata.st_mode):
  507. return f"`{path}` is not a regular file"
  508. return f"`{path}` is larger than the scan cap ({_MAX_REFERENCED_SCRIPT_BYTES} bytes) or the remaining walk budget"
  509. def _refuse_unreadable(budget: _LifecycleScanBudget, path: Path, reason: str) -> bool:
  510. logger.warning("lifecycle guard cannot scan referenced script %s: %s; failing closed", path, reason)
  511. budget.refusal = reason
  512. return True
  513. # --- shell tokenization -----------------------------------------------------------------------
  514. def _split_logical_lines(text: str) -> list[str]:
  515. """Split on newlines outside quotes (a quoted newline is data, not a separator); honors
  516. escapes."""
  517. lines: list[str] = []
  518. current: list[str] = []
  519. in_single = in_double = escape = False
  520. for ch in text:
  521. if escape:
  522. escape = False
  523. elif ch == "\\":
  524. escape = True
  525. elif ch == "'" and not in_double:
  526. in_single = not in_single
  527. elif ch == '"' and not in_single:
  528. in_double = not in_double
  529. elif ch == "\n" and not in_single and not in_double:
  530. lines.append("".join(current))
  531. current = []
  532. continue
  533. current.append(ch)
  534. if current:
  535. lines.append("".join(current))
  536. return lines
  537. def _shlex_tokens(line: str) -> list[str]:
  538. """POSIX-tokenize one shell line, honoring quotes and `#` comments; raises ValueError."""
  539. lexer = shlex.shlex(line, posix=True, punctuation_chars=";&|()")
  540. lexer.whitespace_split = True
  541. lexer.commenters = "#"
  542. return list(lexer)
  543. def _split_segments(tokens: list[str], *, keep_controls: bool = False) -> Iterator[list[str]]:
  544. """Yield non-empty runs of *tokens* between control-operator tokens; with *keep_controls* each
  545. control token is also yielded as its own segment so the line can be rebuilt in order."""
  546. segment: list[str] = []
  547. for token in tokens:
  548. if token and set(token) <= _CONTROL_CHARS:
  549. if segment:
  550. yield segment
  551. segment = []
  552. if keep_controls:
  553. yield [token]
  554. continue
  555. segment.append(token)
  556. if segment:
  557. yield segment
  558. def _iter_command_segments(command: str) -> Iterator[list[str]]:
  559. """Yield shell-tokenized command segments per logical line; a line shlex rejects (unbalanced
  560. quotes) falls back to per-physical-line tokenization."""
  561. for line in _split_logical_lines(command.replace("\\\n", "")):
  562. try:
  563. tokens = _shlex_tokens(line)
  564. except ValueError:
  565. for physical_line in line.splitlines():
  566. try:
  567. yield from _split_segments(_shlex_tokens(physical_line))
  568. except ValueError:
  569. continue
  570. continue
  571. yield from _split_segments(tokens)
  572. def _executable_name(token: str) -> str:
  573. """Command name of an executable token. ``Path(token).name`` is "" for ``.``, ``..`` and ``/``;
  574. the POSIX dot-source builtin is spelled ``.``, so fall back to the raw token or ``.
  575. ./helper.sh`` would escape the sourced-script scan."""
  576. return Path(token).name or token
  577. def _peel_transparent_prefixes(segment: list[str], index: int) -> int:
  578. """Index of the command a wrapper chain actually executes. Unchanged if not a wrapper; may be
  579. ``len(segment)`` when a wrapper has no operand — callers must bounds-check."""
  580. for _ in range(_MAX_PREFIX_PEELS):
  581. if index >= len(segment):
  582. return index
  583. name = _executable_name(segment[index])
  584. if name not in _TRANSPARENT_COMMAND_PREFIXES:
  585. return index
  586. value_options = _TRANSPARENT_PREFIX_VALUE_OPTIONS.get(name, frozenset())
  587. index += 1
  588. while index < len(segment):
  589. token = segment[index]
  590. if token == "--":
  591. # POSIX end-of-options: the command starts at the next token.
  592. index += 1
  593. break
  594. if token in value_options:
  595. index += 2
  596. continue
  597. if token.startswith("-") or _ENV_ASSIGNMENT.match(token):
  598. index += 1
  599. continue
  600. break
  601. for _ in range(_TRANSPARENT_PREFIX_OPERANDS.get(name, 0)):
  602. if index < len(segment) and not segment[index].startswith("-"):
  603. index += 1
  604. return index
  605. def _command_token_index(segment: list[str]) -> Optional[int]:
  606. """Return the executable token index after simple env assignments."""
  607. return next((i for i, token in enumerate(segment) if not _ENV_ASSIGNMENT.match(token)), None)
  608. def _executed_command_index(segment: list[str]) -> Optional[int]:
  609. """Index of the command a segment actually executes (env assignments and wrappers peeled)."""
  610. index = _command_token_index(segment)
  611. if index is None:
  612. return None
  613. index = _peel_transparent_prefixes(segment, index)
  614. return index if index < len(segment) else None
  615. def contains_launchctl_submit_command(command: str) -> bool:
  616. """Detect an executed ``launchctl submit``/``bootstrap``, not quoted text.
  617. Label-independent by design: a NEW job's label is attacker-chosen, so a neutral name defeats any
  618. label-anchored regex. Both verbs register a persistent launchd job — never safe in the gateway.
  619. See #62891.
  620. """
  621. for segment in _iter_command_segments(command):
  622. index = _executed_command_index(segment)
  623. if index is not None and _executable_name(segment[index]) == "launchctl":
  624. arguments = segment[index + 1 :]
  625. if arguments and arguments[0].lower() in {"submit", "bootstrap"}:
  626. return True
  627. return False
  628. def _mask_data_sink_arguments(text: str) -> str:
  629. """Replace data-sink executables' arguments with a neutral placeholder.
  630. The regex cannot tell an EXECUTED lifecycle command from the same characters as *data* (a grep
  631. pattern, a SQL literal): every argument of a ``_DATA_SINK_EXECUTABLES`` segment becomes ``arg``
  632. and a match that survives is a real command. Strictly fail-closed: masking is skipped when the
  633. line pipes into a shell/interpreter, any argument carries an execution marker, or the line
  634. cannot be tokenized. Masking can only ALLOW what the plain regex would block, never block more.
  635. """
  636. lines_out: list[str] = []
  637. changed = False
  638. for line in text.splitlines() or [text]:
  639. if _PIPE_TO_INTERPRETER.search(line):
  640. lines_out.append(line)
  641. continue
  642. try:
  643. tokens = _shlex_tokens(line)
  644. except ValueError:
  645. lines_out.append(line)
  646. continue
  647. rebuilt: list[str] = []
  648. for segment in _split_segments(tokens, keep_controls=True):
  649. index = _command_token_index(segment)
  650. if index is not None and Path(segment[index]).name in _DATA_SINK_EXECUTABLES:
  651. arguments = segment[index + 1 :]
  652. if not any(
  653. _DOT_COMMAND_ARGUMENT.match(argument)
  654. or any(marker in argument for marker in _UNSAFE_DATA_ARG_MARKERS)
  655. for argument in arguments
  656. ):
  657. changed = True
  658. rebuilt.extend(segment[: index + 1])
  659. rebuilt.extend("arg" for _ in arguments)
  660. continue
  661. rebuilt.extend(segment)
  662. lines_out.append(" ".join(rebuilt))
  663. return "\n".join(lines_out) if changed else text
  664. def _lifecycle_command_scan_with_data_exemption(text: str) -> bool:
  665. """Lifecycle scan exempting matches inside data arguments: cheap regex first (no-match pays
  666. nothing), then re-scan with data-sink arguments masked; only a surviving match blocks."""
  667. if not contains_gateway_lifecycle_command(text):
  668. return False
  669. normalized = _SHELL_LINE_CONTINUATION.sub(" ", text)
  670. return contains_gateway_lifecycle_command(_mask_data_sink_arguments(normalized))
  671. def _direct_lifecycle_scan(command: str) -> bool:
  672. """Pure-string direct scans: lifecycle regex (data-exempted) + submit."""
  673. return (
  674. _lifecycle_command_scan_with_data_exemption(command)
  675. or contains_launchctl_submit_command(command)
  676. )
  677. # --- path handling ----------------------------------------------------------------------------
  678. def _resolve_lenient(path: Path) -> Path:
  679. """``path.resolve(strict=False)``, falling back to *path* on OSError (unreadable/long) or
  680. ValueError (embedded NUL from decoded binary tokenized as a path) — never crash the guard."""
  681. try:
  682. return path.resolve(strict=False)
  683. except (OSError, ValueError):
  684. return path
  685. def _is_cloud_placeholder_path(path: Path) -> bool:
  686. """True for paths inside a macOS FileProvider-backed subtree. ``O_NONBLOCK`` does not make
  687. regular-file reads non-blocking, so opening an evicted placeholder can wait indefinitely for
  688. hydration before any command timeout starts: identify the boundary from the path alone."""
  689. parts = path.parts
  690. return any(
  691. parts[index - 1] == "Library" and part in _CLOUD_PLACEHOLDER_MARKERS
  692. for index, part in enumerate(parts)
  693. if index
  694. )
  695. def _on_cloud_path(path: Path) -> bool:
  696. """Lexical OR resolved cloud check: covers direct cloud paths and local symlinks into one."""
  697. return _is_cloud_placeholder_path(path) or _is_cloud_placeholder_path(_resolve_lenient(path))
  698. def _expand_candidate_path(candidate: str) -> Optional[Path]:
  699. """Sanitize a tokenized path candidate at the ingestion boundary. Tokens from shlex-splitting
  700. arbitrary (possibly binary-decoded) text can carry NUL or junk that each downstream ``Path`` op
  701. rejects differently (ValueError, RuntimeError when HOME is unset under launchd, OSError); reject
  702. once here. ``None`` = not a real path, nothing to scan.
  703. Every OS-facing ``Path`` operation downstream (``expanduser``, ``os.open``, ``resolve``) raises a
  704. *different* exception for the same junk (``ValueError: embedded null byte``, ``RuntimeError: Could not
  705. determine home directory`` when HOME is unset under launchd, OSError for over-long paths). Rejecting
  706. here — once, before any OS call — is the whole-class fix; catching per-syscall was the whack-a-mole that
  707. produced #76762, #77703, #77780, and #78256.
  708. """
  709. if not candidate or "\x00" in candidate:
  710. return None
  711. try:
  712. return Path(candidate).expanduser()
  713. except (ValueError, RuntimeError, OSError):
  714. return None
  715. def _resolved_or_nothing(candidate: str, cwd: Optional[str]) -> Iterator[Path]:
  716. """Yield *candidate* anchored on *cwd* (or the process cwd) when it is a real path."""
  717. path = _expand_candidate_path(candidate)
  718. if path is None:
  719. return
  720. if not path.is_absolute():
  721. try:
  722. path = Path(cwd or Path.cwd()) / path
  723. except OSError:
  724. # Path.cwd() can raise when the process cwd was deleted.
  725. return
  726. yield path
  727. def _resolve_script_path(script_path: str) -> Optional[Path]:
  728. """Resolve a cron ``script`` value the way ``cron.scheduler`` does (relative paths live under
  729. ``<HERMES_HOME>/scripts/``) so the guard scans the file that will actually run."""
  730. from hermes_constants import get_hermes_home
  731. raw = _expand_candidate_path(script_path)
  732. if raw is None:
  733. return None
  734. if raw.is_absolute():
  735. return raw
  736. try:
  737. return get_hermes_home() / "scripts" / raw
  738. except (RuntimeError, OSError):
  739. # get_hermes_home() falls back to Path.home(), which raises when neither HERMES_HOME nor
  740. # HOME is resolvable (launchd/systemd) — same ingestion contract: nothing to scan.
  741. return None
  742. def _resolve_script_directory(script_path: str) -> Optional[str]:
  743. """Return the directory *script_path* resolves to, handling relative names."""
  744. try:
  745. path = _resolve_script_path(script_path)
  746. if path is not None and path.is_absolute():
  747. return str(path.parent)
  748. except Exception:
  749. pass
  750. return None
  751. # --- referenced-script discovery --------------------------------------------------------------
  752. def _iter_option_values(segment: list[str], start: int, option: str) -> Iterator[str]:
  753. """Yield values given to *option*, in both ``--opt v`` and ``--opt=v`` form."""
  754. prefix = option + "="
  755. for position in range(start + 1, len(segment)):
  756. token = segment[position]
  757. if token == option and position + 1 < len(segment):
  758. yield segment[position + 1]
  759. elif token.startswith(prefix):
  760. yield token[len(prefix):]
  761. def _references_at(segment: list[str], index: int, cwd: Optional[str]) -> Iterator[Path]:
  762. """Yield the scripts the token at *index* executes, if any."""
  763. if index >= len(segment):
  764. return
  765. executable = segment[index]
  766. executable_name = _executable_name(executable)
  767. if executable_name in {".", "source"}:
  768. if len(segment) > index + 1:
  769. yield from _resolved_or_nothing(segment[index + 1], cwd)
  770. return
  771. if executable_name in _SHELL_EXECUTABLES:
  772. arguments = segment[index + 1 :]
  773. arg_index = 0
  774. while arg_index < len(arguments):
  775. argument = arguments[arg_index]
  776. if argument == "--":
  777. arg_index += 1
  778. break
  779. if argument in _SHELL_COMMAND_FLAGS:
  780. break
  781. if argument in _SHELL_OPTIONS_WITH_VALUES:
  782. arg_index += 2
  783. continue
  784. if argument.startswith("-"):
  785. arg_index += 1
  786. continue
  787. break
  788. if arg_index < len(arguments) and arguments[arg_index] not in _SHELL_COMMAND_FLAGS:
  789. yield from _resolved_or_nothing(arguments[arg_index], cwd)
  790. return
  791. # A bare "/" is pathlib's division operator in Python sources, not an executable; resolving it
  792. # hits the filesystem root and fails the regular-file check, hard-blocking innocent .py scripts.
  793. if executable.strip("/") and ("/" in executable or executable.endswith((".sh", ".bash", ".zsh"))):
  794. yield from _resolved_or_nothing(executable, cwd)
  795. def _iter_referenced_shell_scripts(command: str, *, cwd: Optional[str] = None) -> Iterator[Path]:
  796. """Yield scripts executed directly or through a POSIX shell. Each segment is read at the
  797. original token AND at the peeled wrapper target — additive on purpose: peeling must never REMOVE
  798. a reference (a local ``./timeout`` is a script, not the coreutils wrapper)."""
  799. for segment in _iter_command_segments(command):
  800. index = _command_token_index(segment)
  801. if index is None:
  802. continue
  803. yield from _references_at(segment, index, cwd)
  804. peeled = _peel_transparent_prefixes(segment, index)
  805. if peeled != index:
  806. yield from _references_at(segment, peeled, cwd)
  807. def _iter_shell_command_payloads(command: str) -> Iterator[str]:
  808. """Yield code passed through ``sh|bash|... -c`` (and ``su -c`` / ``env -S``) for recursive
  809. scanning."""
  810. for segment in _iter_command_segments(command):
  811. index = _command_token_index(segment)
  812. if index is None:
  813. continue
  814. # Read at the ORIGINAL token: peeling past `su`/`env` would discard the command option.
  815. for option in _STRING_COMMAND_OPTIONS.get(_executable_name(segment[index]), ()):
  816. yield from _iter_option_values(segment, index, option)
  817. index = _executed_command_index(segment)
  818. if index is None or _executable_name(segment[index]) not in _SHELL_EXECUTABLES:
  819. continue
  820. arguments = segment[index + 1 :]
  821. for arg_index, argument in enumerate(arguments[:-1]):
  822. if argument in _SHELL_COMMAND_FLAGS:
  823. yield arguments[arg_index + 1]
  824. break
  825. # --- referenced-script reading ----------------------------------------------------------------
  826. def _has_binary_magic(data: bytes) -> bool:
  827. """True when *data* starts with a known compiled-binary signature. Deliberately narrower than
  828. "contains a NUL": ``bash`` still executes a NUL-bearing script, so a padded script must not
  829. bypass the scan. A shebang always wins (interpreted, never binary). Extensions are not
  830. consulted: a suffixless script must still be scanned and fail closed if oversized."""
  831. if data.startswith(b"#!"):
  832. return False
  833. return data.startswith(_BINARY_MAGICS)
  834. def _read_referenced_script(
  835. path: Path, *, max_bytes: Optional[int] = None
  836. ) -> tuple[Optional[str], bool]:
  837. """Read a referenced script without racing SQLite connection lifecycle.
  838. The registry check must cover the complete ``open``/``read``/``close``
  839. sequence. A separate ``has_live_connection`` check would leave a race in
  840. which another thread opens SQLite after the check but before this function
  841. closes its descriptor, cancelling that connection's POSIX locks.
  842. """
  843. from hermes_cli.sqlite_safe_read import LiveConnectionError, offline_file_access
  844. try:
  845. with offline_file_access(path, what="read referenced script"):
  846. return _read_referenced_script_unlocked(path, max_bytes=max_bytes)
  847. except LiveConnectionError:
  848. return None, True
  849. except (OSError, ValueError):
  850. # Invalid path values, including embedded NULs, are not scripts.
  851. return None, False
  852. def _read_referenced_script_unlocked(
  853. path: Path, *, max_bytes: Optional[int] = None
  854. ) -> tuple[Optional[str], bool]:
  855. """Return ``(text, unsafe)`` using bounded, regular-file-only reads.
  856. Shared choke point for every local script read, so the cloud-placeholder refusal lives here: a
  857. FileProvider path is never opened — not even to check hydration — because an evicted
  858. placeholder's ``open()`` can hang preflight. Lexical check: direct paths; resolved: symlinks.
  859. ``max_bytes`` lowers the per-file cap to what the calling walk can still afford.
  860. See #88052.
  861. """
  862. byte_limit = _capped_read_limit(max_bytes)
  863. if _on_cloud_path(path):
  864. return None, True
  865. flags = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0)
  866. try:
  867. descriptor = os.open(path, flags)
  868. except (OSError, ValueError):
  869. # OSError: unreadable/missing/over-long. ValueError: embedded NUL in *path*. Either is
  870. # "nothing to scan" — never crash the guard.
  871. return None, False
  872. try:
  873. # ValueError: an embedded NUL byte in *path* itself — a binary's decoded bytes tokenized into a
  874. # bogus script path by the recursion (#77703).
  875. metadata = os.fstat(descriptor)
  876. # Directories are not scripts. Docker Desktop writes ``fpath=(~/.docker/completions …)`` into
  877. # ``~/.zshrc``; the walk then treats that dir as a referenced script and used to fail-closed,
  878. # blocking ``source ~/.zshrc`` (#86753). Devices/sockets stay fail-closed.
  879. if not stat.S_ISREG(metadata.st_mode):
  880. # Directories are not scripts (`fpath=(~/.docker/completions …)` in ~/.zshrc must not
  881. # block `source ~/.zshrc`). Devices/sockets stay fail-closed.
  882. return None, not stat.S_ISDIR(metadata.st_mode)
  883. # Sniff a small prefix first: compiled binaries are never shell scripts, so skip them
  884. # WITHOUT reading the rest or feeding decoded garbage into the recursion.
  885. # Deliberately NOT keyed on the mere presence of a NUL byte (#77927): bash executes a text script
  886. # straight past an embedded NUL, so NUL-bearing text must fall through to the magic-number check +
  887. # NUL-strip below.
  888. data = os.read(descriptor, _BINARY_SNIFF_BYTES)
  889. if _has_binary_magic(data):
  890. return None, False
  891. # A regular file whose size already exceeds the cap fails closed without reading it (the
  892. # walk budget can be far below 1 MiB).
  893. if metadata.st_size > byte_limit:
  894. return None, True
  895. # Read the remainder (bounded); loop because os.read may return short.
  896. while len(data) <= byte_limit:
  897. chunk = os.read(descriptor, byte_limit + 1 - len(data))
  898. if not chunk:
  899. break
  900. data += chunk
  901. except OSError:
  902. return None, False
  903. finally:
  904. os.close(descriptor)
  905. if _has_binary_magic(data):
  906. return None, False
  907. # Size check BEFORE NUL stripping: stripping shrinks the buffer and would let an oversized file
  908. # slip under the threshold past this fail-closed branch.
  909. if len(data) > byte_limit:
  910. return None, True
  911. if b"\x00" in data:
  912. data = data.replace(b"\x00", b"")
  913. return data.decode("utf-8", errors="replace"), False
  914. def _sanitize_remote_script_text(
  915. text: Optional[str], *, max_bytes: Optional[int] = None
  916. ) -> tuple[Optional[str], bool]:
  917. """Apply the local-read contract to text from an untrusted ``read_remote_script`` callback: NUL
  918. means binary (nothing to scan, checked first); oversized fails closed. Size compares re-encoded
  919. *bytes* (matching the ``head -c`` wire bound): a >1 MiB multibyte file truncated at the byte cap
  920. decodes to fewer chars, and a char count would scan instead of failing.
  921. The recursion boundary must not trust its callbacks: any backend (SSH, Modal, Daytona, or a future one)
  922. can hand back raw binary bytes decoded as text, or arbitrarily large output. Enforced here rather than
  923. inside each callback so the guarantee holds for every callback, not just the ones we hardened. See
  924. #76762, #77703.
  925. """
  926. if not text or "\x00" in text:
  927. return None, False
  928. byte_limit = _capped_read_limit(max_bytes)
  929. if len(text) > byte_limit:
  930. return None, True # chars <= bytes: over the cap without encoding
  931. if len(text.encode("utf-8", errors="replace")) > byte_limit:
  932. return None, True
  933. return text, False
  934. def _read_script_for_scanning(script_path: str) -> tuple[str, Optional[str]]:
  935. """``(text, refusal)``: read a cron script with the bounded scanner. Non-regular/oversized/live
  936. SQLite inputs fail closed with a NAMED *refusal* (never a lifecycle-shaped verdict); missing or
  937. unreadable paths stay empty so scheduler validation reports them."""
  938. resolved = _resolve_script_path(script_path)
  939. if resolved is None:
  940. return "", None
  941. script_text, unsafe = _read_referenced_script(resolved)
  942. if unsafe:
  943. return "", _unreadable_reason(resolved)
  944. return script_text or "", None
  945. # --- recursive walk ---------------------------------------------------------------------------
  946. def _contains_unsafe_gateway_action(
  947. command: str, *, cwd: Optional[str], depth: int, visited: set[Path], budget: _LifecycleScanBudget,
  948. read_remote_script: Optional[_ReadRemoteScriptFn] = None, executed: bool = True,
  949. ) -> bool:
  950. """``executed=False`` means *command* is the content of a file that is only MENTIONED in inert
  951. (masked) text: it is still scanned for a literal lifecycle command, but "could not scan" (budget,
  952. depth, size, device, live SQLite, cloud) is "nothing to scan" there, never a block (#113944)."""
  953. # Charge BEFORE _direct_lifecycle_scan: every scan in it tokenizes with shlex.
  954. if not budget.charge_text(command):
  955. return _budget_exhausted(budget, "text", depth) if executed else False
  956. if _direct_lifecycle_scan(command):
  957. return True
  958. if depth >= _MAX_REFERENCED_SCRIPT_DEPTH:
  959. return executed
  960. def recurse(text: str, cwd: Optional[str], executed: bool) -> bool:
  961. return _contains_unsafe_gateway_action(
  962. text, cwd=cwd, depth=depth + 1, visited=visited, budget=budget,
  963. read_remote_script=read_remote_script, executed=executed,
  964. )
  965. # The walks below must see the same masked view `_direct_lifecycle_scan` sees (#110422): a
  966. # path or `sh -c` payload inside a provably-inert heredoc body is never shell-executed, and an
  967. # oversized data file mentioned there otherwise fails closed as a "script".
  968. from tools.shell_heredoc import strip_inert_heredoc_bodies
  969. walk_command = strip_inert_heredoc_bodies(command)
  970. for payload in _iter_shell_command_payloads(walk_command):
  971. if recurse(payload, cwd, executed):
  972. return True
  973. # Paths named only inside a masked body are still READ: an interpreter body that hands
  974. # `/x/restart.sh` to os.system() executes it. Only the fail-closed verdicts (cloud placeholder,
  975. # oversized/binary, budget) stay restricted to the executed view — a mere data mention must not
  976. # trip them. Executed candidates come first so a mention never starves a real script's budget.
  977. candidates = [(path, executed) for path in _iter_referenced_shell_scripts(walk_command, cwd=cwd)]
  978. if walk_command != command:
  979. candidates += [(path, False) for path in _iter_referenced_shell_scripts(command, cwd=cwd)]
  980. for script_path, candidate_executed in candidates:
  981. # Do not touch a FileProvider path even to discover whether the file is hydrated.
  982. if _on_cloud_path(script_path):
  983. if candidate_executed:
  984. return _refuse_unreadable(
  985. budget, script_path,
  986. f"`{script_path}` lives on a cloud-synced path (iCloud Drive / "
  987. "~/Library/CloudStorage) that the guard refuses to open",
  988. )
  989. continue
  990. resolved = _resolve_lenient(script_path)
  991. if resolved in visited:
  992. continue
  993. if not budget.charge_path():
  994. if candidate_executed:
  995. return _budget_exhausted(budget, "paths", depth)
  996. break # remaining candidates are all mentions
  997. visited.add(resolved)
  998. # Never read more than the walk can still afford to tokenize; a file larger than the
  999. # remainder fails closed exactly like an oversized one.
  1000. script_text, unsafe = _read_referenced_script(script_path, max_bytes=budget.bytes_remaining)
  1001. if unsafe:
  1002. if candidate_executed:
  1003. return _refuse_unreadable(budget, script_path, _unreadable_reason(script_path))
  1004. continue
  1005. if script_text is None and read_remote_script is not None:
  1006. # Local path missing; the remote backend's output crosses the same trust boundary as a
  1007. # local read — sanitize identically (binary skip + size fail-closed).
  1008. if not budget.charge_remote_read():
  1009. if candidate_executed:
  1010. return _budget_exhausted(budget, "remote reads", depth)
  1011. break
  1012. script_text, unsafe = _sanitize_remote_script_text(
  1013. read_remote_script(str(script_path)), max_bytes=budget.bytes_remaining
  1014. )
  1015. if unsafe:
  1016. if candidate_executed:
  1017. return _refuse_unreadable(
  1018. budget, script_path,
  1019. f"`{script_path}` read from the backend exceeds the scan cap "
  1020. f"({_MAX_REFERENCED_SCRIPT_BYTES} bytes) or the remaining walk budget",
  1021. )
  1022. continue
  1023. if not script_text:
  1024. continue
  1025. # Relative references inside a script resolve against that script's directory, not the cwd.
  1026. if recurse(script_text, _resolve_script_directory(str(resolved)) or cwd, candidate_executed):
  1027. return True
  1028. return False
  1029. def scan_gateway_lifecycle(
  1030. command: str, *, cwd: Optional[str] = None,
  1031. read_remote_script: Optional[_ReadRemoteScriptFn] = None,
  1032. ) -> tuple[bool, Optional[str]]:
  1033. """``(unsafe, refusal)``: *refusal* names a non-lifecycle reason the walk failed closed (budget,
  1034. size, device, live SQLite, cloud) so callers can tell the model; ``None`` when the verdict is a
  1035. real lifecycle command or the command is allowed.
  1036. Total by construction: never raises. Direct scans are pure string ops; the referenced-script
  1037. walk (filesystem, remote backends, shlex on decoded bytes) is best-effort defense-in-depth — an
  1038. unexpected failure is logged and treated as "walk found nothing".
  1039. This is the contract #76762 established ("a guarded path must never crash the guard") enforced at the
  1040. boundary instead of per-syscall: a guard crash propagates out of ``tools/terminal_tool.py`` and breaks
  1041. every terminal command until the gateway restarts (#77780, #78256), which is strictly worse than either
  1042. verdict.
  1043. """
  1044. budget = _LifecycleScanBudget()
  1045. try:
  1046. unsafe = _contains_unsafe_gateway_action(
  1047. command, cwd=cwd, depth=0, visited=set(), budget=budget,
  1048. read_remote_script=read_remote_script,
  1049. )
  1050. return unsafe, budget.refusal if unsafe else None
  1051. except Exception:
  1052. logger.warning(
  1053. "lifecycle guard referenced-script walk failed; "
  1054. "falling back to direct-scan verdict",
  1055. exc_info=True,
  1056. )
  1057. try:
  1058. return _direct_lifecycle_scan(command), None
  1059. except Exception:
  1060. # If even the data-argument masker fails, fall to raw regex + submit scan: stay total.
  1061. return (contains_gateway_lifecycle_command(command)
  1062. or contains_launchctl_submit_command(command)), None
  1063. def contains_gateway_lifecycle_command_or_referenced_script(
  1064. command: str, *, cwd: Optional[str] = None,
  1065. read_remote_script: Optional[_ReadRemoteScriptFn] = None,
  1066. ) -> bool:
  1067. """Detect lifecycle/submit commands, including bounded nested scripts (see
  1068. ``scan_gateway_lifecycle`` for the contract)."""
  1069. return scan_gateway_lifecycle(command, cwd=cwd, read_remote_script=read_remote_script)[0]
  1070. def check_gateway_lifecycle(prompt: Optional[str], script: Optional[str] = None) -> None:
  1071. """Raise ``GatewayLifecycleBlocked`` if *prompt* or *script* contains a gateway-lifecycle
  1072. command. The script is read from disk and concatenated with the prompt so a command cannot slip
  1073. through by being split across the two. Callers let the ``ValueError``-shaped exception
  1074. propagate."""
  1075. combined = prompt or ""
  1076. python_script = False
  1077. refusal: Optional[str] = None
  1078. if script:
  1079. resolved_script = _resolve_script_path(script)
  1080. # Attribute the refusal correctly: not a lifecycle command, but a cloud path never opened.
  1081. if resolved_script is not None and _on_cloud_path(resolved_script):
  1082. raise GatewayLifecycleBlocked(
  1083. # Attribute the refusal correctly: the script is not known to contain a lifecycle command —
  1084. # it lives on a cloud-synced FileProvider path (iCloud Drive / ~/Library/CloudStorage) that
  1085. # the guard refuses to open because an evicted placeholder can hang preflight indefinitely
  1086. # (#88052). Fail closed with the real reason instead of implying a dangerous lifecycle
  1087. # command.
  1088. "Blocked: the cron script lives on a cloud-synced path "
  1089. "(iCloud Drive / ~/Library/CloudStorage). Opening an "
  1090. "evicted FileProvider placeholder can hang the guard's "
  1091. "preflight scan indefinitely, so it is refused without "
  1092. "being read. Move the script to a local, non-cloud path "
  1093. "(e.g. ~/.hermes/scripts/) and recreate the job."
  1094. )
  1095. python_script = resolved_script is not None and resolved_script.suffix == ".py"
  1096. script_text, refusal = _read_script_for_scanning(script)
  1097. if script_text:
  1098. combined = f"{combined}\n{script_text}"
  1099. if refusal:
  1100. unsafe = True
  1101. elif python_script:
  1102. # Python runs via the interpreter, never a POSIX shell, and the shell reference walk is a
  1103. # false-positive generator on Python sources (pathlib "/" resolves to the filesystem root).
  1104. # The regex still scans the full text; non-regular/oversized files fail closed above (named refusal).
  1105. # The data-exemption masker tokenizes with shlex, so it is charged against the walk budget.
  1106. # The direct command regex below still scans the full text, so a literal `hermes gateway restart`
  1107. # embedded in a .py script is still blocked. See #77131, #78398.
  1108. budget = _LifecycleScanBudget()
  1109. if not budget.charge_text(combined):
  1110. unsafe = _budget_exhausted(budget, "text", 0)
  1111. refusal = budget.refusal
  1112. else:
  1113. unsafe = _lifecycle_command_scan_with_data_exemption(combined)
  1114. else:
  1115. unsafe, refusal = scan_gateway_lifecycle(
  1116. combined, cwd=_resolve_script_directory(script) if script else None
  1117. )
  1118. if unsafe and refusal:
  1119. raise GatewayLifecycleBlocked(
  1120. f"Blocked: the lifecycle guard could not scan this cron job or referenced script: {refusal}. "
  1121. "Nothing in the job is known to contain a gateway lifecycle command, but a script "
  1122. "the job executes must be scannable (a regular text file under 1 MiB) before it can run."
  1123. )
  1124. if unsafe:
  1125. raise GatewayLifecycleBlocked(
  1126. "Blocked: cron job contains a gateway lifecycle command or persistent "
  1127. "launchctl submit operation. This is blocked to prevent agent-driven "
  1128. "SIGTERM-respawn loops under launchd/systemd supervision "
  1129. "(#30719). Run `hermes gateway restart` from a shell outside "
  1130. "the running gateway instead."
  1131. )