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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1074
+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
@@ -166,6 +166,9 @@ pipx run hol-guard supply-chain sync
 pipx run hol-guard supply-chain scan
 pipx run hol-guard supply-chain explain minimist@1.2.5 --ecosystem npm
 pipx run hol-guard explain install-connect
+pipx run hol-guard command test 'git reset --hard HEAD~1'
+pipx run hol-guard command explain 'grep "rm -rf|git clean" README.md'
+pipx run hol-guard command extensions
 ```
 
 What you get from Guard:
@@ -179,6 +182,26 @@ What you get from Guard:
 
 See [docs/guard/get-started.md](docs/guard/get-started.md) for the full local flow.
 
+### Inspect command protection without running it
+
+Command safety extensions make Guard's existing shell, Git, filesystem, data-protection, container, Kubernetes,
+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.
+
+```bash
+hol-guard command test 'rm -rf ./build'
+hol-guard command explain 'grep "rm -rf|git clean" README.md'
+hol-guard command extensions command.shell-mutations --json
+```
+
 <details>
 <summary>Guard commands at a glance</summary>
 

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

@@ -118,6 +118,9 @@ pipx run hol-guard supply-chain sync
 pipx run hol-guard supply-chain scan
 pipx run hol-guard supply-chain explain minimist@1.2.5 --ecosystem npm
 pipx run hol-guard explain install-connect
+pipx run hol-guard command test 'git reset --hard HEAD~1'
+pipx run hol-guard command explain 'grep "rm -rf|git clean" README.md'
+pipx run hol-guard command extensions
 ```
 
 What you get from Guard:
@@ -131,6 +134,26 @@ What you get from Guard:
 
 See [docs/guard/get-started.md](docs/guard/get-started.md) for the full local flow.
 
+### Inspect command protection without running it
+
+Command safety extensions make Guard's existing shell, Git, filesystem, data-protection, container, Kubernetes,
+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.
+
+```bash
+hol-guard command test 'rm -rf ./build'
+hol-guard command explain 'grep "rm -rf|git clean" README.md'
+hol-guard command extensions command.shell-mutations --json
+```
+
 <details>
 <summary>Guard commands at a glance</summary>
 

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.1074 → plugin_scanner-2.0.1076}/docs/guard/get-started.md

@@ -128,6 +128,8 @@ For security reviews, sales conversations, and GRC packets, see the
 | I need to remove Guard from this machine | `hol-guard uninstall --self` | Can Guard disconnect its managed harnesses, remove package shims and local state, then uninstall itself cleanly? |
 | I need install/connect docs | `hol-guard explain install-connect` | Which local-first setup and optional cloud commands should I share? |
 | I need to preview one install before I run it | `hol-guard protect npm install <package> --dry-run` | Would Guard allow, warn, review, or block this exact install request right now? |
+| I need to understand command protection | `hol-guard command test '<command>'` or `hol-guard command explain '<command>'` | Which built-in command safety extension recognizes this command, and why, without executing it or creating Guard state? |
+| I need the command protection catalog | `hol-guard command extensions` | Which built-in command safety extensions and action classes are available in this Guard version? |
 | I need setup or runtime troubleshooting | `hol-guard doctor <harness>` | Why is this harness or Guard runtime not behaving correctly? |
 | A launch was blocked or changed | `hol-guard diff <harness>` | What changed since the last recorded snapshot? |
 | I need to resolve a queued block | `hol-guard approvals` | Which requests are waiting, and how do I approve or deny them? |

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

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

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

@@ -248,6 +248,7 @@ def _resolve_legacy_args(
         "preflight",
         "diff",
         "test-eval",
+        "command",
         "receipts",
         "history",
         "inventory",

{plugin_scanner-2.0.1074 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/cli/commands_dispatch_local.py

@@ -21,6 +21,31 @@ if TYPE_CHECKING:
 from ._commands_shared import *
 from .commands_parser_helpers import *
 
+def _run_guard_command_inspection_command(
+    args: argparse.Namespace,
+    *,
+    input_text: str | None = None,
+    output_stream: TextIO | None = None,
+) -> int:
+    from ..runtime.command_inspection import command_extensions_payload, inspect_command
+
+    command_command = str(getattr(args, "command_command", ""))
+    try:
+        if command_command == "extensions":
+            payload = command_extensions_payload(getattr(args, "extension_id", None))
+            _emit("command-extensions", payload, bool(getattr(args, "json", False)))
+            return 0
+        if command_command not in {"test", "explain"}:
+            print("Choose command test, command explain, or command extensions.", file=sys.stderr)
+            return 2
+        payload = inspect_command(str(getattr(args, "command_text", "")), cwd=Path.cwd(), home_dir=Path.home())
+    except ValueError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 2
+    payload["mode"] = command_command
+    _emit("command-inspection", payload, bool(getattr(args, "json", False)))
+    return 0
+
 def _run_guard_scan_command(
     args: argparse.Namespace,
     *,
@@ -392,6 +417,7 @@ def _run_guard_mcp_command(
 __all__ = [
     "_run_guard_apps_command",
     "_run_guard_bootstrap_command",
+    "_run_guard_command_inspection_command",
     "_run_guard_dashboard_command",
     "_run_guard_detect_command",
     "_run_guard_init_command",

{plugin_scanner-2.0.1074 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/cli/commands_parser.py

@@ -51,7 +51,7 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
         parser_class=FriendlyArgumentParser,
         metavar=(
             "{start,status,dashboard,init,apps,bootstrap,detect,install,update,uninstall,package-shims,run,protect,preflight,scan,diff,"
-            "test-eval,"
+            "test-eval,command,"
             "receipts,inventory,abom,aibom,approvals,explain,allow,deny,policies,trust,exceptions,advisories,events,doctor,connect,"
             "remote-pair,disconnect,"
             "login,sync,device,commands,bridge,mcp}"

{plugin_scanner-2.0.1074 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/cli/commands_parser_local.py

@@ -168,6 +168,28 @@ def _configure_guard_local_parsers(
     protect_parser.add_argument("--package-shim-ui", action="store_true", help=argparse.SUPPRESS)
     protect_parser.add_argument("protect_command", nargs=argparse.REMAINDER)
 
+    command_parser = guard_subparsers.add_parser(
+        "command",
+        help="Inspect commands and built-in command safety extensions without executing anything",
+    )
+    command_subparsers = command_parser.add_subparsers(dest="command_command", required=True, metavar="COMMAND")
+    for command_name in ("test", "explain"):
+        inspect_parser = command_subparsers.add_parser(
+            command_name,
+            help=f"{command_name.title()} how Guard classifies one shell command",
+        )
+        inspect_parser.add_argument(
+            "command_text",
+            help="Exact shell command to inspect; quote to preserve shell syntax",
+        )
+        inspect_parser.add_argument("--json", action="store_true")
+    extensions_parser = command_subparsers.add_parser(
+        "extensions",
+        help="List or inspect built-in command safety extensions",
+    )
+    extensions_parser.add_argument("extension_id", nargs="?")
+    extensions_parser.add_argument("--json", action="store_true")
+
     preflight_parser = guard_subparsers.add_parser(
         "preflight",
         help="Scan an artifact before you add it to a harness config or install path",

{plugin_scanner-2.0.1074 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/cli/commands_router.py

@@ -16,6 +16,7 @@ from ._commands_shared import *
 from .commands_parser_helpers import *
 
 _EARLY_HANDLERS = {
+    "command": "_run_guard_command_inspection_command",
     "scan": "_run_guard_scan_command",
     "preflight": "_run_guard_preflight_command",
     "mcp": "_run_guard_mcp_command",

{plugin_scanner-2.0.1074 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/cli/commands_support_runtime_policy.py

@@ -14,6 +14,7 @@ if TYPE_CHECKING:
     from .commands_support_prompts import _prompt_request_classes, _prompt_requires_hard_block
 
 
+from ..runtime.command_extensions import risk_classes_for_command_action
 from ..store import _runtime_scoped_exact_match_key, runtime_tool_action_exact_match_context
 from ..text import ensure_terminal_punctuation as _ensure_terminal_punctuation
 from ._commands_shared import *
@@ -434,22 +435,7 @@ def _runtime_artifact_risk_classes(artifact: GuardArtifact) -> list[str]:
     action_class = artifact.metadata.get("action_class")
     if not isinstance(action_class, str):
         return []
-    action_risk_classes = {
-        "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"],
-    }
-    return action_risk_classes.get(action_class.strip().lower(), [])
+    return list(risk_classes_for_command_action(action_class))
 
 def _guard_settings_payload(config: GuardConfig) -> dict[str, object]:
     return {

{plugin_scanner-2.0.1074 → plugin_scanner-2.0.1076}/src/codex_plugin_scanner/guard/cli/render.py

@@ -479,6 +479,92 @@ def _render_init(console: Console, payload: dict[str, object]) -> None:
     console.print(_build_steps_panel(_coerce_dict_list(payload.get("next_steps"))))
 
 
+def _render_command_inspection(console: Console, payload: dict[str, object]) -> None:
+    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))
+    summary.add_row("Result", Text(status.upper(), style=f"bold {border_style}"))
+    action_class = classification.get("action_class")
+    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"))
+    console.print(Panel(summary, title="HOL Guard command inspection", border_style=border_style))
+    console.print(Panel(Syntax(str(payload.get("command") or ""), "bash", word_wrap=True), title="Command"))
+    reason = classification.get("reason")
+    if isinstance(reason, str) and reason:
+        console.print(Panel(Text(reason), title="Why", border_style=border_style))
+    if extensions:
+        alternatives = _coerce_string_list(extensions[0].get("safer_alternatives"))
+        if alternatives:
+            console.print(Panel("\n".join(f"• {item}" for item in alternatives), title="Safer approaches"))
+    if str(payload.get("mode") or "") == "explain":
+        trace = _coerce_dict_list(payload.get("trace"))
+        trace_table = Table(title="Evaluation trace", box=box.SIMPLE_HEAD, show_lines=False)
+        trace_table.add_column("Step", style="bold")
+        trace_table.add_column("Result")
+        trace_table.add_column("Detail")
+        for item in trace:
+            trace_table.add_row(
+                str(item.get("step") or ""),
+                str(item.get("result") or ""),
+                str(item.get("detail") or ""),
+            )
+        console.print(trace_table)
+
+
+def _render_command_extensions(console: Console, payload: dict[str, object]) -> None:
+    extensions = _coerce_dict_list(payload.get("extensions"))
+    table = Table(title="Built-in command safety extensions", box=box.SIMPLE_HEAD, show_lines=False)
+    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)
+
+
+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 ''}",
+        f"Action class: {classification.get('action_class') or 'No sensitive action matched'}",
+        f"Reason: {classification.get('reason') or ''}",
+        "Policy: Not evaluated; this inspection creates no approvals or receipts.",
+    ]
+    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)
+
+
+def _plain_text_command_extensions(payload: PayloadDict) -> str:
+    extensions = _coerce_dict_list(payload.get("extensions"))
+    lines = [f"Built-in command safety extensions ({len(extensions)})"]
+    lines.extend(f"{item.get('extension_id')} {item.get('version')} - {item.get('description')}" for item in extensions)
+    return "\n".join(lines)
+
+
 def _init_plan_panel(plan: list[dict[str, object]], status: str) -> Panel:
     table = Table.grid(padding=(0, 1))
     for step in plan:
@@ -2684,11 +2770,15 @@ def _clean_terminal_output(value: str) -> str:
 
 
 _PLAIN_TEXT_RENDERERS: dict[str, PlainTextRenderer] = {
+    "command-extensions": _plain_text_command_extensions,
+    "command-inspection": _plain_text_command_inspection,
     "protect": _plain_text_protect,
 }
 
 
 _RENDERERS: dict[str, Renderer] = {
+    "command-extensions": _render_command_extensions,
+    "command-inspection": _render_command_inspection,
     "approvals": _render_approvals,
     "init": _render_init,
     "start": _render_start,