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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.151"
+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.151 → plugin_scanner-2.0.152}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.151"
+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.151 → 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
@@ -451,6 +452,105 @@ class PersistenceDetector:
         )
 
 
+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.
 
@@ -468,6 +568,7 @@ def register_default_detectors() -> tuple[GuardDetector, ...]:
         CiscoSkillPreflightDetector(),
         FalsePositiveSuppressorDetector(),
         DataFlowExfiltrationDetector(),
+        GuardBypassDetector(),
         PersistenceDetector(),
         PromptInjectionDetector(),
         SafeDecodeDetector(),

{plugin_scanner-2.0.151 → plugin_scanner-2.0.152}/src/codex_plugin_scanner/guard/runtime/runner.py

@@ -29,6 +29,7 @@ from ..redaction import redact_sensitive_text
 from ..store import GuardStore
 from ..types import PromptRequest, RemediationAction
 from .actions import GuardActionEnvelope, redacted_workspace_label
+from .composition_rules import compose_action_from_signals
 from .detectors import DetectorContext, DetectorRegistry, DetectorRunResult, register_default_detectors
 from .prompt_injection import detect_prompt_injection_requests
 
@@ -403,6 +404,14 @@ def _evaluation_with_detector_registry(
         "runtime_detector_signals_v2": [signal.to_dict() for signal in result.signals],
         "runtime_detector_telemetry": [item.to_dict() for item in result.telemetry],
     }
+    base_action: str = "block" if evaluation.get("blocked") else "allow"
+    composition = compose_action_from_signals(result.signals, base_action)  # type: ignore[arg-type]
+    next_evaluation["runtime_detector_composition"] = {
+        "action": composition.action,
+        "reason": composition.reason,
+        "downgraded": composition.downgraded,
+        "upgraded": composition.upgraded,
+    }
     if trace_error is not None:
         next_evaluation["runtime_detector_trace_error"] = trace_error
     return next_evaluation

{plugin_scanner-2.0.151 → plugin_scanner-2.0.152}/src/codex_plugin_scanner/version.py

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

plugin_scanner-2.0.152/tests/test_guard_bypass_detector.py

@@ -0,0 +1,219 @@
+"""Tests for GuardBypassDetector and composition_rules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from codex_plugin_scanner.guard.config import GuardConfig
+from codex_plugin_scanner.guard.runtime.actions import GuardActionEnvelope
+from codex_plugin_scanner.guard.runtime.composition_rules import compose_action_from_signals
+from codex_plugin_scanner.guard.runtime.detectors import DetectorContext, GuardBypassDetector
+from codex_plugin_scanner.guard.runtime.signals import RiskSignalV2
+
+
+def _make_signal(
+    signal_id: str = "test:signal",
+    category: str = "bypass",
+    severity: str = "high",
+    confidence: str = "strong",
+    detector: str = "test.detector",
+) -> RiskSignalV2:
+    return RiskSignalV2(
+        signal_id=signal_id,
+        category=category,
+        severity=severity,
+        confidence=confidence,
+        detector=detector,
+        title="Test",
+        plain_reason="test reason",
+        technical_detail=None,
+        evidence_ref=None,
+        redaction_level="none",
+        false_positive_hint=None,
+        advisory_id=None,
+    )
+
+
+def _bypass_envelope(command: str) -> GuardActionEnvelope:
+    return GuardActionEnvelope(
+        schema_version=1,
+        action_id="",
+        harness="codex",
+        event_name="BashCommand",
+        action_type="shell_command",
+        workspace=None,
+        workspace_hash=None,
+        tool_name="bash",
+        command=command,
+        prompt_excerpt=None,
+        prompt_text=None,
+        target_paths=(),
+        network_hosts=(),
+        mcp_server=None,
+        mcp_tool=None,
+        package_manager=None,
+        package_name=None,
+        script_name=None,
+        raw_payload_redacted={},
+    )
+
+
+def _detector_context(tmp_path: Path) -> DetectorContext:
+    return DetectorContext(
+        config=GuardConfig(guard_home=tmp_path / "guard-home", workspace=tmp_path / "workspace"),
+        workspace=tmp_path / "workspace",
+        prior_decisions={},
+        threat_intel={},
+        redaction_settings={},
+    )
+
+
+class TestGuardBypassDetector:
+    detector = GuardBypassDetector()
+
+    def _detect(self, command: str, tmp_path: Path) -> tuple:
+        ctx = _detector_context(tmp_path)
+        env = _bypass_envelope(command)
+        return self.detector.detect(env, ctx)
+
+    def test_pip_uninstall_holguard(self, tmp_path: Path) -> None:
+        signals = self._detect("pip uninstall holguard", tmp_path)
+        assert any(s.signal_id == "bypass:guard-uninstall" for s in signals)
+        assert all(s.severity == "critical" for s in signals)
+
+    def test_pip3_uninstall_holguard_with_y(self, tmp_path: Path) -> None:
+        signals = self._detect("pip3 uninstall -y holguard", tmp_path)
+        assert any(s.signal_id == "bypass:guard-uninstall" for s in signals)
+
+    def test_pip_uninstall_codex_plugin_scanner(self, tmp_path: Path) -> None:
+        signals = self._detect("pip uninstall codex-plugin-scanner", tmp_path)
+        assert any(s.signal_id == "bypass:guard-uninstall" for s in signals)
+
+    def test_brew_uninstall_hol_guard(self, tmp_path: Path) -> None:
+        signals = self._detect("brew uninstall hol-guard", tmp_path)
+        assert any(s.signal_id == "bypass:guard-uninstall" for s in signals)
+
+    def test_rm_guard_db(self, tmp_path: Path) -> None:
+        signals = self._detect("rm ~/.hol-guard/guard.db", tmp_path)
+        assert any(s.signal_id == "bypass:guard-config-destroy" for s in signals)
+
+    def test_rm_guard_home(self, tmp_path: Path) -> None:
+        signals = self._detect("rm -rf ~/.hol-guard", tmp_path)
+        assert any(s.signal_id == "bypass:guard-config-destroy" for s in signals)
+
+    def test_kill_guard_daemon(self, tmp_path: Path) -> None:
+        signals = self._detect("kill -9 $(pgrep hol-guard)", tmp_path)
+        assert any(s.signal_id == "bypass:guard-daemon-kill" for s in signals)
+
+    def test_pkill_hol_guard(self, tmp_path: Path) -> None:
+        signals = self._detect("pkill -f hol-guard", tmp_path)
+        assert any(s.signal_id == "bypass:guard-daemon-kill" for s in signals)
+
+    def test_pkill_wireguard_is_not_bypass(self, tmp_path: Path) -> None:
+        signals = self._detect("pkill -f wireguard", tmp_path)
+        assert not any(s.signal_id == "bypass:guard-daemon-kill" for s in signals)
+
+    def test_rm_myguard_db_backup_is_not_bypass(self, tmp_path: Path) -> None:
+        signals = self._detect("rm ./myguard.db.backup", tmp_path)
+        assert not any(s.signal_id == "bypass:guard-config-destroy" for s in signals)
+
+    def test_pkill_safeguard_worker_is_not_bypass(self, tmp_path: Path) -> None:
+        signals = self._detect("pkill -f safeguard-worker", tmp_path)
+        assert not any(s.signal_id == "bypass:guard-daemon-kill" for s in signals)
+
+    def test_launchctl_unload_guard(self, tmp_path: Path) -> None:
+        signals = self._detect("launchctl unload ~/Library/LaunchAgents/hol-guard.plist", tmp_path)
+        assert any(s.signal_id == "bypass:guard-daemon-kill" for s in signals)
+
+    def test_benign_pip_install_not_flagged(self, tmp_path: Path) -> None:
+        signals = self._detect("pip install requests", tmp_path)
+        assert signals == ()
+
+    def test_benign_rm_log_not_flagged(self, tmp_path: Path) -> None:
+        signals = self._detect("rm -rf /tmp/myproject.log", tmp_path)
+        assert signals == ()
+
+    def test_benign_kill_other_process_not_flagged(self, tmp_path: Path) -> None:
+        signals = self._detect("kill -9 12345", tmp_path)
+        assert signals == ()
+
+    def test_npm_uninstall_hol_guard(self, tmp_path: Path) -> None:
+        signals = self._detect("npm uninstall -g hol-guard", tmp_path)
+        assert any(s.signal_id == "bypass:guard-uninstall" for s in signals)
+
+
+class TestComposeActionFromSignals:
+    """Tests for composition_rules.compose_action_from_signals."""
+
+    def test_no_signals_returns_base_action(self) -> None:
+        result = compose_action_from_signals((), "allow")
+        assert result.action == "allow"
+        assert not result.upgraded
+        assert not result.downgraded
+
+    def test_no_signals_block_base(self) -> None:
+        result = compose_action_from_signals((), "block")
+        assert result.action == "block"
+
+    def test_bypass_signal_upgrades_to_block(self) -> None:
+        signal = _make_signal(
+            signal_id="bypass:guard-uninstall", category="bypass", severity="critical", confidence="strong"
+        )
+        result = compose_action_from_signals((signal,), "allow")
+        assert result.action == "block"
+        assert result.upgraded
+
+    def test_persistence_signal_upgrades_to_ask(self) -> None:
+        signal = _make_signal(signal_id="persist:cron", category="persistence", severity="high", confidence="strong")
+        result = compose_action_from_signals((signal,), "allow")
+        assert result.action in ("ask", "block")
+        assert result.upgraded
+
+    def test_critical_risk_signal_upgrades_to_block(self) -> None:
+        signal = _make_signal(signal_id="risk:critical", category="data_flow", severity="critical", confidence="strong")
+        result = compose_action_from_signals((signal,), "allow")
+        assert result.action == "block"
+        assert result.upgraded
+
+    def test_strong_fp_with_no_risk_downgrades_block_to_ask(self) -> None:
+        fp = _make_signal(
+            signal_id="fp:source-search:grep", category="false_positive", severity="info", confidence="strong"
+        )
+        result = compose_action_from_signals((fp,), "block")
+        assert result.action == "ask"
+        assert result.downgraded
+
+    def test_strong_fp_source_search_downgrades_ask_to_warn(self) -> None:
+        fp = _make_signal(
+            signal_id="fp:source-search:grep", category="false_positive", severity="info", confidence="strong"
+        )
+        result = compose_action_from_signals((fp,), "ask")
+        assert result.action == "warn"
+        assert result.downgraded
+
+    def test_bypass_beats_fp_downgrade(self) -> None:
+        bypass = _make_signal(
+            signal_id="bypass:guard-uninstall", category="bypass", severity="critical", confidence="strong"
+        )
+        fp = _make_signal(
+            signal_id="fp:source-search:grep", category="false_positive", severity="info", confidence="strong"
+        )
+        result = compose_action_from_signals((bypass, fp), "allow")
+        assert result.action == "block"
+        assert result.upgraded
+        assert not result.downgraded
+
+    def test_fp_weak_confidence_does_not_downgrade(self) -> None:
+        fp = _make_signal(
+            signal_id="fp:source-search:grep", category="false_positive", severity="info", confidence="weak"
+        )
+        result = compose_action_from_signals((fp,), "block")
+        assert result.action == "block"
+        assert not result.downgraded
+
+    def test_composition_result_is_frozen(self) -> None:
+        result = compose_action_from_signals((), "allow")
+        with pytest.raises((AttributeError, TypeError)):
+            result.action = "block"  # type: ignore[misc]