#!/usr/bin/env python3 """Plugin Guard — ``skills_guard`` engine applied to ``hermes plugins install``/``update``. Plugins run in-process but are *expected* to read their own env keys, call provider APIs and spawn subprocesses, so: full pattern set on docs/config files (where prompt-injection lives); the "reads own secret"/"HTTP call with key" family exempt on *code* files; plugin-sized structural limits; VCS/venv noise skipped. ``safe`` installs, ``caution`` needs confirmation, ``dangerous`` is blocked and ``--force`` does NOT override. """ from __future__ import annotations import ast import codecs import io import os import subprocess import tokenize from datetime import datetime, timezone, UTC from pathlib import Path from typing import Iterator, List, Optional, Tuple from tools.plugin_guard_context import ( STEP_DOWN, catalog_cap, is_agent_facing, is_authorized_keys_prose, is_base64_archive_roundtrip, is_base64_media, is_benign_lazy_os_import, is_ci_workflow, is_coin_name_only, is_disclosed_config_note, is_doc_prose, is_env_dump_in_safety_clause, is_hex_in_char_class, is_inert_fixture_line, is_json_prose_value, is_locale_catalog, is_loopback_continuation, is_loopback_only, is_own_proc_read, is_pip_install_in_prose_literal, is_public_client_key, is_quoted_injection_phrase, is_regex_alternation_token, is_repo_root_traversal, is_self_uninstall_doc, is_sudo_inert, is_test_tree, is_trusted_installer_pipe, logical_line, prose_cap) from tools.skills_guard import ( Finding, ScanResult, SUSPICIOUS_BINARY_EXTENSIONS, _determine_verdict, format_scan_report, scan_file) PLUGIN_SCANNER_VERSION = "plugin-guard-v15" # Never scanned: VCS internals, caches, vendored envs. EXCLUDED_DIRS = { ".git", "__pycache__", "node_modules", ".venv", "venv", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".tox"} # Test trees ARE scanned (``plugins_loader`` sets ``submodule_search_locations`` to the # plugin root, so ``from .tests import evil`` runs whatever lives there), but findings under # them step down one severity (``plugin_guard_context.is_test_tree``): fixtures deliberately # hold hostile strings to prove the plugin rejects them, and an un-overridable ``dangerous`` # made such plugins uninstallable and taught authors to obfuscate their own tests (#89610). # Code files, where "reads an env secret" / "HTTP call with a key" is normal (requires_env). CODE_FILE_EXTENSIONS = {".py", ".js", ".ts", ".sh", ".bash", ".rb", ".pl", ".php"} # Line-comment marker per code extension. Whole-line comments explain intent; hardening # notes like "# a symlink could point at /etc/passwd" are prose *about* a defense. COMMENT_PREFIXES_BY_EXTENSION = { ".py": "#", ".sh": "#", ".bash": "#", ".rb": "#", ".pl": "#", ".r": "#", ".jl": "#", ".js": "//", ".ts": "//", ".php": "//"} # One severity step down from the pattern's default. _COMMENT_SEVERITY_CAP = {"critical": "high", "high": "medium"} # History, not an agent-facing instruction surface: a hardening entry mentioning the threat # it fixed ("A symlink could point at /etc/passwd, so ...") is documentation, not the attack. CHANGELOG_FILENAMES = {"changelog.md"} # Pattern ids exempt on code files (every legitimate provider plugin trips them); still # applied in full to docs/config files. CODE_EXEMPT_PATTERN_IDS = { "python_environ_get_secret", "python_getenv_secret", "python_os_environ", "node_process_env", "ruby_env_secret", "env_exfil_httpx", "env_exfil_requests", "env_exfil_fetch", "env_exfil_curl", "env_exfil_wget", # Agent-facing instruction patterns are meaningless inside code (prompt docstrings trip them). "context_exfil", "send_to_url", "fake_policy", # Plugins legitimately write config.yaml in post_setup and base64 credentials (Basic auth). "agent_config_mod", "agent_config_contract", "encoded_exfil"} # Severity remaps: a bundled binary is warn-tier (repos occasionally vendor one); a mere # ``~/.hermes/.env`` mention is how READMEs say where keys go (READING it still trips # ``read_secrets_file``, critical); ``curl | sh`` in READMEs is caution, not a hard block. SEVERITY_REMAP = { "binary_file": "high", "hermes_env_access": "medium", "curl_pipe_shell": "high"} # In JS/TS, these text matches cannot distinguish a UI label or DNS lookup # template from a write or exfiltration operation. Keep them visible and require # confirmation; do not silently allow them. Shell commands and instructions keep # their critical severity, as do separate credential-read/exfiltration findings. JS_CAPABILITY_REMAP = {"dns_exfil": "high", "ssh_backdoor": "high"} # Plugin scans gate a HOST install: what matters is what executes on the host. Two critical # families describe the author's own dev workflow when they appear in documentation files, so # they land at high (caution) there instead of hard-blocking an otherwise auditable plugin; the # same content in runtime code keeps its critical severity. The generic one-step prose cap for # command/path-shaped findings lives in ``plugin_guard_context`` (``DOC_PROSE_EXTENSIONS``). DOC_PROSE_DEMOTIONS = { # Prose modification bullets ("- Modify: `CLAUDE.md`") in plan/design docs describe the # repo's own files; only executable intent (shell writes, code) stays critical. "agent_config_mod": "high", # Example/demo credentials quoted in docs (placeholder hex, test tokens). Real token-shaped # literals (sk-, ghp_, AKIA, glpat-, private keys) keep their own critical patterns. "hardcoded_secret": "high", } # A root-level ``if __name__ == "__main__":`` block is the module's own self-test harness: # ``plugins_loader`` imports plugins and never runs them as scripts, so a sample credential # quoted there is a fixture, not a shipped secret — the test-tree reasoning applied where a # root-level runtime file has no ``tests/`` to hold it (#112139). Narrower than the # test-tree cap because the block is still directly executable code: only the generic # sample-token pattern is demoted; destructive/persistence/exfil findings and the # provider-signature patterns (``sk-``, ``AKIA``, ``ghp_`` ...) keep full severity there. MAIN_GUARD_DEMOTIONS = {"hardcoded_secret": "high"} # Structural limits — plugins are real codebases, far larger than skills. MAX_PLUGIN_FILE_COUNT = 400 MAX_PLUGIN_TOTAL_SIZE_KB = 10 * 1024 # 10MB of scannable tree MAX_PLUGIN_SINGLE_FILE_KB = 1024 # 1MB single file # Committed bytecode (catalog rule 17): an unchecked-hash or sourceless ``.pyc`` is imported in # place of the ``.py`` this scanner read, so it is the same reviewable-but-unscannable tier as a # bundled binary (``SEVERITY_REMAP["binary_file"]``). _BYTECODE_SUFFIXES = (".pyc", ".pyo") def _walk(plugin_dir: Path) -> Iterator[tuple[Path, str]]: """Yield (path, "a/b/c" relative path) for every non-excluded entry under plugin_dir.""" for f in plugin_dir.rglob("*"): try: rel_parts = f.relative_to(plugin_dir).parts except ValueError: continue if not any(part in EXCLUDED_DIRS for part in rel_parts): yield f, "/".join(rel_parts) def _finding(pattern_id: str, severity: str, category: str, file: str, match: str, description: str) -> Finding: return Finding(pattern_id, severity, category, file, 0, match, description) def _is_main_guard(node: ast.If) -> bool: """Return whether an ``if`` node is the conventional module self-test guard.""" test = node.test if not isinstance(test, ast.Compare) or len(test.ops) != 1 or not isinstance(test.ops[0], ast.Eq): return False if len(test.comparators) != 1: return False left, right = test.left, test.comparators[0] return ( isinstance(left, ast.Name) and left.id == "__name__" and isinstance(right, ast.Constant) and right.value == "__main__" ) or ( isinstance(right, ast.Name) and right.id == "__name__" and isinstance(left, ast.Constant) and left.value == "__main__" ) def _parse_python_source(file_path: Path) -> Optional[ast.Module]: """Parse *file_path* as Python; unreadable or invalid source returns ``None``.""" try: return ast.parse(file_path.read_text(encoding="utf-8-sig")) except (OSError, SyntaxError, ValueError): # ValueError: UnicodeDecodeError, NUL bytes return None def _main_guard_body_lines(file_path: Path) -> set[int]: """Return lines executed only by ``if __name__ == '__main__'`` blocks. Invalid Python deliberately returns no lines so its findings retain the conservative severity. """ tree = _parse_python_source(file_path) if tree is None: return set() lines: set[int] = set() for node in ast.walk(tree): if not isinstance(node, ast.If) or not _is_main_guard(node): continue for statement in node.body: lines.update(range(statement.lineno, getattr(statement, "end_lineno", statement.lineno) + 1)) return lines # Nodes that can own a docstring: only the first statement of a module, class or function is one. _DOCSTRING_OWNERS = (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef) def _declares_non_utf8_source(file_path: Path) -> bool: """A PEP 263 cookie (``# coding: utf-7``) makes CPython run a different text than the UTF-8 parse the docstring spans come from, so those spans say nothing about what executes. Fail closed.""" try: raw = file_path.read_bytes().replace(b"\r\n", b"\n").replace(b"\r", b"\n") codec = tokenize.detect_encoding(io.BytesIO(raw).readline)[0] return codecs.lookup(codec).name not in ("utf-8", "utf-8-sig") except (OSError, SyntaxError, LookupError, UnicodeError): return True def _docstring_lines(file_path: Path) -> set[int]: """Return the lines holding module/class/function docstrings and nothing else. A docstring is prose that documents a defense for a reader, so its findings take the same one-step cap as a whole-line comment (#155823). ``ast`` reports a docstring only for the first statement of a module/class/function, so a triple-quoted *constant* (``PAYLOAD = \\"\\"\\"... \\"\\"\\"``) is not included: prose cannot execute, but a string the code can hand to ``exec`` can. A line any other node also occupies (``\\"\\"\\"x\\"\\"\\"; os.system(...)``, a default argument on a multi-line ``def`` header) is code. Invalid Python returns no lines, keeping every finding at its conservative severity. """ tree = _parse_python_source(file_path) if tree is None or _declares_non_utf8_source(file_path): return set() lines: set[int] = set() docstrings: set[int] = set() for node in ast.walk(tree): if not isinstance(node, _DOCSTRING_OWNERS) or not node.body: continue first = node.body[0] if (isinstance(first, ast.Expr) and isinstance(first.value, ast.Constant) and isinstance(first.value.value, str)): docstrings.update((id(first), id(first.value))) lines.update(range(first.lineno, getattr(first, "end_lineno", first.lineno) + 1)) for node in ast.walk(tree): first_line = getattr(node, "lineno", None) if id(node) in docstrings or first_line is None: continue # A compound statement's span is its whole body: drop only its first line here; the # header's own parts (decorators, arguments, defaults, bases) are nodes of their own. last = first_line if hasattr(node, "body") else getattr(node, "end_lineno", first_line) lines.difference_update(range(first_line, last + 1)) return lines def _docstring_cap(f: Finding) -> str: """The comment cap, floored at ``high`` for a critical. A docstring is runtime data any file can read back (``x.__doc__``, ``getattr(x, "__" + "doc__")``, ``inspect.getdoc``) by names no static scan can enumerate, so a critical one stays visible and needs the user's confirmation (``caution``): never ``safe``, and never the un-overridable ``dangerous`` that prose alone caused.""" return "high" if f.severity == "critical" else _comment_severity(f) def _filter_findings(findings: list[Finding], rel_path: str, file_path: Path) -> list[Finding]: """Apply plugin-specific exemptions and severity remaps to raw findings.""" is_code = Path(rel_path).suffix.lower() in CODE_FILE_EXTENSIONS is_python = file_path.suffix.lower() == ".py" main_guard_lines = _main_guard_body_lines(file_path) if is_python else set() is_js = Path(rel_path).suffix.lower() in {".js", ".ts"} # A CI workflow definition runs on the forge's runner, not the host: same cap as a README. is_ci = is_ci_workflow(rel_path) doc_prose = is_doc_prose(rel_path) or is_ci docstring_lines = _docstring_lines(file_path) if is_python else set() locale_catalog = is_locale_catalog(rel_path) lines = _file_lines(file_path) if findings else [] out: list[Finding] = [] for f in findings: if is_code and f.pattern_id in CODE_EXEMPT_PATTERN_IDS: continue f.severity = ( (JS_CAPABILITY_REMAP.get(f.pattern_id) if is_js else None) or SEVERITY_REMAP.get(f.pattern_id) or f.severity ) if doc_prose and f.pattern_id in DOC_PROSE_DEMOTIONS: f.severity = DOC_PROSE_DEMOTIONS[f.pattern_id] line = lines[f.line - 1] if 0 < f.line <= len(lines) else f.match joined = logical_line(lines, f.line - 1) if 0 < f.line <= len(lines) else line f.severity = _context_severity(f, rel_path, line, joined, doc_prose or locale_catalog, is_code, locale_catalog) if _is_defensive_documentation(f, rel_path, docstring_lines): f.severity = _docstring_cap(f) if f.line in docstring_lines else _comment_severity(f) # A quoted injection phrase in a defensive doc (``"ignore previous instructions"`` in a # CHANGELOG / code comment describing the filter that refuses it) is a note, not caution. if is_quoted_injection_phrase(f, line): f.severity = _at_most(f.severity, "medium") # Last and critical-only: a one-step cap that can never re-raise a finding an # earlier remap already lowered. if ( f.pattern_id in MAIN_GUARD_DEMOTIONS and f.severity == "critical" and f.line in main_guard_lines ): f.severity = MAIN_GUARD_DEMOTIONS[f.pattern_id] out.append(f) return out _SEVERITY_RANK = {"low": 0, "medium": 1, "high": 2, "critical": 3} def _at_most(severity: str, cap: str) -> str: """Lower *severity* to *cap*; never raise it.""" return cap if _SEVERITY_RANK.get(severity, 0) > _SEVERITY_RANK[cap] else severity def _comment_severity(f: Finding) -> str: """A whole-line comment / changelog entry cannot execute: one step down for every finding, a second for command/path shapes (a comment is prose); agent-facing shapes keep one step.""" sev = _COMMENT_SEVERITY_CAP.get(f.severity, f.severity) return sev if is_agent_facing(f) else STEP_DOWN.get(sev, sev) def _file_lines(file_path: Path) -> list[str]: """Full source lines (``Finding.match`` is truncated to 120 chars); unreadable → [].""" try: return file_path.read_text(encoding="utf-8-sig").split("\n") except (OSError, UnicodeDecodeError): return [] def _context_severity(f: Finding, rel_path: str, line: str, joined: str, doc_prose: bool, is_code: bool, locale_catalog: bool = False) -> str: """Severity after the inert-context demotions (``plugin_guard_context``). Each rule only ever lowers, and every finding stays in the report; the order runs from the broadest context (where the text lives) to the narrowest (what the token sits inside). *joined* is the logical shell line (``line`` plus its ``\\\\``-continuations).""" sev = f.severity if doc_prose: sev = (catalog_cap(f) if locale_catalog else prose_cap(f)) or sev if is_self_uninstall_doc(f, line): sev = _at_most(sev, "medium") elif is_json_prose_value(f, rel_path, line): sev = prose_cap(f) or sev # `"en": "Bare sudo commands are …"` in a tips/translation table if is_test_tree(rel_path): # A key-shaped literal or quoted-only hostile string in a fixture is the corpus the # plugin's own tests reject (#89610): a note. Executable test code steps down once. inert = f.category == "credential_exposure" or is_inert_fixture_line(f, line, is_code, rel_path) sev = _at_most(sev, "medium") if inert else STEP_DOWN.get(sev, sev) if is_code and is_regex_alternation_token(f, line): sev = STEP_DOWN.get(sev, sev) return _inert_context_cap(f, rel_path, line, joined, is_code, doc_prose, sev) # Narrow inert-context demotions, each a ``(predicate, target severity)`` that only ever lowers. See # ``plugin_guard_context`` for the shape each recognises and the attack twin that keeps full severity. def _inert_context_cap(f: Finding, rel_path: str, line: str, joined: str, is_code: bool, doc_prose: bool, sev: str) -> str: if f.pattern_id == "encoded_exfil" and is_base64_media(line): return "low" to_low = ( is_loopback_only(f, line) # 127.0.0.0/8 is a local service, not egress or is_loopback_continuation(f, line, joined) # loopback health check over a `\`-continuation or is_hex_in_char_class(f, line) # `[\x00-\x1F]`: a control-char filter, not a payload or (is_code and is_pip_install_in_prose_literal(f, line)) # "no pip install is needed" message or is_own_proc_read(f, joined) # `/proc/self/cgroup`: container placement, read only ) if to_low: return "low" # Each predicate recognises a disclosed/inert shape that lands at a note (medium), never a block. to_medium = ( is_base64_archive_roundtrip(f, line) # `tar c… | base64 | base64 -d | tar x`: transport or is_coin_name_only(f, line) # "monero gateway" in a connector index, no miner or is_trusted_installer_pipe(f, line) # `curl … hermes/ollama/bun install.sh | sh` or is_sudo_inert(f, line, rel_path) # advisory `sudo apt install` hint / "never … sudo" or is_env_dump_in_safety_clause(f, line) # `env`/`printenv` in a "never inspect env" rule or is_repo_root_traversal(f, line) # `../../..` to the repo root, no sensitive leaf or is_benign_lazy_os_import(f, line) # `__import__("os").environ.get(...)` one member or is_disclosed_config_note(f, rel_path) # disclosed scoped config-write in install docs or is_authorized_keys_prose(f, line, doc_prose) # `authorized_keys` in a UI string, no write ) if to_medium: return _at_most(sev, "medium") if is_public_client_key(f, line): return _at_most(sev, "high") # public-by-design client key (GOCSPX-, phc_), reviewable caution return sev def _is_defensive_documentation(finding: Finding, rel_path: str, docstring_lines: Optional[set[int]] = None) -> bool: """A whole-line code comment, a Python docstring or a changelog entry *describes* threats (the attack a defense rejects, the hardening a release shipped) instead of executing them, so its findings cap one severity step lower — visible and reviewable, never un-overridable ``dangerous`` from prose alone. Runtime code and agent-facing docs keep full severity. """ if Path(rel_path).name.lower() in CHANGELOG_FILENAMES: return True if docstring_lines and finding.line in docstring_lines: return True prefix = COMMENT_PREFIXES_BY_EXTENSION.get(Path(rel_path).suffix.lower()) if prefix is None or not finding.match: return False stripped = finding.match.lstrip() if not stripped.startswith(prefix): return False if prefix == "#" and stripped.startswith(("#!", "#:")): return False return True def _dangerous_findings_summary(findings: list[Finding]) -> str: """Describe the critical findings that made a plugin install dangerous.""" critical = [finding for finding in findings if finding.severity == "critical"] pattern_ids = sorted({finding.pattern_id for finding in critical}) names = f" ({', '.join(pattern_ids)})" if pattern_ids else "" return f"{len(critical)} critical of {len(findings)} findings{names}" def _tracked_bytecode(plugin_dir: Path) -> set[str]: """``.pyc``/``.pyo`` the checkout tracks. ``hermes plugins validate`` imports the plugin before it scans, so an untracked ``__pycache__`` that run wrote is not shipped content; only the index says what the pinned commit carries. Not a checkout (or no git) → empty.""" try: out = subprocess.run( ["git", "-c", "core.fsmonitor=false", "-C", str(plugin_dir), "ls-files", "-z", "--", "*.pyc", "*.pyo"], capture_output=True, check=True, timeout=60, stdin=subprocess.DEVNULL).stdout except (OSError, subprocess.SubprocessError): return set() return {os.fsdecode(p) for p in out.split(b"\0") if p} def _bytecode_findings(plugin_dir: Path) -> list[Finding]: """Tracked bytecode anywhere, plus bytecode outside ``__pycache__`` (CPython 3 never writes it there, so it was shipped even when the tree is not a checkout).""" loose = {rel for f, rel in _walk(plugin_dir) if rel.endswith(_BYTECODE_SUFFIXES) and f.is_file()} return [_finding("bytecode_file", SEVERITY_REMAP["binary_file"], "structural", rel, "committed bytecode", "committed Python bytecode runs in place of the scanned source (catalog rule 17)") for rel in sorted(loose | _tracked_bytecode(plugin_dir))] def _check_plugin_structure(plugin_dir: Path) -> list[Finding]: """Structural checks sized for plugin repositories.""" findings: list[Finding] = _bytecode_findings(plugin_dir) file_count = 0 total_size = 0 resolved_root = plugin_dir.resolve() for f, rel in _walk(plugin_dir): if f.is_symlink(): file_count += 1 try: resolved = f.resolve() except OSError: findings.append(_finding("broken_symlink", "medium", "traversal", rel, "broken symlink", "broken or circular symlink")) continue if not resolved.is_relative_to(resolved_root): findings.append(_finding("symlink_escape", "critical", "traversal", rel, f"symlink -> {resolved}", "symlink points outside the plugin directory")) continue if not f.is_file(): continue file_count += 1 try: size = f.stat().st_size except OSError: continue total_size += size if size > MAX_PLUGIN_SINGLE_FILE_KB * 1024: findings.append(_finding("oversized_file", "medium", "structural", rel, f"{size // 1024}KB", f"file is {size // 1024}KB (limit: {MAX_PLUGIN_SINGLE_FILE_KB}KB)")) ext = f.suffix.lower() if ext in SUSPICIOUS_BINARY_EXTENSIONS: findings.append(_finding("binary_file", SEVERITY_REMAP["binary_file"], "structural", rel, f"binary: {ext}", f"binary/executable file ({ext}) bundled in plugin (cannot be scanned)")) if file_count > MAX_PLUGIN_FILE_COUNT: findings.append(_finding("too_many_files", "medium", "structural", "(directory)", f"{file_count} files", f"plugin has {file_count} files (limit: {MAX_PLUGIN_FILE_COUNT})")) if total_size > MAX_PLUGIN_TOTAL_SIZE_KB * 1024: findings.append(_finding("oversized_bundle", "medium", "structural", "(directory)", f"{total_size // 1024}KB", f"plugin is {total_size // 1024}KB total (limit: {MAX_PLUGIN_TOTAL_SIZE_KB}KB)")) return findings def scan_plugin(plugin_dir: Path, source: str = "") -> ScanResult: """Scan a plugin directory (typically the temp clone); every external plugin is ``community`` trust.""" all_findings: list[Finding] = [] if plugin_dir.is_dir(): all_findings.extend(_check_plugin_structure(plugin_dir)) for f, rel in sorted(_walk(plugin_dir)): if f.is_file() and not f.is_symlink(): all_findings.extend(_filter_findings(scan_file(f, rel_path=rel), rel, f)) verdict = _determine_verdict(all_findings) if all_findings: categories = sorted({f.category for f in all_findings}) summary = f"{plugin_dir.name}: {verdict} — {len(all_findings)} finding(s) in {', '.join(categories)}" else: summary = f"{plugin_dir.name}: clean scan, no threats detected" result = ScanResult( skill_name=plugin_dir.name, source=source or plugin_dir.name, trust_level="community", verdict=verdict, findings=all_findings, scanned_at=datetime.now(UTC).isoformat(), summary=summary) result.scan_provenance = { "scanner_version": PLUGIN_SCANNER_VERSION, "verdict": verdict, "source": result.source} return result def should_allow_plugin_install( result: ScanResult, force: bool = False) -> tuple[Optional[bool], str]: """Map a verdict to ``(allowed, reason)``: True installs, None asks to confirm, False blocks.""" n = len(result.findings) if result.verdict == "safe": return True, "Allowed (clean scan)" if result.verdict == "caution": if force: return True, f"Force-installed despite caution verdict ({n} findings)" return None, f"Requires confirmation (caution verdict, {n} findings)" return False, ( f"Blocked (dangerous verdict, {_dangerous_findings_summary(result.findings)}). " f"--force does not override a dangerous verdict.") __all__ = [ "PLUGIN_SCANNER_VERSION", "format_scan_report", "scan_plugin", "should_allow_plugin_install", ]