hermes-plugin-guard 0.1.3__py3-none-any.whl

hermes_plugin_guard/__init__.py

@@ -0,0 +1,7 @@
+"""Static security checks for Hermes Agent plugins."""
+
+from .models import Finding, ScanResult, Severity
+from .scanner import scan
+
+__all__ = ["Finding", "ScanResult", "Severity", "scan"]
+__version__ = "0.1.3"

hermes_plugin_guard/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

hermes_plugin_guard/catalog.py

@@ -0,0 +1,252 @@
+"""Rule catalog for stable IDs, help text, and SARIF metadata."""
+
+from __future__ import annotations
+
+from .models import Rule, Severity
+
+
+def _rule(
+    rule_id: str,
+    title: str,
+    description: str,
+    remediation: str,
+    severity: Severity,
+    category: str,
+) -> Rule:
+    return Rule(
+        id=rule_id,
+        title=title,
+        description=description,
+        remediation=remediation,
+        default_severity=severity,
+        category=category,
+    )
+
+
+RULES: dict[str, Rule] = {
+    "HPG001": _rule(
+        "HPG001",
+        "Plugin declaration missing",
+        (
+            "Hermes directory plugins use plugin.yaml; pip-distributed plugins use the "
+            "hermes_agent.plugins entry-point group."
+        ),
+        (
+            "Add plugin.yaml to a directory plugin or declare "
+            '[project.entry-points."hermes_agent.plugins"] in pyproject.toml.'
+        ),
+        Severity.HIGH,
+        "manifest",
+    ),
+    "HPG002": _rule(
+        "HPG002",
+        "Plugin manifest is invalid",
+        "An unreadable or non-mapping manifest cannot be interpreted safely.",
+        "Fix the YAML syntax and keep the root value as a mapping.",
+        Severity.HIGH,
+        "manifest",
+    ),
+    "HPG003": _rule(
+        "HPG003",
+        "Required plugin metadata missing",
+        "Name, version, and description make plugins identifiable and reviewable.",
+        "Add the missing metadata to plugin.yaml or the pyproject.toml project table.",
+        Severity.MEDIUM,
+        "manifest",
+    ),
+    "HPG004": _rule(
+        "HPG004",
+        "Unknown plugin kind",
+        "Unknown plugin kinds are coerced by Hermes and may use the wrong loader.",
+        "Use standalone, backend, exclusive, platform, or model-provider.",
+        Severity.MEDIUM,
+        "manifest",
+    ),
+    "HPG005": _rule(
+        "HPG005",
+        "Plugin entry point missing",
+        "Directory plugins need __init__.py; dashboard plugins need their declared bundle.",
+        "Add the missing entry file and expose the loader expected by the plugin kind.",
+        Severity.HIGH,
+        "manifest",
+    ),
+    "HPG006": _rule(
+        "HPG006",
+        "Hook declaration mismatch",
+        "Literal hook registrations should match the hooks declared by the manifest.",
+        "Update plugin.yaml or the ctx.register_hook call so they agree.",
+        Severity.MEDIUM,
+        "manifest",
+    ),
+    "HPG101": _rule(
+        "HPG101",
+        "Dynamic code execution",
+        (
+            "eval, exec, compile, and direct __import__ calls can execute or obscure "
+            "content that static review cannot fully bound."
+        ),
+        "Use normal imports, a parser, or a narrow allow-listed dispatcher.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG102": _rule(
+        "HPG102",
+        "Unsafe deserialization",
+        "pickle and unsafe YAML loaders can execute attacker-controlled code.",
+        "Use JSON, yaml.safe_load, or an explicitly safe loader.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG103": _rule(
+        "HPG103",
+        "Direct process execution",
+        "Direct process APIs bypass Hermes' terminal approval and output-safety pipeline.",
+        "Use ctx.dispatch_tool('terminal', ...) or strictly constrain arguments and shell=False.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG104": _rule(
+        "HPG104",
+        "Sensitive path reference",
+        "The plugin references a path commonly containing credentials or private keys.",
+        "Remove the access or document and constrain it to the minimum required file.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG105": _rule(
+        "HPG105",
+        "Unrestricted network listener",
+        "Binding to all interfaces can expose an unauthenticated plugin service.",
+        "Bind to loopback by default and require explicit authentication for remote use.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG106": _rule(
+        "HPG106",
+        "Network capability",
+        "The plugin imports a networking client or socket module.",
+        "Review destinations, TLS verification, timeouts, and data sent off-device.",
+        Severity.INFO,
+        "python",
+    ),
+    "HPG107": _rule(
+        "HPG107",
+        "Undeclared secret environment access",
+        (
+            "A secret-like environment variable is read but not declared in requires_env "
+            "or optional_env."
+        ),
+        ("Declare it in plugin.yaml so users see the credential requirement before enablement."),
+        Severity.MEDIUM,
+        "python",
+    ),
+    "HPG108": _rule(
+        "HPG108",
+        "Destructive filesystem operation",
+        "Deletion APIs can remove user or workspace data when paths are not constrained.",
+        "Constrain targets to a plugin-owned directory and add refusal checks.",
+        Severity.MEDIUM,
+        "python",
+    ),
+    "HPG109": _rule(
+        "HPG109",
+        "TLS verification disabled",
+        "Disabling certificate verification permits machine-in-the-middle attacks.",
+        "Keep TLS verification enabled or trust a narrowly scoped custom CA.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG110": _rule(
+        "HPG110",
+        "Privileged plugin surface",
+        "Tool overrides, pre-auth gateway hooks, and message injection can alter core control flow.",
+        "Remove the privileged option or document why it is required and gate it explicitly.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG111": _rule(
+        "HPG111",
+        "Load-time side effect",
+        "Process, network, or destructive calls during import/register run when a plugin is enabled.",
+        "Move the action behind an explicit tool or user-triggered command.",
+        Severity.HIGH,
+        "python",
+    ),
+    "HPG112": _rule(
+        "HPG112",
+        "Outbound network egress",
+        "A concrete outbound connection or request can send plugin or user data off-device.",
+        (
+            "Document and constrain destinations, send only required data, use encrypted "
+            "transport, and make network access visible to users."
+        ),
+        Severity.MEDIUM,
+        "python",
+    ),
+    "HPG201": _rule(
+        "HPG201",
+        "Secret material committed",
+        "Private keys, tokens, and credential files must not ship with a plugin.",
+        "Revoke the credential, remove it from history, and use requires_env instead.",
+        Severity.CRITICAL,
+        "secrets",
+    ),
+    "HPG202": _rule(
+        "HPG202",
+        "Unpinned remote dependency",
+        "Mutable Git or URL dependencies can change without a plugin code review.",
+        "Pin Git dependencies to a full commit SHA and verify the source.",
+        Severity.HIGH,
+        "dependencies",
+    ),
+    "HPG203": _rule(
+        "HPG203",
+        "Dependency has no upper bound",
+        "An open-ended dependency range increases supply-chain and compatibility risk.",
+        "Add a compatible upper bound, for example >=1.2,<2.",
+        Severity.LOW,
+        "dependencies",
+    ),
+    "HPG204": _rule(
+        "HPG204",
+        "Remote installer executes without verification",
+        (
+            "Downloading a mutable script and piping it directly to a shell executes code "
+            "that was not part of the reviewed plugin."
+        ),
+        (
+            "Pin a versioned artifact, verify its checksum or signature, and execute it only "
+            "after verification."
+        ),
+        Severity.HIGH,
+        "dependencies",
+    ),
+    "HPG301": _rule(
+        "HPG301",
+        "Open-source license missing",
+        "A public repository without a license is not safely reusable or contributable.",
+        "Add an OSI-approved LICENSE file.",
+        Severity.MEDIUM,
+        "project",
+    ),
+    "HPG302": _rule(
+        "HPG302",
+        "Security policy missing",
+        "Maintainers need a private path for reporting plugin vulnerabilities.",
+        "Add SECURITY.md with supported versions and a reporting channel.",
+        Severity.LOW,
+        "project",
+    ),
+    "HPG303": _rule(
+        "HPG303",
+        "Tests missing",
+        "Plugins with full agent privileges should have repeatable safety tests.",
+        "Add automated tests covering registration and high-risk paths.",
+        Severity.LOW,
+        "project",
+    ),
+}
+
+
+def get_rule(rule_id: str) -> Rule:
+    return RULES[rule_id]

hermes_plugin_guard/cli.py

@@ -0,0 +1,143 @@
+"""Command-line interface for hermes-plugin-guard."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from . import __version__
+from .catalog import RULES
+from .models import Severity
+from .reporters import render
+from .scanner import scan
+
+FORMATS = ("text", "json", "sarif", "github")
+THRESHOLDS = ("critical", "high", "medium", "low", "info", "none")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hermes-plugin-guard",
+        description=(
+            "Statically inspect Hermes Agent plugins before enabling them. "
+            "Target code is never imported or executed."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan_parser = subparsers.add_parser(
+        "scan",
+        help="scan a plugin directory or repository",
+    )
+    scan_parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="plugin or repository path (default: current directory)",
+    )
+    scan_parser.add_argument(
+        "--format",
+        dest="report_format",
+        choices=FORMATS,
+        default="text",
+        help="output format (default: text)",
+    )
+    scan_parser.add_argument(
+        "--output",
+        type=Path,
+        help="write the report to this file instead of stdout",
+    )
+    scan_parser.add_argument(
+        "--fail-on",
+        choices=THRESHOLDS,
+        default="high",
+        help="minimum severity that returns exit 1 (default: high)",
+    )
+    scan_parser.add_argument(
+        "--exclude",
+        "--exclude-rule",
+        dest="excluded_rules",
+        action="append",
+        default=[],
+        metavar="RULE_ID",
+        help="exclude a rule ID; may be repeated",
+    )
+
+    rules_parser = subparsers.add_parser(
+        "rules",
+        help="list all checks and their default severity",
+    )
+    rules_parser.add_argument(
+        "--format",
+        dest="report_format",
+        choices=("text", "json"),
+        default="text",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "rules":
+        return _print_rules(args.report_format)
+
+    excluded_rules = [value.upper() for value in args.excluded_rules]
+    unknown = sorted(set(excluded_rules) - set(RULES))
+    if unknown:
+        parser.error(f"unknown rule ID(s): {', '.join(unknown)}")
+
+    threshold = None if args.fail_on == "none" else Severity.parse(args.fail_on)
+    try:
+        result = scan(args.path, excluded_rules=excluded_rules)
+        report = render(result, args.report_format, threshold)
+        _write_report(report, args.output)
+    except (FileNotFoundError, NotADirectoryError, OSError, ValueError) as exc:
+        print(f"hermes-plugin-guard: error: {exc}", file=sys.stderr)
+        return 2
+    return 1 if result.fails_at(threshold) else 0
+
+
+def _write_report(report: str, output: Path | None) -> None:
+    if output is None:
+        sys.stdout.write(report)
+        return
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(report, encoding="utf-8")
+
+
+def _print_rules(report_format: str) -> int:
+    if report_format == "json":
+        import json
+
+        payload = [
+            {
+                "id": rule.id,
+                "severity": rule.default_severity.label,
+                "title": rule.title,
+                "category": rule.category,
+                "description": rule.description,
+                "remediation": rule.remediation,
+            }
+            for rule in RULES.values()
+        ]
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 0
+
+    for rule in RULES.values():
+        print(f"{rule.id}  {rule.default_severity.label.upper():8}  {rule.title}")
+        print(f"         {rule.description}")
+        print(f"         Fix: {rule.remediation}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

hermes_plugin_guard/dependency_scan.py

@@ -0,0 +1,264 @@
+"""Supply-chain checks for Python dependency declarations."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+
+from .catalog import get_rule
+from .manifest import MAX_MANIFEST_BYTES
+from .models import Finding
+
+FULL_SHA_RE = re.compile(r"(?i)(?:@|/)[0-9a-f]{40}(?:[#?]|$)")
+NAME_RE = re.compile(r"^[A-Za-z0-9_.-]+")
+REMOTE_FETCH_RE = re.compile(r"(?i)\b(?:curl|wget)\b[^\n]*(?:https?://)")
+PIPE_TO_SHELL_RE = re.compile(
+    r"(?i)\|\s*(?:(?:/usr/bin/env|env)\s+)?(?:ba|da|fi|z)?sh\b"
+    r"|\|\s*(?:iex|invoke-expression)\b"
+)
+
+
+def inspect_dependencies(root: Path, repository_root: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    seen: set[Path] = set()
+    candidates = sorted(root.glob("requirements*.txt"))
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        candidates.append(pyproject)
+    manifest = root / "plugin.yaml"
+    if manifest.is_file():
+        candidates.append(manifest)
+
+    for path in candidates:
+        resolved = path.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        if path.name == "pyproject.toml":
+            findings.extend(_inspect_pyproject(path, repository_root))
+        elif path.name == "plugin.yaml":
+            findings.extend(_inspect_plugin_manifest(path, repository_root))
+        else:
+            findings.extend(_inspect_requirements(path, repository_root))
+    return findings
+
+
+def _inspect_requirements(path: Path, root: Path) -> list[Finding]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError):
+        return []
+    entries = (
+        (line_number, line.strip())
+        for line_number, line in enumerate(lines, start=1)
+        if line.strip() and not line.lstrip().startswith(("#", "-r", "--requirement"))
+    )
+    return _inspect_entries(entries, _relative(path, root))
+
+
+def _inspect_pyproject(path: Path, root: Path) -> list[Finding]:
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return []
+
+    dependencies: list[str] = []
+    project = data.get("project")
+    project_name = ""
+    if isinstance(project, dict):
+        raw_name = project.get("name")
+        if isinstance(raw_name, str):
+            project_name = raw_name
+        raw = project.get("dependencies")
+        if isinstance(raw, list):
+            dependencies.extend(item for item in raw if isinstance(item, str))
+        optional = project.get("optional-dependencies")
+        if isinstance(optional, dict):
+            for group in optional.values():
+                if isinstance(group, list):
+                    dependencies.extend(item for item in group if isinstance(item, str))
+
+    build_system = data.get("build-system")
+    if isinstance(build_system, dict):
+        raw = build_system.get("requires")
+        if isinstance(raw, list):
+            dependencies.extend(item for item in raw if isinstance(item, str))
+
+    lines = path.read_text(encoding="utf-8").splitlines()
+    entries: list[tuple[int, str]] = []
+    search_from = 0
+    for dependency in dependencies:
+        line_number = 1
+        for index in range(search_from, len(lines)):
+            if dependency in lines[index]:
+                line_number = index + 1
+                search_from = index + 1
+                break
+        entries.append((line_number, dependency))
+    ignored_names = {project_name} if project_name else set()
+    return _inspect_entries(entries, _relative(path, root), ignored_names=ignored_names)
+
+
+def _inspect_plugin_manifest(path: Path, root: Path) -> list[Finding]:
+    try:
+        if path.stat().st_size > MAX_MANIFEST_BYTES:
+            # The structural manifest pass reports HPG002. Do not parse the
+            # same oversized untrusted YAML again during dependency analysis.
+            return []
+        with path.open(encoding="utf-8") as stream:
+            text = stream.read(MAX_MANIFEST_BYTES + 1)
+        if len(text) > MAX_MANIFEST_BYTES:
+            return []
+        data = yaml.safe_load(text) or {}
+    except (OSError, UnicodeError, yaml.YAMLError, RecursionError):
+        return []
+    if not isinstance(data, dict):
+        return []
+
+    lines = text.splitlines()
+    pip_dependencies = data.get("pip_dependencies")
+    entries: list[tuple[int, str]] = []
+    if isinstance(pip_dependencies, list):
+        search_from = 0
+        for dependency in pip_dependencies:
+            if not isinstance(dependency, str):
+                continue
+            line_number, search_from = _line_for_yaml_value(
+                lines,
+                dependency,
+                search_from,
+                key=None,
+            )
+            entries.append((line_number, dependency))
+
+    relative = _relative(path, root)
+    findings = _inspect_entries(entries, relative)
+    external_dependencies = data.get("external_dependencies")
+    if not isinstance(external_dependencies, list):
+        return findings
+
+    search_from = 0
+    for dependency in external_dependencies:
+        if not isinstance(dependency, dict):
+            continue
+        install = dependency.get("install")
+        if not isinstance(install, str) or not _pipes_remote_script_to_shell(install):
+            continue
+        line_number, search_from = _line_for_yaml_value(
+            lines,
+            install,
+            search_from,
+            key="install",
+        )
+        rule = get_rule("HPG204")
+        findings.append(
+            Finding(
+                rule_id="HPG204",
+                severity=rule.default_severity,
+                message="External dependency downloads a remote script and pipes it to a shell.",
+                path=relative,
+                line=line_number,
+                evidence="remote download | shell",
+            )
+        )
+    return findings
+
+
+def _line_for_yaml_value(
+    lines: list[str],
+    value: str,
+    search_from: int,
+    *,
+    key: str | None,
+) -> tuple[int, int]:
+    def is_candidate(line: str) -> bool:
+        stripped = line.lstrip()
+        marker = f"{key}:" if key else "-"
+        return stripped.startswith(marker) and value in line
+
+    for index in range(search_from, len(lines)):
+        if is_candidate(lines[index]):
+            return index + 1, index + 1
+    for index, line in enumerate(lines):
+        if is_candidate(line):
+            return index + 1, index + 1
+    return 1, search_from
+
+
+def _pipes_remote_script_to_shell(command: str) -> bool:
+    return bool(REMOTE_FETCH_RE.search(command) and PIPE_TO_SHELL_RE.search(command))
+
+
+def _inspect_entries(
+    entries: Iterable[tuple[int, str]],
+    relative_path: str,
+    *,
+    ignored_names: set[str] | None = None,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    normalized_ignored = {_normalize_name(name) for name in ignored_names or set()}
+    for line, raw_entry in entries:
+        entry = raw_entry.split(";", 1)[0].strip()
+        if not entry or entry.startswith(("-e ", "--editable ")):
+            entry = entry.split(maxsplit=1)[-1] if " " in entry else entry
+
+        is_remote = (
+            "git+" in entry
+            or " @ http://" in entry
+            or " @ https://" in entry
+            or entry.startswith(("http://", "https://"))
+        )
+        if is_remote and not FULL_SHA_RE.search(entry):
+            rule = get_rule("HPG202")
+            findings.append(
+                Finding(
+                    rule_id="HPG202",
+                    severity=rule.default_severity,
+                    message=f"Remote dependency is not pinned to a full commit SHA: {entry!r}.",
+                    path=relative_path,
+                    line=line,
+                    evidence=entry,
+                )
+            )
+            continue
+
+        if is_remote or entry.startswith((".", "/", "file:")):
+            continue
+        if not NAME_RE.match(entry):
+            continue
+
+        match = NAME_RE.match(entry)
+        if match is None:
+            continue
+        if _normalize_name(match.group(0)) in normalized_ignored:
+            continue
+        spec = entry[match.end() :]
+        bounded = "==" in spec or "~=" in spec or "<" in spec
+        if not bounded:
+            rule = get_rule("HPG203")
+            findings.append(
+                Finding(
+                    rule_id="HPG203",
+                    severity=rule.default_severity,
+                    message=f"Dependency has no compatible upper bound: {entry!r}.",
+                    path=relative_path,
+                    line=line,
+                    evidence=entry,
+                )
+            )
+    return findings
+
+
+def _normalize_name(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).casefold()
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()