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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.110
+Version: 2.0.112
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner

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

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

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

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

@@ -97,7 +97,12 @@ 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, classify_secret_path
+from ..runtime.secret_sensitivity import (
+    SecretContentMatch,
+    SecretPathMatch,
+    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
@@ -3236,6 +3241,12 @@ def _runtime_artifact_native_reason(artifact: GuardArtifact, response_payload: d
         trimmed_summary = risk_summary.strip()
         if len(trimmed_summary) > 180:
             trimmed_summary = f"{trimmed_summary[:177].rstrip()}..."
+        action_class = artifact.metadata.get("action_class")
+        if (
+            action_class == "credential exfiltration shell command"
+            and "credential-looking output" not in trimmed_summary.lower()
+        ):
+            trimmed_summary = f"{trimmed_summary} Guard also detected credential-looking output."
         return f"HOL Guard flagged this request: {trimmed_summary}"
     return "HOL Guard flagged this request for review."
 
@@ -4020,7 +4031,10 @@ def _codex_post_tool_output_artifact(
     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)
+    local_source_matches = _codex_sensitive_local_source_matches(command_text, cwd=cwd)
+    references_local_content = bool(local_source_matches) or _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)
@@ -4043,10 +4057,38 @@ def _codex_post_tool_output_artifact(
             sort_keys=True,
         ).encode("utf-8")
     ).hexdigest()
+    local_secret_source = _codex_local_secret_source_label(
+        local_source_matches,
+        command_text=command_text,
+    )
     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")
+        source_signal = "command references local secrets"
+        if local_secret_source is not None:
+            source_signal = f"command references local secrets from {local_secret_source}"
+        runtime_request_signals.append(source_signal)
+    request_summary = _codex_tool_output_request_summary(
+        tool_name=tool_name,
+        command_text=command_text,
+        local_secret_source=local_secret_source,
+    )
+    runtime_request_summary = _codex_tool_output_runtime_summary(local_secret_source)
+    metadata: dict[str, object] = {
+        "tool_name": tool_name,
+        "command_text": command_text,
+        "action_class": "credential exfiltration shell command",
+        "guard_default_action": runtime_default_action,
+        "request_summary": request_summary,
+        "runtime_request_signals": runtime_request_signals,
+        "runtime_request_summary": runtime_request_summary,
+        "runtime_request_reason": (
+            "Guard inspects supported Codex tool output before Codex uses it, so accidental secret reads can be "
+            "stopped even when the filename was not obviously sensitive."
+        ),
+    }
+    if local_secret_source is not None:
+        metadata["secret_source_family"] = local_secret_source
     return GuardArtifact(
         artifact_id=f"codex:{source_scope}:tool-output:{fingerprint}",
         name=f"{tool_name} credential-looking output",
@@ -4054,42 +4096,40 @@ def _codex_post_tool_output_artifact(
         artifact_type="tool_action_request",
         source_scope=source_scope,
         config_path=config_path,
-        metadata={
-            "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": runtime_request_signals,
-            "runtime_request_summary": (
-                "Requests a sensitive native tool action: credential-looking output reached Codex."
-            ),
-            "runtime_request_reason": (
-                "Guard inspects supported Codex tool output before Codex uses it, so accidental secret reads can be "
-                "stopped even when the filename was not obviously sensitive."
-            ),
-        },
+        metadata=metadata,
     )
 
 
 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
+    return bool(_codex_sensitive_local_source_matches(command_text, cwd=cwd))
+
+
+def _codex_sensitive_local_source_matches(command_text: str, *, cwd: Path | None) -> list[SecretPathMatch]:
+    matches = _codex_sensitive_path_matches_in_text(command_text, cwd=cwd)
     try:
         parts = shlex.split(command_text)
     except ValueError:
-        return False
+        return matches
     for part in parts:
         stripped = part.strip()
-        if not stripped or stripped.startswith("-"):
+        if not stripped or stripped.startswith("-") or _codex_token_is_url(stripped):
             continue
-        if _codex_token_is_url(stripped):
+        path_match = classify_secret_path(stripped, cwd=cwd)
+        if path_match is not None:
+            matches.append(path_match)
+    return _dedupe_codex_secret_path_matches(matches)
+
+
+def _dedupe_codex_secret_path_matches(matches: list[SecretPathMatch]) -> list[SecretPathMatch]:
+    deduped: list[SecretPathMatch] = []
+    seen: set[tuple[str, str]] = set()
+    for match in matches:
+        key = (match.family, match.requested_path or match.path)
+        if key in seen:
             continue
-        if classify_secret_path(stripped, cwd=cwd) is not None:
-            return True
-    return False
+        seen.add(key)
+        deduped.append(match)
+    return deduped
 
 
 def _codex_token_is_url(token: str) -> bool:
@@ -4098,12 +4138,18 @@ def _codex_token_is_url(token: str) -> bool:
 
 
 def _codex_text_contains_sensitive_path_token(text: str, *, cwd: Path | None) -> bool:
+    return bool(_codex_sensitive_path_matches_in_text(text, cwd=cwd))
+
+
+def _codex_sensitive_path_matches_in_text(text: str, *, cwd: Path | None) -> list[SecretPathMatch]:
+    matches: list[SecretPathMatch] = []
     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
+        path_match = classify_secret_path(match.group(0), cwd=cwd)
+        if path_match is not None:
+            matches.append(path_match)
+    return matches
 
 
 def _codex_path_token_is_url_path(text: str, start: int) -> bool:
@@ -4150,7 +4196,10 @@ def _codex_pipeline_segment_may_read_local_content(segment: str, *, index: int,
     if not parts:
         return False
     if index == 0:
-        return _codex_command_parts_may_read_local_content(parts, cwd=cwd)
+        return _codex_command_parts_are_environment_dump(parts) or _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
     )
@@ -4207,6 +4256,65 @@ 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_command_reads_environment_pipeline(command_text: str) -> bool:
+    pipeline_segments = _split_codex_safe_read_only_pipeline(command_text)
+    if pipeline_segments is None:
+        return False
+    try:
+        first_parts = _codex_shell_split(pipeline_segments[0])
+    except ValueError:
+        return False
+    return _codex_command_parts_are_environment_dump(first_parts)
+
+
+def _codex_command_parts_are_environment_dump(parts: list[str]) -> bool:
+    if not parts:
+        return False
+    executable = Path(parts[0]).name.lower()
+    if executable == "printenv":
+        return True
+    if executable != "env":
+        return False
+    if _codex_env_args_clear_environment(parts[1:]):
+        return False
+    return not _codex_strip_env_wrapper(parts[1:])
+
+
+def _codex_local_secret_source_label(
+    matches: list[SecretPathMatch],
+    *,
+    command_text: str,
+) -> str | None:
+    families: list[str] = []
+    for match in matches:
+        if match.family not in families:
+            families.append(match.family)
+    if families:
+        if len(families) == 1:
+            return families[0]
+        return f"{families[0]} and other local secret files"
+    if _codex_command_reads_environment_pipeline(command_text):
+        return "environment variables"
+    return None
+
+
+def _codex_tool_output_request_summary(
+    *,
+    tool_name: str,
+    command_text: str,
+    local_secret_source: str | None,
+) -> str:
+    if local_secret_source is not None:
+        return f"Codex tool `{tool_name}` read local secrets from {local_secret_source} while running `{command_text}`."
+    return f"Codex tool `{tool_name}` produced credential-looking output while running `{command_text}`."
+
+
+def _codex_tool_output_runtime_summary(local_secret_source: str | None) -> str:
+    if local_secret_source is not None:
+        return f"Local secrets from {local_secret_source} reached Codex tool output."
+    return "Requests a sensitive native tool action: credential-looking output reached Codex."
+
+
 def _codex_unwrapped_command_parts(parts: list[str]) -> list[str]:
     remaining = parts
     while remaining:
@@ -4255,6 +4363,18 @@ def _codex_strip_env_wrapper(parts: list[str]) -> list[str]:
     return []
 
 
+def _codex_env_args_clear_environment(parts: list[str]) -> bool:
+    for part in parts:
+        if part == "--":
+            return False
+        if part in {"-i", "--ignore-environment"}:
+            return True
+        if part.startswith("-") or ("=" in part and not part.startswith("=")):
+            continue
+        return False
+    return False
+
+
 def _codex_shell_split(command_text: str) -> list[str]:
     lexer = shlex.shlex(command_text, posix=True, punctuation_chars=True)
     lexer.whitespace_split = True

{plugin_scanner-2.0.110 → plugin_scanner-2.0.112}/src/codex_plugin_scanner/guard/cli/render.py

@@ -50,6 +50,7 @@ _SENSITIVE_STRING_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
     ),
     (re.compile(r"(?i)(authorization:\s*)(bearer\s+)?[^\s,;]+"), r"\1*****"),
     (re.compile(r"(?i)(api[-_ ]?key:\s*)[^\s,;]+"), r"\1*****"),
+    (re.compile(r"\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b"), "*****"),
     (re.compile(r"(?i)(bearer\s+)[^\s,;]+"), r"\1*****"),
     (re.compile(r"(?im)\b(?:_authToken|npm[_ -]?token)\s*[:=]\s*[^\s]+"), "npm token redacted"),
     (re.compile(r"\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp)://[^\s]+", re.IGNORECASE), "*****"),
@@ -963,6 +964,8 @@ def _render_hook(console: Console, payload: dict[str, object]) -> None:
     body.add_row("Recorded", _bool_label(bool(payload.get("recorded"))))
     body.add_row("Artifact", str(payload.get("artifact_name") or payload.get("artifact_id") or "unknown"))
     body.add_row("Decision", _action_text(str(payload.get("policy_action", "warn"))))
+    if payload.get("risk_summary"):
+        body.add_row("Why", str(payload.get("risk_summary")))
     if payload.get("path_summary"):
         body.add_row("Path", str(payload.get("path_summary")))
     if payload.get("approval_center_url"):

plugin_scanner-2.0.112/src/codex_plugin_scanner/guard/runtime/data_flow.py

@@ -0,0 +1,384 @@
+"""Local data-flow source and sink helpers for Guard runtime detectors."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from itertools import pairwise
+from typing import Literal
+
+DataSourceType = Literal[
+    "secret_file",
+    "env",
+    "clipboard",
+    "keychain",
+    "command_output",
+    "prompt",
+    "generated_file",
+]
+DataSinkType = Literal[
+    "http_post",
+    "http_get_query",
+    "dns",
+    "webhook",
+    "paste",
+    "git_remote",
+    "package_publish",
+    "clipboard",
+    "local_log",
+]
+
+_VALID_SOURCE_TYPES = frozenset(
+    {
+        "secret_file",
+        "env",
+        "clipboard",
+        "keychain",
+        "command_output",
+        "prompt",
+        "generated_file",
+    }
+)
+_VALID_SINK_TYPES = frozenset(
+    {
+        "http_post",
+        "http_get_query",
+        "dns",
+        "webhook",
+        "paste",
+        "git_remote",
+        "package_publish",
+        "clipboard",
+        "local_log",
+    }
+)
+_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"})
+_INPUT_REDIRECT_PATTERN = re.compile(r"(?<![<])(?:\d*)<\s*(?![<&])(?P<target>\"[^\"]+\"|'[^']+'|[^ \t\r\n;&|<>]+)")
+_URL_PATTERN = re.compile(r"https?://[^\s\"'<>)}\]]+", re.IGNORECASE)
+_CURL_METHOD_PATTERN = re.compile(
+    r"(?i)(?:^|[\s;&|])(?:curl|curl\.exe)\b[^\r\n;&|]*?"
+    r"(?:--request(?:=|\s+)|-X\s*)['\"]?(?P<method>[a-z]+)['\"]?\b"
+)
+_FETCH_METHOD_PATTERN = re.compile(r"(?i)\bmethod\s*:\s*['\"](?P<method>[a-z]+)['\"]")
+_REQUESTS_METHOD_PATTERN = re.compile(r"(?i)\brequests\.(?P<method>get|post|put|patch|delete|head|options)\s*\(")
+_CURL_DATA_PATTERN = re.compile(
+    r"(?i)(?:^|[\s;&|])(?:curl|curl\.exe)\b[^\r\n;&|]*(?:\s-d\b|\s--data(?:-raw|-binary|-urlencode)?\b)"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DataSource:
+    """Redacted local data source referenced by a runtime action."""
+
+    source_type: DataSourceType
+    value: str
+    description: str
+    evidence: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.source_type not in _VALID_SOURCE_TYPES:
+            raise ValueError("source_type must be a known Guard data source type")
+        if not self.value.strip():
+            raise ValueError("value must be a non-empty redacted source identifier")
+        if not self.description.strip():
+            raise ValueError("description must be a non-empty source description")
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "source_type": self.source_type,
+            "value": self.value,
+            "description": self.description,
+            "evidence": self.evidence,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class DataSink:
+    """Redacted destination where local data may leave the trusted context."""
+
+    sink_type: DataSinkType
+    value: str
+    description: str
+    method: str | None = None
+    evidence: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.sink_type not in _VALID_SINK_TYPES:
+            raise ValueError("sink_type must be a known Guard data sink type")
+        if not self.value.strip():
+            raise ValueError("value must be a non-empty redacted sink identifier")
+        if not self.description.strip():
+            raise ValueError("description must be a non-empty sink description")
+        if self.method is not None:
+            if not isinstance(self.method, str):
+                raise ValueError("method must be a known HTTP method")
+            normalized = self.method.upper()
+            if normalized not in _HTTP_METHODS:
+                raise ValueError("method must be a known HTTP method")
+            object.__setattr__(self, "method", normalized)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "sink_type": self.sink_type,
+            "value": self.value,
+            "description": self.description,
+            "method": self.method,
+            "evidence": self.evidence,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ShellPipe:
+    """Top-level shell pipe edge between adjacent command segments."""
+
+    left: str
+    right: str
+
+
+def extract_input_redirects(command: str) -> tuple[str, ...]:
+    """Return file targets read through shell input redirects."""
+
+    targets: list[str] = []
+    for segment in _split_top_level_commands(command):
+        for match in _INPUT_REDIRECT_PATTERN.finditer(segment):
+            target = _strip_shell_quotes(match.group("target"))
+            if target and not target.startswith(("(", "&")):
+                targets.append(target)
+    return _dedupe(targets)
+
+
+def extract_command_substitutions(command: str) -> tuple[str, ...]:
+    """Return commands inside top-level `$()` and backtick substitutions."""
+
+    substitutions: list[str] = []
+    index = 0
+    quote: str | None = None
+    while index < len(command):
+        char = command[index]
+        if char == "\\":
+            index += 2
+            continue
+        if char == "'" and quote is None:
+            quote = "'"
+            index += 1
+            continue
+        if char == "'" and quote == "'":
+            quote = None
+            index += 1
+            continue
+        if char == '"' and quote is None:
+            quote = '"'
+            index += 1
+            continue
+        if char == '"' and quote == '"':
+            quote = None
+            index += 1
+            continue
+        if quote != "'" and command.startswith("$(", index):
+            extracted, end_index = _extract_parenthesized(command, index + 2)
+            if extracted.strip():
+                substitutions.append(extracted.strip())
+            index = end_index + 1
+            continue
+        if quote != "'" and char == "`":
+            extracted, end_index = _extract_backtick(command, index + 1)
+            if extracted.strip():
+                substitutions.append(extracted.strip())
+            index = end_index + 1
+            continue
+        index += 1
+    return tuple(substitutions)
+
+
+def extract_pipes(command: str) -> tuple[ShellPipe, ...]:
+    """Return adjacent top-level pipe edges, ignoring logical OR and quoted pipes."""
+
+    pipes: list[ShellPipe] = []
+    for segment in _split_top_level_commands(command):
+        parts = _split_top_level_pipes(segment)
+        if len(parts) < 2:
+            continue
+        for left, right in pairwise(parts):
+            stripped_left = left.strip()
+            stripped_right = right.strip()
+            if stripped_left and stripped_right:
+                pipes.append(ShellPipe(left=stripped_left, right=stripped_right))
+    return tuple(pipes)
+
+
+def extract_http_methods(command: str) -> tuple[str, ...]:
+    """Return explicit or strongly implied HTTP methods referenced by shell text."""
+
+    methods: list[str] = []
+    for pattern in (_CURL_METHOD_PATTERN, _FETCH_METHOD_PATTERN, _REQUESTS_METHOD_PATTERN):
+        for match in pattern.finditer(command):
+            _append_http_method(methods, match.group("method"))
+    if _CURL_DATA_PATTERN.search(command):
+        _append_http_method(methods, "POST")
+    return _dedupe(methods)
+
+
+def extract_urls(command: str) -> tuple[str, ...]:
+    """Return HTTP(S) URLs while preserving first-seen order."""
+
+    urls = [_strip_url_suffix(match.group(0)) for match in _URL_PATTERN.finditer(command)]
+    return _dedupe(url for url in urls if url)
+
+
+def _append_http_method(methods: list[str], method: str) -> None:
+    normalized = method.upper()
+    if normalized in _HTTP_METHODS:
+        methods.append(normalized)
+
+
+def _dedupe(values: Iterable[str]) -> tuple[str, ...]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        if value in seen:
+            continue
+        seen.add(value)
+        result.append(value)
+    return tuple(result)
+
+
+def _strip_shell_quotes(value: str) -> str:
+    stripped = value.strip()
+    if len(stripped) >= 2 and stripped[0] == stripped[-1] and stripped[0] in {"'", '"'}:
+        return stripped[1:-1]
+    return stripped
+
+
+def _strip_url_suffix(value: str) -> str:
+    return value.rstrip(".,;")
+
+
+def _split_top_level_commands(command: str) -> tuple[str, ...]:
+    parts: list[str] = []
+    start = 0
+    index = 0
+    state = _ShellScanState()
+    while index < len(command):
+        next_index = state.advance(command, index)
+        if next_index != index + 1:
+            index = next_index
+            continue
+        if state.is_top_level and command[index] == ";":
+            _append_segment(parts, command[start:index])
+            start = index + 1
+        elif state.is_top_level and (command.startswith("&&", index) or command.startswith("||", index)):
+            _append_segment(parts, command[start:index])
+            start = index + 2
+            index += 1
+        index += 1
+    _append_segment(parts, command[start:])
+    return tuple(parts)
+
+
+def _split_top_level_pipes(command: str) -> tuple[str, ...]:
+    parts: list[str] = []
+    start = 0
+    index = 0
+    state = _ShellScanState()
+    while index < len(command):
+        next_index = state.advance(command, index)
+        if next_index != index + 1:
+            index = next_index
+            continue
+        if state.is_top_level and command[index] == "|":
+            previous_is_pipe = index > 0 and command[index - 1] == "|"
+            next_is_pipe = index + 1 < len(command) and command[index + 1] == "|"
+            if not previous_is_pipe and not next_is_pipe:
+                _append_segment(parts, command[start:index])
+                start = index + 1
+        index += 1
+    _append_segment(parts, command[start:])
+    return tuple(parts)
+
+
+def _append_segment(parts: list[str], value: str) -> None:
+    stripped = value.strip()
+    if stripped:
+        parts.append(stripped)
+
+
+def _extract_parenthesized(command: str, start: int) -> tuple[str, int]:
+    depth = 1
+    index = start
+    quote: str | None = None
+    while index < len(command):
+        char = command[index]
+        if char == "\\":
+            index += 2
+            continue
+        if char in {"'", '"'}:
+            if quote is None:
+                quote = char
+            elif quote == char:
+                quote = None
+            index += 1
+            continue
+        if quote is None and char == "(":
+            depth += 1
+        elif quote is None and char == ")":
+            depth -= 1
+            if depth == 0:
+                return command[start:index], index
+        index += 1
+    return command[start:], len(command)
+
+
+def _extract_backtick(command: str, start: int) -> tuple[str, int]:
+    index = start
+    while index < len(command):
+        char = command[index]
+        if char == "\\":
+            index += 2
+            continue
+        if char == "`":
+            return command[start:index], index
+        index += 1
+    return command[start:], len(command)
+
+
+class _ShellScanState:
+    def __init__(self) -> None:
+        self.quote: str | None = None
+        self.subshell_depth = 0
+        self.in_backtick = False
+
+    @property
+    def is_top_level(self) -> bool:
+        return self.quote is None and self.subshell_depth == 0 and not self.in_backtick
+
+    def advance(self, command: str, index: int) -> int:
+        char = command[index]
+        if char == "\\":
+            return min(len(command), index + 2)
+        if char == "`" and self.quote != "'":
+            self.in_backtick = not self.in_backtick
+            return index + 1
+        if self.in_backtick:
+            return index + 1
+        if self.quote == "'":
+            if char == "'":
+                self.quote = None
+            return index + 1
+        if char == "'" and self.quote is None:
+            self.quote = "'"
+            return index + 1
+        if char == '"':
+            if self.quote == '"':
+                self.quote = None
+            elif self.quote is None:
+                self.quote = '"'
+            return index + 1
+        if self.quote != "'" and command.startswith("$(", index):
+            _extracted, end_index = _extract_parenthesized(command, index + 2)
+            return min(len(command), end_index + 1)
+        if self.quote is None and char == "(":
+            self.subshell_depth += 1
+        elif self.quote is None and char == ")" and self.subshell_depth > 0:
+            self.subshell_depth -= 1
+        return index + 1