Files
Maciej Lisiewski 6c025ab898 fix(plugins): pin liveness endpoint URL to loopback (salvage #125745) (#155387)
* fix(plugins): pin liveness endpoint URL to loopback, harden manifest liveness parsing

A manifest's liveness.endpoint_path was concatenated verbatim onto the
loopback URL read from the app's runtime server.json and re-parsed by the
probe, so a crafted tail like '@attacker.example/' rewrote the URL authority
and the initialize request carried the runtime file's bearer token to a
manifest-chosen host.

Now the declaration parser only admits a plain path charset (no '@', '?',
'#', whitespace, scheme, or '..' segments), the resolver re-parses the fully
composed URL and requires it to stay on a loopback host with the same port
and no userinfo, and _mcp_initialize re-verifies scheme/host/port before the
socket opens so the transport-facing endpoint() path is covered too.

Adjacent hardening in the same surface: liveness.path must be a rooted
filesystem path in both parse surfaces, server.json key overrides must be
simple key names, malformed pids (bool, >int32) degrade instead of crashing
os.kill, a non-mapping 'fields' value raises ValueError inside the fail-closed
contract instead of TypeError, and a manifest whose liveness fails validation
renders 'unknown' on the catalog card instead of 'present'.

* test(plugins): satisfy ruff PLR0402 in salvaged liveness test

Follow-up to the salvaged #125745 commit after rebasing onto main.

Refs #125744

* test(plugins): build hostile-endpoint fixture with a valid AppLocation tuple

AppDef.locations is tuple[AppLocation, ...]; the fixture passed a bare
string, which only worked because endpoint() never reads locations.

Refs #125744

---------

Co-authored-by: beardthelion <beardthelion@users.noreply.github.com>
2026-11-14 12:46:07 +01:00

475 lines
20 KiB
Python

"""Desktop-application resolver over an `AppDef` (parsed from an MCP manifest's `app:` block).
`locate` stats every declared location in order (fixed paths, PATH, uninstall entries, the flatpak,
snap and Applications directories) and lists directories for a `*` path segment; the first present
one wins. `inspect` reads the version source in-process.
`probe` re-reads the vendor's runtime file on every call; its bearer token is only ever
attached to endpoint URLs that re-verify as plain loopback http.
"""
from __future__ import annotations
import glob
import json
import os
import plistlib
import re
import sys
import time
from dataclasses import dataclass
from typing import Any, Callable, Iterator, Literal
from urllib.parse import urlsplit
from hermes_platform.resolver import known_dirs
from hermes_platform.resolver.base import Effort, Inspection, Probe
from hermes_platform.resolver.core import (
Candidate,
CheckState,
Kind,
LookupContext,
Observation,
Resolution,
locate_command,
)
PresenceKind = Literal["executable", "bundle"]
VersionKind = Literal["pe_resource", "plist", "uninstall_registry", "none"]
LivenessKind = Literal["server_json", "none"]
_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
def _is_plain_loopback_http(parts) -> bool:
"""One predicate for the runtime-url check and the composed-URL/dial-time re-checks:
plain http, loopback host, no userinfo. Callers keep their own port rules and details."""
return (parts.scheme == "http" and parts.hostname in _LOOPBACK_HOSTS
and not parts.username and not parts.password)
@dataclass(frozen=True)
class AppLocation:
"""One place to look. `kind` is `path` or a key of `LOCATION_KINDS`. `value` is the path, or the
value of that kind's `key`. `file` is joined onto an uninstall entry's `InstallLocation`."""
kind: str
value: str
file: str = ""
@dataclass(frozen=True)
class AppDef:
"""One application on one OS. Paths use `%VAR%` and `~`; expansion happens at lookup."""
app_id: str
os_family: str
presence: PresenceKind
locations: tuple[AppLocation, ...]
version_kind: VersionKind = "none"
version_arg: str = ""
liveness_kind: LivenessKind = "none"
liveness_path: str = ""
liveness_pid_key: str = "pid"
liveness_url_key: str = "http"
liveness_token_key: str = "token"
endpoint_path: str = "/mcp"
def _expand(path: str) -> str:
return os.path.expandvars(os.path.expanduser(path))
@dataclass(frozen=True)
class Endpoint:
url: str
token: str = ""
def __repr__(self) -> str:
return f"Endpoint(url={self.url!r}, token=<redacted>)"
@dataclass(frozen=True)
class AppResolver:
definition: AppDef
@property
def name(self) -> str:
return self.definition.app_id
# ---- locate: stat only -------------------------------------------------------------
def locate(self, ctx: LookupContext | None = None) -> Resolution:
d = self.definition
found = [hit for loc in d.locations for hit in _locator(loc.kind)(d, loc, ctx)]
kind: Kind = next((k for c, k in found if c.present), "missing")
return Resolution(kind, tuple(c for c, _ in found))
# ---- inspect: bounded file reads and in-process OS APIs -----------------------------
def inspect(self, res: Resolution, ctx: LookupContext | None = None) -> Inspection:
if not res.found:
return Inspection(Observation.not_checked(), Observation.not_checked())
return Inspection(version=self._version(res.command[0]), signer=Observation.not_checked())
def _version(self, path: str) -> Observation[str]:
kind = self.definition.version_kind
try:
if kind == "none":
return Observation.not_checked()
if kind == "plist":
return _plist_version(path)
if kind == "pe_resource":
return _pe_version(path)
if kind == "uninstall_registry":
return _uninstall_registry_version(self.definition.version_arg)
except Exception as exc: # a vendor's plist/PE/registry entry is untrusted input; never abort the caller
return Observation(CheckState.ERROR, detail=exc.__class__.__name__)
return Observation(CheckState.UNAVAILABLE, detail=f"unknown version kind {kind}")
# ---- probe: fresh, never cached ------------------------------------------------------
def endpoint(self) -> Endpoint | None:
"""Read and validate the current runtime endpoint."""
d = self.definition
if d.liveness_kind != "server_json":
return None
session = _read_server_json(_expand(d.liveness_path), d)
if session is None or _pid_alive(session.pid).value is not True:
return None
endpoint = _endpoint_observation(session.url, d.endpoint_path)
if endpoint.state is not CheckState.PRESENT or not endpoint.value:
return None
return Endpoint(endpoint.value, session.token)
def probe(self, res: Resolution, *, effort: Effort, deadline_s: float = 3.0) -> Probe:
d = self.definition
nc: Observation = Observation.not_checked()
if d.liveness_kind != "server_json":
return Probe(running=nc, answering=nc, endpoint=nc)
session = _read_server_json(_expand(d.liveness_path), d)
if session is None:
absent = Observation(CheckState.ABSENT, False, "runtime file missing or unreadable")
return Probe(running=absent, answering=nc, endpoint=Observation(CheckState.ABSENT))
running = _pid_alive(session.pid)
endpoint_obs = _endpoint_observation(session.url, d.endpoint_path)
if effort is Effort.LOCAL or running.value is not True or endpoint_obs.state is not CheckState.PRESENT:
return Probe(running=running, answering=nc, endpoint=endpoint_obs)
answering = _mcp_initialize(session, endpoint_obs.value or "", deadline_s)
return Probe(running=running, answering=answering, endpoint=endpoint_obs)
# ---- locations: each yields (candidate, resolution kind) in probe order -----------------
_Hit = tuple[Candidate, Kind]
_Locator = Callable[[AppDef, AppLocation, LookupContext | None], list[_Hit]]
def _present(presence: PresenceKind, path: str) -> bool:
if presence == "bundle":
return os.path.isdir(path) and os.path.isfile(os.path.join(path, "Contents", "Info.plist"))
return os.path.isfile(path)
def _hit(d: AppDef, source: str, path: str) -> _Hit:
present = os.path.isabs(path) and _present(d.presence, path)
return Candidate(path, source, present), "known_path"
def _version_order(path: str) -> list:
return [(1, int(part)) if part.isdigit() else (0, part) for part in re.split(r"(\d+)", path)]
def _path_hits(d: AppDef, loc: AppLocation, ctx: LookupContext | None) -> list[_Hit]:
target, source = _expand(loc.value), f"app:{d.app_id}"
not_found: list[_Hit] = [(Candidate(target, source, False), "known_path")]
if not os.path.isabs(target) or "%" in target or "$" in target:
return not_found
if "*" not in target:
return [_hit(d, source, target)]
# A `*` segment stands for a versioned folder (`Blender 5.2`); the highest version is tried first.
pattern = "*".join(glob.escape(part) for part in target.split("*"))
matches = sorted(glob.glob(pattern), key=_version_order, reverse=True)
return [_hit(d, source, match) for match in matches] or not_found
def _command_hits(d: AppDef, loc: AppLocation, ctx: LookupContext | None) -> list[_Hit]:
res = locate_command(loc.value, ctx)
return [(Candidate(c.value, f"app:{d.app_id}:{loc.kind}", c.present), "path_executable") for c in res.candidates]
def _uninstall_hits(d: AppDef, loc: AppLocation, ctx: LookupContext | None) -> list[_Hit]:
if sys.platform != "win32":
return []
# A UNC InstallLocation is skipped so a presence check never touches the network.
return [_hit(d, f"app:{d.app_id}:{loc.kind}", os.path.join(entry["InstallLocation"], loc.file))
for entry in _uninstall_entries(loc.value)
if entry.get("InstallLocation") and not entry["InstallLocation"].startswith(("\\\\", "//"))]
def _in_dirs(dirs: Callable[[], tuple[str, ...]]) -> _Locator:
def hits(d: AppDef, loc: AppLocation, ctx: LookupContext | None) -> list[_Hit]:
return [_hit(d, f"app:{d.app_id}:{loc.kind}", os.path.join(_expand(root), loc.value)) for root in dirs()]
return hits
@dataclass(frozen=True)
class LocationSpec:
"""A location kind a declaration names in a mapping. `only_on` is the one OS family it is valid
under (None: any), `key` names the mapping field holding what to find, `yields` is the presence
it finds, and `needs_file` says the mapping also carries a relative `file`."""
only_on: str | None
key: str
yields: PresenceKind
locate: _Locator
needs_file: bool = False
LOCATION_KINDS: dict[str, LocationSpec] = {
"command": LocationSpec(None, "name", "executable", _command_hits),
"uninstall_registry": LocationSpec("win32", "display_name_prefix", "executable", _uninstall_hits, needs_file=True),
"app_bundle": LocationSpec("darwin", "name", "bundle", _in_dirs(known_dirs.mac_application_dirs)),
"flatpak": LocationSpec("linux", "app_id", "executable", _in_dirs(known_dirs.flatpak_export_dirs)),
"snap": LocationSpec("linux", "name", "executable", _in_dirs(known_dirs.snap_bin_dirs)),
}
def _locator(kind: str) -> _Locator:
"""A plain string location is a `path`; every other kind comes from `LOCATION_KINDS`."""
return _path_hits if kind == "path" else LOCATION_KINDS[kind].locate
# ---- version sources -------------------------------------------------------------------
def _plist_version(bundle: str) -> Observation[str]:
with open(os.path.join(bundle, "Contents", "Info.plist"), "rb") as fh: # windows-footgun: ok — binary mode
info = plistlib.load(fh)
value = info.get("CFBundleShortVersionString") or info.get("CFBundleVersion")
if not value:
return Observation(CheckState.UNAVAILABLE, detail="no version key in Info.plist")
return Observation(CheckState.PRESENT, str(value))
def _pe_version(path: str) -> Observation[str]:
if sys.platform != "win32":
return Observation(CheckState.UNAVAILABLE, detail="pe_resource needs Windows")
import ctypes
from ctypes import wintypes
ver = ctypes.windll.version # type: ignore[attr-defined]
ver.GetFileVersionInfoSizeW.argtypes = [wintypes.LPCWSTR, ctypes.POINTER(wintypes.DWORD)]
ver.GetFileVersionInfoSizeW.restype = wintypes.DWORD
size = ver.GetFileVersionInfoSizeW(path, None)
if not size:
return Observation(CheckState.UNAVAILABLE, detail="no version resource")
buf = ctypes.create_string_buffer(size)
ver.GetFileVersionInfoW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, ctypes.c_void_p]
ver.GetFileVersionInfoW.restype = wintypes.BOOL
if not ver.GetFileVersionInfoW(path, 0, size, buf):
return Observation(CheckState.ERROR, detail="GetFileVersionInfoW failed")
ptr = ctypes.c_void_p()
length = wintypes.UINT()
ver.VerQueryValueW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR, ctypes.POINTER(ctypes.c_void_p), ctypes.POINTER(wintypes.UINT)]
ver.VerQueryValueW.restype = wintypes.BOOL
if not ver.VerQueryValueW(buf, "\\", ctypes.byref(ptr), ctypes.byref(length)) or not ptr.value:
return Observation(CheckState.UNAVAILABLE, detail="no fixed file info")
# VS_FIXEDFILEINFO: dwFileVersionMS at offset 8, dwFileVersionLS at offset 12.
ms = ctypes.cast(ptr.value + 8, ctypes.POINTER(wintypes.DWORD)).contents.value
ls = ctypes.cast(ptr.value + 12, ctypes.POINTER(wintypes.DWORD)).contents.value
return Observation(CheckState.PRESENT, f"{ms >> 16}.{ms & 0xFFFF}.{ls >> 16}.{ls & 0xFFFF}")
def _uninstall_values(entry: Any) -> dict[str, str]:
"""The uninstall entry's values that exist; any of them may be missing."""
import winreg
values: dict[str, str] = {}
for value_name in ("DisplayName", "DisplayVersion", "InstallLocation"):
try:
values[value_name] = str(winreg.QueryValueEx(entry, value_name)[0])
except OSError:
continue
return values
def _uninstall_entry(key: Any, index: int) -> dict[str, str]:
"""One child entry's values; an entry can vanish between EnumKey and OpenKey, which reads as no values."""
import winreg
try:
with winreg.OpenKey(key, winreg.EnumKey(key, index)) as entry:
return _uninstall_values(entry)
except OSError:
return {}
def _uninstall_entries(display_name_prefix: str) -> Iterator[dict[str, str]]:
"""Each uninstall entry whose `DisplayName` starts with the prefix, machine-wide before per-user."""
import winreg
roots = (
(winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall"),
(winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall"),
(winreg.HKEY_CURRENT_USER, r"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall"),
)
for hive, root in roots:
try:
with winreg.OpenKey(hive, root) as key:
count = winreg.QueryInfoKey(key)[0]
for i in range(count):
values = _uninstall_entry(key, i)
if values.get("DisplayName", "").startswith(display_name_prefix):
yield values
except OSError:
continue
def _uninstall_registry_version(display_name_prefix: str) -> Observation[str]:
if sys.platform != "win32":
return Observation(CheckState.UNAVAILABLE, detail="uninstall_registry needs Windows")
entry = next(_uninstall_entries(display_name_prefix), None)
if entry is None:
return Observation(CheckState.ABSENT, detail="no uninstall entry")
if "DisplayVersion" not in entry:
return Observation(CheckState.UNAVAILABLE, detail="entry has no DisplayVersion")
return Observation(CheckState.PRESENT, entry["DisplayVersion"])
# ---- liveness: the token stays inside this section -------------------------------------
@dataclass(frozen=True)
class _Session:
pid: int | None
url: str
token: str
def __repr__(self) -> str:
return f"_Session(pid={self.pid}, url={self.url!r}, token=<redacted>)"
def _read_server_json(path: str, d: AppDef) -> _Session | None:
try:
with open(path, encoding="utf-8") as fh:
data = json.load(fh)
except (OSError, ValueError):
return None
if not isinstance(data, dict):
return None
pid = data.get(d.liveness_pid_key)
url = data.get(d.liveness_url_key)
token = data.get(d.liveness_token_key)
# bool is an int subclass (pid:true would probe PID 1) and os.kill overflows past int32.
valid_pid = isinstance(pid, int) and not isinstance(pid, bool) and 0 < pid <= 0x7FFFFFFF
return _Session(
pid=pid if valid_pid else None,
url=url if isinstance(url, str) else "",
token=token if isinstance(token, str) else "",
)
def _pid_alive(pid: int | None) -> Observation[bool]:
if pid is None or isinstance(pid, bool) or not (0 < pid <= 0x7FFFFFFF):
return Observation(CheckState.UNAVAILABLE, detail="no valid pid in runtime file")
if sys.platform == "win32":
import ctypes
from ctypes import wintypes
k32 = ctypes.windll.kernel32 # type: ignore[attr-defined]
k32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
k32.OpenProcess.restype = wintypes.HANDLE
handle = k32.OpenProcess(0x1000, False, pid) # PROCESS_QUERY_LIMITED_INFORMATION
if not handle:
return Observation(CheckState.ABSENT, False)
k32.CloseHandle.argtypes = [wintypes.HANDLE]
k32.CloseHandle(handle)
return Observation(CheckState.PRESENT, True)
try:
os.kill(pid, 0) # windows-footgun: ok — POSIX only, the win32 branch returned above
except ProcessLookupError:
return Observation(CheckState.ABSENT, False)
except PermissionError:
return Observation(CheckState.PRESENT, True)
return Observation(CheckState.PRESENT, True)
def _endpoint_observation(raw_url: str, fixed_path: str) -> Observation[str]:
"""Accept only a loopback http URL with a numeric port and no userinfo; ``fixed_path`` is
manifest text, so the composed URL is re-parsed and re-verified before returning."""
if not raw_url:
return Observation(CheckState.UNAVAILABLE, detail="no url in runtime file")
try:
parts = urlsplit(raw_url)
hostname, port, username, password = parts.hostname, parts.port, parts.username, parts.password
except ValueError:
return Observation(CheckState.UNAVAILABLE, detail="malformed endpoint")
if parts.scheme != "http" or username or password:
return Observation(CheckState.UNAVAILABLE, detail="endpoint must be plain http without userinfo")
if not _is_plain_loopback_http(parts):
return Observation(CheckState.UNAVAILABLE, detail="endpoint must be loopback")
if port is None or not (1 <= port <= 65535):
return Observation(CheckState.UNAVAILABLE, detail="endpoint needs a numeric port")
# IPv6 literals need brackets in URL authority or the composed URL is unparseable.
host_fmt = f"[{hostname}]" if ":" in hostname else hostname
composed = f"http://{host_fmt}:{port}{fixed_path}"
try:
rejoined = urlsplit(composed)
_ = rejoined.port
except ValueError:
return Observation(CheckState.UNAVAILABLE, detail="malformed endpoint path")
# fixed_path is manifest text: a crafted tail (e.g. '@host/') would rewrite the authority and
# send the runtime file's bearer token to a manifest-chosen host. Re-verify the whole URL.
if not _is_plain_loopback_http(rejoined) or rejoined.port != port:
return Observation(CheckState.UNAVAILABLE, detail="endpoint path must stay on loopback")
return Observation(CheckState.PRESENT, composed)
def _mcp_initialize(session: _Session, endpoint: str, deadline_s: float) -> Observation[bool]:
"""One MCP `initialize` POST under one absolute deadline covering connect, headers, and body."""
import http.client
try:
parts = urlsplit(endpoint)
port = parts.port
except ValueError:
return Observation(CheckState.UNAVAILABLE, detail="malformed endpoint")
if port is None or not (1 <= port <= 65535) or not _is_plain_loopback_http(parts):
# Belt under _endpoint_observation: the caller-side path tail is manifest text, so the
# re-parsed URL must still name a loopback host:port before any connection -- the bearer
# token rides on this request.
return Observation(CheckState.UNAVAILABLE, detail="endpoint is not a loopback http URL")
body = json.dumps({
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {"protocolVersion": "2025-06-18", "capabilities": {},
"clientInfo": {"name": "hermes", "version": "probe"}},
}).encode()
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}
if session.token:
headers["Authorization"] = f"Bearer {session.token}"
deadline = time.monotonic() + max(0.1, deadline_s)
def remaining() -> float:
left = deadline - time.monotonic()
if left <= 0:
raise TimeoutError
return left
conn = None
try:
conn = http.client.HTTPConnection(parts.hostname or "127.0.0.1", port, timeout=remaining())
conn.request("POST", parts.path or "/", body=body, headers=headers)
conn.sock.settimeout(remaining())
status = conn.getresponse().status
except TimeoutError:
return Observation(CheckState.ABSENT, False, f"no answer within {deadline_s:g} s")
except (OSError, http.client.HTTPException, ValueError):
# ValueError covers a non-ASCII path (conn.request -> UnicodeEncodeError) from a
# directly-constructed AppDef, which never passed the declaration charset check.
return Observation(CheckState.ABSENT, False, "connection refused or timed out")
finally:
if conn is not None:
conn.close()
if status in (200, 401, 403):
return Observation(CheckState.PRESENT, True, f"http {status}")
return Observation(CheckState.ABSENT, False, f"http {status}")