plugin-scanner 2.0.103__tar.gz → 2.0.104__tar.gz

{plugin_scanner-2.0.103 → plugin_scanner-2.0.104}/PKG-INFO

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

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

{plugin_scanner-2.0.103 → plugin_scanner-2.0.104}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.103"
+version = "2.0.104"
 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.103 → plugin_scanner-2.0.104}/src/codex_plugin_scanner/guard/config.py

@@ -176,6 +176,9 @@ class GuardConfig:
     telemetry: bool = False
     sync: bool = False
     billing: bool = False
+    runtime_detector_registry: bool = False
+    runtime_detector_timeout_ms: int = 50
+    runtime_detector_disabled_ids: tuple[str, ...] = ()
     risk_actions: dict[str, GuardAction] | None = None
     harness_risk_actions: dict[str, dict[str, GuardAction]] | None = None
     harness_actions: dict[str, GuardAction] | None = None
@@ -252,6 +255,9 @@ def load_guard_config(guard_home: Path, workspace: Path | None = None) -> GuardC
         telemetry=bool(merged.get("telemetry", False)),
         sync=bool(merged.get("sync", False)),
         billing=bool(merged.get("billing", False)),
+        runtime_detector_registry=_coerce_loaded_bool(merged.get("runtime_detector_registry", False)),
+        runtime_detector_timeout_ms=_coerce_loaded_positive_int(merged.get("runtime_detector_timeout_ms", 50), 50),
+        runtime_detector_disabled_ids=_coerce_loaded_string_tuple(merged.get("runtime_detector_disabled_ids")),
         harness_actions=_coerce_action_map(merged.get("harnesses")),
         publisher_actions=_coerce_action_map(merged.get("publishers")),
         artifact_actions=_coerce_action_map(merged.get("artifacts")),
@@ -346,6 +352,22 @@ def _coerce_loaded_security_level(value: object) -> str:
     return DEFAULT_SECURITY_LEVEL
 
 
+def _coerce_loaded_bool(value: object) -> bool:
+    return value if isinstance(value, bool) else False
+
+
+def _coerce_loaded_positive_int(value: object, fallback: int) -> int:
+    if isinstance(value, int) and not isinstance(value, bool) and value > 0:
+        return value
+    return fallback
+
+
+def _coerce_loaded_string_tuple(value: object) -> tuple[str, ...]:
+    if not isinstance(value, list):
+        return ()
+    return tuple(item for item in value if isinstance(item, str) and item.strip())
+
+
 def _coerce_risk_action_payload(value: object) -> dict[str, GuardAction]:
     if not isinstance(value, dict):
         raise ValueError("Risk actions must be a table.")

plugin_scanner-2.0.104/src/codex_plugin_scanner/guard/runtime/detectors.py

@@ -0,0 +1,148 @@
+"""Runtime detector registry primitives for Guard actions."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Protocol
+
+from codex_plugin_scanner.guard.config import GuardConfig
+from codex_plugin_scanner.guard.runtime.actions import GuardActionEnvelope
+from codex_plugin_scanner.guard.runtime.signals import RiskSignalCategory, RiskSignalV2
+
+DETECTOR_CATEGORY_TAGS: tuple[RiskSignalCategory, ...] = (
+    "secret",
+    "network",
+    "prompt",
+    "mcp",
+    "skill",
+    "supply_chain",
+    "encoded",
+    "persistence",
+    "bypass",
+    "false_positive",
+)
+DetectorRunStatus = Literal["ok", "disabled", "filtered", "timeout", "error"]
+
+
+@dataclass(frozen=True, slots=True)
+class DetectorContext:
+    """Context shared with runtime detectors."""
+
+    config: GuardConfig
+    workspace: Path | None
+    prior_decisions: Mapping[str, object]
+    threat_intel: Mapping[str, object]
+    redaction_settings: Mapping[str, object]
+
+
+class GuardDetector(Protocol):
+    """Detector interface for runtime Guard actions."""
+
+    detector_id: str
+    categories: tuple[RiskSignalCategory, ...]
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        """Return typed risk signals for the runtime action."""
+
+
+@dataclass(frozen=True, slots=True)
+class DetectorTelemetry:
+    """Debug-safe detector execution telemetry."""
+
+    detector_id: str
+    categories: tuple[RiskSignalCategory, ...]
+    status: DetectorRunStatus
+    elapsed_ms: int
+    error_type: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "detector_id": self.detector_id,
+            "categories": list(self.categories),
+            "status": self.status,
+            "elapsed_ms": self.elapsed_ms,
+            "error_type": self.error_type,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class DetectorRunResult:
+    """Signals and telemetry produced by a registry run."""
+
+    signals: tuple[RiskSignalV2, ...]
+    telemetry: tuple[DetectorTelemetry, ...]
+
+
+class DetectorRegistry:
+    """Runs detectors in deterministic order with failure isolation."""
+
+    def __init__(
+        self,
+        detectors: Iterable[GuardDetector],
+        *,
+        clock: Callable[[], float] | None = None,
+    ) -> None:
+        self._detectors = tuple(sorted(detectors, key=lambda detector: detector.detector_id))
+        self._clock = clock or time.monotonic
+
+    def run(
+        self,
+        action: GuardActionEnvelope,
+        context: DetectorContext,
+        *,
+        timeout_ms: int = 50,
+        disabled_detector_ids: Sequence[str] = (),
+        enabled_categories: Sequence[RiskSignalCategory] | None = None,
+    ) -> DetectorRunResult:
+        disabled_ids = frozenset(disabled_detector_ids)
+        category_filter = frozenset(enabled_categories) if enabled_categories is not None else None
+        signals: list[RiskSignalV2] = []
+        telemetry: list[DetectorTelemetry] = []
+        for detector in self._detectors:
+            if detector.detector_id in disabled_ids:
+                telemetry.append(_telemetry(detector, "disabled", elapsed_ms=0))
+                continue
+            if category_filter is not None and not category_filter.intersection(detector.categories):
+                telemetry.append(_telemetry(detector, "filtered", elapsed_ms=0))
+                continue
+            started_at = self._clock()
+            try:
+                detector_signals = detector.detect(action, context)
+                elapsed_ms = _elapsed_ms(started_at, self._clock())
+            except Exception as error:
+                elapsed_ms = _elapsed_ms(started_at, self._clock())
+                telemetry.append(_telemetry(detector, "error", elapsed_ms=elapsed_ms, error_type=type(error).__name__))
+                continue
+            if elapsed_ms > timeout_ms:
+                telemetry.append(_telemetry(detector, "timeout", elapsed_ms=elapsed_ms))
+                continue
+            signals.extend(detector_signals)
+            telemetry.append(_telemetry(detector, "ok", elapsed_ms=elapsed_ms))
+        return DetectorRunResult(signals=tuple(signals), telemetry=tuple(telemetry))
+
+
+def register_default_detectors() -> tuple[GuardDetector, ...]:
+    return ()
+
+
+def _elapsed_ms(started_at: float, finished_at: float) -> int:
+    return max(0, round((finished_at - started_at) * 1000))
+
+
+def _telemetry(
+    detector: GuardDetector,
+    status: DetectorRunStatus,
+    *,
+    elapsed_ms: int,
+    error_type: str | None = None,
+) -> DetectorTelemetry:
+    return DetectorTelemetry(
+        detector_id=detector.detector_id,
+        categories=detector.categories,
+        status=status,
+        elapsed_ms=elapsed_ms,
+        error_type=error_type,
+    )

{plugin_scanner-2.0.103 → plugin_scanner-2.0.104}/src/codex_plugin_scanner/guard/runtime/runner.py

@@ -26,6 +26,7 @@ from ..models import GuardArtifact, HarnessDetection, PolicyDecision
 from ..store import GuardStore
 from ..types import PromptRequest, RemediationAction
 from .actions import GuardActionEnvelope, redacted_workspace_label
+from .detectors import DetectorContext, DetectorRegistry, register_default_detectors
 
 _APPROVAL_METADATA_KEYS = (
     "approval_center_url",
@@ -251,6 +252,12 @@ def guard_run(
             if key in pending_evaluation:
                 reevaluated[key] = pending_evaluation[key]
         evaluation = reevaluated
+    evaluation = _evaluation_with_detector_registry(
+        evaluation,
+        action_envelope,
+        context,
+        config,
+    )
     if "config_paths" not in evaluation:
         evaluation["config_paths"] = list(detection.config_paths) or _guard_run_config_paths(
             detection=detection,
@@ -337,6 +344,36 @@ def _evaluation_with_action_envelope(
     return {**evaluation, "artifacts": normalized_artifacts}
 
 
+def _evaluation_with_detector_registry(
+    evaluation: dict[str, Any],
+    action_envelope: GuardActionEnvelope,
+    context: HarnessContext,
+    config: GuardConfig,
+) -> dict[str, Any]:
+    if not config.runtime_detector_registry:
+        return evaluation
+    detector_context = DetectorContext(
+        config=config,
+        workspace=context.workspace_dir,
+        prior_decisions={},
+        threat_intel={},
+        redaction_settings={},
+    )
+    result = DetectorRegistry(register_default_detectors()).run(
+        action_envelope,
+        detector_context,
+        timeout_ms=config.runtime_detector_timeout_ms,
+        disabled_detector_ids=config.runtime_detector_disabled_ids,
+    )
+    if not result.signals and not result.telemetry:
+        return evaluation
+    return {
+        **evaluation,
+        "runtime_detector_signals_v2": [signal.to_dict() for signal in result.signals],
+        "runtime_detector_telemetry": [item.to_dict() for item in result.telemetry],
+    }
+
+
 def _guard_run_config_paths(
     *,
     detection: HarnessDetection,

{plugin_scanner-2.0.103 → plugin_scanner-2.0.104}/src/codex_plugin_scanner/version.py

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

{plugin_scanner-2.0.103 → plugin_scanner-2.0.104}/tests/test_guard_config_paths.py

@@ -110,6 +110,27 @@ def test_guard_config_loads_security_level_and_risk_action_overrides(tmp_path):
     assert resolve_risk_action(config, "credential_exfiltration", harness="codex") == "block"
 
 
+def test_load_guard_config_parses_hidden_runtime_detector_registry(tmp_path):
+    guard_home = tmp_path / ".hol-guard"
+    _write_text(
+        guard_home / "config.toml",
+        "\n".join(
+            [
+                "runtime_detector_registry = true",
+                "runtime_detector_timeout_ms = 75",
+                'runtime_detector_disabled_ids = ["secret.local"]',
+            ]
+        )
+        + "\n",
+    )
+
+    config = load_guard_config(guard_home)
+
+    assert config.runtime_detector_registry is True
+    assert config.runtime_detector_timeout_ms == 75
+    assert config.runtime_detector_disabled_ids == ("secret.local",)
+
+
 def test_guard_config_strict_profile_defaults_review_sensitive_risks(tmp_path):
     guard_home = tmp_path / ".hol-guard"
     _write_text(guard_home / "config.toml", 'security_level = "strict"\n')

plugin_scanner-2.0.104/tests/test_guard_runtime_detectors.py

@@ -0,0 +1,295 @@
+"""Behavior tests for Guard runtime detector registry plumbing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from codex_plugin_scanner.guard.adapters.base import HarnessContext
+from codex_plugin_scanner.guard.config import GuardConfig
+from codex_plugin_scanner.guard.models import HarnessDetection
+from codex_plugin_scanner.guard.runtime import runner as guard_runner_module
+from codex_plugin_scanner.guard.runtime.actions import GuardActionEnvelope
+from codex_plugin_scanner.guard.runtime.detectors import (
+    DETECTOR_CATEGORY_TAGS,
+    DetectorContext,
+    DetectorRegistry,
+    register_default_detectors,
+)
+from codex_plugin_scanner.guard.runtime.signals import RiskSignalCategory, RiskSignalV2
+from codex_plugin_scanner.guard.store import GuardStore
+
+
+class StepClock:
+    def __init__(self, values: list[float]) -> None:
+        self.values = values
+
+    def __call__(self) -> float:
+        return self.values.pop(0)
+
+
+class RecordingDetector:
+    def __init__(
+        self,
+        detector_id: str,
+        categories: tuple[RiskSignalCategory, ...],
+        calls: list[str],
+        signal: RiskSignalV2 | None = None,
+        raises: Exception | None = None,
+    ) -> None:
+        self.detector_id = detector_id
+        self.categories = categories
+        self.calls = calls
+        self.signal = signal
+        self.raises = raises
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        self.calls.append(self.detector_id)
+        assert action.action_type == "harness_start"
+        assert context.workspace is not None
+        if self.raises is not None:
+            raise self.raises
+        if self.signal is None:
+            return ()
+        return (self.signal,)
+
+
+def _signal(signal_id: str, category: RiskSignalCategory) -> RiskSignalV2:
+    return RiskSignalV2(
+        signal_id=signal_id,
+        category=category,
+        severity="medium",
+        confidence="likely",
+        detector="test-detector",
+        title="Detector signal",
+        plain_reason="Detector found a risky runtime action.",
+        technical_detail=None,
+        evidence_ref=None,
+        redaction_level="summary",
+        false_positive_hint=None,
+        advisory_id=None,
+    )
+
+
+def _action() -> GuardActionEnvelope:
+    return GuardActionEnvelope(
+        schema_version=1,
+        action_id="action-1",
+        harness="codex",
+        event_name="HarnessStart",
+        action_type="harness_start",
+        workspace="~/workspace",
+        workspace_hash="workspace-hash",
+        tool_name=None,
+        command=None,
+        prompt_excerpt=None,
+        target_paths=(),
+        network_hosts=(),
+        mcp_server=None,
+        mcp_tool=None,
+        package_manager=None,
+        package_name=None,
+        script_name=None,
+        raw_payload_redacted={},
+    )
+
+
+def _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={"artifact": "allow"},
+        threat_intel={"source": "unit-test"},
+        redaction_settings={"level": "summary"},
+    )
+
+
+def test_detector_registry_runs_in_deterministic_detector_id_order(tmp_path):
+    calls: list[str] = []
+    registry = DetectorRegistry(
+        (
+            RecordingDetector("network.egress", ("network",), calls, _signal("network:egress", "network")),
+            RecordingDetector("secret.local", ("secret",), calls, _signal("secret:local", "secret")),
+        ),
+        clock=StepClock([0.0, 0.001, 0.002, 0.003]),
+    )
+
+    result = registry.run(_action(), _context(tmp_path))
+
+    assert calls == ["network.egress", "secret.local"]
+    assert [signal.signal_id for signal in result.signals] == ["network:egress", "secret:local"]
+    assert [item.status for item in result.telemetry] == ["ok", "ok"]
+
+
+def test_detector_registry_skips_disabled_detector_ids(tmp_path):
+    calls: list[str] = []
+    registry = DetectorRegistry(
+        (
+            RecordingDetector("network.egress", ("network",), calls, _signal("network:egress", "network")),
+            RecordingDetector("secret.local", ("secret",), calls, _signal("secret:local", "secret")),
+        ),
+        clock=StepClock([0.0, 0.001]),
+    )
+
+    result = registry.run(_action(), _context(tmp_path), disabled_detector_ids=("network.egress",))
+
+    assert calls == ["secret.local"]
+    assert [signal.signal_id for signal in result.signals] == ["secret:local"]
+    assert [(item.detector_id, item.status) for item in result.telemetry] == [
+        ("network.egress", "disabled"),
+        ("secret.local", "ok"),
+    ]
+
+
+def test_detector_registry_discards_signals_when_detector_exceeds_timeout(tmp_path):
+    calls: list[str] = []
+    registry = DetectorRegistry(
+        (RecordingDetector("secret.slow", ("secret",), calls, _signal("secret:slow", "secret")),),
+        clock=StepClock([0.0, 0.075]),
+    )
+
+    result = registry.run(_action(), _context(tmp_path), timeout_ms=50)
+
+    assert calls == ["secret.slow"]
+    assert result.signals == ()
+    assert result.telemetry[0].status == "timeout"
+    assert result.telemetry[0].elapsed_ms == 75
+
+
+def test_detector_registry_isolates_detector_exceptions_as_telemetry(tmp_path):
+    calls: list[str] = []
+    registry = DetectorRegistry(
+        (
+            RecordingDetector("secret.broken", ("secret",), calls, raises=RuntimeError("boom")),
+            RecordingDetector("secret.healthy", ("secret",), calls, signal=_signal("secret:healthy", "secret")),
+        ),
+        clock=StepClock([0.0, 0.001, 0.002, 0.003]),
+    )
+
+    result = registry.run(_action(), _context(tmp_path))
+
+    assert calls == ["secret.broken", "secret.healthy"]
+    assert [signal.signal_id for signal in result.signals] == ["secret:healthy"]
+    assert result.telemetry[0].status == "error"
+    assert result.telemetry[0].error_type == "RuntimeError"
+
+
+def test_detector_registry_filters_by_detector_categories(tmp_path):
+    calls: list[str] = []
+    registry = DetectorRegistry(
+        (
+            RecordingDetector("network.egress", ("network",), calls, _signal("network:egress", "network")),
+            RecordingDetector("secret.local", ("secret",), calls, _signal("secret:local", "secret")),
+        ),
+        clock=StepClock([0.0, 0.001]),
+    )
+
+    result = registry.run(_action(), _context(tmp_path), enabled_categories=("secret",))
+
+    assert calls == ["secret.local"]
+    assert [signal.signal_id for signal in result.signals] == ["secret:local"]
+    assert result.telemetry[0].status == "filtered"
+    assert result.telemetry[0].detector_id == "network.egress"
+
+
+def test_register_default_detectors_is_empty_until_specific_detectors_land():
+    assert register_default_detectors() == ()
+    planned_categories = {
+        "secret",
+        "network",
+        "prompt",
+        "mcp",
+        "skill",
+        "supply_chain",
+        "encoded",
+        "persistence",
+        "bypass",
+        "false_positive",
+    }
+    assert planned_categories.issubset(set(DETECTOR_CATEGORY_TAGS))
+
+
+def test_guard_run_invokes_detector_registry_only_when_feature_flag_enabled(tmp_path, monkeypatch):
+    calls: list[str] = []
+    detector = RecordingDetector("secret.local", ("secret",), calls, _signal("secret:local", "secret"))
+    detection = HarnessDetection(
+        harness="codex",
+        installed=True,
+        command_available=True,
+        config_paths=(),
+        artifacts=(),
+    )
+
+    def evaluate_stub(*_args: object, **_kwargs: object) -> dict[str, object]:
+        return {"blocked": False, "artifacts": [], "receipts_recorded": 0}
+
+    monkeypatch.setattr(guard_runner_module, "detect_harness", lambda _harness, _context: detection)
+    monkeypatch.setattr(guard_runner_module, "evaluate_detection", evaluate_stub)
+    monkeypatch.setattr(guard_runner_module, "register_default_detectors", lambda: (detector,))
+
+    context = HarnessContext(
+        home_dir=tmp_path / "home",
+        workspace_dir=tmp_path / "workspace",
+        guard_home=tmp_path / "guard-home",
+    )
+    store = GuardStore(tmp_path / "guard-home")
+    disabled = GuardConfig(guard_home=tmp_path / "guard-home", workspace=tmp_path / "workspace")
+    enabled = GuardConfig(
+        guard_home=tmp_path / "guard-home",
+        workspace=tmp_path / "workspace",
+        runtime_detector_registry=True,
+    )
+
+    disabled_result = guard_runner_module.guard_run("codex", context, store, disabled, True, [])
+    enabled_result = guard_runner_module.guard_run("codex", context, store, enabled, True, [])
+
+    assert calls == ["secret.local"]
+    assert "runtime_detector_signals_v2" not in disabled_result
+    assert enabled_result["runtime_detector_signals_v2"] == [_signal("secret:local", "secret").to_dict()]
+    assert isinstance(enabled_result["runtime_detector_telemetry"], list)
+
+
+def test_guard_run_keeps_detector_results_after_blocked_resolver_reevaluation(tmp_path, monkeypatch):
+    calls: list[str] = []
+    detector = RecordingDetector("secret.local", ("secret",), calls, _signal("secret:local", "secret"))
+    detection = HarnessDetection(
+        harness="codex",
+        installed=True,
+        command_available=True,
+        config_paths=(),
+        artifacts=(),
+    )
+
+    def evaluate_stub(*_args: object, **_kwargs: object) -> dict[str, object]:
+        return {"blocked": True, "artifacts": [], "receipts_recorded": 0}
+
+    def blocked_resolver_stub(_detection: HarnessDetection, _evaluation: dict[str, object]) -> dict[str, object]:
+        return {"blocked": True, "artifacts": [], "approval_delivery": "queued"}
+
+    monkeypatch.setattr(guard_runner_module, "detect_harness", lambda _harness, _context: detection)
+    monkeypatch.setattr(guard_runner_module, "evaluate_detection", evaluate_stub)
+    monkeypatch.setattr(guard_runner_module, "register_default_detectors", lambda: (detector,))
+
+    context = HarnessContext(
+        home_dir=tmp_path / "home",
+        workspace_dir=tmp_path / "workspace",
+        guard_home=tmp_path / "guard-home",
+    )
+    config = GuardConfig(
+        guard_home=tmp_path / "guard-home",
+        workspace=tmp_path / "workspace",
+        runtime_detector_registry=True,
+    )
+
+    result = guard_runner_module.guard_run(
+        "codex",
+        context,
+        GuardStore(tmp_path / "guard-home"),
+        config,
+        False,
+        [],
+        blocked_resolver=blocked_resolver_stub,
+    )
+
+    assert calls == ["secret.local"]
+    assert result["runtime_detector_signals_v2"] == [_signal("secret:local", "secret").to_dict()]
+    assert result["approval_delivery"] == "queued"