plugin-scanner 2.0.1083__tar.gz → 2.0.1084__tar.gz

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1083
+Version: 2.0.1084
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://hol.org/guard
 Project-URL: Documentation, https://github.com/hashgraph-online/hol-guard/tree/main/docs/guard

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/docs/guard/command-extension-architecture.md

@@ -67,6 +67,9 @@ Decision composition must be monotonic:
 
 A versioned truth table covering source authority, required status, extension mode, severity, uncertainty, safe variants, overlap, memory, and configured policy is a release artifact and executable test fixture.
 
+The accepted registry and minimum-action truth table is documented in
+[`command-extension-precedence.md`](command-extension-precedence.md) and enforced by the command extension tests.
+
 ## Memory migration
 
 The new security identity hashes the complete canonical command semantics, not a prefix or display label. It binds dialect, transport, normalized segments and suffixes, wrappers, aliases and executable path source, security-relevant environment overrides including `PATH`, cwd scope, workspace/source scope, parser confidence, and controlling rule ID plus semantic version.

plugin_scanner-2.0.1084/docs/guard/command-extension-precedence.md

@@ -0,0 +1,45 @@
+# Command Extension Registry and Decision Floors
+
+## Status
+
+Accepted. This contract governs schema-v2 built-in command extensions while final decisions remain in Guard's existing policy, memory, approval, and receipt systems.
+
+## Registry authority
+
+The registry validates all extensions before evaluation:
+
+- IDs, semantic versions, aliases, dependencies, conflicts, and rule ownership are deterministic and unique.
+- Required extensions must come from the built-in source. Local-admin and signed managed definitions cannot claim required status.
+- Aliases resolve to one canonical extension and cannot shadow another extension ID.
+- Dependencies must exist and form an acyclic graph. Conflicting extensions cannot coexist.
+- Matcher indexes are conservative. Recognized executable and keyword hints reduce candidate work; unknown matcher types remain always evaluated.
+- Indexes select candidates only. Matchers remain the source of rule evidence, and registry order remains stable.
+
+## Decision floor
+
+An extension emits evidence and a minimum action. It never grants an allow or replaces workspace policy.
+
+| Required | Severity | Rule mode | Minimum action |
+| --- | --- | --- | --- |
+| no | any | disabled | allow |
+| no | any | monitor | monitor |
+| no | any | review | review |
+| no | any | enforce | block |
+| no | any | required | review |
+| yes | low, medium, high | any | at least review |
+| yes | critical | any | block |
+
+Additional invariants:
+
+1. Multiple matches retain all evidence. The strongest minimum action controls; severity breaks ties.
+2. A trusted built-in safe variant suppresses only evidence from its declaring rule and matched segment.
+3. Required status is immutable outside built-in definitions. External configuration cannot add a safe variant to a required rule.
+4. Parser uncertainty with sensitive evidence raises the minimum action to review.
+5. Remembered decisions require the full security identity. They are evaluated after extension evidence and cannot weaken a required floor.
+6. Workspace and managed policy may preserve or strengthen the floor. Final approval and block authority remains outside extensions.
+
+## Compatibility
+
+Existing action classes remain the controlling runtime classification when the compatibility detector supplies one. Structured rules add ordered evidence, unioned risks, a controlling rule ID, and a minimum action without changing policy storage or approval contracts.
+
+Inspection exposes the floor and controlling rule for debugging. It remains side-effect-free and does not claim that final policy was evaluated.

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/pyproject.toml

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

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.1083"
+version = "2.0.1084"
 description = "Open-source antivirus and runtime protection for AI agents, tools, MCP servers, plugins, skills, and package installs."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/src/codex_plugin_scanner/guard/runtime/command_evaluation.py

@@ -4,10 +4,26 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Literal
 
-from .command_extensions import BUILT_IN_COMMAND_EXTENSION_REGISTRY, CommandSafetyExtension
+from .command_extensions import (
+    BUILT_IN_COMMAND_EXTENSION_REGISTRY,
+    CommandSafetyExtension,
+    CommandSafetyExtensionRegistry,
+)
 from .command_model import CanonicalCommand, parse_shell_command
-from .command_rules import CommandRuleMatch
+from .command_rules import CommandRuleMatch, CommandRuleMode
+
+CommandDecisionFloor = Literal["allow", "monitor", "review", "block"]
+_FLOOR_RANK: dict[CommandDecisionFloor, int] = {"allow": 0, "monitor": 1, "review": 2, "block": 3}
+_SEVERITY_RANK = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+_MODE_FLOOR: dict[CommandRuleMode, CommandDecisionFloor] = {
+    "disabled": "allow",
+    "monitor": "monitor",
+    "review": "review",
+    "enforce": "block",
+    "required": "review",
+}
 
 
 @dataclass(frozen=True, slots=True)
@@ -32,6 +48,8 @@ class CompositeCommandEvaluation:
     matches: tuple[OwnedCommandRuleMatch, ...]
     controlling_action_class: str | None
     controlling_reason: str | None
+    controlling_rule_id: str | None
+    minimum_action: CommandDecisionFloor
 
     @property
     def risk_classes(self) -> tuple[str, ...]:
@@ -46,6 +64,8 @@ class CompositeCommandEvaluation:
             "security_identity": self.command.security_identity,
             "controlling_action_class": self.controlling_action_class,
             "controlling_reason": self.controlling_reason,
+            "controlling_rule_id": self.controlling_rule_id,
+            "minimum_action": self.minimum_action,
             "risk_classes": list(self.risk_classes),
             "matches": [owned.to_dict() for owned in self.matches],
             "parse_confidence": self.command.confidence,
@@ -61,16 +81,17 @@ def evaluate_command(
     compatibility_reason: str | None = None,
     cwd: Path | None = None,
     home_dir: Path | None = None,
+    registry: CommandSafetyExtensionRegistry = BUILT_IN_COMMAND_EXTENSION_REGISTRY,
 ) -> CompositeCommandEvaluation:
     """Evaluate every built-in rule without executing or persisting the command."""
 
     command = canonical_command or parse_shell_command(command_text, cwd=cwd, home_dir=home_dir)
-    structured = BUILT_IN_COMMAND_EXTENSION_REGISTRY.matching_rules(command)
+    structured = registry.matching_rules(command)
     selected = list(structured)
     selected_rule_ids = {rule.rule_id for _extension, rule, _evidence in selected}
     if compatibility_action_class is not None:
-        extension = BUILT_IN_COMMAND_EXTENSION_REGISTRY.for_action_class(compatibility_action_class)
-        rule = BUILT_IN_COMMAND_EXTENSION_REGISTRY.rule_for_action_class(compatibility_action_class)
+        extension = registry.for_action_class(compatibility_action_class)
+        rule = registry.rule_for_action_class(compatibility_action_class)
         if extension is not None and rule is not None and rule.rule_id not in selected_rule_ids:
             selected.append((extension, rule, ()))
 
@@ -93,14 +114,45 @@ def evaluate_command(
             )
         )
 
+    controlling_match = max(owned_matches, key=_match_precedence_key, default=None)
     controlling_action_class = compatibility_action_class
     controlling_reason = compatibility_reason
-    if controlling_action_class is None and owned_matches:
-        controlling_action_class = owned_matches[0].match.action_class
-        controlling_reason = owned_matches[0].match.reason
+    if controlling_action_class is None and controlling_match is not None:
+        controlling_action_class = controlling_match.match.action_class
+        controlling_reason = controlling_match.match.reason
+    minimum_action: CommandDecisionFloor = "allow"
+    for owned in owned_matches:
+        minimum_action = _stronger_floor(minimum_action, _rule_floor(owned))
+    if compatibility_action_class is not None:
+        minimum_action = _stronger_floor(minimum_action, "review")
+    if command.confidence != "exact" and (compatibility_action_class is not None or owned_matches):
+        minimum_action = _stronger_floor(minimum_action, "review")
     return CompositeCommandEvaluation(
         command=command,
         matches=tuple(owned_matches),
         controlling_action_class=controlling_action_class,
         controlling_reason=controlling_reason,
+        controlling_rule_id=controlling_match.match.rule.rule_id if controlling_match is not None else None,
+        minimum_action=minimum_action,
+    )
+
+
+def _rule_floor(owned: OwnedCommandRuleMatch) -> CommandDecisionFloor:
+    rule = owned.match.rule
+    if owned.extension.required and rule.severity == "critical":
+        return "block"
+    if owned.extension.required:
+        return "review"
+    return _MODE_FLOOR[rule.default_mode]
+
+
+def _stronger_floor(left: CommandDecisionFloor, right: CommandDecisionFloor) -> CommandDecisionFloor:
+    return left if _FLOOR_RANK[left] >= _FLOOR_RANK[right] else right
+
+
+def _match_precedence_key(owned: OwnedCommandRuleMatch) -> tuple[int, int, int]:
+    return (
+        _FLOOR_RANK[_rule_floor(owned)],
+        _SEVERITY_RANK[owned.match.rule.severity],
+        0 if owned.match.rule.compatibility_fallback else 1,
     )

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/src/codex_plugin_scanner/guard/runtime/command_extensions.py

@@ -4,14 +4,18 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass
-from typing import final
+from typing import Literal, final
 
 from .command_builtin_rules import COMMAND_ACTION_RISK_CLASSES, rules_for_extension
 from .command_model import CanonicalCommand
-from .command_rules import CommandSafetyRule, MatcherEvidence
+from .command_rules import CommandSafetyRule, MatcherEvidence, matcher_index_hints
 
 COMMAND_EXTENSION_SCHEMA_VERSION = 2
 _VERSION_PATTERN = re.compile(r"^[1-9][0-9]*\.[0-9]+\.[0-9]+$")
+_EXTENSION_ID_PATTERN = re.compile(r"^command\.[a-z0-9]+(?:[.-][a-z0-9]+)*$")
+
+CommandExtensionSource = Literal["built-in", "local-admin", "signed-cloud"]
+_VALID_EXTENSION_SOURCES = frozenset({"built-in", "local-admin", "signed-cloud"})
 
 
 def risk_classes_for_command_action(action_class: str) -> tuple[str, ...]:
@@ -33,6 +37,10 @@ class CommandSafetyExtension:
     safer_alternatives: tuple[str, ...]
     rules: tuple[CommandSafetyRule, ...] = ()
     required: bool = False
+    source: CommandExtensionSource = "built-in"
+    aliases: tuple[str, ...] = ()
+    dependencies: tuple[str, ...] = ()
+    conflicts: tuple[str, ...] = ()
 
     def to_dict(self) -> dict[str, object]:
         return {
@@ -43,7 +51,10 @@ class CommandSafetyExtension:
             "description": self.description,
             "enabled": True,
             "required": self.required,
-            "source": "built-in",
+            "source": self.source,
+            "aliases": list(self.aliases),
+            "dependencies": list(self.dependencies),
+            "conflicts": list(self.conflicts),
             "action_classes": list(self.action_classes),
             "risk_classes": list(self.risk_classes),
             "safer_alternatives": list(self.safer_alternatives),
@@ -62,11 +73,20 @@ class CommandSafetyExtensionRegistry:
         by_action_class: dict[str, CommandSafetyExtension] = {}
         by_action_rule: dict[str, CommandSafetyRule] = {}
         by_rule_id: dict[str, CommandSafetyRule] = {}
+        aliases: dict[str, str] = {}
+        rule_records: list[tuple[CommandSafetyExtension, CommandSafetyRule]] = []
+        executable_index: dict[str, set[str]] = {}
+        keyword_index: dict[str, set[str]] = {}
+        unindexed_rule_ids: set[str] = set()
         for extension in ordered:
             _validate_extension(extension)
             if extension.extension_id in by_id:
                 raise ValueError(f"Duplicate command safety extension ID: {extension.extension_id}")
             by_id[extension.extension_id] = extension
+            for alias in extension.aliases:
+                if alias in by_id or alias in aliases:
+                    raise ValueError(f"Duplicate command safety extension alias: {alias}")
+                aliases[alias] = extension.extension_id
             for action_class in extension.action_classes:
                 normalized_action_class = action_class.strip().lower()
                 owner = by_action_class.get(normalized_action_class)
@@ -100,6 +120,15 @@ class CommandSafetyExtensionRegistry:
                         f"Command safety rule {rule.rule_id} declares risks outside its extension: {undeclared}"
                     )
                 by_rule_id[rule.rule_id] = rule
+                rule_records.append((extension, rule))
+                if rule.matcher is not None:
+                    hints = matcher_index_hints(rule.matcher)
+                    if not hints.complete or (not hints.executables and not hints.keywords):
+                        unindexed_rule_ids.add(rule.rule_id)
+                    for executable in hints.executables:
+                        executable_index.setdefault(executable, set()).add(rule.rule_id)
+                    for keyword in hints.keywords:
+                        keyword_index.setdefault(keyword, set()).add(rule.rule_id)
                 for action_class in rule.action_classes:
                     normalized_action_class = action_class.strip().lower()
                     if normalized_action_class not in {item.strip().lower() for item in extension.action_classes}:
@@ -117,18 +146,25 @@ class CommandSafetyExtensionRegistry:
                     raise ValueError(
                         f"Command safety extension {extension.extension_id} rules must own every action class"
                     )
+        _validate_registry_relationships(ordered, by_id=by_id, aliases=aliases)
         self._extensions = ordered
         self._by_id = by_id
+        self._aliases = aliases
         self._by_action_class = by_action_class
         self._by_action_rule = by_action_rule
         self._by_rule_id = by_rule_id
+        self._rule_records = tuple(rule_records)
+        self._executable_index = {key: frozenset(value) for key, value in executable_index.items()}
+        self._keyword_index = {key: frozenset(value) for key, value in keyword_index.items()}
+        self._unindexed_rule_ids = frozenset(unindexed_rule_ids)
 
     @property
     def extensions(self) -> tuple[CommandSafetyExtension, ...]:
         return self._extensions
 
     def get(self, extension_id: str) -> CommandSafetyExtension | None:
-        return self._by_id.get(extension_id.strip().lower())
+        normalized = extension_id.strip().lower()
+        return self._by_id.get(self._aliases.get(normalized, normalized))
 
     def for_action_class(self, action_class: str) -> CommandSafetyExtension | None:
         return self._by_action_class.get(action_class.strip().lower())
@@ -139,6 +175,22 @@ class CommandSafetyExtensionRegistry:
     def rule_for_action_class(self, action_class: str) -> CommandSafetyRule | None:
         return self._by_action_rule.get(action_class.strip().lower())
 
+    def candidate_rule_ids(self, command: CanonicalCommand) -> tuple[str, ...]:
+        """Return deterministic rule candidates from conservative registry indexes."""
+
+        candidate_rule_ids = set(self._unindexed_rule_ids)
+        command_executables = {
+            segment.executable.replace("\\", "/").rsplit("/", 1)[-1].lower()
+            for segment in command.segments
+            if segment.executable is not None
+        }
+        command_keywords = {token.lower() for segment in command.segments for token in segment.tokens}
+        for executable in command_executables:
+            candidate_rule_ids.update(self._executable_index.get(executable, ()))
+        for keyword in command_keywords:
+            candidate_rule_ids.update(self._keyword_index.get(keyword, ()))
+        return tuple(rule.rule_id for _extension, rule in self._rule_records if rule.rule_id in candidate_rule_ids)
+
     def matching_rules(
         self,
         command: CanonicalCommand,
@@ -146,30 +198,28 @@ class CommandSafetyExtensionRegistry:
         """Return every structured rule match in deterministic registry order."""
 
         matches: list[tuple[CommandSafetyExtension, CommandSafetyRule, tuple[MatcherEvidence, ...]]] = []
-        for extension in self._extensions:
-            for rule in extension.rules:
-                if rule.matcher is None:
-                    continue
-                evidence = rule.matcher.match(command)
-                if not evidence:
-                    continue
-                safe_segment_indexes = {
-                    safe_evidence.segment_index
-                    for variant in rule.safe_variants
-                    for safe_evidence in variant.matcher.match(command)
-                }
-                effective_evidence = tuple(item for item in evidence if item.segment_index not in safe_segment_indexes)
-                if not effective_evidence:
-                    continue
-                matches.append((extension, rule, effective_evidence))
+        candidate_rule_ids = frozenset(self.candidate_rule_ids(command))
+        for extension, rule in self._rule_records:
+            if rule.matcher is None or rule.rule_id not in candidate_rule_ids:
+                continue
+            evidence = rule.matcher.match(command)
+            if not evidence:
+                continue
+            safe_segment_indexes = {
+                safe_evidence.segment_index
+                for variant in rule.safe_variants
+                for safe_evidence in variant.matcher.match(command)
+            }
+            effective_evidence = tuple(item for item in evidence if item.segment_index not in safe_segment_indexes)
+            if not effective_evidence:
+                continue
+            matches.append((extension, rule, effective_evidence))
         return tuple(matches)
 
 
 def _validate_extension(extension: CommandSafetyExtension) -> None:
-    if not extension.extension_id.startswith("command."):
-        raise ValueError("Command safety extension IDs must start with 'command.'")
-    if extension.extension_id != extension.extension_id.lower():
-        raise ValueError("Command safety extension IDs must be lowercase")
+    if not _EXTENSION_ID_PATTERN.fullmatch(extension.extension_id):
+        raise ValueError("Command safety extension IDs must be lowercase and start with 'command.'")
     if not _VERSION_PATTERN.fullmatch(extension.version):
         raise ValueError(f"Invalid command safety extension version: {extension.version}")
     if not extension.name.strip() or not extension.description.strip():
@@ -184,6 +234,54 @@ def _validate_extension(extension: CommandSafetyExtension) -> None:
         raise ValueError(f"Command safety extension {extension.extension_id} has duplicate risk classes")
     if not extension.safer_alternatives:
         raise ValueError(f"Command safety extension {extension.extension_id} requires safer alternatives")
+    if extension.source not in _VALID_EXTENSION_SOURCES:
+        raise ValueError(f"Command safety extension {extension.extension_id} has invalid source")
+    if extension.required and extension.source != "built-in":
+        raise ValueError(f"Required command safety extension {extension.extension_id} must be built-in")
+    for field_name, values in (
+        ("aliases", extension.aliases),
+        ("dependencies", extension.dependencies),
+        ("conflicts", extension.conflicts),
+    ):
+        if len(set(values)) != len(values) or any(not _EXTENSION_ID_PATTERN.fullmatch(value) for value in values):
+            raise ValueError(f"Command safety extension {extension.extension_id} has invalid {field_name}")
+
+
+def _validate_registry_relationships(
+    extensions: tuple[CommandSafetyExtension, ...],
+    *,
+    by_id: dict[str, CommandSafetyExtension],
+    aliases: dict[str, str],
+) -> None:
+    for alias in aliases:
+        if alias in by_id:
+            raise ValueError(f"Command safety extension alias shadows an extension ID: {alias}")
+    for extension in extensions:
+        for dependency in extension.dependencies:
+            if dependency not in by_id:
+                raise ValueError(
+                    f"Command safety extension {extension.extension_id} has unknown dependency {dependency}"
+                )
+        for conflict in extension.conflicts:
+            if conflict == extension.extension_id or conflict in by_id:
+                raise ValueError(f"Command safety extension {extension.extension_id} conflicts with {conflict}")
+
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(extension_id: str) -> None:
+        if extension_id in visiting:
+            raise ValueError(f"Command safety extension dependency cycle includes {extension_id}")
+        if extension_id in visited:
+            return
+        visiting.add(extension_id)
+        for dependency in by_id[extension_id].dependencies:
+            visit(dependency)
+        visiting.remove(extension_id)
+        visited.add(extension_id)
+
+    for extension in extensions:
+        visit(extension.extension_id)
 
 
 _BUILT_IN_EXTENSIONS = (

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/src/codex_plugin_scanner/guard/runtime/command_inspection.py

@@ -90,6 +90,8 @@ def inspect_command(
                 "wrapper_chain": [],
             },
             "risk_classes": [],
+            "minimum_action": evaluation.minimum_action,
+            "controlling_rule_id": evaluation.controlling_rule_id,
             "signals": [],
             "extensions": [],
             "rules": [],
@@ -145,6 +147,8 @@ def inspect_command(
             "wrapper_chain": wrapper_chain,
         },
         "risk_classes": list(evaluation.risk_classes),
+        "minimum_action": evaluation.minimum_action,
+        "controlling_rule_id": evaluation.controlling_rule_id,
         "signals": [signal.to_dict() for signal in signals],
         "extensions": [extensions_by_id[extension_id].to_dict() for extension_id in sorted(extensions_by_id)],
         "rules": [owned.to_dict() for owned in evaluation.matches],

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/src/codex_plugin_scanner/guard/runtime/command_rules.py

@@ -294,6 +294,44 @@ class CommandRuleMatch:
         }
 
 
+@dataclass(frozen=True, slots=True)
+class MatcherIndexHints:
+    """Conservative registry hints that never replace matcher evaluation."""
+
+    executables: frozenset[str] = frozenset()
+    keywords: frozenset[str] = frozenset()
+    complete: bool = True
+
+
+def matcher_index_hints(matcher: CommandMatcher) -> MatcherIndexHints:
+    """Return conservative executable and keyword hints for a trusted matcher."""
+
+    if isinstance(matcher, ExecutableMatcher):
+        return MatcherIndexHints(
+            executables=matcher.executables,
+            keywords=frozenset((*matcher.subcommands, *matcher.required_flags)),
+        )
+    if isinstance(matcher, ArgumentMatcher):
+        return MatcherIndexHints(
+            executables=matcher.executables,
+            keywords=matcher.required_arguments,
+        )
+    if isinstance(matcher, PipelineMatcher):
+        return _merge_matcher_hints((matcher.producer, matcher.consumer))
+    if isinstance(matcher, (AnyMatcher, AllMatcher)):
+        return _merge_matcher_hints(matcher.matchers)
+    return MatcherIndexHints(complete=False)
+
+
+def _merge_matcher_hints(matchers: tuple[CommandMatcher, ...]) -> MatcherIndexHints:
+    child_hints = tuple(matcher_index_hints(matcher) for matcher in matchers)
+    return MatcherIndexHints(
+        executables=frozenset(value for hints in child_hints for value in hints.executables),
+        keywords=frozenset(value for hints in child_hints for value in hints.keywords),
+        complete=all(hints.complete for hints in child_hints),
+    )
+
+
 def _segment_matches_executable(segment: CommandSegment, executables: frozenset[str]) -> bool:
     if segment.executable is None:
         return False

{plugin_scanner-2.0.1083 → plugin_scanner-2.0.1084}/src/codex_plugin_scanner/version.py

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