plugin-scanner 2.0.150__tar.gz → 2.0.152__tar.gz

{plugin_scanner-2.0.150 → plugin_scanner-2.0.152}/PKG-INFO

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

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

{plugin_scanner-2.0.150 → plugin_scanner-2.0.152}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.150"
+version = "2.0.152"
 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.152/src/codex_plugin_scanner/guard/runtime/composition_rules.py

@@ -0,0 +1,143 @@
+"""Signal composition rules for Guard detector action decisions.
+
+Combines false-positive advisory signals with risk signals to produce a
+calibrated action recommendation: allow, warn, ask, or block.
+
+The base policy action (from config/approval policy) is used as the starting
+point. Composition rules may only *downgrade* (block → ask, ask → warn,
+warn → allow) when strong false-positive evidence is present, and may only
+*upgrade* (warn → ask, ask → block) when high-confidence risk signals demand it.
+
+Composition rules never override an explicit user policy choice.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from codex_plugin_scanner.guard.runtime.signals import RiskSignalV2
+
+ComposedAction = Literal["allow", "warn", "ask", "block"]
+
+_ACTION_RANK: dict[ComposedAction, int] = {
+    "allow": 0,
+    "warn": 1,
+    "ask": 2,
+    "block": 3,
+}
+
+_RANK_ACTION: dict[int, ComposedAction] = {v: k for k, v in _ACTION_RANK.items()}
+
+_DOWNGRADE_BLOCK_CATEGORIES = frozenset({"bypass", "persistence"})
+_DOWNGRADE_PROTECTED_SEVERITIES = frozenset({"critical", "high"})
+_FP_DOWNGRADE_MAX_SEVERITY = frozenset({"info", "low"})
+
+
+@dataclass(frozen=True, slots=True)
+class CompositionResult:
+    """Result of applying composition rules to a set of signals."""
+
+    action: ComposedAction
+    reason: str
+    downgraded: bool
+    upgraded: bool
+
+
+def compose_action_from_signals(
+    signals: tuple[RiskSignalV2, ...],
+    base_action: ComposedAction,
+) -> CompositionResult:
+    """Apply composition rules to signals and return a calibrated action.
+
+    Args:
+        signals: All signals from the detector run (risk + advisory).
+        base_action: The starting action from config/policy evaluation.
+
+    Returns:
+        A ``CompositionResult`` with the final action and an explanation.
+    """
+    risk_signals = tuple(s for s in signals if s.category != "false_positive")
+    fp_signals = tuple(s for s in signals if s.category == "false_positive")
+
+    if not signals:
+        return CompositionResult(
+            action=base_action,
+            reason="no detector signals; base policy action applies",
+            downgraded=False,
+            upgraded=False,
+        )
+
+    current_rank = _ACTION_RANK[base_action]
+    upgrade_reason: str | None = None
+    downgrade_reason: str | None = None
+
+    for signal in risk_signals:
+        if signal.category == "bypass" and signal.confidence in ("likely", "strong"):
+            new_rank = max(current_rank, _ACTION_RANK["block"])
+            if new_rank > current_rank:
+                upgrade_reason = f"bypass signal '{signal.detector}' forces block"
+                current_rank = new_rank
+
+        if signal.category == "persistence" and signal.severity in ("high", "critical"):
+            new_rank = max(current_rank, _ACTION_RANK["ask"])
+            if new_rank > current_rank:
+                upgrade_reason = upgrade_reason or f"persistence signal '{signal.detector}' requires review"
+                current_rank = new_rank
+
+        if signal.severity == "critical" and signal.confidence in ("likely", "strong"):
+            new_rank = max(current_rank, _ACTION_RANK["block"])
+            if new_rank > current_rank:
+                upgrade_reason = upgrade_reason or f"critical signal '{signal.detector}' forces block"
+                current_rank = new_rank
+
+    final_rank = current_rank
+
+    if fp_signals and not upgrade_reason:
+        all_fp_strong = all(s.confidence == "strong" for s in fp_signals)
+        risk_severities = frozenset(s.severity for s in risk_signals)
+        only_low_risk = risk_severities.issubset(_FP_DOWNGRADE_MAX_SEVERITY)
+        risk_cats = frozenset(s.category for s in risk_signals)
+        no_protected_cats = not risk_cats.intersection(_DOWNGRADE_BLOCK_CATEGORIES)
+
+        if all_fp_strong and only_low_risk and no_protected_cats and base_action == "block":
+            final_rank = min(final_rank, _ACTION_RANK["ask"])
+            downgrade_reason = "strong false-positive signals with only low-severity risk; downgraded block → ask"
+
+        elif all_fp_strong and only_low_risk and no_protected_cats and base_action == "ask":
+            source_search_present = any(s.signal_id.startswith("fp:source-search:") for s in fp_signals)
+            if source_search_present and not risk_signals:
+                final_rank = min(final_rank, _ACTION_RANK["warn"])
+                downgrade_reason = "strong source-search false-positive with no risk signals; downgraded ask → warn"
+
+    if upgrade_reason:
+        return CompositionResult(
+            action=_RANK_ACTION[final_rank],
+            reason=upgrade_reason,
+            downgraded=False,
+            upgraded=final_rank > _ACTION_RANK[base_action],
+        )
+
+    if downgrade_reason:
+        return CompositionResult(
+            action=_RANK_ACTION[final_rank],
+            reason=downgrade_reason,
+            downgraded=True,
+            upgraded=False,
+        )
+
+    if risk_signals:
+        top = max(risk_signals, key=lambda s: (_ACTION_RANK.get("ask", 2), s.severity))
+        return CompositionResult(
+            action=_RANK_ACTION[final_rank],
+            reason=f"risk signal '{top.detector}' ({top.severity}/{top.confidence}); base action applies",
+            downgraded=False,
+            upgraded=False,
+        )
+
+    return CompositionResult(
+        action=_RANK_ACTION[final_rank],
+        reason="advisory false-positive signals only; base action applies",
+        downgraded=False,
+        upgraded=False,
+    )

{plugin_scanner-2.0.150 → plugin_scanner-2.0.152}/src/codex_plugin_scanner/guard/runtime/detectors.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import time
 from collections.abc import Callable, Iterable, Mapping, Sequence
 from dataclasses import dataclass
@@ -12,6 +13,14 @@ from codex_plugin_scanner.guard.config import GuardConfig
 from codex_plugin_scanner.guard.runtime.actions import GuardActionEnvelope
 from codex_plugin_scanner.guard.runtime.cisco_preflight import CiscoMcpPreflightDetector, CiscoSkillPreflightDetector
 from codex_plugin_scanner.guard.runtime.data_flow_rules import detect_data_flow_exfiltration
+from codex_plugin_scanner.guard.runtime.false_positive_rules import (
+    classify_docs_example_source,
+    classify_health_endpoint_fetch,
+    classify_package_metadata_access,
+    classify_source_search_command,
+    classify_version_file_access,
+)
+from codex_plugin_scanner.guard.runtime.persistence_rules import detect_persistence_mechanisms
 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
@@ -286,6 +295,262 @@ class SafeDecodeDetector:
         return tuple(signals)
 
 
+class FalsePositiveSuppressorDetector:
+    """Detects patterns that are commonly benign, emitting advisory false_positive signals.
+
+    These signals do not directly change policy action but provide hints that
+    policy composition rules and operators can use to reduce unnecessary blocks.
+    """
+
+    detector_id = "false_positive.suppressor"
+    categories: tuple[RiskSignalCategory, ...] = ("false_positive",)
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        del context
+        signals: list[RiskSignalV2] = []
+
+        if action.action_type == "shell_command" and action.command is not None:
+            classification = classify_source_search_command(action.command)
+            if classification.is_source_search:
+                signals.append(
+                    RiskSignalV2(
+                        signal_id=f"fp:source-search:{classification.tool}",
+                        category="false_positive",
+                        severity="info",
+                        confidence="strong",
+                        detector=self.detector_id,
+                        title="Read-only code or filesystem search",
+                        plain_reason=(
+                            f"This command uses '{classification.tool}' to search code or the filesystem "
+                            "and does not access secret files or pipe output to the network."
+                        ),
+                        technical_detail=classification.reason,
+                        evidence_ref="command",
+                        redaction_level="none",
+                        false_positive_hint=None,
+                        advisory_id=None,
+                    )
+                )
+
+            if classify_health_endpoint_fetch(action.command):
+                signals.append(
+                    RiskSignalV2(
+                        signal_id="fp:health-endpoint-fetch",
+                        category="false_positive",
+                        severity="info",
+                        confidence="strong",
+                        detector=self.detector_id,
+                        title="Localhost health or readiness check",
+                        plain_reason=(
+                            "This command fetches a localhost health or readiness endpoint,"
+                            " which is a normal development pattern."
+                        ),
+                        technical_detail="matched localhost health endpoint pattern",
+                        evidence_ref="command",
+                        redaction_level="none",
+                        false_positive_hint=None,
+                        advisory_id=None,
+                    )
+                )
+
+        if action.action_type == "file_read" and action.target_paths:
+            if classify_version_file_access(list(action.target_paths)):
+                signals.append(
+                    RiskSignalV2(
+                        signal_id="fp:version-file-access",
+                        category="false_positive",
+                        severity="info",
+                        confidence="strong",
+                        detector=self.detector_id,
+                        title="Version pin file access",
+                        plain_reason=(
+                            "Reading a version pin file (.nvmrc, .python-version, etc.) is a normal"
+                            " toolchain operation with no sensitive data."
+                        ),
+                        technical_detail="matched version pin file pattern",
+                        evidence_ref="target_paths",
+                        redaction_level="none",
+                        false_positive_hint=None,
+                        advisory_id=None,
+                    )
+                )
+
+            if classify_package_metadata_access(list(action.target_paths)):
+                signals.append(
+                    RiskSignalV2(
+                        signal_id="fp:package-metadata-access",
+                        category="false_positive",
+                        severity="info",
+                        confidence="strong",
+                        detector=self.detector_id,
+                        title="Package manifest or lock file access",
+                        plain_reason=(
+                            "Reading package.json, requirements.txt, or similar manifests is a normal"
+                            " dependency management operation."
+                        ),
+                        technical_detail="matched package metadata file pattern",
+                        evidence_ref="target_paths",
+                        redaction_level="none",
+                        false_positive_hint=None,
+                        advisory_id=None,
+                    )
+                )
+
+            for path in action.target_paths:
+                if classify_docs_example_source(path):
+                    signals.append(
+                        RiskSignalV2(
+                            signal_id=f"fp:docs-example-source:{path[:40]}",
+                            category="false_positive",
+                            severity="info",
+                            confidence="strong",
+                            detector=self.detector_id,
+                            title="Access to docs or example file",
+                            plain_reason=(
+                                "The file path points to documentation, examples, or fixture data,"
+                                " which rarely contains real credentials or sensitive content."
+                            ),
+                            technical_detail=f"matched docs/example path: {path}",
+                            evidence_ref="target_paths",
+                            redaction_level="none",
+                            false_positive_hint=None,
+                            advisory_id=None,
+                        )
+                    )
+                    break
+
+        return tuple(signals)
+
+
+class PersistenceDetector:
+    """Detects commands that install persistence mechanisms on the host system."""
+
+    detector_id = "persistence.mechanism"
+    categories: tuple[RiskSignalCategory, ...] = ("persistence",)
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        del context
+        if action.action_type != "shell_command" or action.command is None:
+            return ()
+        matches = detect_persistence_mechanisms(action.command)
+        return tuple(
+            RiskSignalV2(
+                signal_id=f"persistence:{match.mechanism}",
+                category="persistence",
+                severity="high",
+                confidence="moderate",
+                detector=self.detector_id,
+                title=f"Persistence via {match.mechanism.replace('_', ' ')}",
+                plain_reason=match.plain_reason,
+                technical_detail=f"mechanism: {match.mechanism}",
+                evidence_ref="command",
+                redaction_level="summary",
+                false_positive_hint=match.false_positive_hint,
+                advisory_id=None,
+            )
+            for match in matches
+        )
+
+
+class GuardBypassDetector:
+    """Detects shell commands that uninstall, disable, or circumvent HOL Guard."""
+
+    detector_id = "bypass.shell"
+    categories: tuple[RiskSignalCategory, ...] = ("bypass",)
+
+    _UNINSTALL_PATTERN = re.compile(
+        r"(?:^|[\s;&|])"
+        r"(?:"
+        r"pip(?:3)?\s+uninstall\s+(?:-y\s+)?(?:holguard|hol[_-]guard|codex[_-]plugin[_-]scanner)\b|"
+        r"brew\s+(?:uninstall|remove)\s+hol[_-]guard\b|"
+        r"npm\s+(?:uninstall|remove)\s+(?:-g\s+)?hol[_-]guard\b|"
+        r"apt(?:-get)?\s+(?:remove|purge)\s+hol[_-]guard\b"
+        r")",
+        re.IGNORECASE,
+    )
+
+    _CONFIG_DESTROY_PATTERN = re.compile(
+        r"(?:^|[\s;&|])"
+        r"(?:rm|rmdir)\b[^\r\n;&|]{0,100}"
+        r"(?:~?/?\.hol[_-]guard|guard[_-]home|(?<![a-zA-Z0-9_])guard\.db(?![a-zA-Z0-9_])|(?<![a-zA-Z0-9_])guard\.lock(?![a-zA-Z0-9_]))",
+        re.IGNORECASE,
+    )
+
+    _DAEMON_KILL_PATTERN = re.compile(
+        r"(?:^|[\s;&|])"
+        r"(?:"
+        r"kill\b[^\r\n;&|]{0,80}hol[_-]guard|"
+        r"pkill\b[^\r\n;&|]{0,40}(?<![a-zA-Z0-9_])hol[_-]guard(?![a-zA-Z0-9_])|"
+        r"launchctl\s+(?:unload|disable)\b[^\r\n;&|]{0,80}(?:hol[_-]guard|com\.hol\.guard)"
+        r")",
+        re.IGNORECASE,
+    )
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        del context
+        if action.action_type not in ("shell_command", "prompt") or action.command is None:
+            return ()
+        signals: list[RiskSignalV2] = []
+        if self._UNINSTALL_PATTERN.search(action.command):
+            signals.append(
+                RiskSignalV2(
+                    signal_id="bypass:guard-uninstall",
+                    category="bypass",
+                    severity="critical",
+                    confidence="strong",
+                    detector=self.detector_id,
+                    title="Command uninstalls HOL Guard",
+                    plain_reason=("This command removes HOL Guard, which would disable all AI harness protection."),
+                    technical_detail="matched guard uninstall pattern",
+                    evidence_ref="command",
+                    redaction_level="summary",
+                    false_positive_hint=("Allow only if you intentionally want to remove Guard from this machine."),
+                    advisory_id=None,
+                )
+            )
+        if self._CONFIG_DESTROY_PATTERN.search(action.command):
+            signals.append(
+                RiskSignalV2(
+                    signal_id="bypass:guard-config-destroy",
+                    category="bypass",
+                    severity="critical",
+                    confidence="strong",
+                    detector=self.detector_id,
+                    title="Command destroys Guard configuration or data",
+                    plain_reason=(
+                        "This command deletes HOL Guard configuration or state files,"
+                        " which would reset all protection settings and history."
+                    ),
+                    technical_detail="matched guard config/data deletion pattern",
+                    evidence_ref="command",
+                    redaction_level="summary",
+                    false_positive_hint=("Allow only if you intend to fully reset Guard and are aware of data loss."),
+                    advisory_id=None,
+                )
+            )
+        if self._DAEMON_KILL_PATTERN.search(action.command):
+            signals.append(
+                RiskSignalV2(
+                    signal_id="bypass:guard-daemon-kill",
+                    category="bypass",
+                    severity="high",
+                    confidence="strong",
+                    detector=self.detector_id,
+                    title="Command stops HOL Guard daemon",
+                    plain_reason=(
+                        "This command stops the HOL Guard background service,"
+                        " which temporarily disables harness protection."
+                    ),
+                    technical_detail="matched guard daemon kill/unload pattern",
+                    evidence_ref="command",
+                    redaction_level="summary",
+                    false_positive_hint="Allow only if you intentionally want to pause Guard for maintenance.",
+                    advisory_id=None,
+                )
+            )
+        return tuple(signals)
+
+
 def register_default_detectors() -> tuple[GuardDetector, ...]:
     """Return the default ordered detector list.
 
@@ -293,11 +558,18 @@ def register_default_detectors() -> tuple[GuardDetector, ...]:
     before native data-flow and prompt detectors evaluate the same action.
     This ordering is intentional: scanner evidence can influence policy before
     runtime detectors produce additional signals.
+
+    FalsePositiveSuppressorDetector runs early to annotate benign patterns
+    before risk detectors evaluate the same action, so policy resolution can
+    factor in FP signals when composing the final action.
     """
     return (
         CiscoMcpPreflightDetector(),
         CiscoSkillPreflightDetector(),
+        FalsePositiveSuppressorDetector(),
         DataFlowExfiltrationDetector(),
+        GuardBypassDetector(),
+        PersistenceDetector(),
         PromptInjectionDetector(),
         SafeDecodeDetector(),
         SecretPathDetector(),