plugin_validate.py 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693
  1. """``hermes plugins validate`` — admission checks for a plugin directory.
  2. This is the command the plugin-catalog admission CI (and the
  3. ``.github/actions/plugin-validate`` composite action) runs against a
  4. candidate plugin. It performs static manifest checks plus a
  5. subprocess-isolated capability probe: the plugin is imported and its
  6. ``register(ctx)`` called against a minimal recording stub context in a
  7. scratch child process (with a throwaway ``HERMES_HOME``), so a crashing or
  8. malicious plugin cannot take down the CLI, and the *actually registered*
  9. tools/hooks/middleware are compared against the manifest's declared
  10. ``provides_*`` lists.
  11. """
  12. from __future__ import annotations
  13. import json
  14. import os
  15. import re
  16. import subprocess
  17. import sys
  18. import tempfile
  19. from dataclasses import dataclass, field
  20. from pathlib import Path
  21. from typing import Any, Dict, List, Optional, Tuple
  22. from hermes_cli.plugin_validate_core_override import check_core_override
  23. from hermes_cli.plugin_validate_desktop import check_desktop_surface
  24. from hermes_cli.plugin_validate_private_imports import check_private_imports
  25. from hermes_cli.plugin_validate_locales import check_language_packs
  26. from hermes_cli.plugins_manifest import _CONFIG_SCHEMA_TYPES
  27. _UPPER_SNAKE_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
  28. # Admission accepts exactly the ``config_schema`` types the loader type-checks at load time (and the
  29. # Desktop settings renderer keys its field table on) — a private copy drifted and rejected ``secret``.
  30. _CONFIG_TYPES = frozenset(_CONFIG_SCHEMA_TYPES)
  31. _PROBE_TIMEOUT = 30
  32. _PROBE_SENTINEL = "HERMES_VALIDATE_JSON:"
  33. @dataclass
  34. class ValidationReport:
  35. """Result of validating one plugin directory."""
  36. checks: list[tuple[str, bool, str]] = field(default_factory=list)
  37. warnings: list[str] = field(default_factory=list)
  38. isolation: Optional[dict[str, Any]] = None # plugin-host readiness; informational, never fails
  39. @property
  40. def failures(self) -> list[str]:
  41. return [detail or name for name, ok, detail in self.checks if not ok]
  42. @property
  43. def ok(self) -> bool:
  44. return all(ok for _name, ok, _detail in self.checks)
  45. @property
  46. def exit_code(self) -> int:
  47. return 0 if self.ok else 1
  48. def add(self, name: str, ok: bool, detail: str = "") -> None:
  49. self.checks.append((name, ok, detail))
  50. def warn(self, message: str) -> None:
  51. self.warnings.append(message)
  52. def to_dict(self) -> dict[str, Any]:
  53. return {
  54. "ok": self.ok,
  55. "checks": [
  56. {"name": name, "ok": ok, "detail": detail}
  57. for name, ok, detail in self.checks
  58. ],
  59. "warnings": list(self.warnings),
  60. "isolation": self.isolation,
  61. }
  62. # ─── Static checks ───────────────────────────────────────────────────────────
  63. def _requires_hermes_spec_valid(spec: str) -> bool:
  64. """Strictly validate a ``requires_hermes`` spec.
  65. Unlike :func:`hermes_cli.plugins_manifest.version_satisfies` (permissive at load
  66. time), validation REJECTS clauses whose version segment doesn't parse —
  67. a typo'd spec should fail admission, not silently gate nothing.
  68. """
  69. from hermes_cli.plugins_manifest import _VERSION_COMPARATOR_RE, _version_tuple
  70. for clause in spec.split(","):
  71. clause = clause.strip()
  72. if not clause:
  73. continue
  74. m = _VERSION_COMPARATOR_RE.match(clause)
  75. target = m.group(2) if m else clause
  76. if _version_tuple(target) is None:
  77. return False
  78. return True
  79. def _check_manifest_fields(report: ValidationReport, manifest: dict) -> None:
  80. missing = [
  81. f for f in ("name", "version", "description") if not manifest.get(f)
  82. ]
  83. if missing:
  84. report.add(
  85. "manifest fields",
  86. False,
  87. f"plugin.yaml missing required field(s): {', '.join(missing)}",
  88. )
  89. else:
  90. report.add("manifest fields", True, "name, version, description present")
  91. def _check_requires_hermes(report: ValidationReport, manifest: dict) -> None:
  92. spec = str(manifest.get("requires_hermes") or "").strip()
  93. if not spec:
  94. report.add("requires_hermes", True, "not declared")
  95. return
  96. if _requires_hermes_spec_valid(spec):
  97. report.add("requires_hermes", True, f"spec {spec!r} parses")
  98. else:
  99. report.add(
  100. "requires_hermes",
  101. False,
  102. f"requires_hermes spec {spec!r} does not parse "
  103. "(expected e.g. \">=0.19\" or \">=0.19, <1.0\")",
  104. )
  105. def _check_config_spec(report: ValidationReport, manifest: dict) -> None:
  106. """Validate the manifest ``config_schema`` mapping (#64165 format)."""
  107. raw = manifest.get("config_schema")
  108. if raw in (None, [], {}):
  109. report.add("config schema", True, "not declared")
  110. return
  111. problems: list[str] = []
  112. if not isinstance(raw, dict):
  113. problems.append("config_schema: must be a mapping of key -> spec")
  114. else:
  115. for skey, spec in raw.items():
  116. if not isinstance(spec, dict):
  117. problems.append(
  118. f"config_schema.{skey}: must be a mapping (e.g. {{type: str}})"
  119. )
  120. continue
  121. typ = spec.get("type")
  122. if typ is not None and str(typ).lower() not in _CONFIG_TYPES:
  123. problems.append(
  124. f"config_schema.{skey}: type must be one of "
  125. f"{'/'.join(sorted(_CONFIG_TYPES))}"
  126. )
  127. required = spec.get("required")
  128. if required is not None and not isinstance(required, bool):
  129. problems.append(
  130. f"config_schema.{skey}: required must be a boolean"
  131. )
  132. if problems:
  133. report.add("config schema", False, "; ".join(problems))
  134. else:
  135. report.add("config schema", True, "shape valid")
  136. def _check_requires_env(report: ValidationReport, manifest: dict) -> None:
  137. raw = manifest.get("requires_env") or []
  138. problems: list[str] = []
  139. if not isinstance(raw, list):
  140. problems.append("requires_env: must be a list")
  141. raw = []
  142. for i, entry in enumerate(raw):
  143. if isinstance(entry, str):
  144. name = entry
  145. elif isinstance(entry, dict):
  146. name = str(entry.get("name") or "")
  147. else:
  148. problems.append(f"requires_env[{i}]: must be a string or mapping")
  149. continue
  150. if not _UPPER_SNAKE_RE.match(name):
  151. problems.append(
  152. f"requires_env[{i}]: {name!r} is not UPPER_SNAKE_CASE"
  153. )
  154. if problems:
  155. report.add("requires_env", False, "; ".join(problems))
  156. else:
  157. report.add("requires_env", True, "all entries UPPER_SNAKE")
  158. def _check_oauth(report: ValidationReport, manifest: dict, plugin_dir: Path) -> None:
  159. """``oauth:`` clients (hermes_cli.plugin_oauth): shape, https and declared variables fail admission; a
  160. host outside the IdP's domains and plugin code that names a token URL are reviewer warnings."""
  161. from hermes_cli.plugin_oauth import oauth_admission_problems, oauth_admission_warnings
  162. if manifest.get("oauth") in (None, []):
  163. report.add("oauth", True, "not declared")
  164. return
  165. problems = oauth_admission_problems(manifest, plugin_dir)
  166. report.add("oauth", not problems, "; ".join(problems) or "clients valid")
  167. for warning in oauth_admission_warnings(manifest, plugin_dir):
  168. report.warn(warning)
  169. # ─── Capability probe (subprocess-isolated) ──────────────────────────────────
  170. # Self-contained harness run in a scratch child process. Imports the plugin
  171. # module using the same file-location mechanics PluginManager uses, calls
  172. # register() against a recording stub ctx, and prints a sentinel-prefixed
  173. # JSON line of what was actually registered. Deliberately imports NOTHING
  174. # from hermes so a hostile plugin only sees a bare interpreter — the one
  175. # exception is `providers` for `kind: model-provider`, whose contract IS
  176. # calling providers.register_provider at import.
  177. _PROBE_SCRIPT = r"""
  178. import importlib.util
  179. import json
  180. import sys
  181. plugin_dir = sys.argv[1]
  182. sentinel = sys.argv[2]
  183. options = json.loads(sys.argv[3])
  184. # Public method names of the real PluginContext, computed by the parent so the
  185. # stub's attribute surface cannot drift from the class plugins run against.
  186. context_methods = set(options["context_methods"])
  187. provider_kind = options["kind"] == "model-provider"
  188. recorded = {"tools": [], "hooks": [], "middleware": [], "commands": [], "providers": [], "trusted_inbound": []}
  189. class RecordingContext:
  190. plugin_config = {}
  191. profile_name = "default"
  192. plugin_id = "hermes_validate_probe_plugin"
  193. def register_tool(self, name, *args, **kwargs):
  194. recorded["tools"].append(str(name))
  195. def register_hook(self, hook_name, callback, *, hold_stream=False):
  196. recorded["hooks"].append(str(hook_name))
  197. def register_middleware(self, kind, callback):
  198. recorded["middleware"].append(str(kind))
  199. def register_command(self, name, *args, **kwargs):
  200. recorded["commands"].append(str(name))
  201. def register_cli_command(self, name, *args, **kwargs):
  202. recorded["commands"].append(str(name))
  203. def register_platform(self, name, *args, **kwargs):
  204. if kwargs.get("trusted_inbound"):
  205. recorded["trusted_inbound"].append(str(name))
  206. def get_config(self, key, default=None):
  207. # Mirrors PluginContext.get_config with no config on disk: the DEFAULT, never None —
  208. # plugins do `int(ctx.get_config("timeout", 180))` in register().
  209. return default
  210. def __getattr__(self, name):
  211. # Any other REAL registration surface (platforms, providers, skills,
  212. # context engines, ...) is accepted as a no-op — the probe only audits
  213. # the declared-capability categories. Names the real PluginContext does
  214. # not have raise AttributeError exactly like it would; handing back a
  215. # callable made `getattr(ctx, "profile_path", None)` truthy and crashed
  216. # register() in the probe alone.
  217. if name in context_methods:
  218. def _noop(*args, **kwargs):
  219. return None
  220. return _noop
  221. raise AttributeError(name)
  222. def emit(payload):
  223. print(sentinel + json.dumps(payload))
  224. if provider_kind:
  225. # `kind: model-provider` plugins register at import via
  226. # providers.register_provider(ProviderProfile) — the PluginManager never
  227. # calls a register(ctx) on them (plugins_discovery skips the kind), so the
  228. # probe records that call instead of demanding an entry point that would
  229. # be dead code.
  230. try:
  231. import providers as _providers
  232. except Exception as exc:
  233. emit({"error": "model-provider probe could not import providers: %s" % exc})
  234. sys.exit(0)
  235. _real_register_provider = _providers.register_provider
  236. def _recording_register_provider(profile):
  237. recorded["providers"].append(str(getattr(profile, "name", profile)))
  238. return _real_register_provider(profile)
  239. _providers.register_provider = _recording_register_provider
  240. try:
  241. spec = importlib.util.spec_from_file_location(
  242. "hermes_validate_probe_plugin",
  243. plugin_dir + "/__init__.py",
  244. submodule_search_locations=[plugin_dir],
  245. )
  246. module = importlib.util.module_from_spec(spec)
  247. module.__path__ = [plugin_dir]
  248. sys.modules[spec.name] = module
  249. spec.loader.exec_module(module)
  250. except Exception as exc:
  251. emit({"error": "import failed: %s" % exc})
  252. sys.exit(0)
  253. if provider_kind:
  254. if not recorded["providers"]:
  255. emit({"error": "model-provider plugin registered no ProviderProfile at import"})
  256. else:
  257. emit(recorded)
  258. sys.exit(0)
  259. register = getattr(module, "register", None)
  260. if register is None:
  261. emit({"error": "no register() function"})
  262. sys.exit(0)
  263. try:
  264. register(RecordingContext())
  265. except Exception as exc:
  266. emit({"error": "register() raised: %s" % exc})
  267. sys.exit(0)
  268. emit(recorded)
  269. """
  270. def _probe_options(manifest: dict) -> dict:
  271. from hermes_cli.plugins import PluginContext
  272. return {
  273. "kind": str(manifest.get("kind") or ""),
  274. "context_methods": sorted(
  275. n for n in dir(PluginContext)
  276. if not n.startswith("_") and callable(getattr(PluginContext, n))
  277. ),
  278. }
  279. def _run_capability_probe(
  280. plugin_dir: Path, manifest: dict, probe: Optional[tuple[list[str], dict[str, str]]] = None,
  281. ) -> tuple[Optional[dict], str]:
  282. """Run the recording probe in a scratch subprocess.
  283. *probe* is ``(python argv prefix, env)`` of the dependency environment to import the plugin
  284. from (``pm.environments.venv_command``); None probes this interpreter.
  285. Returns ``(recorded, error)`` — exactly one is meaningful: *recorded*
  286. is the ``{tools, hooks, middleware, commands, providers}`` dict on
  287. success, and *error* is a human-readable failure description otherwise.
  288. """
  289. with tempfile.TemporaryDirectory(prefix="hermes-validate-") as scratch:
  290. env = dict(probe[1] if probe else os.environ)
  291. env["HERMES_HOME"] = scratch
  292. # The probe imports this tree's ``providers``; name the tree instead of relying on the cwd.
  293. repo_root = str(Path(__file__).resolve().parents[1])
  294. env["PYTHONPATH"] = os.pathsep.join(p for p in (repo_root, env.get("PYTHONPATH", "")) if p)
  295. python, *options = probe[0] if probe else [sys.executable]
  296. try:
  297. result = subprocess.run(
  298. [
  299. # -P: ``-c`` would put the user's cwd ahead of Hermes and the plugin's imports.
  300. python, "-P", *options,
  301. "-c",
  302. _PROBE_SCRIPT,
  303. str(plugin_dir),
  304. _PROBE_SENTINEL,
  305. json.dumps(_probe_options(manifest)),
  306. ],
  307. capture_output=True,
  308. text=True, encoding="utf-8", errors="replace",
  309. timeout=_PROBE_TIMEOUT,
  310. env=env,
  311. check=False,
  312. )
  313. except subprocess.TimeoutExpired:
  314. return None, f"capability probe timed out after {_PROBE_TIMEOUT}s"
  315. payload: Optional[dict] = None
  316. for line in (result.stdout or "").splitlines():
  317. if line.startswith(_PROBE_SENTINEL):
  318. try:
  319. payload = json.loads(line[len(_PROBE_SENTINEL):])
  320. except json.JSONDecodeError:
  321. payload = None
  322. if payload is None:
  323. err = (result.stderr or "").strip()
  324. return None, (
  325. "capability probe produced no result "
  326. f"(exit {result.returncode})" + (f": {err}" if err else "")
  327. )
  328. if "error" in payload:
  329. return None, str(payload["error"])
  330. return payload, ""
  331. def _declared_list(manifest: dict, key: str) -> list[str]:
  332. raw = manifest.get(key) or []
  333. if not isinstance(raw, list):
  334. return []
  335. return [str(item) for item in raw if isinstance(item, str)]
  336. def _check_capabilities(
  337. report: ValidationReport, manifest: dict, plugin_dir: Path,
  338. probe: Optional[tuple[Path, dict[str, str]]] = None,
  339. ) -> Optional[dict]:
  340. """Probe actual registrations and diff against declared capabilities.
  341. Returns the recorded dict (for the built-in collision check) or None
  342. when the probe failed / was skipped.
  343. """
  344. if not (plugin_dir / "__init__.py").is_file():
  345. report.warn(
  346. "no __init__.py — capability probe skipped (manifest-only plugin)"
  347. )
  348. report.add("capability probe", True, "skipped (no __init__.py)")
  349. return None
  350. recorded, error = _run_capability_probe(plugin_dir, manifest, probe)
  351. if recorded is None:
  352. report.add("capability probe", False, error)
  353. return None
  354. if recorded.get("providers"):
  355. report.add(
  356. "capability probe", True,
  357. "import registered provider(s): " + ", ".join(recorded["providers"]),
  358. )
  359. else:
  360. report.add("capability probe", True, "register() ran in isolation")
  361. for kind, manifest_key in (
  362. ("tools", "provides_tools"),
  363. ("hooks", "provides_hooks"),
  364. ("middleware", "provides_middleware"),
  365. ):
  366. declared = set(_declared_list(manifest, manifest_key))
  367. actual = set(recorded.get(kind) or [])
  368. undeclared = sorted(actual - declared)
  369. unregistered = sorted(declared - actual)
  370. if undeclared:
  371. report.add(
  372. f"declared {kind}",
  373. False,
  374. f"undeclared {kind} registered (not in {manifest_key}): "
  375. f"{', '.join(undeclared)}",
  376. )
  377. else:
  378. report.add(f"declared {kind}", True, "matches registrations")
  379. if unregistered:
  380. report.warn(
  381. f"{manifest_key} declares {', '.join(unregistered)} "
  382. f"but register() did not register them"
  383. )
  384. return recorded
  385. def _builtin_tool_names() -> list[str]:
  386. """Return the built-in tool registry names (discovery-timing safe).
  387. ``tools.registry`` starts empty — built-in tool modules self-register on
  388. import, so we must run ``discover_builtin_tools()`` first (idempotent;
  389. see the AGENTS.md discover_plugins timing pitfall).
  390. """
  391. try:
  392. from tools.registry import discover_builtin_tools, registry
  393. discover_builtin_tools()
  394. return list(registry.get_all_tool_names())
  395. except Exception:
  396. return []
  397. def _check_builtin_collisions(
  398. report: ValidationReport, manifest: dict, recorded: Optional[dict]
  399. ) -> None:
  400. candidate_tools = set(_declared_list(manifest, "provides_tools"))
  401. if recorded:
  402. candidate_tools.update(recorded.get("tools") or [])
  403. if not candidate_tools:
  404. report.add("built-in tool collisions", True, "no tools to check")
  405. return
  406. builtin = set(_builtin_tool_names())
  407. collisions = sorted(candidate_tools & builtin)
  408. if collisions:
  409. report.add(
  410. "built-in tool collisions",
  411. False,
  412. "tool name(s) collide with built-in tools: "
  413. f"{', '.join(collisions)}",
  414. )
  415. else:
  416. report.add("built-in tool collisions", True, "no collisions")
  417. # ─── Entry point ─────────────────────────────────────────────────────────────
  418. def validate_plugin_dir(
  419. plugin_dir: Path, probe: Optional[tuple[list[str], dict[str, str]]] = None,
  420. ) -> ValidationReport:
  421. """Run every admission check against *plugin_dir* and return the report. *probe* is
  422. ``(python argv prefix, env)`` for the capability probe (see ``_run_capability_probe``)."""
  423. report = ValidationReport()
  424. plugin_dir = Path(plugin_dir)
  425. if not plugin_dir.is_dir():
  426. report.add(
  427. "plugin directory", False, f"{plugin_dir} is not a directory"
  428. )
  429. return report
  430. manifest_file = plugin_dir / "plugin.yaml"
  431. if not manifest_file.is_file():
  432. manifest_file = plugin_dir / "plugin.yml"
  433. if not manifest_file.is_file():
  434. # Portable Agent Plugins v1 (#81196): a plugin.json-only package is
  435. # admissible — validated through the portable manifest reader. When a
  436. # package carries both manifests the native plugin.yaml always wins
  437. # (this branch is only reached when no native manifest exists).
  438. portable_file = plugin_dir / "plugin.json"
  439. if portable_file.is_file():
  440. return _validate_portable_plugin(report, plugin_dir)
  441. report.add(
  442. "manifest", False,
  443. "no plugin.yaml (or portable plugin.json) in the plugin directory",
  444. )
  445. return report
  446. import hermes_yaml as yaml
  447. try:
  448. manifest = yaml.safe_load(
  449. manifest_file.read_text(encoding="utf-8-sig")
  450. )
  451. except Exception as exc:
  452. report.add("manifest", False, f"plugin.yaml failed to parse: {exc}")
  453. return report
  454. if not isinstance(manifest, dict):
  455. report.add("manifest", False, "plugin.yaml must be a mapping")
  456. return report
  457. report.add("manifest", True, "plugin.yaml parses")
  458. _check_manifest_fields(report, manifest)
  459. _check_requires_hermes(report, manifest)
  460. _check_config_spec(report, manifest)
  461. _check_requires_env(report, manifest)
  462. _check_oauth(report, manifest, plugin_dir)
  463. _check_loadable(report, plugin_dir, manifest)
  464. _check_python_dependencies(report, plugin_dir)
  465. recorded = _check_capabilities(report, manifest, plugin_dir, probe)
  466. _check_builtin_collisions(report, manifest, recorded)
  467. _check_trusted_inbound(report, recorded)
  468. _check_security_scan(report, plugin_dir)
  469. check_core_override(report, plugin_dir)
  470. check_private_imports(report, plugin_dir)
  471. check_desktop_surface(report, plugin_dir)
  472. check_language_packs(report, manifest, plugin_dir)
  473. from hermes_cli.plugin_isolation_audit import audit_plugin_dir
  474. report.isolation = audit_plugin_dir(plugin_dir, manifest).to_dict()
  475. return report
  476. def _check_trusted_inbound(report: ValidationReport, recorded: Optional[dict]) -> None:
  477. """Surface ``trusted_inbound`` platforms (their events skip user allowlists and pairing); one
  478. naming a core platform fails, as the loader refuses it."""
  479. from gateway.platform_registry import core_ships_platform
  480. for name in (recorded or {}).get("trusted_inbound") or []:
  481. if core_ships_platform(name):
  482. report.add("trusted inbound", False, f"platform '{name}' ships with core; trusted_inbound is refused for it")
  483. else:
  484. report.add("trusted inbound", True, f"platform '{name}' is trusted_inbound: its events skip user allowlists and pairing")
  485. _LOADABLE_ENTRYPOINTS = ("__init__.py", "desktop/plugin.js", "plugin.json")
  486. def _check_loadable(report: ValidationReport, plugin_dir: Path, manifest: Optional[dict] = None) -> None:
  487. """A plugin.yaml with nothing beside it that Hermes can load (no ``register()`` module, no
  488. desktop bundle, no portable manifest, no declared language pack) installs "successfully" and does
  489. nothing — a pip-layout repo whose code lives under ``src/`` behind an entry point is the usual shape."""
  490. present = [rel for rel in _LOADABLE_ENTRYPOINTS if (plugin_dir / rel).is_file()]
  491. if (manifest or {}).get("provides_locales") and (plugin_dir / "locales").is_dir():
  492. present.append("locales/ (language pack)")
  493. report.add(
  494. "loadable", bool(present),
  495. f"entry: {', '.join(present)}" if present else
  496. "nothing to load: no __init__.py, desktop/plugin.js, plugin.json or provides_locales + locales/ beside "
  497. "plugin.yaml (pip-layout packages need a directory-plugin wrapper with a pyproject.toml declaring the deps)",
  498. )
  499. def _check_python_dependencies(report: ValidationReport, plugin_dir: Path) -> None:
  500. """Declared deps (pyproject ``[project].dependencies`` or manifest ``python_dependencies``) must be
  501. well-formed PEP 508 specs the installer will accept; a plugin opting out with
  502. ``python_runtime: external`` declares none."""
  503. from pm.plugin_declarations import read_python_declaration, unsupported_requirements
  504. try:
  505. decl = read_python_declaration(plugin_dir)
  506. if decl.external:
  507. report.add("python dependencies", True, "external runtime (plugin manages its own)")
  508. return
  509. urls = unsupported_requirements(decl.requirements)
  510. installable = decl.install_requirements
  511. except (ValueError, OSError) as exc:
  512. report.add("python dependencies", False, f"declaration invalid: {exc}")
  513. return
  514. if urls:
  515. report.warn("python dependencies: direct URL requirement(s) are not managed by PM; "
  516. f"use a plugin-owned external runtime: {', '.join(urls)}")
  517. source = "pyproject" if decl.pyproject is not None else "manifest"
  518. detail = f"{len(installable)} requirements from {source}" if decl.requirements else "none declared"
  519. report.add("python dependencies", True, detail)
  520. def _check_security_scan(report: ValidationReport, plugin_dir: Path) -> None:
  521. """Run the install-time scanner at admission, so a pin a reviewer approves is one the
  522. installer will accept: ``dangerous`` fails the entry; ``caution`` findings surface as
  523. warnings for the reviewer (the installer trusts them once the pin is merged)."""
  524. from tools.plugin_guard import scan_plugin
  525. result = scan_plugin(plugin_dir)
  526. flagged = [f for f in result.findings if f.severity in ("critical", "high")]
  527. summary = ", ".join(sorted({f"{f.pattern_id} ({Path(f.file).name}:{f.line})" for f in flagged})) or "no findings"
  528. if result.verdict == "dangerous":
  529. report.add("security scan", False, f"dangerous: {summary}")
  530. return
  531. report.add("security scan", True, result.verdict)
  532. if result.verdict == "caution":
  533. report.warn(f"security scan caution: {summary}")
  534. def _validate_portable_plugin(report: ValidationReport, plugin_dir: Path) -> ValidationReport:
  535. """Admission checks for a portable Agent Plugins v1 (plugin.json) package.
  536. Portable packages have no register() entry point, so the capability
  537. probe does not apply; validation is the manifest reader's own
  538. diagnostics (schema shape, name, supported subset).
  539. """
  540. try:
  541. from hermes_cli.agent_plugins import load_agent_plugin
  542. from hermes_platform.resolver.availability import availability
  543. with tempfile.TemporaryDirectory() as data_root:
  544. package = load_agent_plugin(plugin_dir, Path(data_root))
  545. manifest = package.manifest
  546. diagnostics = package.diagnostics
  547. except Exception as exc:
  548. report.add("portable manifest", False, f"plugin.json failed validation: {exc}")
  549. return report
  550. for diag in diagnostics:
  551. scope = getattr(diag, "scope", "")
  552. message = getattr(diag, "message", str(diag))
  553. report.warnings.append(f"{scope}: {message}" if scope else message)
  554. report.add("portable manifest", True, "plugin.json parses (Agent Plugins v1)")
  555. name = str(manifest.get("name") or "").strip()
  556. report.add(
  557. "manifest fields",
  558. bool(name),
  559. "name present" if name else "plugin.json missing required 'name'",
  560. )
  561. from hermes_cli.agent_plugins import manifest_config_schema
  562. _check_config_spec(report, {"config_schema": manifest_config_schema(manifest)})
  563. for server_name, config in package.mcp_servers.items():
  564. if config.get("trust") == "untrusted":
  565. report.add(f"server trust: {server_name}", True,
  566. "untrusted (Hermes asks before every write-capable tool call)")
  567. if config.get("tool_costs"):
  568. limit = config.get("spend_limit") or 0
  569. report.add(f"server costs: {server_name}", True,
  570. f"{len(config['tool_costs'])} costed tool(s), "
  571. + (f"spend limit {limit} {config.get('cost_unit') or 'credits'} per chat" if limit
  572. else "no spend limit"))
  573. for server_name, server_decl in package.server_declarations.items():
  574. result = availability(server_decl.declaration)
  575. detail = result.state
  576. if result.version:
  577. detail += f", version {result.version}"
  578. if result.path:
  579. detail += f", path {result.path}"
  580. report.add(f"server availability: {server_name}", True, detail)
  581. _check_security_scan(report, plugin_dir)
  582. check_desktop_surface(report, plugin_dir)
  583. from hermes_cli.plugin_isolation_audit import audit_plugin_dir
  584. report.isolation = audit_plugin_dir(plugin_dir, manifest).to_dict()
  585. return report