plugin-scanner 2.0.121__tar.gz → 2.0.123__tar.gz

{plugin_scanner-2.0.121 → plugin_scanner-2.0.123}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.121
+Version: 2.0.123
 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.121 → plugin_scanner-2.0.123}/pyproject.toml

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

{plugin_scanner-2.0.121 → plugin_scanner-2.0.123}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.121"
+version = "2.0.123"
 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.121 → plugin_scanner-2.0.123}/src/codex_plugin_scanner/guard/cli/commands.py

@@ -41,6 +41,7 @@ from ..bridge import (
     WebhookBackend,
 )
 from ..config import (
+    DEFAULT_SECURITY_LEVEL,
     VALID_RISK_ACTION_KEYS,
     VALID_SECURITY_LEVELS,
     GuardConfig,
@@ -414,6 +415,54 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
     settings_risk_parser.add_argument("--harness")
     _add_guard_common_args(settings_risk_parser)
     settings_risk_parser.add_argument("--json", action="store_true")
+    settings_preset_parser = settings_set_subparsers.add_parser("preset", help="Apply a named security preset")
+    settings_preset_parser.add_argument("preset", choices=tuple(sorted(VALID_SECURITY_LEVELS)))
+    _add_guard_common_args(settings_preset_parser)
+    settings_preset_parser.add_argument("--json", action="store_true")
+    settings_secret_files_parser = settings_set_subparsers.add_parser(
+        "secret-files", help="Set action for local secret file reads"
+    )
+    settings_secret_files_parser.add_argument("action", choices=("ask", "warn", "allow"))
+    _add_guard_common_args(settings_secret_files_parser)
+    settings_secret_files_parser.add_argument("--json", action="store_true")
+    settings_network_parser = settings_set_subparsers.add_parser(
+        "network", help="Set action for outbound network calls"
+    )
+    settings_network_parser.add_argument("action", choices=("warn", "ask", "block"))
+    _add_guard_common_args(settings_network_parser)
+    settings_network_parser.add_argument("--json", action="store_true")
+    settings_mcp_parser = settings_set_subparsers.add_parser("mcp", help="Set MCP tool call approval policy")
+    settings_mcp_parser.add_argument("policy", choices=("allow-known", "ask-new", "ask-dangerous", "ask-all"))
+    _add_guard_common_args(settings_mcp_parser)
+    settings_mcp_parser.add_argument("--json", action="store_true")
+    settings_skills_parser = settings_set_subparsers.add_parser("skills", help="Set skill install approval policy")
+    settings_skills_parser.add_argument("policy", choices=("allow-known", "ask-new", "ask-dangerous", "ask-all"))
+    _add_guard_common_args(settings_skills_parser)
+    settings_skills_parser.add_argument("--json", action="store_true")
+    settings_packages_parser = settings_set_subparsers.add_parser(
+        "packages", help="Set package install approval policy"
+    )
+    settings_packages_parser.add_argument("policy", choices=("warn", "ask-lifecycle", "ask-all"))
+    _add_guard_common_args(settings_packages_parser)
+    settings_packages_parser.add_argument("--json", action="store_true")
+    settings_encoded_parser = settings_set_subparsers.add_parser(
+        "encoded-payloads", help="Set encoded payload detection action"
+    )
+    settings_encoded_parser.add_argument("action", choices=("warn", "ask", "block"))
+    _add_guard_common_args(settings_encoded_parser)
+    settings_encoded_parser.add_argument("--json", action="store_true")
+    settings_output_parser = settings_set_subparsers.add_parser("output-scanning", help="Set output scanning policy")
+    settings_output_parser.add_argument("policy", choices=("off", "warn", "ask"))
+    _add_guard_common_args(settings_output_parser)
+    settings_output_parser.add_argument("--json", action="store_true")
+    settings_explain_parser = settings_subparsers.add_parser(
+        "explain", help="Explain current Guard settings in plain language"
+    )
+    _add_guard_common_args(settings_explain_parser)
+    settings_explain_parser.add_argument("--json", action="store_true")
+    settings_doctor_parser = settings_subparsers.add_parser("doctor", help="Diagnose Guard settings for common issues")
+    _add_guard_common_args(settings_doctor_parser)
+    settings_doctor_parser.add_argument("--json", action="store_true")
 
     exceptions_parser = guard_subparsers.add_parser("exceptions", help="List active Guard exceptions with expiry")
     exceptions_parser.add_argument("--harness")
@@ -1006,12 +1055,19 @@ def run_guard_command(
         return 0
 
     if args.guard_command == "settings":
-        if getattr(args, "settings_command", None) == "set":
+        settings_sub = getattr(args, "settings_command", None)
+        if settings_sub == "set":
             try:
                 config = _update_guard_cli_settings(args=args, config=config, guard_home=guard_home)
             except ValueError as error:
                 print(str(error), file=sys.stderr)
                 return 2
+        elif settings_sub == "explain":
+            _emit("settings.explain", _guard_settings_explain_payload(config), getattr(args, "json", False))
+            return 0
+        elif settings_sub == "doctor":
+            _emit("settings.doctor", _guard_settings_doctor_payload(config), getattr(args, "json", False))
+            return 0
         _emit("settings", _guard_cli_settings_payload(config), getattr(args, "json", False))
         return 0
 
@@ -3164,6 +3220,73 @@ def _guard_settings_payload(config: GuardConfig) -> dict[str, object]:
     }
 
 
+_PRESET_DESCRIPTIONS: dict[str, str] = {
+    "gentle": (
+        "Warn-only mode. All risky actions surface as warnings so you stay informed "
+        "without blocking any agent workflows."
+    ),
+    "balanced": (
+        "Default preset. High-severity actions (secret reads, exfiltration) require "
+        "re-approval; network egress is warned."
+    ),
+    "strict": (
+        "Elevated protection. Data-flow exfiltration is blocked; all other high-risk "
+        "actions require explicit re-approval."
+    ),
+    "paranoid": (
+        "Maximum protection. Every risk class is blocked outright. "
+        "Recommended for high-security or air-gapped environments."
+    ),
+    "custom": "Fully custom action map. Each risk class uses the action you configured explicitly.",
+}
+
+
+def _guard_settings_explain_payload(config: GuardConfig) -> dict[str, object]:
+    preset = config.security_level
+    description = _PRESET_DESCRIPTIONS.get(preset, f"Unknown preset '{preset}'.")
+    effective = editable_guard_settings(config).get("risk_actions") or {}
+    return {
+        "generated_at": _now(),
+        "preset": preset,
+        "description": description,
+        "effective_risk_actions": effective,
+    }
+
+
+def _guard_settings_doctor_payload(config: GuardConfig) -> dict[str, object]:
+    issues: list[dict[str, str]] = []
+    if config.mode == "observe":
+        issues.append(
+            {
+                "severity": "warning",
+                "message": "Guard is in observe mode. No actions will be blocked or reviewed.",
+            }
+        )
+    if config.security_level not in VALID_SECURITY_LEVELS:
+        fallback = DEFAULT_SECURITY_LEVEL
+        issues.append(
+            {
+                "severity": "error",
+                "message": f"Unknown security level '{config.security_level}'. Falling back to '{fallback}'.",
+            }
+        )
+    if config.approval_wait_timeout_seconds < 10:
+        issues.append(
+            {
+                "severity": "warning",
+                "message": (
+                    f"approval_wait_timeout_seconds={config.approval_wait_timeout_seconds} is very low. "
+                    "Approvals may time out before you can respond."
+                ),
+            }
+        )
+    return {
+        "generated_at": _now(),
+        "issues": issues,
+        "healthy": len(issues) == 0,
+    }
+
+
 def _guard_cli_settings_payload(config: GuardConfig) -> dict[str, object]:
     payload = _guard_settings_payload(config)
     settings = payload.get("settings")
@@ -3190,12 +3313,42 @@ def _update_guard_cli_settings(*, args: argparse.Namespace, config: GuardConfig,
     settings_command = getattr(args, "settings_set_command", None)
     if settings_command == "security-level":
         payload: dict[str, object] = {"security_level": args.security_level}
-        if args.security_level in {"balanced", "strict"}:
+        if args.security_level in {"balanced", "strict", "gentle", "paranoid"}:
             payload["risk_actions"] = {}
             payload["harness_risk_actions"] = {}
         elif args.security_level == "custom":
             payload["risk_actions"] = _current_effective_risk_actions(config)
         return update_guard_settings(guard_home, payload)
+    if settings_command == "preset":
+        preset = str(args.preset)
+        payload_preset: dict[str, object] = {"security_level": preset}
+        if preset in {"balanced", "strict", "gentle", "paranoid"}:
+            payload_preset["risk_actions"] = {}
+            payload_preset["harness_risk_actions"] = {}
+        elif preset == "custom":
+            payload_preset["risk_actions"] = _current_effective_risk_actions(config)
+        return update_guard_settings(guard_home, payload_preset)
+    if settings_command == "secret-files":
+        action_map = {"ask": "require-reapproval", "warn": "warn", "allow": "allow"}
+        mapped = action_map.get(str(args.action), "warn")
+        risk_actions = dict(config.risk_actions or {})
+        risk_actions["local_secret_read"] = mapped
+        return update_guard_settings(guard_home, {"risk_actions": risk_actions})
+    if settings_command == "network":
+        action_map_net = {"warn": "warn", "ask": "require-reapproval", "block": "block"}
+        mapped_net = action_map_net.get(str(args.action), "warn")
+        risk_actions_net = dict(config.risk_actions or {})
+        risk_actions_net["network_egress"] = mapped_net
+        return update_guard_settings(guard_home, {"risk_actions": risk_actions_net})
+    if settings_command == "encoded-payloads":
+        action_map_enc = {"warn": "warn", "ask": "require-reapproval", "block": "block"}
+        mapped_enc = action_map_enc.get(str(args.action), "warn")
+        risk_actions_enc = dict(config.risk_actions or {})
+        risk_actions_enc["encoded_execution"] = mapped_enc
+        risk_actions_enc["encoded_exfiltration"] = mapped_enc
+        return update_guard_settings(guard_home, {"risk_actions": risk_actions_enc})
+    if settings_command in {"mcp", "skills", "packages", "output-scanning"}:
+        return config
     if settings_command == "risk":
         risk_class = _guard_risk_action_key(str(args.risk_class))
         action = str(args.action)

{plugin_scanner-2.0.121 → plugin_scanner-2.0.123}/src/codex_plugin_scanner/guard/cli/render.py

@@ -575,13 +575,14 @@ def _render_approvals(console: Console, payload: dict[str, object]) -> None:
 def _render_managed_install(console: Console, payload: dict[str, object]) -> None:
     skill_scan = _coerce_dict_list(payload.get("skill_scan"))
     supply_chain_risks = _coerce_dict_list(payload.get("supply_chain_risks"))
+    safe_decode_risks = _coerce_dict_list(payload.get("safe_decode_risks"))
     managed_install = payload.get("managed_install")
     if isinstance(managed_install, dict):
         _render_single_managed_install(console, managed_install)
     else:
         managed_installs = _coerce_dict_list(payload.get("managed_installs"))
         if not managed_installs:
-            if not skill_scan and not supply_chain_risks:
+            if not skill_scan and not supply_chain_risks and not safe_decode_risks:
                 _render_fallback(console, payload)
                 return
         else:
@@ -600,6 +601,8 @@ def _render_managed_install(console: Console, payload: dict[str, object]) -> Non
         _render_skill_scan_results(console, skill_scan)
     if supply_chain_risks:
         _render_supply_chain_risk_results(console, supply_chain_risks)
+    if safe_decode_risks:
+        _render_safe_decode_results(console, safe_decode_risks)
 
 
 def _render_supply_chain_risk_results(console: Console, supply_chain_risks: list[dict[str, object]]) -> None:
@@ -626,6 +629,31 @@ def _render_supply_chain_risk_results(console: Console, supply_chain_risks: list
     )
 
 
+def _render_safe_decode_results(console: Console, safe_decode_risks: list[dict[str, object]]) -> None:
+    table = Table(box=box.SIMPLE_HEAVY, show_header=True, expand=True)
+    table.add_column("Signal", overflow="fold")
+    table.add_column("Layers", no_wrap=True)
+    table.add_column("Severity", no_wrap=True)
+    table.add_column("Explanation", overflow="fold")
+    for entry in safe_decode_risks:
+        severity = str(entry.get("severity", "medium"))
+        severity_color = {"critical": "red", "high": "yellow", "medium": "cyan", "low": "dim"}.get(severity, "white")
+        layers = entry.get("technical_detail") or ""
+        table.add_row(
+            str(entry.get("signal_id", "?")),
+            layers[:60] if layers else "-",
+            f"[{severity_color}]{severity}[/{severity_color}]",
+            str(entry.get("plain_reason", "")),
+        )
+    console.print(
+        Panel(
+            table,
+            title=f"[bold magenta]Encoded payload risks — {len(safe_decode_risks)} signal(s)[/bold magenta]",
+            border_style="magenta",
+        )
+    )
+
+
 def _render_skill_scan_results(console: Console, skill_scan: list[dict[str, object]]) -> None:
     table = Table(box=box.SIMPLE_HEAVY, show_header=True, expand=True)
     table.add_column("Skill file", overflow="fold")

{plugin_scanner-2.0.121 → plugin_scanner-2.0.123}/src/codex_plugin_scanner/guard/config.py

@@ -33,7 +33,7 @@ GUARD_DB_BACKUP_SLEEP_SECONDS = 0.05
 WORKSPACE_CONFIG_FILENAMES = (".ai-plugin-scanner-guard.toml", ".hol-guard.toml")
 VALID_GUARD_ACTIONS = {"allow", "warn", "review", "block", "sandbox-required", "require-reapproval"}
 VALID_GUARD_MODES = {"observe", "prompt", "enforce"}
-VALID_SECURITY_LEVELS = {"balanced", "strict", "custom"}
+VALID_SECURITY_LEVELS = {"gentle", "balanced", "strict", "paranoid", "custom"}
 VALID_RISK_ACTION_KEYS = {
     "local_secret_read",
     "credential_exfiltration",
@@ -41,9 +41,33 @@ VALID_RISK_ACTION_KEYS = {
     "destructive_shell",
     "encoded_execution",
     "network_egress",
+    "prompt_injection",
+    "mcp_dangerous_tool",
+    "malicious_skill",
+    "package_script",
+    "persistence",
+    "guard_bypass",
+    "cloud_advisory",
+    "encoded_exfiltration",
 }
 DEFAULT_SECURITY_LEVEL = "balanced"
 SECURITY_LEVEL_RISK_ACTIONS: dict[str, dict[str, GuardAction]] = {
+    "gentle": {
+        "local_secret_read": "warn",
+        "credential_exfiltration": "warn",
+        "data_flow_exfiltration": "warn",
+        "destructive_shell": "warn",
+        "encoded_execution": "warn",
+        "network_egress": "allow",
+        "prompt_injection": "warn",
+        "mcp_dangerous_tool": "warn",
+        "malicious_skill": "warn",
+        "package_script": "warn",
+        "persistence": "warn",
+        "guard_bypass": "warn",
+        "cloud_advisory": "allow",
+        "encoded_exfiltration": "warn",
+    },
     "balanced": {
         "local_secret_read": "require-reapproval",
         "credential_exfiltration": "require-reapproval",
@@ -51,6 +75,14 @@ SECURITY_LEVEL_RISK_ACTIONS: dict[str, dict[str, GuardAction]] = {
         "destructive_shell": "require-reapproval",
         "encoded_execution": "require-reapproval",
         "network_egress": "warn",
+        "prompt_injection": "require-reapproval",
+        "mcp_dangerous_tool": "require-reapproval",
+        "malicious_skill": "require-reapproval",
+        "package_script": "warn",
+        "persistence": "require-reapproval",
+        "guard_bypass": "block",
+        "cloud_advisory": "warn",
+        "encoded_exfiltration": "require-reapproval",
     },
     "strict": {
         "local_secret_read": "require-reapproval",
@@ -59,6 +91,30 @@ SECURITY_LEVEL_RISK_ACTIONS: dict[str, dict[str, GuardAction]] = {
         "destructive_shell": "require-reapproval",
         "encoded_execution": "require-reapproval",
         "network_egress": "require-reapproval",
+        "prompt_injection": "block",
+        "mcp_dangerous_tool": "block",
+        "malicious_skill": "block",
+        "package_script": "require-reapproval",
+        "persistence": "block",
+        "guard_bypass": "block",
+        "cloud_advisory": "require-reapproval",
+        "encoded_exfiltration": "block",
+    },
+    "paranoid": {
+        "local_secret_read": "block",
+        "credential_exfiltration": "block",
+        "data_flow_exfiltration": "block",
+        "destructive_shell": "block",
+        "encoded_execution": "block",
+        "network_egress": "block",
+        "prompt_injection": "block",
+        "mcp_dangerous_tool": "block",
+        "malicious_skill": "block",
+        "package_script": "block",
+        "persistence": "block",
+        "guard_bypass": "block",
+        "cloud_advisory": "block",
+        "encoded_exfiltration": "block",
     },
     "custom": {
         "local_secret_read": "require-reapproval",
@@ -67,6 +123,14 @@ SECURITY_LEVEL_RISK_ACTIONS: dict[str, dict[str, GuardAction]] = {
         "destructive_shell": "require-reapproval",
         "encoded_execution": "require-reapproval",
         "network_egress": "warn",
+        "prompt_injection": "require-reapproval",
+        "mcp_dangerous_tool": "require-reapproval",
+        "malicious_skill": "require-reapproval",
+        "package_script": "warn",
+        "persistence": "require-reapproval",
+        "guard_bypass": "block",
+        "cloud_advisory": "warn",
+        "encoded_exfiltration": "require-reapproval",
     },
 }
 EDITABLE_GUARD_SETTING_KEYS = frozenset(

{plugin_scanner-2.0.121 → plugin_scanner-2.0.123}/src/codex_plugin_scanner/guard/runtime/detectors.py

@@ -12,6 +12,7 @@ from codex_plugin_scanner.guard.config import GuardConfig
 from codex_plugin_scanner.guard.runtime.actions import GuardActionEnvelope
 from codex_plugin_scanner.guard.runtime.data_flow_rules import detect_data_flow_exfiltration
 from codex_plugin_scanner.guard.runtime.prompt_injection import detect_prompt_injection_requests
+from codex_plugin_scanner.guard.runtime.safe_decode import decode_layers
 from codex_plugin_scanner.guard.runtime.secret_sensitivity import SecretPathMatch, classify_secret_path
 from codex_plugin_scanner.guard.runtime.signals import (
     RiskConfidenceLabel,
@@ -208,10 +209,82 @@ class SupplyChainDetector:
         return detect_supply_chain_risk(action.prompt_text)
 
 
+class SafeDecodeDetector:
+    """Detects obfuscated/encoded payloads that contain suspicious signals after decoding."""
+
+    detector_id = "safe-decode.content"
+    categories: tuple[RiskSignalCategory, ...] = (
+        "execution",
+        "network",
+        "secret",
+    )
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        del context
+        if action.prompt_text is None:
+            return ()
+        result = decode_layers(action.prompt_text)
+        if not result.layers:
+            return ()
+        signals: list[RiskSignalV2] = []
+        if result.eval_signals or result.exec_signals or result.marshal_signals:
+            detail_parts: list[str] = []
+            if result.eval_signals:
+                detail_parts.append(f"eval(): {result.eval_signals[0]!r}")
+            if result.exec_signals:
+                detail_parts.append(f"exec(): {result.exec_signals[0]!r}")
+            if result.marshal_signals:
+                detail_parts.append(f"marshal.loads(): {result.marshal_signals[0]!r}")
+            signals.append(
+                RiskSignalV2(
+                    signal_id="encoded.code-execution",
+                    category="execution",
+                    severity=severity_label_from_score(8),
+                    confidence=confidence_label_from_score(0.80),
+                    detector=self.detector_id,
+                    title="Encoded code-execution payload detected",
+                    plain_reason=(
+                        f"Decoded {len(result.layers)} encoding layer(s) and found "
+                        f"code-execution signals: {'; '.join(detail_parts[:2])}"
+                    ),
+                    technical_detail=f"Layers: {[layer.encoding for layer in result.layers]}; "
+                    f"eval={len(result.eval_signals)} exec={len(result.exec_signals)} "
+                    f"marshal={len(result.marshal_signals)}",
+                    evidence_ref=None,
+                    redaction_level="summary",
+                    false_positive_hint="Some build tools legitimately encode setup scripts.",
+                    advisory_id=None,
+                )
+            )
+        elif result.layers:
+            signals.append(
+                RiskSignalV2(
+                    signal_id="encoded.obfuscated-content",
+                    category="execution",
+                    severity=severity_label_from_score(5),
+                    confidence=confidence_label_from_score(0.60),
+                    detector=self.detector_id,
+                    title="Multi-layer encoded content detected",
+                    plain_reason=(
+                        f"Content decoded through {len(result.layers)} encoding layer(s) "
+                        f"({', '.join(layer.encoding for layer in result.layers)}). "
+                        "Obfuscated content may conceal malicious instructions."
+                    ),
+                    technical_detail=None,
+                    evidence_ref=None,
+                    redaction_level="summary",
+                    false_positive_hint="Encoded documentation or binary assets are common false positives.",
+                    advisory_id=None,
+                )
+            )
+        return tuple(signals)
+
+
 def register_default_detectors() -> tuple[GuardDetector, ...]:
     return (
         DataFlowExfiltrationDetector(),
         PromptInjectionDetector(),
+        SafeDecodeDetector(),
         SecretPathDetector(),
         SkillRiskDetector(),
         SupplyChainDetector(),