plugin-scanner 2.0.1075__tar.gz → 2.0.1076__tar.gz

{plugin_scanner-2.0.1075 → plugin_scanner-2.0.1076}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1075
+Version: 2.0.1076
 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
@@ -188,6 +188,10 @@ Command safety extensions make Guard's existing shell, Git, filesystem, data-pro
 encoded-execution, and self-protection behavior inspectable. They are built-in capability boundaries over the same
 parser used by harness hooks, not downloadable regex bundles.
 
+Each extension publishes stable rule IDs and structured rule metadata. Command inspection also returns a canonical,
+side-effect-free parse model with wrapper, pipeline, environment-override, provenance, and confidence details so
+automation can distinguish exact parsing from malformed or unsupported input.
+
 Use `command test` for a concise classification and `command explain` for the complete evaluation trace. Both are
 side-effect free: they do not execute the command, evaluate final policy, create an approval, or record a receipt.
 Use `--json` for a stable automation contract.

{plugin_scanner-2.0.1075 → plugin_scanner-2.0.1076}/README.md

@@ -140,6 +140,10 @@ Command safety extensions make Guard's existing shell, Git, filesystem, data-pro
 encoded-execution, and self-protection behavior inspectable. They are built-in capability boundaries over the same
 parser used by harness hooks, not downloadable regex bundles.
 
+Each extension publishes stable rule IDs and structured rule metadata. Command inspection also returns a canonical,
+side-effect-free parse model with wrapper, pipeline, environment-override, provenance, and confidence details so
+automation can distinguish exact parsing from malformed or unsupported input.
+
 Use `command test` for a concise classification and `command explain` for the complete evaluation trace. Both are
 side-effect free: they do not execute the command, evaluate final policy, create an approval, or record a receipt.
 Use `--json` for a stable automation contract.

plugin_scanner-2.0.1076/docs/guard/command-extension-architecture.md

@@ -0,0 +1,106 @@
+# Command Extension Architecture
+
+## Status and scope
+
+This document defines the target contract for Guard command safety extensions. The schema-v2 registry and canonical command model currently preserve compatibility with existing action and risk classes while rule-level evaluation migrates behind them. Extensions detect and explain command facts; Guard's existing policy, approval, memory, and receipt systems retain decision authority.
+
+## Parse-once command model
+
+Each harness adapter extracts a command and declares its input boundary before parsing:
+
+- **Dialect:** `posix`, `powershell`, `cmd`, `argv`, or `unknown`.
+- **Transport:** shell string, argument vector, or embedded script.
+- **Provenance:** harness, event, extraction method, workspace/source scope, and whether text was direct or reconstructed.
+
+The parser boundary produces one immutable `CanonicalCommand` per request. The complete contract carries normalized text, cwd and platform context, security-relevant command-local environment overrides, parse confidence, wrapper chain, source spans, embedded scripts, and ordered segments. Segments preserve separators, pipeline position, executable/path source, subcommands, flags, operands, redirects, and execution-versus-data context.
+
+Consumers receive this model; they do not retokenize raw text. Dialects never share quoting rules, parsing never expands or executes shell content, and compound-command suffixes are retained. Unsupported dialects, malformed input, and exceeded limits return typed uncertainty rather than a partial success that can imply safety.
+
+```text
+harness request
+  -> adapter extraction with dialect, transport, and provenance
+  -> canonical parser (once)
+  -> context classification and executable/keyword index
+  -> all applicable extension matchers
+  -> composite evidence artifact
+  -> existing policy and memory evaluation
+  -> one response, approval item, and receipt
+```
+
+## Matcher boundary
+
+A `CommandMatcher` is side-effect-free and evaluates the canonical invocation or one of its segments. It returns zero or more `RuleMatch` values. Matchers use structured executable, subcommand, flag, operand, path, redirect, pipeline, data-flow, platform, and embedded-script fields. Compound matchers expose explicit `all`, `any`, and `not` semantics.
+
+Safe variants are positive, rule-local predicates such as a verified dry run, preview, read-only operation, or bounded target. A safe variant cannot suppress another rule. Regex is a bounded fallback for trusted definitions: compile it at registry construction, validate complexity, constrain input and match count, and evaluate it behind a hard interruption boundary when linear behavior is not guaranteed. Timeout or budget exhaustion produces uncertainty.
+
+Every match carries stable extension and rule IDs, extension version, severity, risk classes, matched segment and source-span references, redaction-safe evidence, confidence, safe-variant results, safer alternatives, and evaluation time. Matchers emit evidence only; they never emit `allow`, approve a request, write memory, or execute commands.
+
+## Registry boundary
+
+The injected registry is the sole source for runtime hooks, command inspection, dashboard APIs, and generated reference documentation. Construction validates:
+
+- schema and semantic versions; unique extension and rule IDs; deterministic ordering;
+- required status, source authority, dependencies, conflicts, aliases, and category ownership;
+- declared action/risk compatibility during migration;
+- matcher type, complexity, count, and time budgets;
+- source attribution as built-in, local-admin, or signed managed configuration;
+- rollback protection and the rule that external definitions cannot shadow built-ins.
+
+The registry indexes executable and bounded keywords so unrelated extensions are not evaluated. It imports no code from workspace or externally supplied definitions. Declarative external rules remain constrained by the matcher schema and protected configuration authority.
+
+Schema v2 makes leaf extensions own rules. Existing extension IDs, action classes, and risk classes remain available through a single compatibility translator until all consumers migrate. Stored extension settings require an explicit, versioned migration; unknown versions fail closed to a non-weaker state.
+
+## Evidence and policy authority
+
+All matches survive evaluation. The engine creates one composite artifact containing ordered matches, the union of risk classes, parser uncertainty, safe-variant outcomes, and the controlling rule. This produces one policy evaluation and one user action, avoiding duplicate prompts and receipts.
+
+The artifact is evidence, not policy. Guard policy resolves configured risk actions, source/workspace scope, managed policy, remembered decisions, approvals, and final `allow`, `warn`, `review`, `sandbox-required`, `require-reapproval`, or `block` behavior. Extension metadata, modes, and safer alternatives cannot grant authority.
+
+Decision composition must be monotonic:
+
+1. Required critical rules establish a minimum action that lower-authority input cannot reduce.
+2. A safe variant affects only its declaring rule.
+3. Multiple matches retain all evidence and the strongest controlling requirement.
+4. Destructive-executable parser or matcher uncertainty requires at least review.
+5. Remembered allow applies only to an equivalent full security identity.
+6. Managed, local-admin, workspace, and extension inputs may strengthen an outcome only within their authority.
+
+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.
+
+## 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.
+
+New memory writes use only the versioned identity. Legacy exact-command and pattern memory may be read during a bounded migration window only when every security-relevant field can be proven equivalent. Missing context, changed rule semantics, uncertainty, or broader legacy scope yields `require-reapproval`; it never falls back to a weaker pattern. Migration records the old and new identity versions without persisting newly exposed raw command material.
+
+## Redaction and persistence
+
+Raw text, tokens, embedded payloads, environment values, and source spans are ephemeral parser inputs by default. Persistence stores stable IDs, schema and extension versions, classifications, confidence, hashes, timing, controlling-rule metadata, and redacted excerpts or span descriptors. Secret values must not enter evidence, logs, metrics, generated docs, or matcher errors.
+
+Existing receipt redaction policy controls any authorized raw-command retention. Inspection and policy simulation are side-effect-free: no receipt, approval, memory, event, queue, lease, migration write, or network refresh. Relaxing a display setting must not reconstruct data that was never retained.
+
+## Limits and performance
+
+The parser enforces independent byte, token, segment, wrapper-depth, nesting, embedded-payload, and total-time limits. The evaluator enforces per-rule, per-extension, match-count, regex, and total-request budgets. Every limit failure is typed, observable in explain output, and non-allowing for potentially destructive input.
+
+Evaluation targets are p95 below 5 ms through 1 KiB and below 20 ms through 32 KiB on supported development hardware, with no more than 10% regression in benign hook p95 from the recorded baseline. Timing is available in debug and explain output, not normal hook output.
+
+## Rollout gates
+
+1. **Contract gate:** approve models, schemas, monotonic truth table, threat model, capability matrix, and latency/false-positive baselines.
+2. **Parity gate:** ship parser, matcher library, registry v2, and compatibility translator with the existing extension set; remove no legacy path until behavior parity passes.
+3. **Required-core gate:** add critical filesystem, Git, system, self-protection, platform, and embedded-script rules only after bypass and false-positive suites pass.
+4. **Domain gate:** add infrastructure, container, package, cloud, storage, and data domains in review or monitor mode until corpus and performance evidence supports stronger enforcement.
+5. **External-definition gate:** enable declarative local-admin and signed managed definitions only after signature, rollback, authority, corpus, and resource-budget controls pass.
+
+## Acceptance tests
+
+- Assert exactly one parser invocation per harness request and the same injected registry across runtime, CLI, dashboard, and generated docs.
+- Cover each dialect/transport independently, wrappers, aliases, cwd, `PATH`, separators, suffixes, pipelines, redirects, heredocs, substitutions, malformed input, and every limit.
+- For every rule, test destructive examples, safe counterparts, explicit safe variants, reordered flags, quoted search/print examples, paths with spaces, and platform syntax.
+- Assert deterministic registry output; reject duplicate IDs, invalid dependencies, shadowing, rollback, unknown schemas, and unsafe matcher complexity.
+- Execute the monotonic truth table, cross-extension overlap, required-rule, safe-variant isolation, uncertainty, and remembered-allow cases.
+- Prove one composite artifact, decision, approval item, and receipt while retaining all ordered evidence.
+- Verify legacy policy/action compatibility and require reapproval for any non-equivalent memory migration.
+- Verify full, partial, and no-redaction persistence; assert secrets and ephemeral parse material are absent from default storage and output.
+- Benchmark benign and destructive corpora, matcher timeouts, pathological input, CLI side-effect freedom, harness contracts, and installed-package end-to-end behavior.

plugin_scanner-2.0.1076/docs/guard/command-extension-threat-model.md

@@ -0,0 +1,119 @@
+# Command Extension Threat Model
+
+## Security objective
+
+Command extensions must improve detection without becoming a second policy engine or a code-loading mechanism. Untrusted command text, workspace content, extension configuration, and remembered decisions must not weaken required protections, disclose secrets, exhaust the hook, or cross workspace/source authority boundaries.
+
+## Assets and invariants
+
+- Final policy authority, approval signing, leases, step-up checks, and managed-policy isolation remain outside extensions.
+- Built-in registry content, required status, rule semantics, enabled state, and precedence cannot be downgraded by agent- or workspace-controlled input.
+- The complete command, including suffixes, wrappers, executable resolution, cwd, and security-relevant environment, is evaluated once.
+- All relevant matches and parser uncertainty survive into one composite evidence artifact.
+- Raw command material and secrets are ephemeral unless explicit receipt policy authorizes retention.
+- Inspection and simulation never execute commands or mutate Guard state.
+
+## Trust boundaries
+
+| Boundary | Trust and permitted authority |
+| --- | --- |
+| Harness adapter | May extract text and provenance; may not choose dialect silently or declare safety. |
+| Command input and workspace | Untrusted data. Files may recommend extensions but cannot load code, disable required rules, or grant policy authority. |
+| Canonical parser | Trusted code processing hostile input under strict limits; performs no expansion or execution. |
+| Built-in registry | Trusted, versioned product content protected by existing integrity controls. |
+| Local-admin definitions | Declarative and explicitly approved from protected state; cannot shadow or weaken built-ins. |
+| Managed definitions | Declarative, signed, fresh, rollback-protected, and bound to the correct workspace/source authority. |
+| Matcher output | Untrusted evidence until schema, ownership, confidence, and budget checks pass. Never a final decision. |
+| Policy and memory | Sole decision authority, constrained by precedence, scope, identity version, and integrity checks. |
+| Receipts, dashboard, and sync | Persistence and display boundary governed by redaction and workspace/source isolation. |
+
+## Threats and controls
+
+### Parser confusion and bypass
+
+An attacker may exploit dialect confusion, quoting, separators, pipelines, nested wrappers, aliases, command substitution, heredocs, embedded scripts, symlinks, cwd, or command-local `PATH` to hide a destructive suffix or change executable resolution.
+
+**Controls:** adapters declare dialect, transport, and provenance; one parser preserves all segments and source spans; dialect parsers do not fall through to another grammar; executable path source and relevant environment are part of the model; parsing performs no expansion; malformed, unsupported, over-limit, or low-confidence destructive input requires review.
+
+### Data mistaken for execution
+
+Destructive words inside search patterns, tests, comments, echo/printf arguments, or quoted examples can cause denial of service through false approvals. Conversely, substitutions or embedded scripts can make executable content look like inert data.
+
+**Controls:** every segment has explicit execution, data, quoted-example, or unknown context; safe variants are structured positive matches; embedded execution is extracted with bounded recursion; unknown context cannot suppress a required rule; canonical corpus tests include quoted and executable counterparts.
+
+### Matcher evasion or resource exhaustion
+
+Hostile input or declarative patterns may trigger excessive tokenization, match explosions, catastrophic regex behavior, deep nesting, or timeouts. A timeout could otherwise become an allow.
+
+**Controls:** independent parser and evaluator byte, token, segment, depth, payload, match-count, and time budgets; executable/keyword indexing; registry-time regex validation and compilation; guaranteed-linear matching or interruptible isolation for non-linear cases; timeout is typed uncertainty and never automatic safety.
+
+### Registry poisoning and authority escalation
+
+A project or managed source may duplicate a built-in ID, redefine risk, mark a destructive operation safe, disable a required extension, import executable code, introduce invalid dependencies, or replay an older definition.
+
+**Controls:** immutable built-in ownership; schema and semantic-version checks; unique IDs; source attribution; dependency/conflict validation; no runtime imports from external locations; local-admin approval; managed signature, freshness, scope, and rollback checks; project definitions remain monitor-only until promoted. External input may not override built-in IDs, required rules, risk classes, or precedence.
+
+### Safe-variant and overlap downgrade
+
+A broad safe predicate or lower-severity match may suppress a critical match from another rule. First-match evaluation may discard evidence or select the weaker result.
+
+**Controls:** evaluate all indexed rules; safe variants apply only to their owner; required critical rules establish a minimum action; union risks and retain ordered evidence; select the strongest controlling requirement through an executable monotonic truth table. Lower-authority input can never reduce that minimum.
+
+### Evidence used as policy
+
+An extension may attempt to return `allow`, self-approve, alter policy state, or manufacture an authoritative source. Multiple matches may create duplicate approvals that users approve inconsistently.
+
+**Controls:** matcher schemas contain facts and safer alternatives, not final actions; extension modes are policy inputs with bounded authority; only the existing policy engine resolves outcomes. One command creates one composite artifact, one policy decision, one approval item, and one receipt.
+
+### Remembered-allow replay
+
+A remembered allow for a prefix or normalized label may be replayed with a destructive suffix, wrapper, changed cwd, alias, `PATH`, workspace source, parser confidence, or changed rule semantics.
+
+**Controls:** versioned memory identity binds the full canonical command, dialect, transport, suffixes, wrappers, executable source, relevant environment, cwd and workspace/source scope, confidence, and controlling rule semantics. Legacy memory is accepted only on proven equivalence; missing context, broader scope, semantic change, or uncertainty requires reapproval.
+
+### Secret disclosure and persistence drift
+
+Commands, environment overrides, paths, embedded payloads, source spans, errors, traces, receipts, dashboard views, or sync records may expose credentials. A later redaction change may accidentally backfill material that was intended to remain ephemeral.
+
+**Controls:** default persistence is stable IDs, hashes, classifications, confidence, timing, and redacted excerpts/span descriptors. Raw parse material is discarded after evaluation unless explicit receipt policy authorizes retention. Matcher errors and metrics contain no raw secrets. Display and sync apply the configured redaction level and workspace/source isolation; relaxed settings cannot recreate unretained data.
+
+### Simulation side effects
+
+Inspection or evaluation intended for debugging may write memory, create approvals or receipts, refresh policy, enqueue work, acquire leases, emit events, or execute a command.
+
+**Controls:** inspection is policy-independent; policy evaluation uses a frozen local snapshot. Both are read-only and have tests asserting no filesystem, database, queue, event, network, lease, or execution side effects.
+
+## Monotonic precedence requirements
+
+The release truth table must prove these invariants for every combination of source authority, required status, mode, severity, safe variant, uncertainty, overlap, remembered decision, and policy action:
+
+1. Required minimum action is never reduced.
+2. Safe evidence cannot cancel unrelated unsafe evidence.
+3. Parser or matcher uncertainty cannot become an allow for potentially destructive input.
+4. A remembered allow cannot outrank changed security identity or controlling rule semantics.
+5. External configuration cannot claim stronger source authority than its validated origin.
+6. Additional evidence or stronger policy can preserve or increase, never decrease, the controlling requirement.
+
+## Rollout and operational gates
+
+- Record benign/destructive latency and false-positive baselines before enforcement migration.
+- Freeze schemas, parser confidence semantics, memory identity, redaction invariants, and the precedence truth table before replacing legacy classification paths.
+- Require behavioral parity for existing action/risk classes and remembered-policy flows before expanding coverage.
+- Release required rules only after bypass, overlap, safe-variant, and false-positive corpora pass.
+- Default ambiguous new domains to monitor or review until coverage and performance evidence justify enforcement.
+- Admit external declarative definitions only after integrity, rollback, scope, corpus, and resource-limit tests pass.
+- Stop rollout on policy weakening, cross-workspace leakage, secret persistence, matcher budget failure, or benign hook p95 regression above the approved threshold.
+
+## Security acceptance tests
+
+- Dialect-confusion cases and independent POSIX, PowerShell, cmd, argv, and embedded-script fixtures.
+- Suffix, separator, wrapper, alias, executable-resolution, cwd, symlink, `PATH`, pipeline, substitution, redirect, heredoc, and source-workspace bypass cases.
+- Search/print/test-runner quoted examples paired with executable destructive forms.
+- Required-rule versus safe-variant and cross-extension overlap across the full monotonic truth table.
+- Duplicate/shadowed IDs, invalid source claims, dependency cycles, unknown schemas, version rollback, bad signatures, stale definitions, and wrong-scope managed content.
+- Byte, token, segment, nesting, payload, matcher-count, regex, and wall-time exhaustion with typed uncertainty and no silent allow.
+- Composite evidence retains all matches while creating exactly one decision, approval, and receipt.
+- Memory replay attempts with changed suffix, wrapper, cwd, environment, source, confidence, or rule version require reapproval.
+- Full, partial, and no-redaction tests prove default storage, logs, errors, dashboard output, and sync records contain no unauthorized secret-bearing material.
+- Inspection and simulation tests prove deterministic output and zero execution, persistence, network, queue, event, lease, or approval side effects.
+- Compatibility, harness contract, benchmark, pathological-input, packaged-install, and representative end-to-end tests pass before release.

{plugin_scanner-2.0.1075 → plugin_scanner-2.0.1076}/pyproject.toml

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

{plugin_scanner-2.0.1075 → plugin_scanner-2.0.1076}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.1075"
+version = "2.0.1076"
 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.1075 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/cli/render.py

@@ -483,6 +483,7 @@ def _render_command_inspection(console: Console, payload: dict[str, object]) ->
     status = str(payload.get("status") or "invalid")
     classification = _coerce_object_dict(payload.get("classification"))
     extensions = _coerce_dict_list(payload.get("extensions"))
+    rules = _coerce_dict_list(payload.get("rules"))
     risk_classes = _coerce_string_list(payload.get("risk_classes"))
     border_style = "yellow" if status == "review" else "cyan"
     summary = Table.grid(padding=(0, 1))
@@ -491,6 +492,8 @@ def _render_command_inspection(console: Console, payload: dict[str, object]) ->
     summary.add_row("Action class", Text(str(action_class or "No sensitive action matched")))
     if extensions:
         summary.add_row("Extension", Text(str(extensions[0].get("extension_id") or "unknown"), style="cyan"))
+    if rules:
+        summary.add_row("Rule", Text(str(rules[0].get("rule_id") or "unknown"), style="cyan"))
     if risk_classes:
         summary.add_row("Risk classes", Text(", ".join(risk_classes)))
     summary.add_row("Policy", Text("Not evaluated; this inspection creates no approvals or receipts", style="dim"))
@@ -524,12 +527,14 @@ def _render_command_extensions(console: Console, payload: dict[str, object]) ->
     table.add_column("Extension", style="bold cyan", no_wrap=True)
     table.add_column("Version", no_wrap=True)
     table.add_column("Coverage")
+    table.add_column("Rules")
     table.add_column("Purpose")
     for extension in extensions:
         table.add_row(
             str(extension.get("extension_id") or ""),
             str(extension.get("version") or ""),
             str(len(_coerce_string_list(extension.get("action_classes")))),
+            str(extension.get("rule_count") or 0),
             str(extension.get("description") or ""),
         )
     console.print(table)
@@ -538,6 +543,7 @@ def _render_command_extensions(console: Console, payload: dict[str, object]) ->
 def _plain_text_command_inspection(payload: PayloadDict) -> str:
     classification = _coerce_object_dict(payload.get("classification"))
     extensions = _coerce_dict_list(payload.get("extensions"))
+    rules = _coerce_dict_list(payload.get("rules"))
     lines = [
         f"HOL Guard command inspection: {str(payload.get('status') or 'invalid').upper()}",
         f"Command: {payload.get('command') or ''}",
@@ -547,6 +553,8 @@ def _plain_text_command_inspection(payload: PayloadDict) -> str:
     ]
     if extensions:
         lines.insert(3, f"Extension: {extensions[0].get('extension_id') or 'unknown'}")
+    if rules:
+        lines.insert(4, f"Rule: {rules[0].get('rule_id') or 'unknown'}")
     return "\n".join(lines)
 
 

plugin_scanner-2.0.1076/src/codex_plugin_scanner/guard/runtime/command_builtin_rules.py

@@ -0,0 +1,134 @@
+"""Built-in compatibility rules for existing Guard command action classes."""
+
+from __future__ import annotations
+
+from .command_rules import CommandSafetyRule
+
+COMMAND_ACTION_RISK_CLASSES: dict[str, tuple[str, ...]] = {
+    "credential exfiltration shell command": (
+        "data_flow_exfiltration",
+        "credential_exfiltration",
+        "network_egress",
+    ),
+    "guard-managed config write": ("destructive_shell",),
+    "docker-sensitive command": ("network_egress", "destructive_shell"),
+    "docker client config access": ("local_secret_read",),
+    "encoded or encrypted shell command": ("encoded_execution",),
+    "kubernetes secret read command": ("local_secret_read",),
+    "shell file upload command": ("credential_exfiltration", "network_egress"),
+    "sensitive local file write": ("destructive_shell", "local_secret_read"),
+    "destructive shell command": ("destructive_shell",),
+    "guard approval self-authorization command": ("policy_bypass",),
+    "github pr body shell substitution": ("execution",),
+}
+
+
+def _compatibility_rule(
+    *,
+    rule_id: str,
+    title: str,
+    description: str,
+    action_class: str,
+    safer_alternative: str,
+) -> CommandSafetyRule:
+    return CommandSafetyRule(
+        rule_id=rule_id,
+        title=title,
+        description=description,
+        severity="high",
+        risk_classes=COMMAND_ACTION_RISK_CLASSES[action_class.lower()],
+        action_classes=(action_class,),
+        safer_alternatives=(safer_alternative,),
+    )
+
+
+BUILT_IN_COMMAND_RULES = (
+    _compatibility_rule(
+        rule_id="command.container-runtime.docker-sensitive",
+        title="Sensitive container operation",
+        description="Identifies container operations that can expose credentials or mutate protected state.",
+        action_class="docker-sensitive command",
+        safer_alternative="Use a pinned image, minimal privileges, and a preview where the command supports one.",
+    ),
+    _compatibility_rule(
+        rule_id="command.container-runtime.docker-config-access",
+        title="Container credential access",
+        description="Identifies reads of local container client authentication configuration.",
+        action_class="Docker client config access",
+        safer_alternative="Pass only the specific credential material required by the operation.",
+    ),
+    _compatibility_rule(
+        rule_id="command.data-protection.credential-exfiltration",
+        title="Credential data transfer",
+        description="Identifies shell flows that can send credential material to a network destination.",
+        action_class="credential exfiltration shell command",
+        safer_alternative="Send an explicit non-secret value and review the exact destination and payload.",
+    ),
+    _compatibility_rule(
+        rule_id="command.data-protection.file-upload",
+        title="Local file upload",
+        description="Identifies shell upload flows that read local files or standard input.",
+        action_class="shell file upload command",
+        safer_alternative="Upload a reviewed non-secret artifact through an allowlisted destination.",
+    ),
+    _compatibility_rule(
+        rule_id="command.encoded-execution.decode-and-execute",
+        title="Encoded execution",
+        description="Identifies decode or decrypt chains that immediately execute their output.",
+        action_class="encoded or encrypted shell command",
+        safer_alternative="Decode to a file, inspect the result, then invoke the reviewed file directly.",
+    ),
+    _compatibility_rule(
+        rule_id="command.guard-self-protection.self-authorization",
+        title="Guard self-authorization",
+        description="Identifies commands that attempt to approve or weaken their own Guard decision.",
+        action_class="Guard approval self-authorization command",
+        safer_alternative="Approve the request through Guard's authenticated approval surface.",
+    ),
+    _compatibility_rule(
+        rule_id="command.kubernetes-secrets.secret-read",
+        title="Cluster secret read",
+        description="Identifies cluster CLI operations that can reveal Secret payloads.",
+        action_class="Kubernetes secret read command",
+        safer_alternative="Request non-secret metadata or only the specific field required.",
+    ),
+    _compatibility_rule(
+        rule_id="command.shell-mutations.destructive-shell",
+        title="Destructive shell mutation",
+        description="Identifies destructive shell, filesystem, and version-control mutations.",
+        action_class="destructive shell command",
+        safer_alternative="Use a dry run or narrow preview before applying the mutation.",
+    ),
+    _compatibility_rule(
+        rule_id="command.shell-mutations.managed-config-write",
+        title="Guard-managed configuration write",
+        description="Identifies direct writes to configuration managed by Guard.",
+        action_class="guard-managed config write",
+        safer_alternative="Use Guard's setup or repair command to update managed configuration.",
+    ),
+    _compatibility_rule(
+        rule_id="command.shell-mutations.sensitive-file-write",
+        title="Sensitive local file write",
+        description="Identifies writes that can replace or expose sensitive local state.",
+        action_class="sensitive local file write",
+        safer_alternative="Write to a scoped temporary path and review the final destination.",
+    ),
+    _compatibility_rule(
+        rule_id="command.shell-mutations.github-body-substitution",
+        title="Command substitution in remote body",
+        description="Identifies shell substitution used to construct a remote request body.",
+        action_class="GitHub PR body shell substitution",
+        safer_alternative="Use a literal body file whose contents can be reviewed before submission.",
+    ),
+)
+
+_RULES_BY_EXTENSION: dict[str, tuple[CommandSafetyRule, ...]] = {}
+for _rule_definition in BUILT_IN_COMMAND_RULES:
+    _extension_id, _separator, _rule_name = _rule_definition.rule_id.rpartition(".")
+    _RULES_BY_EXTENSION[_extension_id] = (*_RULES_BY_EXTENSION.get(_extension_id, ()), _rule_definition)
+
+
+def rules_for_extension(extension_id: str) -> tuple[CommandSafetyRule, ...]:
+    """Return deterministic built-in rules owned by one extension."""
+
+    return _RULES_BY_EXTENSION.get(extension_id, ())

{plugin_scanner-2.0.1075 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/runtime/command_extensions.py

@@ -6,32 +6,17 @@ import re
 from dataclasses import dataclass
 from typing import final
 
-COMMAND_EXTENSION_SCHEMA_VERSION = 1
-_VERSION_PATTERN = re.compile(r"^[1-9][0-9]*\.[0-9]+\.[0-9]+$")
+from .command_builtin_rules import COMMAND_ACTION_RISK_CLASSES, rules_for_extension
+from .command_rules import CommandSafetyRule
 
-_ACTION_RISK_CLASSES: dict[str, tuple[str, ...]] = {
-    "credential exfiltration shell command": (
-        "data_flow_exfiltration",
-        "credential_exfiltration",
-        "network_egress",
-    ),
-    "guard-managed config write": ("destructive_shell",),
-    "docker-sensitive command": ("network_egress", "destructive_shell"),
-    "docker client config access": ("local_secret_read",),
-    "encoded or encrypted shell command": ("encoded_execution",),
-    "kubernetes secret read command": ("local_secret_read",),
-    "shell file upload command": ("credential_exfiltration", "network_egress"),
-    "sensitive local file write": ("destructive_shell", "local_secret_read"),
-    "destructive shell command": ("destructive_shell",),
-    "guard approval self-authorization command": ("policy_bypass",),
-    "github pr body shell substitution": ("execution",),
-}
+COMMAND_EXTENSION_SCHEMA_VERSION = 2
+_VERSION_PATTERN = re.compile(r"^[1-9][0-9]*\.[0-9]+\.[0-9]+$")
 
 
 def risk_classes_for_command_action(action_class: str) -> tuple[str, ...]:
     """Return the existing runtime risk classes for a command action class."""
 
-    return _ACTION_RISK_CLASSES.get(action_class.strip().lower(), ())
+    return COMMAND_ACTION_RISK_CLASSES.get(action_class.strip().lower(), ())
 
 
 @dataclass(frozen=True, slots=True)
@@ -45,6 +30,7 @@ class CommandSafetyExtension:
     action_classes: tuple[str, ...]
     risk_classes: tuple[str, ...]
     safer_alternatives: tuple[str, ...]
+    rules: tuple[CommandSafetyRule, ...] = ()
 
     def to_dict(self) -> dict[str, object]:
         return {
@@ -58,6 +44,8 @@ class CommandSafetyExtension:
             "action_classes": list(self.action_classes),
             "risk_classes": list(self.risk_classes),
             "safer_alternatives": list(self.safer_alternatives),
+            "rule_count": len(self.rules),
+            "rules": [rule.to_dict() for rule in self.rules],
         }
 
 
@@ -69,6 +57,8 @@ class CommandSafetyExtensionRegistry:
         ordered = tuple(sorted(extensions, key=lambda extension: extension.extension_id))
         by_id: dict[str, CommandSafetyExtension] = {}
         by_action_class: dict[str, CommandSafetyExtension] = {}
+        by_action_rule: dict[str, CommandSafetyRule] = {}
+        by_rule_id: dict[str, CommandSafetyRule] = {}
         for extension in ordered:
             _validate_extension(extension)
             if extension.extension_id in by_id:
@@ -93,9 +83,45 @@ class CommandSafetyExtensionRegistry:
                         )
                     )
                     raise ValueError(message)
+            for rule in extension.rules:
+                if not rule.rule_id.startswith(f"{extension.extension_id}."):
+                    raise ValueError(
+                        f"Command safety rule {rule.rule_id} must use extension prefix {extension.extension_id}"
+                    )
+                if rule.rule_id in by_rule_id:
+                    raise ValueError(f"Duplicate command safety rule ID: {rule.rule_id}")
+                undeclared_rule_risks = set(rule.risk_classes).difference(extension.risk_classes)
+                if undeclared_rule_risks:
+                    undeclared = ", ".join(sorted(undeclared_rule_risks))
+                    raise ValueError(
+                        f"Command safety rule {rule.rule_id} declares risks outside its extension: {undeclared}"
+                    )
+                by_rule_id[rule.rule_id] = rule
+                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}:
+                        raise ValueError(
+                            f"Command safety rule {rule.rule_id} owns undeclared action class {action_class!r}"
+                        )
+                    existing_rule = by_action_rule.get(normalized_action_class)
+                    if existing_rule is not None:
+                        ownership = " and ".join((existing_rule.rule_id, rule.rule_id))
+                        raise ValueError(f"Command action class {action_class!r} is owned by rules {ownership}")
+                    by_action_rule[normalized_action_class] = rule
+            if extension.rules:
+                rule_actions = {
+                    action_class.strip().lower() for rule in extension.rules for action_class in rule.action_classes
+                }
+                extension_actions = {action_class.strip().lower() for action_class in extension.action_classes}
+                if rule_actions != extension_actions:
+                    raise ValueError(
+                        f"Command safety extension {extension.extension_id} rules must own every action class"
+                    )
         self._extensions = ordered
         self._by_id = by_id
         self._by_action_class = by_action_class
+        self._by_action_rule = by_action_rule
+        self._by_rule_id = by_rule_id
 
     @property
     def extensions(self) -> tuple[CommandSafetyExtension, ...]:
@@ -107,6 +133,12 @@ class CommandSafetyExtensionRegistry:
     def for_action_class(self, action_class: str) -> CommandSafetyExtension | None:
         return self._by_action_class.get(action_class.strip().lower())
 
+    def get_rule(self, rule_id: str) -> CommandSafetyRule | None:
+        return self._by_rule_id.get(rule_id.strip().lower())
+
+    def rule_for_action_class(self, action_class: str) -> CommandSafetyRule | None:
+        return self._by_action_rule.get(action_class.strip().lower())
+
 
 def _validate_extension(extension: CommandSafetyExtension) -> None:
     if not extension.extension_id.startswith("command."):
@@ -141,6 +173,7 @@ _BUILT_IN_EXTENSIONS = (
             "Use a pinned image and a read-only container filesystem where possible.",
             "Pass only the specific secret or file required by the container.",
         ),
+        rules=rules_for_extension("command.container-runtime"),
     ),
     CommandSafetyExtension(
         extension_id="command.data-protection",
@@ -153,6 +186,7 @@ _BUILT_IN_EXTENSIONS = (
             "Send an explicit non-secret value instead of piping local files or environment output.",
             "Use a destination allowlist and review the exact payload before transmission.",
         ),
+        rules=rules_for_extension("command.data-protection"),
     ),
     CommandSafetyExtension(
         extension_id="command.encoded-execution",
@@ -164,6 +198,7 @@ _BUILT_IN_EXTENSIONS = (
         action_classes=("encoded or encrypted shell command",),
         risk_classes=("encoded_execution",),
         safer_alternatives=("Decode the payload to a file, inspect it, then invoke the reviewed file directly.",),
+        rules=rules_for_extension("command.encoded-execution"),
     ),
     CommandSafetyExtension(
         extension_id="command.guard-self-protection",
@@ -173,6 +208,7 @@ _BUILT_IN_EXTENSIONS = (
         action_classes=("Guard approval self-authorization command",),
         risk_classes=("policy_bypass",),
         safer_alternatives=("Approve the pending request through Guard's authenticated approval surface.",),
+        rules=rules_for_extension("command.guard-self-protection"),
     ),
     CommandSafetyExtension(
         extension_id="command.kubernetes-secrets",
@@ -182,6 +218,7 @@ _BUILT_IN_EXTENSIONS = (
         action_classes=("Kubernetes secret read command",),
         risk_classes=("local_secret_read",),
         safer_alternatives=("Request only the required non-secret field or metadata instead of the Secret payload.",),
+        rules=rules_for_extension("command.kubernetes-secrets"),
     ),
     CommandSafetyExtension(
         extension_id="command.shell-mutations",
@@ -200,6 +237,7 @@ _BUILT_IN_EXTENSIONS = (
             "Narrow the target path or Git ref and avoid recursive or forced mutation.",
             "Use a literal body file instead of shell substitution in command arguments.",
         ),
+        rules=rules_for_extension("command.shell-mutations"),
     ),
 )