plugin-scanner 2.0.153__tar.gz → 2.0.155__tar.gz

{plugin_scanner-2.0.153 → plugin_scanner-2.0.155}/PKG-INFO

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

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

{plugin_scanner-2.0.153 → plugin_scanner-2.0.155}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.153"
+version = "2.0.155"
 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.155/src/codex_plugin_scanner/guard/insights.py

@@ -0,0 +1,223 @@
+"""GuardInsight model and action-type-specific generators (L246-L252)."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from .runtime.actions import GuardActionEnvelope
+from .runtime.signals import RiskSignalV2
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def _max_severity(signals: tuple[RiskSignalV2, ...]) -> str:
+    order = {"critical": 4, "high": 3, "medium": 2, "low": 1, "info": 0}
+    best = "info"
+    for sig in signals:
+        if order.get(sig.severity, 0) > order.get(best, 0):
+            best = sig.severity
+    return best
+
+
+def _detector_ids(signals: tuple[RiskSignalV2, ...]) -> tuple[str, ...]:
+    return tuple(sig.detector for sig in signals if sig.detector)
+
+
+def _first_reason(signals: tuple[RiskSignalV2, ...]) -> str:
+    for sig in signals:
+        if sig.plain_reason:
+            return sig.plain_reason
+    return "Risk signals detected."
+
+
+@dataclass(frozen=True, slots=True)
+class GuardInsight:
+    """Human-readable insight generated from a detected risk event.
+
+    Captures what happened, why it was risky, the source/sink/app context,
+    which detectors fired, and a user-facing recommendation.
+    """
+
+    insight_id: str
+    action_id: str
+    action_type: str
+    harness: str
+    what_happened: str
+    why_risky: str
+    source: str | None
+    sink: str | None
+    app: str
+    scanner_evidence: tuple[str, ...] = field(default_factory=tuple)
+    recommendation: str = ""
+    severity: str = "low"
+    created_at: str = field(default_factory=_now_iso)
+
+
+def insight_from_prompt_block(
+    action: GuardActionEnvelope,
+    signals: tuple[RiskSignalV2, ...],
+) -> GuardInsight | None:
+    """L247: Generate a GuardInsight for a blocked prompt action."""
+    if not signals:
+        return None
+    excerpt = action.prompt_excerpt or (action.prompt_text or "")[:80]
+    return GuardInsight(
+        insight_id=str(uuid.uuid4()),
+        action_id=action.action_id,
+        action_type="prompt",
+        harness=action.harness,
+        what_happened=f"AI submitted a prompt that triggered a risk signal. Excerpt: {excerpt!r}",
+        why_risky=_first_reason(signals),
+        source=action.harness,
+        sink=None,
+        app=action.harness,
+        scanner_evidence=_detector_ids(signals),
+        recommendation=(
+            "Review the prompt text for injection attempts or data exfiltration patterns. "
+            "Allow only if you trust the source and intent."
+        ),
+        severity=_max_severity(signals),
+    )
+
+
+def insight_from_bash_command(
+    action: GuardActionEnvelope,
+    signals: tuple[RiskSignalV2, ...],
+) -> GuardInsight | None:
+    """L248: Generate a GuardInsight for a blocked bash/shell command."""
+    if not signals:
+        return None
+    cmd = (action.command or "")[:120]
+    return GuardInsight(
+        insight_id=str(uuid.uuid4()),
+        action_id=action.action_id,
+        action_type="shell_command",
+        harness=action.harness,
+        what_happened=f"AI attempted to run a shell command: {cmd!r}",
+        why_risky=_first_reason(signals),
+        source=action.tool_name or "bash",
+        sink=None,
+        app=action.harness,
+        scanner_evidence=_detector_ids(signals),
+        recommendation=(
+            "Inspect the full command before allowing. Pipe-to-shell and network-fetch patterns "
+            "are common supply-chain attack vectors."
+        ),
+        severity=_max_severity(signals),
+    )
+
+
+def insight_from_mcp_tool_call(
+    action: GuardActionEnvelope,
+    signals: tuple[RiskSignalV2, ...],
+) -> GuardInsight | None:
+    """L249: Generate a GuardInsight for a blocked MCP tool call."""
+    if not signals:
+        return None
+    tool = action.mcp_tool or action.tool_name or "unknown"
+    server = action.mcp_server or "unknown"
+    return GuardInsight(
+        insight_id=str(uuid.uuid4()),
+        action_id=action.action_id,
+        action_type="mcp_tool",
+        harness=action.harness,
+        what_happened=f"AI invoked MCP tool {tool!r} on server {server!r}",
+        why_risky=_first_reason(signals),
+        source=server,
+        sink=None,
+        app=action.harness,
+        scanner_evidence=_detector_ids(signals),
+        recommendation=(
+            f"Verify that the MCP tool {tool!r} is from a trusted source and that "
+            "the server configuration has not been tampered with."
+        ),
+        severity=_max_severity(signals),
+    )
+
+
+def insight_from_skill_scan(
+    *,
+    action_id: str,
+    harness: str,
+    skill_name: str,
+    signals: tuple[RiskSignalV2, ...],
+) -> GuardInsight | None:
+    """L250: Generate a GuardInsight for a flagged skill scan result."""
+    if not signals:
+        return None
+    return GuardInsight(
+        insight_id=str(uuid.uuid4()),
+        action_id=action_id,
+        action_type="skill_scan",
+        harness=harness,
+        what_happened=f"Skill scan flagged {skill_name!r} as potentially dangerous",
+        why_risky=_first_reason(signals),
+        source=skill_name,
+        sink=None,
+        app=harness,
+        scanner_evidence=_detector_ids(signals),
+        recommendation=(
+            f"Review the skill definition for {skill_name!r}. "
+            "Remove or isolate the skill if you did not install it intentionally."
+        ),
+        severity=_max_severity(signals),
+    )
+
+
+def insight_from_package_script(
+    action: GuardActionEnvelope,
+    signals: tuple[RiskSignalV2, ...],
+) -> GuardInsight | None:
+    """L251: Generate a GuardInsight for a blocked package/script action."""
+    if not signals:
+        return None
+    pkg = action.package_name or action.script_name or (action.command or "")[:60]
+    mgr = action.package_manager or "unknown"
+    return GuardInsight(
+        insight_id=str(uuid.uuid4()),
+        action_id=action.action_id,
+        action_type=action.action_type,
+        harness=action.harness,
+        what_happened=f"AI tried to run a {mgr} package or script: {pkg!r}",
+        why_risky=_first_reason(signals),
+        source=mgr,
+        sink=pkg,
+        app=action.harness,
+        scanner_evidence=_detector_ids(signals),
+        recommendation=(
+            f"Verify that {pkg!r} is a legitimate package and that it does not "
+            "run post-install scripts that modify system state or phone home."
+        ),
+        severity=_max_severity(signals),
+    )
+
+
+def insight_from_encoded_payload(
+    action: GuardActionEnvelope,
+    signals: tuple[RiskSignalV2, ...],
+) -> GuardInsight | None:
+    """L252: Generate a GuardInsight for an encoded/obfuscated payload."""
+    if not signals:
+        return None
+    cmd = (action.command or action.prompt_text or "")[:80]
+    return GuardInsight(
+        insight_id=str(uuid.uuid4()),
+        action_id=action.action_id,
+        action_type=action.action_type,
+        harness=action.harness,
+        what_happened=f"AI submitted a payload containing encoded or obfuscated content: {cmd!r}",
+        why_risky="Encoded payloads can hide malicious commands from static analysis and bypass security controls.",
+        source=action.tool_name or action.harness,
+        sink=None,
+        app=action.harness,
+        scanner_evidence=_detector_ids(signals),
+        recommendation=(
+            "Decode the payload manually and inspect the plaintext before allowing. "
+            "Legitimate commands do not need encoding."
+        ),
+        severity=_max_severity(signals),
+    )

{plugin_scanner-2.0.153 → plugin_scanner-2.0.155}/src/codex_plugin_scanner/guard/runtime/detectors.py

@@ -219,9 +219,10 @@ class SupplyChainDetector:
 
     def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
         del context
-        if action.prompt_text is None:
-            return ()
-        return detect_supply_chain_risk(action.prompt_text)
+        signals: list[RiskSignalV2] = []
+        for content in filter(None, (action.prompt_text, action.command)):
+            signals.extend(detect_supply_chain_risk(content))
+        return tuple(signals)
 
 
 class SafeDecodeDetector:
@@ -551,6 +552,106 @@ class GuardBypassDetector:
         return tuple(signals)
 
 
+_MCP_RISKY_TOOL_PATTERN = re.compile(
+    r"(?:exec(?:ute)?|run|shell|spawn|eval|invoke|dispatch|launch)"
+    r"|(?:write|send|upload|post|exfil|steal|dump|leak).*(?:cred|secret|token|key|password)"
+    r"|(?:arbitrary|remote|unsafe|untruste[d])",
+    re.IGNORECASE,
+)
+
+
+class McpToolSchemaRiskDetector:
+    """Detects MCP tool names that suggest dangerous execution or exfiltration capability."""
+
+    detector_id = "mcp.schema-risk"
+    categories: tuple[RiskSignalCategory, ...] = ("mcp",)
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        del context
+        if action.action_type != "mcp_tool" or action.mcp_tool is None:
+            return ()
+        tool_name = action.mcp_tool
+        if not _MCP_RISKY_TOOL_PATTERN.search(tool_name):
+            return ()
+        return (
+            RiskSignalV2(
+                signal_id=f"mcp:schema-risk:{tool_name[:40]}",
+                category="mcp",
+                severity="high",
+                confidence="moderate",
+                detector=self.detector_id,
+                title="MCP tool name suggests dangerous capability",
+                plain_reason=(
+                    f"The MCP tool '{tool_name}' has a name that suggests it can execute code,"
+                    " run shell commands, or exfiltrate credentials. Review the tool's actual"
+                    " implementation before approving."
+                ),
+                technical_detail=f"tool name matched risky-capability pattern: {tool_name!r}",
+                evidence_ref="mcp_tool",
+                redaction_level="summary",
+                false_positive_hint=(
+                    "Allow if this tool is from a trusted server and its implementation"
+                    " is audited and does not perform unauthorized actions."
+                ),
+                advisory_id=None,
+            ),
+        )
+
+
+_MCP_INJECTION_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"ignore\s+(?:all\s+)?(?:previous|prior|above)\s+instruction", re.IGNORECASE),
+    re.compile(r"you\s+(?:are\s+now|have\s+no\s+restriction|must\s+obey)", re.IGNORECASE),
+    re.compile(r"(?:disregard|forget|override)\s+(?:your\s+)?(?:instruction|system\s+prompt|training)", re.IGNORECASE),
+    re.compile(r"(?:send|post|upload|exfil(?:trate)?)\s+.*\bto\s+https?://(?!localhost|127\.0\.0\.1)", re.IGNORECASE),
+    re.compile(
+        r"when\s+you\s+(?:read|access|open|process)\s+.{0,60}(?:also|then|and)\s+(?:send|post|upload)",
+        re.IGNORECASE,
+    ),
+)
+
+
+class McpDescriptionDeceptionDetector:
+    """Detects prompt injection and deception patterns in MCP tool descriptions or prompts."""
+
+    detector_id = "mcp.description-deception"
+    categories: tuple[RiskSignalCategory, ...] = ("prompt",)
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        del context
+        if action.action_type not in ("mcp_tool", "mcp_tool_call") or action.prompt_excerpt is None:
+            return ()
+        excerpt = action.prompt_excerpt
+        signals: list[RiskSignalV2] = []
+        for i, pattern in enumerate(_MCP_INJECTION_PATTERNS):
+            m = pattern.search(excerpt)
+            if m:
+                signals.append(
+                    RiskSignalV2(
+                        signal_id=f"mcp:desc-deception:p{i}",
+                        category="prompt",
+                        severity="critical",
+                        confidence="strong",
+                        detector=self.detector_id,
+                        title="MCP description contains prompt injection or jailbreak attempt",
+                        plain_reason=(
+                            "The tool description or prompt contains language designed to override"
+                            " your AI assistant's instructions or cause it to exfiltrate data."
+                            " This is a common technique used by malicious MCP servers."
+                        ),
+                        technical_detail=f"matched deception pattern {i}: {m.group(0)[:60]!r}",
+                        evidence_ref="prompt_excerpt",
+                        redaction_level="summary",
+                        false_positive_hint=(
+                            "Allow only if you authored this tool description yourself"
+                            " and verified it does not cause unintended behavior."
+                        ),
+                        advisory_id=None,
+                    )
+                )
+                break
+        return tuple(signals)
+
+
 def register_default_detectors() -> tuple[GuardDetector, ...]:
     """Return the default ordered detector list.
 
@@ -569,6 +670,8 @@ def register_default_detectors() -> tuple[GuardDetector, ...]:
         FalsePositiveSuppressorDetector(),
         DataFlowExfiltrationDetector(),
         GuardBypassDetector(),
+        McpDescriptionDeceptionDetector(),
+        McpToolSchemaRiskDetector(),
         PersistenceDetector(),
         PromptInjectionDetector(),
         SafeDecodeDetector(),

{plugin_scanner-2.0.153 → plugin_scanner-2.0.155}/src/codex_plugin_scanner/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for tool version."""
 
-__version__ = "2.0.153"
+__version__ = "2.0.155"