plugin-scanner 2.0.146__tar.gz → 2.0.148__tar.gz

{plugin_scanner-2.0.146 → plugin_scanner-2.0.148}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.146
+Version: 2.0.148
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner

{plugin_scanner-2.0.146 → plugin_scanner-2.0.148}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.146"
+version = "2.0.148"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.146 → plugin_scanner-2.0.148}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.146"
+version = "2.0.148"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.146 → plugin_scanner-2.0.148}/src/codex_plugin_scanner/guard/adapters/base.py

@@ -7,11 +7,13 @@ import os
 import shutil
 import subprocess
 from dataclasses import dataclass
+from functools import cached_property
 from pathlib import Path
 
 from ...path_support import resolves_within_root
 from ..models import GuardArtifact, HarnessDetection
 from ..shims import install_guard_shim, remove_guard_shim
+from .contracts import HarnessCoverageSummary, HarnessSetupContract, HarnessSetupStep, setup_contract_for
 
 
 @dataclass(frozen=True, slots=True)
@@ -118,6 +120,28 @@ class HarnessAdapter:
             **shim_manifest,
         }
 
+    @cached_property
+    def _setup_contract(self) -> HarnessSetupContract:
+        contract = setup_contract_for(self.harness)
+        if contract is None:
+            raise ValueError(f"Unsupported harness setup contract: {self.harness}")
+        return contract
+
+    def setup_contract(self) -> HarnessSetupContract:
+        return self._setup_contract
+
+    def setup_steps(self) -> tuple[HarnessSetupStep, ...]:
+        return self.setup_contract().setup_steps
+
+    def verify_steps(self) -> tuple[HarnessSetupStep, ...]:
+        return self.setup_contract().verify_steps
+
+    def repair_steps(self) -> tuple[HarnessSetupStep, ...]:
+        return self.setup_contract().repair_steps
+
+    def coverage_summary(self) -> HarnessCoverageSummary:
+        return self.setup_contract().coverage
+
     def executable_candidates(self, context: HarnessContext) -> tuple[Path, ...]:
         del context
         return ()

{plugin_scanner-2.0.146 → plugin_scanner-2.0.148}/src/codex_plugin_scanner/guard/adapters/contracts.py

@@ -44,6 +44,85 @@ class HarnessProtectionContract:
     smoke_command: str
 
 
+@dataclass(frozen=True, slots=True)
+class HarnessSetupStep:
+    """Plain-language action for connecting or checking one harness."""
+
+    step_id: str
+    title: str
+    body: str
+    command: tuple[str, ...] = ()
+    writes_config: bool = False
+    requires_confirmation: bool = False
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "step_id": self.step_id,
+            "title": self.title,
+            "body": self.body,
+            "command": list(self.command),
+            "writes_config": self.writes_config,
+            "requires_confirmation": self.requires_confirmation,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class HarnessCoverageSummary:
+    """Summary of what Guard can and cannot observe for one harness."""
+
+    native_hooks: bool
+    browser_fallback: bool
+    mcp_proxy: bool
+    prompt_hooks: bool
+    blind_spots: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "native_hooks": self.native_hooks,
+            "browser_fallback": self.browser_fallback,
+            "mcp_proxy": self.mcp_proxy,
+            "prompt_hooks": self.prompt_hooks,
+            "blind_spots": list(self.blind_spots),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class HarnessSetupContract:
+    """Dashboard and CLI setup contract for one supported harness."""
+
+    harness: str
+    display_name: str
+    install_aliases: tuple[str, ...]
+    setup_steps: tuple[HarnessSetupStep, ...]
+    verify_steps: tuple[HarnessSetupStep, ...]
+    repair_steps: tuple[HarnessSetupStep, ...]
+    coverage: HarnessCoverageSummary
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "harness": self.harness,
+            "display_name": self.display_name,
+            "install_aliases": list(self.install_aliases),
+            "setup_steps": [step.to_dict() for step in self.setup_steps],
+            "verify_steps": [step.to_dict() for step in self.verify_steps],
+            "repair_steps": [step.to_dict() for step in self.repair_steps],
+            "coverage": self.coverage.to_dict(),
+        }
+
+
+_DISPLAY_NAMES = {
+    "codex": "Codex",
+    "claude-code": "Claude Code",
+    "opencode": "OpenCode",
+    "copilot": "Copilot",
+    "cursor": "Cursor",
+    "gemini": "Gemini",
+    "hermes": "Hermes",
+    "openclaw": "OpenClaw",
+    "antigravity": "Antigravity",
+}
+
+
 HARNESS_CONTRACTS: tuple[HarnessProtectionContract, ...] = (
     HarnessProtectionContract(
         harness="codex",
@@ -183,6 +262,73 @@ def contract_for(harness: str) -> HarnessProtectionContract | None:
     return _CONTRACT_BY_ALIAS.get(harness)
 
 
+def setup_contract_for(harness: str) -> HarnessSetupContract | None:
+    """Return guided setup metadata for a harness name or install alias."""
+
+    contract = contract_for(harness)
+    if contract is None:
+        return None
+    alias = contract.install_aliases[0] if contract.install_aliases else contract.harness
+    display_name = _DISPLAY_NAMES.get(contract.harness, contract.harness)
+    coverage = HarnessCoverageSummary(
+        native_hooks=contract.native_approval,
+        browser_fallback=contract.browser_fallback,
+        mcp_proxy="mcp_tool" in contract.event_surfaces,
+        prompt_hooks="prompt" in contract.event_surfaces,
+        blind_spots=(contract.known_blind_spots,),
+    )
+    setup_steps = (
+        HarnessSetupStep(
+            step_id="connect",
+            title=f"Connect {display_name}",
+            body=f"Add Guard's local protection hooks for {display_name}.",
+            command=("hol-guard", "apps", "connect", alias),
+            writes_config=True,
+        ),
+        HarnessSetupStep(
+            step_id="review-coverage",
+            title="Review what Guard can see",
+            body="Check covered events and known blind spots before relying on this app.",
+        ),
+    )
+    verify_steps = (
+        HarnessSetupStep(
+            step_id="safe-test",
+            title="Run a safe protection test",
+            body="Confirm Guard can detect the app without reading secrets or changing app config.",
+            command=("hol-guard", "apps", "test", alias),
+        ),
+    )
+    repair_steps = (
+        HarnessSetupStep(
+            step_id="repair",
+            title=f"Repair {display_name} protection",
+            body="Re-apply Guard managed config if hooks were removed or changed.",
+            command=("hol-guard", "apps", "repair", alias),
+            writes_config=True,
+        ),
+    )
+    return HarnessSetupContract(
+        harness=contract.harness,
+        display_name=display_name,
+        install_aliases=contract.install_aliases,
+        setup_steps=setup_steps,
+        verify_steps=verify_steps,
+        repair_steps=repair_steps,
+        coverage=coverage,
+    )
+
+
+def all_setup_contracts() -> tuple[HarnessSetupContract, ...]:
+    """Return guided setup metadata for all supported harnesses."""
+
+    return tuple(
+        setup_contract
+        for contract in HARNESS_CONTRACTS
+        if (setup_contract := setup_contract_for(contract.harness)) is not None
+    )
+
+
 def harness_contracts_table() -> str:
     """Return a Markdown table summarising all harness contracts."""
     header = (

{plugin_scanner-2.0.146 → plugin_scanner-2.0.148}/src/codex_plugin_scanner/guard/cli/commands.py

@@ -121,7 +121,13 @@ from .connect_flow import (
     DEFAULT_GUARD_SYNC_URL,
     run_guard_connect_command,
 )
-from .install_commands import apply_managed_install
+from .install_commands import (
+    apply_managed_install,
+    build_harness_setup_plan,
+    build_harness_verification,
+    list_harness_setup_items,
+    uninstall_confirmation_token,
+)
 from .product import build_guard_start_payload, build_guard_status_payload
 from .update_commands import run_guard_update
 
@@ -134,6 +140,7 @@ _GUARD_HELP_GROUPS = (
     "  start        First-run setup and the Guard operating loop\n"
     "  status       Current local protection state and next actions\n"
     "  dashboard    Open the local Guard dashboard in your browser\n"
+    "  apps         Connect, test, repair, or disconnect protected apps\n"
     "  run          Enforce Guard before a harness launch\n"
     "  approvals    Resolve the current request queue\n"
     "  receipts     Review recent local decisions\n"
@@ -235,7 +242,7 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
         required=True,
         parser_class=FriendlyArgumentParser,
         metavar=(
-            "{start,status,dashboard,bootstrap,detect,install,update,uninstall,run,protect,preflight,scan,diff,receipts,inventory,abom,"
+            "{start,status,dashboard,apps,bootstrap,detect,install,update,uninstall,run,protect,preflight,scan,diff,receipts,inventory,abom,"
             "approvals,explain,allow,deny,policies,exceptions,advisories,events,doctor,connect,login,sync,device,bridge}"
         ),
     )
@@ -255,6 +262,25 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
     _add_guard_common_args(dashboard_parser)
     dashboard_parser.add_argument("--json", action="store_true")
 
+    apps_parser = guard_subparsers.add_parser("apps", help="Connect, test, repair, or disconnect protected apps")
+    _add_guard_common_args(apps_parser)
+    apps_parser.add_argument("--json", action="store_true")
+    apps_subparsers = apps_parser.add_subparsers(dest="apps_command", parser_class=FriendlyArgumentParser)
+    for app_command, help_text in (
+        ("connect", "Connect an app to local Guard protection"),
+        ("test", "Run a safe local Guard protection check"),
+        ("repair", "Repair Guard-managed app config"),
+        ("disconnect", "Remove Guard-managed app config"),
+    ):
+        app_parser = apps_subparsers.add_parser(app_command, help=help_text)
+        app_parser.add_argument("harness")
+        _add_guard_common_args(app_parser, suppress_defaults=True)
+        app_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS)
+        if app_command in {"connect", "repair"}:
+            app_parser.add_argument("--dry-run", action="store_true")
+        if app_command == "disconnect":
+            app_parser.add_argument("--confirm")
+
     admin_parser = guard_subparsers.add_parser("admin", help=argparse.SUPPRESS)
     _add_guard_common_args(admin_parser)
     admin_parser.add_argument("--json", action="store_true")
@@ -680,10 +706,15 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
     ]
 
 
-def _add_guard_common_args(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("--home")
-    parser.add_argument("--guard-home")
-    parser.add_argument("--workspace")
+def _add_guard_common_args(
+    parser: argparse.ArgumentParser,
+    *,
+    suppress_defaults: bool = False,
+) -> None:
+    default = argparse.SUPPRESS if suppress_defaults else None
+    parser.add_argument("--home", default=default)
+    parser.add_argument("--guard-home", default=default)
+    parser.add_argument("--workspace", default=default)
 
 
 def _add_guard_cisco_mode_arg(parser: argparse.ArgumentParser) -> None:
@@ -702,6 +733,82 @@ def _guard_http_url(value: str) -> str:
     return value
 
 
+def _run_apps_command(
+    args: argparse.Namespace,
+    context: HarnessContext,
+    store: GuardStore,
+    workspace: str | None,
+) -> int:
+    apps_command = getattr(args, "apps_command", None)
+    if apps_command is None:
+        _emit(
+            "apps",
+            {
+                "generated_at": _now(),
+                "items": list_harness_setup_items(context, store),
+            },
+            getattr(args, "json", False),
+        )
+        return 0
+
+    harness = str(getattr(args, "harness", "")).strip()
+    if not harness:
+        print("guard apps requires a harness.", file=sys.stderr)
+        return 2
+    if apps_command == "test":
+        try:
+            payload = build_harness_verification(harness, context, store)
+        except ValueError as error:
+            print(str(error), file=sys.stderr)
+            return 2
+        _emit("apps", payload, getattr(args, "json", False))
+        return 0
+
+    if apps_command in {"connect", "repair"} and bool(getattr(args, "dry_run", False)):
+        try:
+            payload = build_harness_setup_plan(apps_command, harness, context, dry_run=True)
+        except ValueError as error:
+            print(str(error), file=sys.stderr)
+            return 2
+        _emit("apps", payload, getattr(args, "json", False))
+        return 0
+
+    if apps_command == "disconnect":
+        try:
+            canonical_harness = get_adapter(harness).harness
+        except ValueError as error:
+            print(str(error), file=sys.stderr)
+            return 2
+        expected_confirmation = uninstall_confirmation_token(canonical_harness)
+        if getattr(args, "confirm", None) != expected_confirmation:
+            payload = {
+                "error": "confirmation_required",
+                "harness": canonical_harness,
+                "confirmation_phrase": expected_confirmation,
+                "confirm_command": f"hol-guard apps disconnect {canonical_harness} --confirm {expected_confirmation}",
+            }
+            _emit("apps", payload, getattr(args, "json", False))
+            return 2
+
+    install_command = "uninstall" if apps_command == "disconnect" else "install"
+    try:
+        payload = apply_managed_install(
+            install_command,
+            harness,
+            False,
+            context,
+            store,
+            workspace,
+            _now(),
+        )
+    except ValueError as error:
+        print(str(error), file=sys.stderr)
+        return 2
+    payload["action"] = apps_command
+    _emit("apps", payload, getattr(args, "json", False))
+    return 0
+
+
 def _build_cisco_scan_options(mode: str) -> ScanOptions:
     return ScanOptions(cisco_skill_scan=mode, cisco_mcp_scan=mode)
 
@@ -879,6 +986,9 @@ def run_guard_command(
         _emit("detect", payload, getattr(args, "json", False))
         return 0
 
+    if args.guard_command == "apps":
+        return _run_apps_command(args, context, store, str(workspace) if workspace else None)
+
     if args.guard_command == "install":
         try:
             payload = apply_managed_install(

plugin_scanner-2.0.148/src/codex_plugin_scanner/guard/cli/install_commands.py

@@ -0,0 +1,273 @@
+"""Helpers for Guard harness install and uninstall flows."""
+
+from __future__ import annotations
+
+import glob as globlib
+from pathlib import Path
+
+from ..adapters import get_adapter, list_adapters
+from ..adapters.base import HarnessAdapter, HarnessContext
+from ..adapters.contracts import contract_for
+from ..consumer import detect_all
+from ..runtime.skill_protection import build_skill_identity, detect_skill_content_risk
+from ..store import GuardStore
+
+
+def apply_managed_install(
+    command: str,
+    requested_harness: str | None,
+    install_all: bool,
+    context: HarnessContext,
+    store: GuardStore,
+    workspace: str | None,
+    now: str,
+) -> dict[str, object]:
+    targets = _resolve_targets(command, requested_harness, install_all, context, store)
+    active = command == "install"
+    managed_installs: list[dict[str, object]] = []
+    for harness in targets:
+        adapter = get_adapter(harness)
+        canonical_harness = adapter.harness
+        manifest = adapter.install(context) if active else adapter.uninstall(context)
+        store.set_managed_install(canonical_harness, active, workspace, manifest, now)
+        managed_install = store.get_managed_install(canonical_harness)
+        if managed_install is not None:
+            managed_installs.append(managed_install)
+    payload: dict[str, object] = {
+        "managed_installs": managed_installs,
+        "auto_detected": requested_harness is None or install_all,
+    }
+    if len(managed_installs) == 1:
+        payload["managed_install"] = managed_installs[0]
+    if active and context.workspace_dir is not None:
+        skill_scan = scan_workspace_skills(context.workspace_dir, store, now)
+        if skill_scan:
+            payload["skill_scan"] = skill_scan
+    return payload
+
+
+def list_harness_setup_items(context: HarnessContext, store: GuardStore | None = None) -> list[dict[str, object]]:
+    items: list[dict[str, object]] = []
+    for adapter in list_adapters():
+        detection = _safe_setup_detection(adapter, context, store)
+        detected = detection["installed"] or detection["command_available"] or bool(detection["config_paths"])
+        if detection["installed"]:
+            status = "protected"
+        elif detected:
+            status = "found"
+        else:
+            status = "not_found"
+        items.append(
+            {
+                "harness": adapter.harness,
+                "status": status,
+                "installed": detection["installed"],
+                "command_available": detection["command_available"],
+                "config_paths": detection["config_paths"],
+                "artifact_count": 0,
+                **adapter.setup_contract().to_dict(),
+            }
+        )
+    return items
+
+
+def build_harness_setup_plan(
+    action: str,
+    requested_harness: str,
+    context: HarnessContext,
+    *,
+    dry_run: bool,
+) -> dict[str, object]:
+    adapter = get_adapter(requested_harness)
+    contract = adapter.setup_contract()
+    if action == "repair":
+        steps = adapter.repair_steps()
+    elif action == "uninstall":
+        steps = ()
+    else:
+        steps = adapter.setup_steps()
+    payload: dict[str, object] = {
+        "harness": adapter.harness,
+        "action": action,
+        "dry_run": dry_run,
+        "contract": contract.to_dict(),
+        "steps": [step.to_dict() for step in steps],
+        "workspace": str(context.workspace_dir) if context.workspace_dir is not None else None,
+    }
+    if action == "uninstall":
+        confirmation_phrase = uninstall_confirmation_token(adapter.harness)
+        payload["confirmation_phrase"] = confirmation_phrase
+        payload["confirm_command"] = f"hol-guard apps disconnect {adapter.harness} --confirm {confirmation_phrase}"
+        payload["steps"] = [
+            {
+                "step_id": "disconnect",
+                "title": f"Disconnect {contract.display_name}",
+                "body": "Remove Guard managed config for this app.",
+                "command": ["hol-guard", "apps", "disconnect", adapter.harness],
+                "writes_config": True,
+                "requires_confirmation": True,
+            }
+        ]
+    return payload
+
+
+def build_harness_verification(
+    requested_harness: str,
+    context: HarnessContext,
+    store: GuardStore | None = None,
+) -> dict[str, object]:
+    adapter = get_adapter(requested_harness)
+    detection = _safe_setup_detection(adapter, context, store)
+    return {
+        "harness": adapter.harness,
+        "safe": True,
+        "contract": adapter.setup_contract().to_dict(),
+        "verification": {
+            "checked": True,
+            "writes_config": False,
+            "installed": detection["installed"],
+            "command_available": detection["command_available"],
+            "config_paths": detection["config_paths"],
+            "artifact_count": 0,
+            "warnings": [],
+            "steps": [step.to_dict() for step in adapter.verify_steps()],
+        },
+    }
+
+
+def uninstall_confirmation_token(harness: str) -> str:
+    return f"disconnect-{harness}"
+
+
+def _safe_setup_detection(
+    adapter: HarnessAdapter,
+    context: HarnessContext,
+    store: GuardStore | None,
+) -> dict[str, object]:
+    managed = store.get_managed_install(adapter.harness) if store is not None else None
+    protection_contract = contract_for(adapter.harness)
+    config_paths = protection_contract.config_paths if protection_contract is not None else ()
+    return {
+        "installed": bool(managed and managed.get("active")),
+        "command_available": adapter.resolved_executable(context) is not None,
+        "config_paths": _existing_contract_config_paths(config_paths, context),
+    }
+
+
+def _existing_contract_config_paths(config_paths: tuple[str, ...], context: HarnessContext) -> list[str]:
+    existing: list[str] = []
+    for config_path in config_paths:
+        for candidate in _contract_config_path_candidates(config_path, context):
+            if candidate.exists():
+                existing.append(str(candidate))
+    return sorted(dict.fromkeys(existing))
+
+
+def _contract_config_path_candidates(config_path: str, context: HarnessContext) -> tuple[Path, ...]:
+    expanded_path = _expand_contract_config_path(config_path, context)
+    if globlib.has_magic(str(expanded_path)):
+        return tuple(sorted(Path(path) for path in globlib.glob(str(expanded_path))))
+    return (expanded_path,)
+
+
+def _expand_contract_config_path(config_path: str, context: HarnessContext) -> Path:
+    path = Path(config_path)
+    if path.parts and path.parts[0] == "~":
+        return context.home_dir.joinpath(*path.parts[1:])
+    if path.is_absolute():
+        return path
+    return context.home_dir / path
+
+
+def scan_workspace_skills(
+    workspace_dir: Path,
+    store: GuardStore,
+    now: str,
+) -> list[dict[str, object]]:
+    """Scan SKILL.md files in workspace and return risk summaries for any findings."""
+    results: list[dict[str, object]] = []
+    skills_dirs = [
+        workspace_dir / ".codex" / "skills",
+        workspace_dir / ".agents" / "skills",
+        workspace_dir / "skills",
+    ]
+    for skills_dir in skills_dirs:
+        if not skills_dir.is_dir():
+            continue
+        for skill_path in sorted(skills_dir.rglob("SKILL.md")):
+            try:
+                content = skill_path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            identity = build_skill_identity(content, skill_path=str(skill_path))
+            artifact_id = f"skill-path:{skill_path}"
+            stored = store.get_snapshot("skill_scan", artifact_id)
+            stored_hash = stored.get("identity_hash") if stored else None
+            if stored_hash == identity.identity_hash:
+                continue
+            signals = detect_skill_content_risk(content, skill_path=str(skill_path))
+            store.save_snapshot(
+                "skill_scan",
+                artifact_id,
+                {"identity_hash": identity.identity_hash, "skill_path": str(skill_path)},
+                identity.identity_hash,
+                now,
+            )
+            if signals:
+                results.append(
+                    {
+                        "skill_path": str(skill_path.relative_to(workspace_dir)),
+                        "identity_hash": identity.identity_hash,
+                        "risk_count": len(signals),
+                        "severities": sorted({s.severity for s in signals}),
+                        "signal_ids": [s.signal_id for s in signals],
+                    }
+                )
+    return results
+
+
+def _resolve_targets(
+    command: str,
+    requested_harness: str | None,
+    install_all: bool,
+    context: HarnessContext,
+    store: GuardStore,
+) -> list[str]:
+    if requested_harness is not None and install_all:
+        raise ValueError("Pass either a harness or --all, not both.")
+    if requested_harness is not None and not install_all:
+        return [get_adapter(requested_harness).harness]
+    if not install_all:
+        action = "install" if command == "install" else "uninstall"
+        raise ValueError(f"Guard {action} requires a harness or --all.")
+    detected = {
+        detection.harness
+        for detection in detect_all(context)
+        if detection.installed
+        or detection.command_available
+        or len(detection.config_paths) > 0
+        or len(detection.artifacts) > 0
+    }
+    if command == "uninstall":
+        detected.update(
+            str(item.get("harness"))
+            for item in store.list_managed_installs()
+            if bool(item.get("active")) and isinstance(item.get("harness"), str)
+        )
+    targets = sorted(detected)
+    if targets:
+        return targets
+    action = "install" if command == "install" else "remove"
+    raise ValueError(
+        f"No supported harnesses were detected for Guard {action}. Pass a harness explicitly or configure one first."
+    )
+
+
+__all__ = [
+    "apply_managed_install",
+    "build_harness_setup_plan",
+    "build_harness_verification",
+    "list_harness_setup_items",
+    "scan_workspace_skills",
+    "uninstall_confirmation_token",
+]