| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302 |
- """What an MCP consent row will run or contact, worded for the card before the user approves.
- Install reads the catalog manifest's transport; enable and authorize read the configured
- ``mcp_servers`` entry. The line is display-only and never carries env values or headers.
- The card exists so the user consents to what will run, so hiding execution is worse than showing a
- secret. The line is never cut, and a value is masked only when its own name says it is secret: a long
- flag such as ``--api-key=…`` / ``--token …`` / ``--token:…``, a ``GITHUB_TOKEN=…`` assignment, a
- ``docker``-style ``-e KEY=…`` / ``--env KEY=…``, an ``Authorization:`` / ``Cookie:`` / API-key header
- arg, a URL userinfo password, a secret-named URL query value (``?token=``, ``?key=``). A named secret's
- value is masked whatever it holds (shell metacharacters included) — execve argv never runs a shell.
- Positional args, short flags (``-p``, ``-k``, ``-t``), packages, images, scripts and URL paths are
- always shown, even when one of them is a key: the user approves that exact command. The program given
- to an interpreter's inline-program flag (``sh -c``, ``python -c``, ``node -e``, ``perl -e``), found
- past any wrapper (``env``, ``npx -y node``, ``sudo -u x bash``), is never masked, and a bare
- ``KEY=VALUE`` holding a line break or shell metacharacter is shown too, so a secret name inside code
- cannot hide the code. An argument is quoted when it would not read back as exactly that one argument
- (whitespace, a quote, backslash or shell metacharacter, an empty argument), so ``shlex.split`` of the
- line is the argv shown; an argument with control or invisible code points is a bash ``$'…'`` word whose
- escapes keep a real newline distinct from the literal text ``\n``.
- """
- from __future__ import annotations
- import re
- import shlex
- import unicodedata
- from typing import Any, Optional
- from agent.redact import SECRET_HEADER_NAME_LIST, sanitize_command_for_display
- # A flag or query name that says its value is secret, after camelCase/snake_case fold to kebab. The
- # word ends its segment (``--access-token``, ``--apikey``; not ``--tokenizer``, ``--max-tokens``),
- # ``auth`` is a whole segment (not ``--author``), and ``pass``/``pwd`` are the whole name.
- _SECRET_NAME_RE = re.compile(
- r"(?:token|secret|passw(?:or)?d|api-?key|credentials?|private-?key|bearer)(?=-|$)"
- r"|(?:^|-)auth(?:orization)?(?=-|$)|^(?:pass|pwd)$")
- # Names for where a secret lives or how it is supplied, not the secret: ``--token-file``,
- # ``--password-stdin``, ``--auth-type``; ``--no-auth`` is a switch, so the next arg is not its value.
- _NOT_A_VALUE_RE = re.compile(
- r"-(?:file|path|dir|env|var|name|url|uri|stdin|prompt|type|mode|method|scheme|helper|cmd|command)$"
- r"|^(?:no|disable|enable|skip|use|with|without)-")
- _CAMEL_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
- # ``KEY=VALUE`` (an ``env`` prefix, a ``-e`` value): the key's last identifier carries the name.
- _ASSIGN_RE = re.compile(r"^([^\s=]*?)([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.DOTALL)
- # A bare ``KEY=VALUE`` positional is ambiguous: a real env assignment, or code an interpreter runs
- # (``sh -c 'TOKEN=x; curl …'``). Only when the value can only be data (no line break, ``;``, ``|``,
- # ``&``, ``$(…)``, a backtick, brackets, quotes) is it masked; a value that can run or split is shown.
- # The value of a recognised secret mechanism (a named flag, ``-e``/``--env``, a header, URL userinfo
- # or query) is always masked instead, whatever it holds — that is never an interpreter's code.
- _PLAIN_VALUE_RE = re.compile(r"[^\s;|&$`<>(){}'\"\\]+")
- # A header value is masked whole; only a line break or control (header injection) keeps it visible.
- _PLAIN_HEADER_VALUE_RE = re.compile(r"[^\x00-\x1f\x7f]+")
- # A precise interpreter word (command or arg, ``/usr/bin/python3.12``, ``bash.exe``). Names are
- # listed in full, never ``[a-z]*sh`` (that caught ``ssh`` and ``publish`` and hid the secret after).
- _INTERPRETER_RE = re.compile(
- r"(?:sh|bash|zsh|dash|ksh|mksh|ash|fish|csh|tcsh|rc|python[\d.]*|pypy[\d.]*|node(?:js)?|deno|bun|"
- r"tsx|ts-node|ruby|perl[\d.]*|php[\d.]*|lua(?:jit)?|pwsh|powershell|osascript|tclsh|r|rscript|elixir)(?:\.exe)?",
- re.IGNORECASE)
- # Commands that run a following command; the real command (and whether it is an interpreter) is found
- # past the wrapper's options, so ``-e`` after ``npx -y node`` is node's eval, not a docker env var.
- _WRAPPERS = frozenset({
- "env", "sudo", "doas", "nohup", "setsid", "nice", "ionice", "time", "timeout", "stdbuf",
- "command", "exec", "busybox", "chroot", "xargs", "uv", "uvx", "npx", "pnpm", "bunx", "pipx",
- "poetry", "yarn",
- })
- _INLINE_CODE_FLAG_RE = re.compile(r"(-[ceEpr]|--eval|--print|--?command)(=?)(.*)", re.IGNORECASE | re.DOTALL)
- _SECRET_ENV_RE = re.compile(r"TOKEN|SECRET|PASSW(?:OR)?D|API_?KEY|AUTH(?!OR(?!IZ))|CREDENTIAL|PRIVATE_?KEY",
- re.IGNORECASE)
- # One header arg, alone or as ``--header=…`` / attached ``-H…``: the auth scheme stays, the value goes.
- _HEADER_NAMES = "|".join(sorted({"cookie", *SECRET_HEADER_NAME_LIST}, key=len, reverse=True))
- _SECRET_HEADER_ARG_RE = re.compile(
- rf"^((?:--header[=:]?|-H)?[ \t]*(?:(?:proxy-)?authorization[ \t]*:[ \t]*(?:(?:bearer|basic|token|digest)[ \t]+)?"
- rf"|(?:{_HEADER_NAMES})[ \t]*:[ \t]*))(\S.*)$",
- re.IGNORECASE | re.DOTALL,
- )
- _LONG_FLAG_RE = re.compile(r"--([^=:]+)([=:]?)")
- def _is_secret_name(name: str) -> bool:
- """True when a flag's or query parameter's own name says its value is a secret."""
- norm = _CAMEL_RE.sub("-", name).lower().replace("_", "-").replace(".", "-")
- return bool(_SECRET_NAME_RE.search(norm)) and not _NOT_A_VALUE_RE.search(norm)
- def _mask_arg(arg: str, interpreter: bool = False) -> tuple[str, bool]:
- """``(shown, mask_next)`` for one argv entry. ``interpreter`` is True while the command word (argv[0])
- is an interpreter and its own options are still being read: a named-secret flag then shows its value
- (it may be the script or its code) instead of masking it, but an attached ``--flag=`` secret is still
- masked, since that value is never the program."""
- if (header := _SECRET_HEADER_ARG_RE.match(arg)) and _PLAIN_HEADER_VALUE_RE.fullmatch(header.group(2)):
- return f"{header.group(1)}***", False
- if arg.startswith("--"):
- flag = _LONG_FLAG_RE.match(arg)
- if flag and _is_secret_name(flag.group(1)):
- if not flag.group(2):
- return arg, not interpreter
- return f"{flag.group(0)}***", False # ``--api-key=VALUE``: the value is never the program
- # ``--env=GITHUB_TOKEN=…``: the assignment's own key names the secret.
- if flag and flag.group(2):
- return f"{flag.group(0)}{_mask_assignment(arg[flag.end():], force=True)}", False
- return arg, False
- # ``KEY=VALUE`` alone, or attached to a short flag (``-eGITHUB_TOKEN=…``, java ``-Dapi.token=…``).
- return _mask_assignment(arg), False
- def _mask_assignment(text: str, force: bool = False) -> str:
- """A ``KEY=VALUE`` whose key names a secret, with the value masked. ``force`` masks it whatever the
- value holds (the value of ``-e``/``--env``/``--flag=``); otherwise only a plain data value is masked,
- so a bare ``KEY=VALUE`` that is really an interpreter's inline code is shown."""
- assign = _ASSIGN_RE.match(text)
- if assign and _SECRET_ENV_RE.search(assign.group(2)) and (force or _PLAIN_VALUE_RE.fullmatch(assign.group(3))):
- return f"{assign.group(1)}{assign.group(2)}=***"
- return text
- def _is_interpreter(word: str) -> bool:
- return bool(_INTERPRETER_RE.fullmatch(re.split(r"[\\/]", word)[-1]))
- def _effective_is_interpreter(command: str, args: list[str]) -> bool:
- """Whether the command that actually runs is an interpreter, looking past wrapper words. ``env …
- sh``, ``npx -y node`` and ``sudo -u x bash`` all resolve to an interpreter, so a later ``-e`` is its
- eval flag, not a ``docker``-style env var worth masking."""
- if _is_interpreter(command):
- return True
- if re.split(r"[\\/]", command)[-1] not in _WRAPPERS:
- return False
- return any(_is_interpreter(a) for a in args if not a.startswith("-") and "=" not in a)
- def _mask_flag_values(command: str, args: list[str]) -> list[str]:
- out: list[str] = []
- interp = _is_interpreter(command) # argv[0] is an interpreter; its own flags may carry inline code
- allow_env_force = not _effective_is_interpreter(command, args)
- code_next = mask_next = env_next = False
- for arg in args:
- # The program an interpreter runs inline (``sh -c 'GITHUB_TOKEN=x; curl …'``) is what the user
- # approves: shown whole, whatever names it mentions.
- if code_next:
- out.append(arg)
- code_next = interp = False
- continue
- if mask_next:
- mask_next = False
- if not arg.startswith("-"): # a following flag is the next flag, not the secret's value
- out.append("***")
- continue
- if env_next:
- out.append(_mask_assignment(arg, force=True))
- env_next = False
- continue
- if interp and (inline := _INLINE_CODE_FLAG_RE.fullmatch(arg)):
- out.append(arg)
- code_next = not (inline.group(2) or inline.group(3))
- interp = code_next # attached code (``-ccode``/``--eval=code``) ends the option region now
- continue
- if interp and not arg.startswith("-"):
- interp = False # the script positional: its own args mask normally from here
- # ``docker``-style ``-e KEY=VALUE`` / ``--env KEY=VALUE`` (only when no interpreter runs).
- if allow_env_force and arg in ("-e", "--env"):
- out.append(arg)
- env_next = True
- continue
- shown, mask_next = _mask_arg(arg, interpreter=interp)
- out.append(shown)
- return out
- _URL_RE = re.compile(r"\b[A-Za-z][A-Za-z0-9+.-]*://[^\s]+")
- def _mask_query_pair(pair: str) -> str:
- key, eq, _value = pair.partition("=")
- # ``?key=`` is an API key in a URL (``?key=AIza…``); as a flag, ``--key`` is often a key *file*.
- return f"{key}=***" if eq and (key.lower() == "key" or _is_secret_name(key)) else pair
- def _mask_url(match: re.Match[str]) -> str:
- """A userinfo password and secret-named query values become ``***``. Host, path, other query
- values and the fragment stay: the path of a ``deno run https://…`` URL is the code that runs."""
- url = match.group(0)
- head, sep, rest = url.partition("://")
- rest, hash_, fragment = rest.partition("#")
- rest, qmark, query = rest.partition("?")
- authority, slash, path = rest.partition("/")
- userinfo, at, host = authority.rpartition("@")
- if at and ":" in userinfo: # a userinfo password is always secret, whatever it holds
- authority = f"{userinfo.partition(':')[0]}:***@{host}"
- out = f"{head}{sep}{authority}{slash}{path}"
- if qmark:
- out += "?" + "&".join(_mask_query_pair(pair) for pair in query.split("&"))
- return out + hash_ + fragment
- # Tab and newline are the two controls the approval sanitizer keeps; the card draws one line.
- _LINE_BREAKS = str.maketrans({"\t": "\\t", "\n": "\\n"})
- def _escape_composing(ch: str) -> str:
- # A combining mark draws over the letter before it (``pk\u0336g`` reads as a struck ``k``) and
- # U+FFFC draws as a box. Other non-ASCII letters stay as written (homoglyphs are out of scope).
- if ch == "\ufffc" or unicodedata.category(ch) in ("Mn", "Me"):
- return ch.encode("unicode_escape").decode("ascii")
- return ch
- def _visible(text: str) -> str:
- """Every control, format (bidi overrides/isolates, zero-width, BOM, soft hyphen), separator and
- combining code point as a visible escape such as ``\\u202e``: the line must read as the argv runs,
- and the user should see that an arg is unusual rather than a cleaned-up version of it."""
- shown = sanitize_command_for_display(text.translate(_LINE_BREAKS))
- return shown if shown.isascii() else "".join(map(_escape_composing, shown))
- def scrub(text: str) -> str:
- """One value as written (spaces kept), named secrets in URLs masked, never cut. The shape-based
- secret redactor is not run here: it masks positionals that merely look like keys (a package
- named ``sk-…``, a JWT-shaped script arg), and the card must not hide what runs."""
- return _visible(_URL_RE.sub(_mask_url, text))
- # Characters that change how a shell or ``shlex.split`` reads a word: such a word, or an empty one,
- # is quoted, so ``python -c 'X=print(1)'`` reads as the one argument it is.
- _NEEDS_QUOTE_RE = re.compile(r"[\s'\"\\;|&$`<>(){}]")
- # Common controls get a readable name; every other hidden code point gets its ``\\x``/``\\u`` escape.
- _CONTROL_NAMES = {"\n": "\\n", "\t": "\\t", "\r": "\\r"}
- def _is_hidden(ch: str) -> bool:
- """A control, format (bidi override/isolate, zero-width, BOM, soft hyphen), non-space separator or
- combining code point: shown as an escape so the line reads as the argv runs, never a hidden char."""
- return not ch.isprintable() or unicodedata.category(ch) in ("Mn", "Me", "Mc") or ch == "\ufffc"
- def _escape_cp(ch: str) -> str:
- if ch in _CONTROL_NAMES:
- return _CONTROL_NAMES[ch]
- o = ord(ch)
- return f"\\x{o:02x}" if o <= 0xff else (f"\\u{o:04x}" if o <= 0xffff else f"\\U{o:08x}")
- def _ansi_c_quote(text: str) -> str:
- """An arg holding hidden code points as a bash ``$'…'`` word: backslashes are doubled and each hidden
- code point is a visible escape, so a real newline (``$'a\\nb'``) never reads as the literal text
- ``a\\n b`` (``'a\\nb'``) — the card must show which one the shell runs."""
- body = "".join("\\\\" if c == "\\" else (_escape_cp(c) if _is_hidden(c) else c) for c in text)
- return "$'" + body.replace("'", "\\'") + "'"
- def _word(arg: str) -> str:
- """One argv entry as one shell word: ``''`` for an empty arg, ``'review server.py'`` with both
- spaces, so the line never reads as a different argv. An arg with control or invisible code points is a
- ``$'…'`` word (bash reads it back); a plain arg is ``shlex.quote``-d, so ``shlex.split`` of the line
- is the argv shown."""
- shown = _URL_RE.sub(_mask_url, arg)
- if any(_is_hidden(c) for c in shown):
- return _ansi_c_quote(shown)
- return shlex.quote(shown) if not shown or _NEEDS_QUOTE_RE.search(shown) else shown
- def _env_keys(env: Any) -> list[str]:
- """The child's extra env names, never their values: the runtime merges them into the spawn."""
- if not isinstance(env, dict):
- return []
- return [scrub(str(k)) for k in sorted(env, key=str) if str(k).strip()]
- def launch_target(url: Any, command: Any, args: Any, env: Any = None, cwd: Any = None) -> Optional[dict[str, Any]]:
- """``{"kind": "remote"|"stdio", "target": text}``, plus ``env`` (names only) and ``cwd`` when a stdio
- entry sets them; the URL wins, as the transport choice does."""
- if isinstance(url, str) and url.strip():
- return {"kind": "remote", "target": scrub(url.strip())}
- if not (isinstance(command, str) and command.strip()):
- return None
- # A bare string ``args`` is one argument, not a sequence of characters.
- argv = [args] if isinstance(args, str) else list(args or []) if isinstance(args, (list, tuple)) else []
- shown = _mask_flag_values(command, [str(a) for a in argv if a is not None])
- out: dict[str, Any] = {"kind": "stdio", "target": " ".join(map(_word, [command, *shown]))}
- if keys := _env_keys(env):
- out["env"] = keys
- if isinstance(cwd, str) and cwd.strip():
- out["cwd"] = _word(cwd)
- return out
- def launch_for(action: str, name: str) -> Optional[dict[str, Any]]:
- """The line for one MCP row; None when the name resolves to nothing readable."""
- if action == "install":
- from hermes_cli.mcp_catalog import get_entry
- entry = get_entry(name)
- if entry is None:
- return None
- transport = entry.transport
- return launch_target(transport.url, transport.command, transport.args, transport.env)
- from hermes_cli.mcp_catalog import installed_servers
- cfg = installed_servers().get(name)
- if not isinstance(cfg, dict):
- return None
- return launch_target(cfg.get("url"), cfg.get("command"), cfg.get("args"), cfg.get("env"), cfg.get("cwd"))
|