mcp_launch.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  1. """What an MCP consent row will run or contact, worded for the card before the user approves.
  2. Install reads the catalog manifest's transport; enable and authorize read the configured
  3. ``mcp_servers`` entry. The line is display-only and never carries env values or headers.
  4. The card exists so the user consents to what will run, so hiding execution is worse than showing a
  5. secret. The line is never cut, and a value is masked only when its own name says it is secret: a long
  6. flag such as ``--api-key=…`` / ``--token …`` / ``--token:…``, a ``GITHUB_TOKEN=…`` assignment, a
  7. ``docker``-style ``-e KEY=…`` / ``--env KEY=…``, an ``Authorization:`` / ``Cookie:`` / API-key header
  8. arg, a URL userinfo password, a secret-named URL query value (``?token=``, ``?key=``). A named secret's
  9. value is masked whatever it holds (shell metacharacters included) — execve argv never runs a shell.
  10. Positional args, short flags (``-p``, ``-k``, ``-t``), packages, images, scripts and URL paths are
  11. always shown, even when one of them is a key: the user approves that exact command. The program given
  12. to an interpreter's inline-program flag (``sh -c``, ``python -c``, ``node -e``, ``perl -e``), found
  13. past any wrapper (``env``, ``npx -y node``, ``sudo -u x bash``), is never masked, and a bare
  14. ``KEY=VALUE`` holding a line break or shell metacharacter is shown too, so a secret name inside code
  15. cannot hide the code. An argument is quoted when it would not read back as exactly that one argument
  16. (whitespace, a quote, backslash or shell metacharacter, an empty argument), so ``shlex.split`` of the
  17. line is the argv shown; an argument with control or invisible code points is a bash ``$'…'`` word whose
  18. escapes keep a real newline distinct from the literal text ``\n``.
  19. """
  20. from __future__ import annotations
  21. import re
  22. import shlex
  23. import unicodedata
  24. from typing import Any, Optional
  25. from agent.redact import SECRET_HEADER_NAME_LIST, sanitize_command_for_display
  26. # A flag or query name that says its value is secret, after camelCase/snake_case fold to kebab. The
  27. # word ends its segment (``--access-token``, ``--apikey``; not ``--tokenizer``, ``--max-tokens``),
  28. # ``auth`` is a whole segment (not ``--author``), and ``pass``/``pwd`` are the whole name.
  29. _SECRET_NAME_RE = re.compile(
  30. r"(?:token|secret|passw(?:or)?d|api-?key|credentials?|private-?key|bearer)(?=-|$)"
  31. r"|(?:^|-)auth(?:orization)?(?=-|$)|^(?:pass|pwd)$")
  32. # Names for where a secret lives or how it is supplied, not the secret: ``--token-file``,
  33. # ``--password-stdin``, ``--auth-type``; ``--no-auth`` is a switch, so the next arg is not its value.
  34. _NOT_A_VALUE_RE = re.compile(
  35. r"-(?:file|path|dir|env|var|name|url|uri|stdin|prompt|type|mode|method|scheme|helper|cmd|command)$"
  36. r"|^(?:no|disable|enable|skip|use|with|without)-")
  37. _CAMEL_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
  38. # ``KEY=VALUE`` (an ``env`` prefix, a ``-e`` value): the key's last identifier carries the name.
  39. _ASSIGN_RE = re.compile(r"^([^\s=]*?)([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.DOTALL)
  40. # A bare ``KEY=VALUE`` positional is ambiguous: a real env assignment, or code an interpreter runs
  41. # (``sh -c 'TOKEN=x; curl …'``). Only when the value can only be data (no line break, ``;``, ``|``,
  42. # ``&``, ``$(…)``, a backtick, brackets, quotes) is it masked; a value that can run or split is shown.
  43. # The value of a recognised secret mechanism (a named flag, ``-e``/``--env``, a header, URL userinfo
  44. # or query) is always masked instead, whatever it holds — that is never an interpreter's code.
  45. _PLAIN_VALUE_RE = re.compile(r"[^\s;|&$`<>(){}'\"\\]+")
  46. # A header value is masked whole; only a line break or control (header injection) keeps it visible.
  47. _PLAIN_HEADER_VALUE_RE = re.compile(r"[^\x00-\x1f\x7f]+")
  48. # A precise interpreter word (command or arg, ``/usr/bin/python3.12``, ``bash.exe``). Names are
  49. # listed in full, never ``[a-z]*sh`` (that caught ``ssh`` and ``publish`` and hid the secret after).
  50. _INTERPRETER_RE = re.compile(
  51. r"(?:sh|bash|zsh|dash|ksh|mksh|ash|fish|csh|tcsh|rc|python[\d.]*|pypy[\d.]*|node(?:js)?|deno|bun|"
  52. r"tsx|ts-node|ruby|perl[\d.]*|php[\d.]*|lua(?:jit)?|pwsh|powershell|osascript|tclsh|r|rscript|elixir)(?:\.exe)?",
  53. re.IGNORECASE)
  54. # Commands that run a following command; the real command (and whether it is an interpreter) is found
  55. # past the wrapper's options, so ``-e`` after ``npx -y node`` is node's eval, not a docker env var.
  56. _WRAPPERS = frozenset({
  57. "env", "sudo", "doas", "nohup", "setsid", "nice", "ionice", "time", "timeout", "stdbuf",
  58. "command", "exec", "busybox", "chroot", "xargs", "uv", "uvx", "npx", "pnpm", "bunx", "pipx",
  59. "poetry", "yarn",
  60. })
  61. _INLINE_CODE_FLAG_RE = re.compile(r"(-[ceEpr]|--eval|--print|--?command)(=?)(.*)", re.IGNORECASE | re.DOTALL)
  62. _SECRET_ENV_RE = re.compile(r"TOKEN|SECRET|PASSW(?:OR)?D|API_?KEY|AUTH(?!OR(?!IZ))|CREDENTIAL|PRIVATE_?KEY",
  63. re.IGNORECASE)
  64. # One header arg, alone or as ``--header=…`` / attached ``-H…``: the auth scheme stays, the value goes.
  65. _HEADER_NAMES = "|".join(sorted({"cookie", *SECRET_HEADER_NAME_LIST}, key=len, reverse=True))
  66. _SECRET_HEADER_ARG_RE = re.compile(
  67. rf"^((?:--header[=:]?|-H)?[ \t]*(?:(?:proxy-)?authorization[ \t]*:[ \t]*(?:(?:bearer|basic|token|digest)[ \t]+)?"
  68. rf"|(?:{_HEADER_NAMES})[ \t]*:[ \t]*))(\S.*)$",
  69. re.IGNORECASE | re.DOTALL,
  70. )
  71. _LONG_FLAG_RE = re.compile(r"--([^=:]+)([=:]?)")
  72. def _is_secret_name(name: str) -> bool:
  73. """True when a flag's or query parameter's own name says its value is a secret."""
  74. norm = _CAMEL_RE.sub("-", name).lower().replace("_", "-").replace(".", "-")
  75. return bool(_SECRET_NAME_RE.search(norm)) and not _NOT_A_VALUE_RE.search(norm)
  76. def _mask_arg(arg: str, interpreter: bool = False) -> tuple[str, bool]:
  77. """``(shown, mask_next)`` for one argv entry. ``interpreter`` is True while the command word (argv[0])
  78. is an interpreter and its own options are still being read: a named-secret flag then shows its value
  79. (it may be the script or its code) instead of masking it, but an attached ``--flag=`` secret is still
  80. masked, since that value is never the program."""
  81. if (header := _SECRET_HEADER_ARG_RE.match(arg)) and _PLAIN_HEADER_VALUE_RE.fullmatch(header.group(2)):
  82. return f"{header.group(1)}***", False
  83. if arg.startswith("--"):
  84. flag = _LONG_FLAG_RE.match(arg)
  85. if flag and _is_secret_name(flag.group(1)):
  86. if not flag.group(2):
  87. return arg, not interpreter
  88. return f"{flag.group(0)}***", False # ``--api-key=VALUE``: the value is never the program
  89. # ``--env=GITHUB_TOKEN=…``: the assignment's own key names the secret.
  90. if flag and flag.group(2):
  91. return f"{flag.group(0)}{_mask_assignment(arg[flag.end():], force=True)}", False
  92. return arg, False
  93. # ``KEY=VALUE`` alone, or attached to a short flag (``-eGITHUB_TOKEN=…``, java ``-Dapi.token=…``).
  94. return _mask_assignment(arg), False
  95. def _mask_assignment(text: str, force: bool = False) -> str:
  96. """A ``KEY=VALUE`` whose key names a secret, with the value masked. ``force`` masks it whatever the
  97. value holds (the value of ``-e``/``--env``/``--flag=``); otherwise only a plain data value is masked,
  98. so a bare ``KEY=VALUE`` that is really an interpreter's inline code is shown."""
  99. assign = _ASSIGN_RE.match(text)
  100. if assign and _SECRET_ENV_RE.search(assign.group(2)) and (force or _PLAIN_VALUE_RE.fullmatch(assign.group(3))):
  101. return f"{assign.group(1)}{assign.group(2)}=***"
  102. return text
  103. def _is_interpreter(word: str) -> bool:
  104. return bool(_INTERPRETER_RE.fullmatch(re.split(r"[\\/]", word)[-1]))
  105. def _effective_is_interpreter(command: str, args: list[str]) -> bool:
  106. """Whether the command that actually runs is an interpreter, looking past wrapper words. ``env …
  107. sh``, ``npx -y node`` and ``sudo -u x bash`` all resolve to an interpreter, so a later ``-e`` is its
  108. eval flag, not a ``docker``-style env var worth masking."""
  109. if _is_interpreter(command):
  110. return True
  111. if re.split(r"[\\/]", command)[-1] not in _WRAPPERS:
  112. return False
  113. return any(_is_interpreter(a) for a in args if not a.startswith("-") and "=" not in a)
  114. def _mask_flag_values(command: str, args: list[str]) -> list[str]:
  115. out: list[str] = []
  116. interp = _is_interpreter(command) # argv[0] is an interpreter; its own flags may carry inline code
  117. allow_env_force = not _effective_is_interpreter(command, args)
  118. code_next = mask_next = env_next = False
  119. for arg in args:
  120. # The program an interpreter runs inline (``sh -c 'GITHUB_TOKEN=x; curl …'``) is what the user
  121. # approves: shown whole, whatever names it mentions.
  122. if code_next:
  123. out.append(arg)
  124. code_next = interp = False
  125. continue
  126. if mask_next:
  127. mask_next = False
  128. if not arg.startswith("-"): # a following flag is the next flag, not the secret's value
  129. out.append("***")
  130. continue
  131. if env_next:
  132. out.append(_mask_assignment(arg, force=True))
  133. env_next = False
  134. continue
  135. if interp and (inline := _INLINE_CODE_FLAG_RE.fullmatch(arg)):
  136. out.append(arg)
  137. code_next = not (inline.group(2) or inline.group(3))
  138. interp = code_next # attached code (``-ccode``/``--eval=code``) ends the option region now
  139. continue
  140. if interp and not arg.startswith("-"):
  141. interp = False # the script positional: its own args mask normally from here
  142. # ``docker``-style ``-e KEY=VALUE`` / ``--env KEY=VALUE`` (only when no interpreter runs).
  143. if allow_env_force and arg in ("-e", "--env"):
  144. out.append(arg)
  145. env_next = True
  146. continue
  147. shown, mask_next = _mask_arg(arg, interpreter=interp)
  148. out.append(shown)
  149. return out
  150. _URL_RE = re.compile(r"\b[A-Za-z][A-Za-z0-9+.-]*://[^\s]+")
  151. def _mask_query_pair(pair: str) -> str:
  152. key, eq, _value = pair.partition("=")
  153. # ``?key=`` is an API key in a URL (``?key=AIza…``); as a flag, ``--key`` is often a key *file*.
  154. return f"{key}=***" if eq and (key.lower() == "key" or _is_secret_name(key)) else pair
  155. def _mask_url(match: re.Match[str]) -> str:
  156. """A userinfo password and secret-named query values become ``***``. Host, path, other query
  157. values and the fragment stay: the path of a ``deno run https://…`` URL is the code that runs."""
  158. url = match.group(0)
  159. head, sep, rest = url.partition("://")
  160. rest, hash_, fragment = rest.partition("#")
  161. rest, qmark, query = rest.partition("?")
  162. authority, slash, path = rest.partition("/")
  163. userinfo, at, host = authority.rpartition("@")
  164. if at and ":" in userinfo: # a userinfo password is always secret, whatever it holds
  165. authority = f"{userinfo.partition(':')[0]}:***@{host}"
  166. out = f"{head}{sep}{authority}{slash}{path}"
  167. if qmark:
  168. out += "?" + "&".join(_mask_query_pair(pair) for pair in query.split("&"))
  169. return out + hash_ + fragment
  170. # Tab and newline are the two controls the approval sanitizer keeps; the card draws one line.
  171. _LINE_BREAKS = str.maketrans({"\t": "\\t", "\n": "\\n"})
  172. def _escape_composing(ch: str) -> str:
  173. # A combining mark draws over the letter before it (``pk\u0336g`` reads as a struck ``k``) and
  174. # U+FFFC draws as a box. Other non-ASCII letters stay as written (homoglyphs are out of scope).
  175. if ch == "\ufffc" or unicodedata.category(ch) in ("Mn", "Me"):
  176. return ch.encode("unicode_escape").decode("ascii")
  177. return ch
  178. def _visible(text: str) -> str:
  179. """Every control, format (bidi overrides/isolates, zero-width, BOM, soft hyphen), separator and
  180. combining code point as a visible escape such as ``\\u202e``: the line must read as the argv runs,
  181. and the user should see that an arg is unusual rather than a cleaned-up version of it."""
  182. shown = sanitize_command_for_display(text.translate(_LINE_BREAKS))
  183. return shown if shown.isascii() else "".join(map(_escape_composing, shown))
  184. def scrub(text: str) -> str:
  185. """One value as written (spaces kept), named secrets in URLs masked, never cut. The shape-based
  186. secret redactor is not run here: it masks positionals that merely look like keys (a package
  187. named ``sk-…``, a JWT-shaped script arg), and the card must not hide what runs."""
  188. return _visible(_URL_RE.sub(_mask_url, text))
  189. # Characters that change how a shell or ``shlex.split`` reads a word: such a word, or an empty one,
  190. # is quoted, so ``python -c 'X=print(1)'`` reads as the one argument it is.
  191. _NEEDS_QUOTE_RE = re.compile(r"[\s'\"\\;|&$`<>(){}]")
  192. # Common controls get a readable name; every other hidden code point gets its ``\\x``/``\\u`` escape.
  193. _CONTROL_NAMES = {"\n": "\\n", "\t": "\\t", "\r": "\\r"}
  194. def _is_hidden(ch: str) -> bool:
  195. """A control, format (bidi override/isolate, zero-width, BOM, soft hyphen), non-space separator or
  196. combining code point: shown as an escape so the line reads as the argv runs, never a hidden char."""
  197. return not ch.isprintable() or unicodedata.category(ch) in ("Mn", "Me", "Mc") or ch == "\ufffc"
  198. def _escape_cp(ch: str) -> str:
  199. if ch in _CONTROL_NAMES:
  200. return _CONTROL_NAMES[ch]
  201. o = ord(ch)
  202. return f"\\x{o:02x}" if o <= 0xff else (f"\\u{o:04x}" if o <= 0xffff else f"\\U{o:08x}")
  203. def _ansi_c_quote(text: str) -> str:
  204. """An arg holding hidden code points as a bash ``$'…'`` word: backslashes are doubled and each hidden
  205. code point is a visible escape, so a real newline (``$'a\\nb'``) never reads as the literal text
  206. ``a\\n b`` (``'a\\nb'``) — the card must show which one the shell runs."""
  207. body = "".join("\\\\" if c == "\\" else (_escape_cp(c) if _is_hidden(c) else c) for c in text)
  208. return "$'" + body.replace("'", "\\'") + "'"
  209. def _word(arg: str) -> str:
  210. """One argv entry as one shell word: ``''`` for an empty arg, ``'review server.py'`` with both
  211. spaces, so the line never reads as a different argv. An arg with control or invisible code points is a
  212. ``$'…'`` word (bash reads it back); a plain arg is ``shlex.quote``-d, so ``shlex.split`` of the line
  213. is the argv shown."""
  214. shown = _URL_RE.sub(_mask_url, arg)
  215. if any(_is_hidden(c) for c in shown):
  216. return _ansi_c_quote(shown)
  217. return shlex.quote(shown) if not shown or _NEEDS_QUOTE_RE.search(shown) else shown
  218. def _env_keys(env: Any) -> list[str]:
  219. """The child's extra env names, never their values: the runtime merges them into the spawn."""
  220. if not isinstance(env, dict):
  221. return []
  222. return [scrub(str(k)) for k in sorted(env, key=str) if str(k).strip()]
  223. def launch_target(url: Any, command: Any, args: Any, env: Any = None, cwd: Any = None) -> Optional[dict[str, Any]]:
  224. """``{"kind": "remote"|"stdio", "target": text}``, plus ``env`` (names only) and ``cwd`` when a stdio
  225. entry sets them; the URL wins, as the transport choice does."""
  226. if isinstance(url, str) and url.strip():
  227. return {"kind": "remote", "target": scrub(url.strip())}
  228. if not (isinstance(command, str) and command.strip()):
  229. return None
  230. # A bare string ``args`` is one argument, not a sequence of characters.
  231. argv = [args] if isinstance(args, str) else list(args or []) if isinstance(args, (list, tuple)) else []
  232. shown = _mask_flag_values(command, [str(a) for a in argv if a is not None])
  233. out: dict[str, Any] = {"kind": "stdio", "target": " ".join(map(_word, [command, *shown]))}
  234. if keys := _env_keys(env):
  235. out["env"] = keys
  236. if isinstance(cwd, str) and cwd.strip():
  237. out["cwd"] = _word(cwd)
  238. return out
  239. def launch_for(action: str, name: str) -> Optional[dict[str, Any]]:
  240. """The line for one MCP row; None when the name resolves to nothing readable."""
  241. if action == "install":
  242. from hermes_cli.mcp_catalog import get_entry
  243. entry = get_entry(name)
  244. if entry is None:
  245. return None
  246. transport = entry.transport
  247. return launch_target(transport.url, transport.command, transport.args, transport.env)
  248. from hermes_cli.mcp_catalog import installed_servers
  249. cfg = installed_servers().get(name)
  250. if not isinstance(cfg, dict):
  251. return None
  252. return launch_target(cfg.get("url"), cfg.get("command"), cfg.get("args"), cfg.get("env"), cfg.get("cwd"))