Files
hermes-agent/hermes_cli/plugin_catalog_presence.py
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

196 lines
8.3 KiB
Python

"""Whether the desktop app a catalog plugin drives is on this machine, before the plugin is installed.
A portable plugin declares its app in ``plugin.json`` (``extensions.com.nousresearch.hermes.servers``).
The catalog pins the commit, so the declaration is read once per pin from the repo at that commit and
judged by the same ``hermes_platform`` resolver the installer and the Plugins-tab pill use. Nothing is
installed, spawned or connected. Any failure to read the declaration is ``unknown``, never a guess.
"""
from __future__ import annotations
import json
import logging
import re
from dataclasses import dataclass
from typing import Any, Dict, Optional, Tuple
logger = logging.getLogger(__name__)
_GITHUB = re.compile(r"^https://github\.com/([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?$")
_TIMEOUT = 5.0
_MAX_BYTES = 256 * 1024
_DISCLOSURE = re.compile(r"\bDisclosure\s*[:\u2014]\s*(.+)")
# (repo, sha, subdir) -> manifest dict, or None when the pin has no readable plugin.json. A pin is
# immutable, so the process keeps the answer.
_manifests: dict[tuple[str, str, str], Optional[dict[str, Any]]] = {}
@dataclass(frozen=True)
class Presence:
"""``state`` uses the card's vocabulary (``CatalogAppState``); ``sentence`` is empty when present or unknown."""
state: str
sentence: str = ""
UNKNOWN = Presence("unknown")
def _raw_manifest_url(repo: str, sha: str, subdir: str) -> Optional[str]:
match = _GITHUB.match(repo.strip())
if not match:
return None
path = "/".join(p for p in (subdir.strip("/"), "plugin.json") if p)
return f"https://raw.githubusercontent.com/{match.group(1)}/{match.group(2)}/{sha}/{path}"
def _pinned_manifest(repo: str, sha: str, subdir: str) -> Optional[dict[str, Any]]:
key = (repo, sha, subdir)
if key in _manifests:
return _manifests[key]
url = _raw_manifest_url(repo, sha, subdir)
manifest: Optional[dict[str, Any]] = None
if url:
try:
import httpx
resp = httpx.get(url, timeout=_TIMEOUT, follow_redirects=True)
if resp.status_code == 200 and len(resp.content) <= _MAX_BYTES:
data = json.loads(resp.content)
manifest = data if isinstance(data, dict) else None
elif resp.status_code != 404:
return None # transient: do not remember
except Exception as exc:
logger.debug("plugin catalog presence: %s unreadable: %s", url, exc)
return None
_manifests[key] = manifest
return manifest
def _server_presence(decl: Any, liveness_raw: Any, title: str) -> Presence:
from hermes_platform.declaration import gpu_label
from hermes_platform.host import facts
from hermes_platform.resolver.app import AppResolver
from hermes_platform.resolver.availability import availability
from hermes_platform.resolver.base import Effort
from tools.mcp_liveness import parse_liveness
available = availability(decl)
if available.state == "no_requirements":
return UNKNOWN
if available.state in ("missing_app", "unsupported_os"):
return Presence("missing_app", f"needs {title}")
if available.state == "unsupported_gpu":
return Presence("missing_app", f"needs {gpu_label(decl.required_gpu)}")
if available.state == "version_too_old":
found = f" (found {available.version})" if available.version else ""
return Presence("missing_app", f"needs {title} {available.min_version} or newer{found}")
if liveness_raw is None:
return Presence("present")
try:
live = parse_liveness(liveness_raw)
except ValueError:
return UNKNOWN # a declaration we cannot read is never a guess
if live.kind == "static":
return Presence("present")
if live.kind == "interactive_session":
return Presence("present") if facts.interactive_session() else Presence(
"app_not_running", f"{title} needs an interactive desktop session")
definition = decl.app_for(facts.os_family())
if definition is None:
return Presence("missing_app", f"needs {title}")
resolver = AppResolver(live.app_definition(definition))
probe = resolver.probe(resolver.locate(), effort=Effort.LOCAL)
return Presence("present") if probe.running.value is True else Presence(
"app_not_running", f"{title} is not running")
def presence(entry: Any) -> Presence:
"""The app state of one catalog entry on this host. The worst server wins (missing, then not running)."""
from hermes_cli.agent_plugins import _server_declarations
manifest = _pinned_manifest(entry.repo, entry.sha, entry.subdir)
if not manifest:
return UNKNOWN
raw_servers = (manifest.get("extensions") or {}).get("com.nousresearch.hermes", {}).get("servers") or {}
if not isinstance(raw_servers, dict) or not raw_servers:
return UNKNOWN
try:
declarations = _server_declarations(manifest, {name: {} for name in raw_servers})
except Exception as exc:
logger.debug("plugin catalog presence: %s declaration invalid: %s", entry.name, exc)
return UNKNOWN
title = getattr(entry, "title", "") or entry.name
rank = {"missing_app": 0, "app_not_running": 1, "present": 2, "unknown": 3}
found = [_server_presence(d.declaration, d.liveness, title) for d in declarations.values()]
return min(found, key=lambda p: rank[p.state]) if found else UNKNOWN
def _onboarding_catalog() -> list:
"""Catalog entries curated for onboarding (``onboarding: true``) that this OS can run."""
from hermes_cli.plugin_catalog import load_catalog_live
from hermes_cli.plugins_cmd_catalog import normalized_platforms
from hermes_platform.host.facts import os_family
here = os_family()
return [entry for entry in load_catalog_live()
if entry.onboarding and (not entry.platforms or here in normalized_platforms(entry.platforms))]
def onboarding_names() -> list[str]:
"""The onboarding plugins this OS runs, by catalog name; no presence probe."""
return [entry.name for entry in _onboarding_catalog()]
def onboarding_entries() -> list[dict[str, Any]]:
"""Catalog entries curated for the onboarding card (``onboarding: true``) that this OS can run,
each with its app state. Platform mismatch is the only exclusion; a missing app is reported."""
rows = []
for entry in _onboarding_catalog():
found = presence(entry)
rows.append({
"name": entry.name,
"title": entry.title or entry.name,
"description": _first_sentence(entry.description),
"tier": entry.tier,
"platforms": list(entry.platforms),
"app_state": found.state,
"sentence": found.sentence,
})
return rows
def presence_for(names: list[str]) -> list[dict[str, Any]]:
"""The named catalog plugins this OS runs, in the order asked, each with its app state and the
catalog description's disclosure. A name the live catalog does not carry (unknown or removed) is dropped."""
from concurrent.futures import ThreadPoolExecutor
from hermes_cli.plugin_catalog import load_catalog_live
from hermes_cli.plugins_cmd_catalog import normalized_platforms
from hermes_platform.host.facts import os_family
here = os_family()
by_name = {entry.name: entry for entry in load_catalog_live()}
entries = [by_name[name] for name in dict.fromkeys(names) if name in by_name
and (not by_name[name].platforms or here in normalized_platforms(by_name[name].platforms))]
if not entries:
return []
# Each manifest read is bounded by _TIMEOUT; in parallel the whole answer waits one timeout, not one per name.
with ThreadPoolExecutor(max_workers=len(entries)) as pool:
found = list(pool.map(presence, entries))
return [{"name": entry.name, "title": entry.title or entry.name, "state": state.state,
"sentence": state.sentence, "disclosure": _disclosure(entry.description)}
for entry, state in zip(entries, found)]
def _disclosure(text: str) -> str:
"""The sentence after the description's ``Disclosure:`` (or ``Disclosure —``) marker; empty when absent."""
match = _DISCLOSURE.search(" ".join(str(text or "").split()))
return _first_sentence(match.group(1)) if match else ""
def _first_sentence(text: str) -> str:
text = " ".join(str(text or "").split())
head, dot, _rest = text.partition(". ")
return f"{head}." if dot else text