plugin-scanner 2.0.108__tar.gz → 2.0.110__tar.gz

{plugin_scanner-2.0.108 → plugin_scanner-2.0.110}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.108
+Version: 2.0.110
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner
@@ -302,33 +302,44 @@ The scanner evaluates only the surfaces a plugin actually exposes, then normaliz
 
 ```bash
 # Scan a plugin directory
-plugin-scanner ./my-plugin
+plugin-scanner scan ./my-plugin
 
 # Auto-detect all supported ecosystems inside a repo (default)
-plugin-scanner ./plugins-repo --ecosystem auto
+plugin-scanner scan ./plugins-repo --ecosystem auto
 
 # Scan only Claude package surfaces
-plugin-scanner ./plugins-repo --ecosystem claude
+plugin-scanner scan ./plugins-repo --ecosystem claude
 
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 
 # Output JSON
-plugin-scanner ./my-plugin --json
+plugin-scanner scan ./my-plugin --format json
 
 # Write a SARIF report for GitHub code scanning
-plugin-scanner ./my-plugin --format sarif --output plugin-scanner.sarif
+plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif
 
 # Fail CI on findings at or above high severity
-plugin-scanner ./my-plugin --fail-on-severity high
+plugin-scanner scan ./my-plugin --fail-on-severity high
 
 # Require Cisco skill scanning with a strict policy
-plugin-scanner ./my-plugin --cisco-skill-scan on --cisco-policy strict
+plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict
 
 # Require optional Cisco MCP static analysis
-plugin-scanner ./my-plugin --cisco-mcp-scan on
+plugin-scanner scan ./my-plugin --cisco-mcp-scan on
 ```
 
+Use the bare `plugin-scanner ./my-plugin` form only for compatibility with older automation. New scripts and docs should
+prefer explicit subcommands so `scan`, `lint`, `verify`, `submit`, and `doctor` have predictable help, flags, and output.
+
+| Need | Command | Output contract |
+| :--- | :--- | :--- |
+| Human release summary | `plugin-scanner scan ./my-plugin` | terminal summary first, optional JSON/Markdown/SARIF with `--format` |
+| Rule-level authoring feedback | `plugin-scanner lint ./my-plugin` | human findings by default, JSON with `--format json` |
+| Runtime readiness details | `plugin-scanner verify ./my-plugin` | human pass/fail by default, JSON with `--format json` |
+| Publishable quality artifact | `plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json` | writes one artifact for one plugin directory |
+| Troubleshooting bundle | `plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip` | diagnostic JSON and bundle artifacts |
+
 ## Quality Suite Commands
 
 ```bash

{plugin_scanner-2.0.108 → plugin_scanner-2.0.110}/README.md

@@ -262,33 +262,44 @@ The scanner evaluates only the surfaces a plugin actually exposes, then normaliz
 
 ```bash
 # Scan a plugin directory
-plugin-scanner ./my-plugin
+plugin-scanner scan ./my-plugin
 
 # Auto-detect all supported ecosystems inside a repo (default)
-plugin-scanner ./plugins-repo --ecosystem auto
+plugin-scanner scan ./plugins-repo --ecosystem auto
 
 # Scan only Claude package surfaces
-plugin-scanner ./plugins-repo --ecosystem claude
+plugin-scanner scan ./plugins-repo --ecosystem claude
 
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 
 # Output JSON
-plugin-scanner ./my-plugin --json
+plugin-scanner scan ./my-plugin --format json
 
 # Write a SARIF report for GitHub code scanning
-plugin-scanner ./my-plugin --format sarif --output plugin-scanner.sarif
+plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif
 
 # Fail CI on findings at or above high severity
-plugin-scanner ./my-plugin --fail-on-severity high
+plugin-scanner scan ./my-plugin --fail-on-severity high
 
 # Require Cisco skill scanning with a strict policy
-plugin-scanner ./my-plugin --cisco-skill-scan on --cisco-policy strict
+plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict
 
 # Require optional Cisco MCP static analysis
-plugin-scanner ./my-plugin --cisco-mcp-scan on
+plugin-scanner scan ./my-plugin --cisco-mcp-scan on
 ```
 
+Use the bare `plugin-scanner ./my-plugin` form only for compatibility with older automation. New scripts and docs should
+prefer explicit subcommands so `scan`, `lint`, `verify`, `submit`, and `doctor` have predictable help, flags, and output.
+
+| Need | Command | Output contract |
+| :--- | :--- | :--- |
+| Human release summary | `plugin-scanner scan ./my-plugin` | terminal summary first, optional JSON/Markdown/SARIF with `--format` |
+| Rule-level authoring feedback | `plugin-scanner lint ./my-plugin` | human findings by default, JSON with `--format json` |
+| Runtime readiness details | `plugin-scanner verify ./my-plugin` | human pass/fail by default, JSON with `--format json` |
+| Publishable quality artifact | `plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json` | writes one artifact for one plugin directory |
+| Troubleshooting bundle | `plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip` | diagnostic JSON and bundle artifacts |
+
 ## Quality Suite Commands
 
 ```bash

{plugin_scanner-2.0.108 → plugin_scanner-2.0.110}/docs/guard/get-started.md

@@ -76,6 +76,30 @@ Use it when you want to protect a harness before local MCP servers, skills, hook
    hol-guard device rotate
    ```
 
+## Which command should I use?
+
+| Situation | Command | What it answers |
+| :--- | :--- | :--- |
+| I need the current protection posture | `hol-guard status` | What is Guard watching, is sync connected, and what is the next action? |
+| 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? |
+| I need decision history | `hol-guard receipts` | What decisions did Guard record locally? |
+| I need the tracked catalog | `hol-guard inventory` | Which artifacts are currently tracked and present? |
+| I need an exportable evidence artifact | `hol-guard abom` | What local AI-BOM can I attach to an audit or handoff? |
+| I need the chronological log | `hol-guard events` | What happened over time on this machine? |
+
+## Troubleshooting
+
+| Symptom | Start here | Then try |
+| :--- | :--- | :--- |
+| Guard did not find my harness | `hol-guard detect --json` | `hol-guard doctor <harness> --json` for adapter-specific warnings |
+| `hol-guard run` paused a launch | `hol-guard diff <harness>` | `hol-guard approvals`, then retry `hol-guard run <harness>` |
+| I approved a prompt and want proof | `hol-guard receipts` | `hol-guard explain <artifact-id>` for the latest receipt and diff context |
+| I need audit or handoff evidence | `hol-guard inventory` | `hol-guard abom --format json` for machine-readable export |
+| I need to understand recent activity | `hol-guard events` | Use `--name <event>` to filter a noisy local timeline |
+| Cloud sync or pairing looks wrong | `hol-guard status` | `hol-guard connect` or `hol-guard sync --json` depending on the status output |
+
 ## Evidence-first decisions
 
 Guard now scores local decisions from structured evidence, not only string heuristics. Each changed artifact carries:

{plugin_scanner-2.0.108 → plugin_scanner-2.0.110}/docs/guard/testing-matrix.md

@@ -10,6 +10,8 @@ Automated coverage in this phase includes:
 - consumer-mode JSON contract generation against scanner fixtures
 - local HTTP sync against a live in-process server instead of mocked transport
 - scheduled self-hosted harness smoke through `.github/workflows/harness-smoke.yml`
+- CLI DX contract tests for summary-first `run`, `explain`, `doctor`, `scan`, `lint`, and `verify` output
+- scanner command consistency tests for nonexistent target handling across `scan`, `lint`, `verify`, `doctor`, and `submit`
 
 Manual verification should include:
 
@@ -32,6 +34,14 @@ Manual verification should include:
 - `hol-guard install codex`
 - `hol-guard run codex --dry-run --default-action allow --json`
 - `hol-guard receipts`
+- `hol-guard explain codex:project:<artifact-name>`
+- `hol-guard diff codex`
+- `hol-guard events`
+- `hol-guard abom`
+- `plugin-scanner scan tests/fixtures/good-plugin --format json`
+- `plugin-scanner lint tests/fixtures/good-plugin --format json`
+- `plugin-scanner verify tests/fixtures/good-plugin --format json`
+- `plugin-scanner doctor tests/fixtures/good-plugin --component mcp --bundle dist/doctor.zip`
 - `codex mcp list`
 - `cursor-agent mcp list`
 - `antigravity --help`

{plugin_scanner-2.0.108 → plugin_scanner-2.0.110}/pyproject.toml

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

{plugin_scanner-2.0.108 → plugin_scanner-2.0.110}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.108"
+version = "2.0.110"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.108 → plugin_scanner-2.0.110}/src/codex_plugin_scanner/guard/cli/commands.py

@@ -97,7 +97,7 @@ from ..runtime.secret_file_requests import (
     extract_sensitive_tool_action_request,
     is_explicitly_benign_tool_action_request,
 )
-from ..runtime.secret_sensitivity import SecretContentMatch, classify_secret_content
+from ..runtime.secret_sensitivity import SecretContentMatch, classify_secret_content, classify_secret_path
 from ..runtime.surface_server import GuardSurfaceRuntime
 from ..store import GuardStore
 from .approval_commands import add_approval_parser, run_approval_command
@@ -150,7 +150,15 @@ _GUARD_HELP_GROUPS = (
     "  bootstrap    Detect, install, and launch the approval center\n"
     "  install      Enable Guard management for a harness\n"
     "  uninstall    Disable Guard management for a harness\n"
-    "  update       Update hol-guard in the current environment"
+    "  update       Update hol-guard in the current environment\n"
+    "\n"
+    "Command selection:\n"
+    "  Use status for current posture and the next safe step\n"
+    "  Use doctor for setup and runtime probes\n"
+    "  Use diff for changed artifacts after a blocked launch\n"
+    "  Use explain for detailed artifact evidence\n"
+    "  Use approvals for queued decisions and receipts for audit history\n"
+    "  Use events for the local timeline"
 )
 
 
@@ -2991,16 +2999,47 @@ def _runtime_stored_policy_action(
 def _runtime_artifact_policy_action(config: GuardConfig, artifact: GuardArtifact, harness: str) -> str:
     if _prompt_requires_hard_block(artifact):
         return "block"
-    risk_actions = [
-        resolve_risk_action(config, risk_class, harness=_canonical_harness_name(harness))
-        for risk_class in _runtime_artifact_risk_classes(artifact)
-    ]
+    canonical_harness = _canonical_harness_name(harness)
+    risk_classes = _runtime_artifact_risk_classes(artifact)
+    has_configured_risk_action = any(
+        _resolve_configured_risk_action(config, risk_class, harness=canonical_harness) for risk_class in risk_classes
+    )
+    if has_configured_risk_action:
+        risk_actions = [
+            _resolve_configured_risk_action(config, risk_class, harness=canonical_harness)
+            or resolve_risk_action(config, risk_class, harness=canonical_harness)
+            for risk_class in risk_classes
+        ]
+        resolved_actions = [action for action in risk_actions if action in VALID_GUARD_ACTIONS]
+        if resolved_actions:
+            return max(resolved_actions, key=_guard_action_severity)
+    guard_default_action = _runtime_artifact_guard_default_action(artifact)
+    if guard_default_action is not None:
+        return guard_default_action
+    risk_actions = [resolve_risk_action(config, risk_class, harness=canonical_harness) for risk_class in risk_classes]
     resolved_actions = [action for action in risk_actions if action in VALID_GUARD_ACTIONS]
     if resolved_actions:
         return max(resolved_actions, key=_guard_action_severity)
     return SAFE_CHANGED_HASH_ACTION
 
 
+def _resolve_configured_risk_action(config: GuardConfig, risk_class: str, *, harness: str) -> str | None:
+    if config.harness_risk_actions is not None:
+        harness_actions = config.harness_risk_actions.get(harness)
+        if harness_actions is not None and risk_class in harness_actions:
+            return harness_actions[risk_class]
+    if config.risk_actions is not None and risk_class in config.risk_actions:
+        return config.risk_actions[risk_class]
+    return None
+
+
+def _runtime_artifact_guard_default_action(artifact: GuardArtifact) -> str | None:
+    value = artifact.metadata.get("guard_default_action")
+    if value in VALID_GUARD_ACTIONS:
+        return str(value)
+    return None
+
+
 def _guard_action_severity(action: str) -> int:
     return {
         "allow": 0,
@@ -3977,13 +4016,16 @@ def _codex_post_tool_output_artifact(
     cwd: Path | None,
 ) -> GuardArtifact | None:
     response_text = _collect_codex_tool_response_text(payload.get("tool_response"))
-    content_matches = classify_secret_content(response_text)
-    if not content_matches:
-        return None
     tool_name = _coalesce_string(payload.get("tool_name"), "Bash")
     command_text = _codex_post_tool_command_text(payload)
     if not command_text:
         command_text = tool_name
+    references_local_content = _codex_command_may_read_local_content(command_text, cwd=cwd)
+    content_matches = classify_secret_content(response_text)
+    if not content_matches and references_local_content:
+        content_matches = classify_secret_content(response_text, suppress_samples=False)
+    if not content_matches:
+        return None
     if _codex_source_inspection_can_skip_secret_output(
         command_text=command_text,
         response_text=response_text,
@@ -4001,6 +4043,10 @@ def _codex_post_tool_output_artifact(
             sort_keys=True,
         ).encode("utf-8")
     ).hexdigest()
+    runtime_default_action = "require-reapproval" if references_local_content else "warn"
+    runtime_request_signals = ["tool output contains credential-looking material"]
+    if references_local_content:
+        runtime_request_signals.append("command references a sensitive local source")
     return GuardArtifact(
         artifact_id=f"codex:{source_scope}:tool-output:{fingerprint}",
         name=f"{tool_name} credential-looking output",
@@ -4012,10 +4058,11 @@ def _codex_post_tool_output_artifact(
             "tool_name": tool_name,
             "command_text": command_text,
             "action_class": "credential exfiltration shell command",
+            "guard_default_action": runtime_default_action,
             "request_summary": (
                 f"Codex tool `{tool_name}` produced credential-looking output while running `{command_text}`."
             ),
-            "runtime_request_signals": ["tool output contains credential-looking material"],
+            "runtime_request_signals": runtime_request_signals,
             "runtime_request_summary": (
                 "Requests a sensitive native tool action: credential-looking output reached Codex."
             ),
@@ -4027,6 +4074,209 @@ def _codex_post_tool_output_artifact(
     )
 
 
+def _codex_command_references_sensitive_local_source(command_text: str, *, cwd: Path | None) -> bool:
+    if _codex_text_contains_sensitive_path_token(command_text, cwd=cwd):
+        return True
+    try:
+        parts = shlex.split(command_text)
+    except ValueError:
+        return False
+    for part in parts:
+        stripped = part.strip()
+        if not stripped or stripped.startswith("-"):
+            continue
+        if _codex_token_is_url(stripped):
+            continue
+        if classify_secret_path(stripped, cwd=cwd) is not None:
+            return True
+    return False
+
+
+def _codex_token_is_url(token: str) -> bool:
+    parsed = urllib.parse.urlparse(token)
+    return bool(parsed.scheme and parsed.netloc)
+
+
+def _codex_text_contains_sensitive_path_token(text: str, *, cwd: Path | None) -> bool:
+    for match in _PROMPT_PATH_TOKEN_PATTERN.finditer(text):
+        if _codex_path_token_is_url_path(text, match.start()):
+            continue
+        if classify_secret_path(match.group(0), cwd=cwd) is not None:
+            return True
+    return False
+
+
+def _codex_path_token_is_url_path(text: str, start: int) -> bool:
+    prefix = text[:start].lower()
+    last_separator = max(prefix.rfind(separator) for separator in " \t\r\n'\"`<>|;(){}[]")
+    token_prefix = prefix[last_separator + 1 :]
+    if "://" in token_prefix:
+        return True
+    scheme = ""
+    if token_prefix.endswith(":/"):
+        scheme = token_prefix[:-2]
+    elif token_prefix.endswith(":"):
+        scheme = token_prefix[:-1]
+    return _codex_token_prefix_is_url_scheme(scheme)
+
+
+def _codex_token_prefix_is_url_scheme(scheme: str) -> bool:
+    return bool(scheme) and scheme[0].isalpha() and all(char.isalnum() or char in "+.-" for char in scheme)
+
+
+def _codex_command_may_read_local_content(command_text: str, *, cwd: Path | None) -> bool:
+    if _codex_command_references_sensitive_local_source(command_text, cwd=cwd):
+        return True
+    if any(marker in command_text for marker in ("$(", "${", "`")):
+        return True
+    pipeline_segments = _split_codex_safe_read_only_pipeline(command_text)
+    if pipeline_segments is not None:
+        return any(
+            _codex_pipeline_segment_may_read_local_content(segment, index=index, cwd=cwd)
+            for index, segment in enumerate(pipeline_segments)
+        )
+    try:
+        parts = _codex_shell_split(command_text)
+    except ValueError:
+        return True
+    return _codex_command_parts_may_read_local_content(parts, cwd=cwd)
+
+
+def _codex_pipeline_segment_may_read_local_content(segment: str, *, index: int, cwd: Path | None) -> bool:
+    try:
+        parts = _codex_shell_split(segment)
+    except ValueError:
+        return True
+    if not parts:
+        return False
+    if index == 0:
+        return _codex_command_parts_may_read_local_content(parts, cwd=cwd)
+    return _codex_command_is_read_only_source_search(segment, cwd=cwd) or _codex_command_is_read_only_source_view(
+        segment, cwd=cwd
+    )
+
+
+def _codex_command_parts_may_read_local_content(parts: list[str], *, cwd: Path | None) -> bool:
+    for start in _codex_command_start_indexes(parts):
+        previous_token = parts[start - 1] if start > 0 else None
+        segment_parts = _codex_command_segment_parts(parts, start)
+        if previous_token == "|":
+            if _codex_command_sequence_is_read_only_source_inspection(segment_parts, cwd=cwd):
+                return True
+            continue
+        if _codex_command_sequence_starts_with_local_reader(segment_parts, cwd=cwd):
+            return True
+    return False
+
+
+def _codex_command_start_indexes(parts: list[str]) -> list[int]:
+    starts = [0] if parts else []
+    for index, part in enumerate(parts[:-1]):
+        if part in {"&&", "||", ";", "&", "|", "|&"}:
+            starts.append(index + 1)
+    return starts
+
+
+def _codex_command_segment_parts(parts: list[str], start: int) -> list[str]:
+    end = start
+    while end < len(parts) and parts[end] not in {"&&", "||", ";", "&", "|", "|&"}:
+        end += 1
+    return parts[start:end]
+
+
+def _codex_command_sequence_is_read_only_source_inspection(parts: list[str], *, cwd: Path | None) -> bool:
+    command_parts = _codex_unwrapped_command_parts(parts)
+    if not command_parts:
+        return False
+    segment = shlex.join(command_parts)
+    return _codex_command_is_read_only_source_search(segment, cwd=cwd) or _codex_command_is_read_only_source_view(
+        segment, cwd=cwd
+    )
+
+
+def _codex_command_sequence_starts_with_local_reader(parts: list[str], *, cwd: Path | None) -> bool:
+    command_parts = _codex_unwrapped_command_parts(parts)
+    if not command_parts:
+        return False
+    if _codex_command_parts_are_git_grep(command_parts):
+        return True
+    return _codex_command_part_is_local_reader(command_parts, 0, cwd=cwd)
+
+
+def _codex_command_parts_are_git_grep(parts: list[str]) -> bool:
+    return bool(parts) and Path(parts[0]).name.lower() == "git" and _git_grep_search_args(parts[1:]) is not None
+
+
+def _codex_unwrapped_command_parts(parts: list[str]) -> list[str]:
+    remaining = parts
+    while remaining:
+        executable = Path(remaining[0]).name.lower()
+        if executable == "command":
+            remaining = _codex_strip_command_wrapper(remaining[1:])
+            continue
+        if executable == "env":
+            remaining = _codex_strip_env_wrapper(remaining[1:])
+            continue
+        return remaining
+    return []
+
+
+def _codex_strip_command_wrapper(parts: list[str]) -> list[str]:
+    index = 0
+    while index < len(parts) and parts[index] in {"-p", "-v", "-V"}:
+        index += 1
+    if index < len(parts) and parts[index] == "--":
+        index += 1
+    return parts[index:]
+
+
+def _codex_strip_env_wrapper(parts: list[str]) -> list[str]:
+    index = 0
+    while index < len(parts):
+        part = parts[index]
+        if part == "--":
+            return parts[index + 1 :]
+        if part in {"-i", "-0", "--ignore-environment", "--null"}:
+            index += 1
+            continue
+        if part in {"-u", "--unset", "-C", "--chdir", "-S", "--split-string"}:
+            index += 2
+            continue
+        if part.startswith(("--unset=", "--chdir=", "--split-string=")):
+            index += 1
+            continue
+        if part.startswith("-"):
+            index += 1
+            continue
+        if "=" in part and not part.startswith("="):
+            index += 1
+            continue
+        return parts[index:]
+    return []
+
+
+def _codex_shell_split(command_text: str) -> list[str]:
+    lexer = shlex.shlex(command_text, posix=True, punctuation_chars=True)
+    lexer.whitespace_split = True
+    lexer.commenters = ""
+    return list(lexer)
+
+
+def _codex_command_part_is_local_reader(parts: list[str], index: int, *, cwd: Path | None) -> bool:
+    local_read_commands = {"cat", "grep", "head", "rg", "sed", "tail"}
+    executable = Path(parts[index]).name.lower()
+    if executable not in local_read_commands:
+        return False
+    if index == 0:
+        return True
+    if parts[index - 1] == "|":
+        segment = shlex.join(parts[index:])
+        return _codex_command_is_read_only_source_search(segment, cwd=cwd) or _codex_command_is_read_only_source_view(
+            segment, cwd=cwd
+        )
+    return parts[index - 1] in {"&&", "||", ";", "&", "|&"}
+
+
 def _codex_post_tool_command_is_read_only_source_inspection(
     *,
     payload: dict[str, object],