plugin-scanner 2.0.762__tar.gz → 2.0.764__tar.gz

{plugin_scanner-2.0.762 → plugin_scanner-2.0.764}/PKG-INFO

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

{plugin_scanner-2.0.762 → plugin_scanner-2.0.764}/pyproject.toml

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

{plugin_scanner-2.0.762 → plugin_scanner-2.0.764}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.762"
+version = "2.0.764"
 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.762 → plugin_scanner-2.0.764}/src/codex_plugin_scanner/guard/runtime/actions.py

@@ -13,6 +13,7 @@ from typing import Literal, TypeGuard
 
 from ..redaction import redact_text
 from .secret_sensitivity import redacted_secret_path_context
+from .shell_command_wrappers import normalize_transparent_shell_command
 
 GuardActionType = Literal[
     "prompt",
@@ -62,7 +63,12 @@ _PATH_KEYS = (
     "targetPath",
     "targetPaths",
 )
-_COMMAND_KEYS = ("command", "cmd", "shell_command", "shellCommand")
+_COMMAND_KEYS = (
+    "command",
+    "cmd",
+    "shell_command",
+    "shellCommand",
+)
 _SENSITIVE_RAW_KEYS = frozenset(
     {
         "api_key",
@@ -496,20 +502,27 @@ def _normalize_action_payload(
     if not tool_input and tool_call_input is not None:
         tool_input = tool_call_input
     raw_command = _command_from_payload(tool_input)
-    command = _command_detail(raw_command, home_dir=home_dir)
+    normalized_command, wrapper_chain = _normalized_shell_command(tool_name, raw_command)
+    if wrapper_chain and isinstance(tool_input, Mapping):
+        normalized_payload["tool_input"] = {
+            **dict(tool_input),
+            "guard_inner_command": normalized_command,
+            "guard_shell_wrappers": list(wrapper_chain),
+        }
+    command = _command_detail(normalized_command, home_dir=home_dir)
     prompt_text = _prompt_text(_prompt_value(normalized_payload))
     prompt_excerpt = _prompt_excerpt(prompt_text)
     mcp_server, mcp_tool = _mcp_details(normalized_payload, tool_name)
     action_type = _action_type(
         event_name=event_name,
         tool_name=tool_name,
-        command=raw_command,
+        command=normalized_command,
         prompt_excerpt=prompt_excerpt,
         mcp_server=mcp_server,
     )
     target_paths = _target_paths(
         tool_input=tool_input,
-        command=raw_command,
+        command=normalized_command,
         prompt_text=prompt_text,
         home_dir=home_dir,
     )
@@ -518,8 +531,8 @@ def _normalize_action_payload(
     workspace_hash = _workspace_hash(workspace)
     workspace_path = Path(workspace) if workspace is not None else None
     package_intent = (
-        _package_intent_parser_module().parse_package_intent(raw_command, workspace=workspace_path)
-        if raw_command
+        _package_intent_parser_module().parse_package_intent(normalized_command, workspace=workspace_path)
+        if normalized_command
         else None
     )
     package_targets = (
@@ -697,6 +710,15 @@ def _command_from_payload(tool_input: Mapping[str, object]) -> str | None:
     return None
 
 
+def _normalized_shell_command(tool_name: str | None, command: str | None) -> tuple[str | None, tuple[str, ...]]:
+    if command is None:
+        return None, ()
+    if not isinstance(tool_name, str) or tool_name.strip().lower() not in _SHELL_TOOL_NAMES:
+        return command, ()
+    normalized = normalize_transparent_shell_command(command)
+    return normalized.normalized_command, normalized.wrapper_chain
+
+
 def _command_detail(command: str | None, *, home_dir: Path | str | None) -> str | None:
     if command is None:
         return None

{plugin_scanner-2.0.762 → plugin_scanner-2.0.764}/src/codex_plugin_scanner/guard/runtime/secret_file_requests.py

@@ -12,7 +12,7 @@ import os
 import re
 import shlex
 import stat
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 
 from ..models import GuardArtifact
@@ -32,6 +32,7 @@ from .false_positive_rules import (
 from .secret_sensitivity import SecretPathMatch as SensitivePathMatch
 from .secret_sensitivity import classify_secret_path
 from .sed_scripts import sed_script_is_bounded_print
+from .shell_command_wrappers import normalize_transparent_shell_command
 
 _FILE_READ_TOOL_NAMES = frozenset(
     {
@@ -54,7 +55,12 @@ _PATH_KEYS = (
     "targetPath",
 )
 _PATH_LIST_KEYS = ("paths", "file_paths", "filePaths")
-_COMMAND_KEYS = ("command", "cmd", "shell_command", "shellCommand")
+_COMMAND_KEYS = (
+    "command",
+    "cmd",
+    "shell_command",
+    "shellCommand",
+)
 _SUDO_OPTION_VALUE_FLAGS = frozenset({"-u", "-g", "-h", "-p", "-C", "-D", "-R", "-r", "-T", "-t"})
 _SUDO_OPTION_VALUE_LONG_FLAGS = frozenset(
     {
@@ -551,6 +557,8 @@ class ToolActionRequestMatch:
     command_text: str
     action_class: str
     reason: str
+    raw_command_text: str | None = None
+    wrapper_chain: tuple[str, ...] = ()
 
 
 def is_file_read_tool_name(tool_name: str | None) -> bool:
@@ -696,12 +704,26 @@ def extract_sensitive_tool_action_request(
     if effective_tool_name is None:
         return None
     for command_text in _candidate_command_texts(arguments):
+        raw_command_text = command_text
+        wrapper_chain: tuple[str, ...] = ()
+        normalized_command_text = command_text
+        if effective_tool_name in _SHELL_TOOL_NAMES:
+            normalized_command = normalize_transparent_shell_command(command_text)
+            command_text = normalized_command.normalized_command
+            normalized_command_text = command_text
+            wrapper_chain = normalized_command.wrapper_chain
         docker_sensitive_request = _docker_sensitive_tool_action_request(
             tool_name=requested_tool_name,
             normalized_tool_name=effective_tool_name,
             command_text=command_text,
         )
         if docker_sensitive_request is not None:
+            if wrapper_chain:
+                docker_sensitive_request = _request_with_wrapper_context(
+                    docker_sensitive_request,
+                    raw_command_text=raw_command_text,
+                    wrapper_chain=wrapper_chain,
+                )
             return docker_sensitive_request
         docker_config_request = _docker_config_tool_action_request(
             tool_name=requested_tool_name,
@@ -711,6 +733,12 @@ def extract_sensitive_tool_action_request(
             home_dir=home_dir,
         )
         if docker_config_request is not None:
+            if wrapper_chain:
+                docker_config_request = _request_with_wrapper_context(
+                    docker_config_request,
+                    raw_command_text=raw_command_text,
+                    wrapper_chain=wrapper_chain,
+                )
             return docker_config_request
         destructive_shell_request = _destructive_shell_tool_action_request(
             tool_name=requested_tool_name,
@@ -720,7 +748,31 @@ def extract_sensitive_tool_action_request(
             home_dir=home_dir,
         )
         if destructive_shell_request is not None:
+            if wrapper_chain:
+                destructive_shell_request = _request_with_wrapper_context(
+                    destructive_shell_request,
+                    raw_command_text=raw_command_text,
+                    wrapper_chain=wrapper_chain,
+                )
             return destructive_shell_request
+        if wrapper_chain:
+            destructive_shell_request = _destructive_shell_tool_action_request(
+                tool_name=requested_tool_name,
+                normalized_tool_name=effective_tool_name,
+                command_text=raw_command_text,
+                cwd=cwd,
+                home_dir=home_dir,
+            )
+            if destructive_shell_request is not None:
+                destructive_shell_request = _request_with_wrapper_context(
+                    replace(
+                        destructive_shell_request,
+                        command_text=normalized_command_text,
+                    ),
+                    raw_command_text=raw_command_text,
+                    wrapper_chain=wrapper_chain,
+                )
+                return destructive_shell_request
     return None
 
 
@@ -730,6 +782,8 @@ def is_explicitly_benign_tool_action_request(tool_name: object, arguments: objec
         return False
     found_benign_candidate = False
     for command_text in _candidate_command_texts(arguments):
+        if normalized_tool_name in _SHELL_TOOL_NAMES:
+            command_text = normalize_transparent_shell_command(command_text).normalized_command
         stripped_command = command_text.strip()
         if not stripped_command:
             continue
@@ -3336,7 +3390,18 @@ def build_tool_action_request_artifact(
         ).encode("utf-8")
     ).hexdigest()
     request_summary = f"Requested `{request.tool_name}` action `{request.command_text}` ({request.action_class})."
+    if request.wrapper_chain:
+        request_summary = (
+            f"Requested `{request.tool_name}` action `{request.command_text}` via transparent wrappers "
+            f"`{' -> '.join(request.wrapper_chain)}` ({request.action_class})."
+        )
     risk_summary = f"Requests a sensitive native tool action: {request.action_class}."
+    runtime_reason = request.reason
+    if request.wrapper_chain:
+        runtime_reason = (
+            f"Guard normalized the transparent wrapper chain {' -> '.join(request.wrapper_chain)} "
+            f"before evaluation. {request.reason}"
+        )
     return GuardArtifact(
         artifact_id=f"{harness}:{source_scope}:tool-action:{fingerprint}",
         name=f"{request.tool_name} {request.action_class}",
@@ -3351,11 +3416,30 @@ def build_tool_action_request_artifact(
             "request_summary": request_summary,
             "runtime_request_signals": [f"invokes a sensitive native tool action: {request.action_class}"],
             "runtime_request_summary": risk_summary,
-            "runtime_request_reason": request.reason,
+            "runtime_request_reason": runtime_reason,
+            "raw_command_text": request.raw_command_text,
+            "wrapper_chain": list(request.wrapper_chain),
         },
     )
 
 
+def _request_with_wrapper_context(
+    request: ToolActionRequestMatch,
+    *,
+    raw_command_text: str,
+    wrapper_chain: tuple[str, ...],
+) -> ToolActionRequestMatch:
+    return ToolActionRequestMatch(
+        tool_name=request.tool_name,
+        normalized_tool_name=request.normalized_tool_name,
+        command_text=request.command_text,
+        action_class=request.action_class,
+        reason=request.reason,
+        raw_command_text=raw_command_text,
+        wrapper_chain=wrapper_chain,
+    )
+
+
 def _candidate_paths(value: object) -> list[str]:
     results: list[str] = []
     _collect_candidate_paths(value, results, depth=0)

plugin_scanner-2.0.764/src/codex_plugin_scanner/guard/runtime/shell_command_wrappers.py

@@ -0,0 +1,373 @@
+"""Normalize transparent shell wrappers before Guard evaluates a command."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+
+_MAX_NORMALIZE_BYTES = 8192
+_ENV_ASSIGNMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*$")
+_SHELL_CONTROL_TOKENS = frozenset({"&&", "||", ";", "|", "|&", "&"})
+_LEAN_CTX_BINARIES = frozenset({"lean-ctx"})
+_SHELL_STRING_WRAPPERS = frozenset({"ash", "bash", "dash", "fish", "sh", "zsh"})
+_PLAIN_WRAPPERS = frozenset({"command", "nice", "nohup", "stdbuf", "time"})
+_ENV_OPTION_FLAGS_WITH_VALUES = frozenset({"-u", "-C", "--unset", "--chdir"})
+_NICE_OPTION_FLAGS_WITH_VALUES = frozenset({"-n", "--adjustment"})
+_STDBUF_VALUE_FLAGS = frozenset({"-i", "-o", "-e"})
+_TIME_OPTION_FLAGS_WITH_VALUES = frozenset({"-f", "-o", "--format", "--output"})
+
+
+@dataclass(frozen=True, slots=True)
+class ShellCommandNormalization:
+    raw_command: str
+    normalized_command: str
+    wrapper_chain: tuple[str, ...] = ()
+
+
+def normalize_transparent_shell_command(command_text: str) -> ShellCommandNormalization:
+    stripped = command_text.strip()
+    if not stripped or len(stripped) > _MAX_NORMALIZE_BYTES:
+        return ShellCommandNormalization(
+            raw_command=stripped,
+            normalized_command=stripped,
+            wrapper_chain=(),
+        )
+    normalized_command, wrapper_chain = _normalize_command_text(stripped, depth=0)
+    return ShellCommandNormalization(
+        raw_command=stripped,
+        normalized_command=normalized_command or stripped,
+        wrapper_chain=wrapper_chain,
+    )
+
+
+def _normalize_command_text(command_text: str, *, depth: int) -> tuple[str, tuple[str, ...]]:
+    if depth > 8:
+        return command_text, ()
+    try:
+        parts = shlex.split(command_text, posix=True, comments=False)
+    except ValueError:
+        return command_text, ()
+    if not parts:
+        return command_text, ()
+    prefix_env, index = _consume_leading_env_assignments(parts, start=0)
+    normalized, wrappers = _normalize_parts(parts[index:], depth=depth)
+    if not wrappers:
+        return command_text, ()
+    if normalized is None:
+        return command_text, wrappers
+    if prefix_env:
+        normalized = _join_command_fragments(_join_shell_tokens(prefix_env), normalized)
+    return normalized, wrappers
+
+
+def _normalize_parts(parts: list[str], *, depth: int) -> tuple[str | None, tuple[str, ...]]:
+    current = list(parts)
+    preserved_env: list[str] = []
+    wrappers: list[str] = []
+    while current:
+        current_env, env_index = _consume_leading_env_assignments(current, start=0)
+        if current_env:
+            preserved_env.extend(current_env)
+            current = current[env_index:]
+            if not current:
+                break
+        command_name = _command_name(current[0])
+        if command_name in _LEAN_CTX_BINARIES:
+            normalized = _unwrap_lean_ctx(current)
+            if normalized is None:
+                break
+            inner_command, suffix = normalized
+            wrappers.append(command_name)
+            inner_text, inner_wrappers = _normalize_command_text(inner_command, depth=depth + 1)
+            suffix_text = _join_shell_tokens(suffix) if suffix else ""
+            inner_command_text = _join_command_fragments(inner_text, suffix_text)
+            if preserved_env:
+                inner_command_text = _join_command_fragments(_join_shell_tokens(preserved_env), inner_command_text)
+            return inner_command_text, tuple((*wrappers, *inner_wrappers))
+        if command_name in _SHELL_STRING_WRAPPERS:
+            normalized = _unwrap_shell_string_wrapper(current)
+            if normalized is None:
+                break
+            inner_command, suffix = normalized
+            wrappers.append(command_name)
+            inner_text, inner_wrappers = _normalize_command_text(inner_command, depth=depth + 1)
+            suffix_text = _join_shell_tokens(suffix) if suffix else ""
+            inner_command_text = _join_command_fragments(inner_text, suffix_text)
+            if preserved_env:
+                inner_command_text = _join_command_fragments(_join_shell_tokens(preserved_env), inner_command_text)
+            return inner_command_text, tuple((*wrappers, *inner_wrappers))
+        if command_name == "env":
+            next_parts, env_prefix, env_split = _strip_env_wrapper(current)
+            if env_split is not None:
+                wrappers.append("env")
+                inner_text, inner_wrappers = _normalize_command_text(env_split, depth=depth + 1)
+                all_env = [*preserved_env, *env_prefix]
+                if all_env:
+                    inner_text = _join_command_fragments(_join_shell_tokens(all_env), inner_text)
+                return inner_text, tuple((*wrappers, *inner_wrappers))
+            if next_parts is None:
+                break
+            wrappers.append("env")
+            preserved_env.extend(env_prefix)
+            current = next_parts
+            continue
+        if command_name == "command":
+            next_parts = _strip_command_wrapper(current)
+            if next_parts is None:
+                break
+            wrappers.append("command")
+            current = next_parts
+            continue
+        if command_name == "time":
+            next_parts = _strip_time_wrapper(current)
+            if next_parts is None:
+                break
+            wrappers.append("time")
+            current = next_parts
+            continue
+        if command_name == "nice":
+            next_parts = _strip_nice_wrapper(current)
+            if next_parts is None:
+                break
+            wrappers.append("nice")
+            current = next_parts
+            continue
+        if command_name == "nohup":
+            next_parts = _strip_nohup_wrapper(current)
+            if next_parts is None:
+                break
+            wrappers.append("nohup")
+            current = next_parts
+            continue
+        if command_name == "stdbuf":
+            next_parts = _strip_stdbuf_wrapper(current)
+            if next_parts is None:
+                break
+            wrappers.append("stdbuf")
+            current = next_parts
+            continue
+        break
+    current_text = _join_shell_tokens(current)
+    if preserved_env:
+        current_text = _join_command_fragments(_join_shell_tokens(preserved_env), current_text)
+    return current_text, tuple(wrappers)
+
+
+def _consume_leading_env_assignments(parts: list[str], *, start: int) -> tuple[list[str], int]:
+    prefix: list[str] = []
+    index = start
+    while index < len(parts) and _ENV_ASSIGNMENT_RE.fullmatch(parts[index]):
+        prefix.append(parts[index])
+        index += 1
+    return prefix, index
+
+
+def _unwrap_lean_ctx(parts: list[str]) -> tuple[str, list[str]] | None:
+    index = 1
+    while index < len(parts):
+        token = parts[index]
+        if token == "--":
+            index += 1
+            break
+        if token in {"-c", "--command"}:
+            if index + 1 >= len(parts):
+                return None
+            return parts[index + 1], parts[index + 2 :]
+        index += 1
+    return None
+
+
+def _unwrap_shell_string_wrapper(parts: list[str]) -> tuple[str, list[str]] | None:
+    index = 1
+    while index < len(parts):
+        token = parts[index]
+        if token == "--":
+            index += 1
+            break
+        if token.startswith("-") and not token.startswith("--") and "c" in token[1:]:
+            if index + 1 >= len(parts):
+                return None
+            return parts[index + 1], parts[index + 2 :]
+        if token.startswith("-"):
+            index += 1
+            continue
+        return None
+    return None
+
+
+def _strip_env_wrapper(parts: list[str]) -> tuple[list[str] | None, list[str], str | None]:
+    env_prefix: list[str] = []
+    index = 1
+    while index < len(parts):
+        token = parts[index]
+        if _ENV_ASSIGNMENT_RE.fullmatch(token):
+            env_prefix.append(token)
+            index += 1
+            continue
+        if token == "--":
+            return parts[index + 1 :], env_prefix, None
+        if token in {"-S", "--split-string"}:
+            if index + 1 >= len(parts):
+                return None, env_prefix, None
+            return [], env_prefix, parts[index + 1]
+        split_string = _env_clustered_split_string_payload(token)
+        if split_string is not None:
+            if split_string:
+                return [], env_prefix, split_string
+            if index + 1 >= len(parts):
+                return None, env_prefix, None
+            return [], env_prefix, parts[index + 1]
+        short_option_tokens = _env_short_option_tokens_consumed(token)
+        if short_option_tokens is not None:
+            if index + short_option_tokens - 1 >= len(parts):
+                return None, env_prefix, None
+            index += short_option_tokens
+            continue
+        if token in _ENV_OPTION_FLAGS_WITH_VALUES:
+            if index + 1 >= len(parts):
+                return None, env_prefix, None
+            index += 2
+            continue
+        if any(token.startswith(f"{flag}=") for flag in {"--unset", "--chdir", "--split-string"}):
+            if token.startswith("--split-string="):
+                return [], env_prefix, token.partition("=")[2]
+            index += 1
+            continue
+        if token.startswith("-"):
+            index += 1
+            continue
+        return parts[index:], env_prefix, None
+    return None, env_prefix, None
+
+
+def _strip_command_wrapper(parts: list[str]) -> list[str] | None:
+    index = 1
+    while index < len(parts):
+        token = parts[index]
+        if token == "--":
+            return parts[index + 1 :]
+        if not token.startswith("-"):
+            return parts[index:]
+        if "v" in token[1:] or "V" in token[1:]:
+            return None
+        index += 1
+    return None
+
+
+def _strip_time_wrapper(parts: list[str]) -> list[str] | None:
+    index = 1
+    while index < len(parts):
+        token = parts[index]
+        if token == "--":
+            return parts[index + 1 :]
+        if token in _TIME_OPTION_FLAGS_WITH_VALUES:
+            if index + 1 >= len(parts):
+                return None
+            index += 2
+            continue
+        if token.startswith("--format=") or token.startswith("--output="):
+            index += 1
+            continue
+        if (token.startswith("-f") and token != "-f") or (token.startswith("-o") and token != "-o"):
+            index += 1
+            continue
+        if token.startswith("-"):
+            index += 1
+            continue
+        return parts[index:]
+    return None
+
+
+def _strip_nice_wrapper(parts: list[str]) -> list[str] | None:
+    index = 1
+    while index < len(parts):
+        token = parts[index]
+        if token == "--":
+            return parts[index + 1 :]
+        if token in _NICE_OPTION_FLAGS_WITH_VALUES:
+            if index + 1 >= len(parts):
+                return None
+            index += 2
+            continue
+        if token.startswith("--adjustment=") or (token.startswith("-n") and token != "-n"):
+            index += 1
+            continue
+        if token.startswith("-"):
+            index += 1
+            continue
+        return parts[index:]
+    return None
+
+
+def _strip_nohup_wrapper(parts: list[str]) -> list[str] | None:
+    index = 1
+    while index < len(parts) and parts[index].startswith("-"):
+        index += 1
+    return parts[index:] or None
+
+
+def _strip_stdbuf_wrapper(parts: list[str]) -> list[str] | None:
+    index = 1
+    while index < len(parts):
+        token = parts[index]
+        if token == "--":
+            return parts[index + 1 :]
+        if token in _STDBUF_VALUE_FLAGS:
+            if index + 1 >= len(parts):
+                return None
+            index += 2
+            continue
+        if any(token.startswith(flag) for flag in _STDBUF_VALUE_FLAGS):
+            index += 1
+            continue
+        if token.startswith("-"):
+            index += 1
+            continue
+        return parts[index:]
+    return None
+
+
+def _env_short_option_tokens_consumed(token: str) -> int | None:
+    if not token.startswith("-") or token.startswith("--") or len(token) <= 2:
+        return None
+    for index, flag_character in enumerate(token[1:], start=1):
+        if flag_character not in {"C", "S", "u"}:
+            continue
+        if index < len(token) - 1:
+            return 1
+        return 2
+    return 1
+
+
+def _env_clustered_split_string_payload(token: str) -> str | None:
+    if not token.startswith("-") or token.startswith("--") or len(token) <= 2:
+        return None
+    split_index = token.find("S", 1)
+    if split_index == -1:
+        return None
+    if split_index + 1 >= len(token):
+        return ""
+    return token[split_index + 1 :]
+
+
+def _command_name(token: str) -> str:
+    return Path(token).name.lower()
+
+
+def _join_command_fragments(*fragments: str) -> str:
+    return " ".join(fragment for fragment in fragments if fragment).strip()
+
+
+def _join_shell_tokens(tokens: list[str]) -> str:
+    rendered: list[str] = []
+    for token in tokens:
+        if token in _SHELL_CONTROL_TOKENS:
+            rendered.append(token)
+            continue
+        rendered.append(shlex.quote(token))
+    return " ".join(rendered).strip()
+
+
+__all__ = ["ShellCommandNormalization", "normalize_transparent_shell_command"]