langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/tools/bash/bash_hardening.py

@@ -0,0 +1,734 @@
+"""
+tools/bash/bash_hardening.py — BashRuntimeTool 模块3：安全攻防加固
+
+职责：
+    在 AST 结构审批、路径授权、PolicyEngine 之外，补上 command-string 层面的
+    防绕过检查，避免 env / wrapper / quoting / git-internal 等模式绕过主权限链。
+
+协作者（对照 CC 更大攻防规则库方向扩展）：
+    1. BashCommandCanonicalizer — env/wrapper 固定点归一化
+    2. BashEnvSecurityChecker — 高危环境变量（含 JVM/SSH/TLS 劫持面）
+    3. BashUnicodeRiskChecker — 零宽 / RTL 等不可见字符混淆
+    4. BashExecutionContextChecker — sudo/chroot/nsenter 等执行上下文切换
+    5. BashCrossPlatformBinaryChecker — wsl/cmd/powershell 等跨边界执行
+    6. BashRemoteShellPipelineChecker — curl|bash、base64|sh 等「下载/解码→解释器」链
+    7. BashShellRiskChecker — quoting / heredoc / UNC / WebDAV 等
+    8. BashGitCliInjectionChecker — git -c hooksPath / sshCommand 等 CLI 注入
+    9. BashGitSecurityChecker — .git 路径、bare、compound cd 等
+
+观测：
+    BashSecurityHardener.audit_explain() 返回结构化快照，便于与 CC 式调试输出对齐。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_agentx.tool_runtime.models import AuthorizationDecision
+from langchain_agentx.utils.host_platform import get_host_platform
+
+from .ast_security import BashAstAnalysis, BashWrapperStripper
+from .path_security import BashPathExtractorRegistry
+
+
+@dataclass(frozen=True)
+class BashHardeningCheckResult:
+    behavior: str
+    message: str | None = None
+    policy_id: str | None = None
+    ask_prompt: str | None = None
+    rule_code: str | None = None
+    category: str | None = None
+    extra: dict[str, Any] | None = None
+
+    def to_decision(self) -> AuthorizationDecision:
+        meta: dict[str, Any] | None = None
+        if self.rule_code or self.category or self.extra:
+            bh: dict[str, Any] = {}
+            if self.rule_code:
+                bh["rule_code"] = self.rule_code
+            if self.category:
+                bh["category"] = self.category
+            if self.extra:
+                bh.update(self.extra)
+            meta = {"bash_hardening": bh}
+        return AuthorizationDecision(
+            behavior=self.behavior,
+            message=self.message,
+            policy_id=self.policy_id,
+            ask_prompt=self.ask_prompt,
+            metadata=meta,
+        )
+
+
+class BashCommandCanonicalizer:
+    """对命令做 env/wrapper 固定点归一化，供策略匹配使用。"""
+
+    _ENV_ASSIGNMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*$")
+
+    def __init__(self, wrapper_stripper: BashWrapperStripper | None = None) -> None:
+        self._wrapper_stripper = wrapper_stripper or BashWrapperStripper()
+
+    def canonicalize(self, command: str) -> str:
+        tokens = self._split(command)
+        if not tokens:
+            return command.strip()
+
+        previous: list[str] | None = None
+        current = list(tokens)
+        while current != previous and current:
+            previous = list(current)
+            current = self._strip_assignments(current)
+            current = self._wrapper_stripper.strip(current)
+
+        return " ".join(current) if current else command.strip()
+
+    @staticmethod
+    def _split(command: str) -> list[str]:
+        try:
+            return shlex.split(command)
+        except ValueError:
+            return command.split()
+
+    def _strip_assignments(self, tokens: list[str]) -> list[str]:
+        index = 0
+        while index < len(tokens) and self._ENV_ASSIGNMENT_RE.match(tokens[index]):
+            index += 1
+        return tokens[index:]
+
+
+class BashEnvSecurityChecker:
+    """检测前导环境变量中的高风险执行劫持面。"""
+
+    SAFE_ENV_VARS = frozenset({
+        "TERM", "COLORTERM", "NO_COLOR", "FORCE_COLOR", "CLICOLOR",
+        "LANG", "LANGUAGE", "LC_ALL", "LC_CTYPE", "LC_MESSAGES", "TZ",
+        "COLUMNS", "LINES", "CI",
+    })
+    BINARY_HIJACK_VARS = frozenset({
+        "PATH", "LD_PRELOAD", "LD_LIBRARY_PATH", "DYLD_INSERT_LIBRARIES",
+        "DYLD_LIBRARY_PATH", "PYTHONPATH", "PYTHONHOME", "PYTHONSTARTUP",
+        "RUBYLIB", "RUBYOPT", "PERL5LIB", "PERL5OPT", "NODE_PATH",
+        "NODE_OPTIONS", "GIT_EXEC_PATH", "GIT_CONFIG", "GIT_CONFIG_GLOBAL",
+        "GIT_CONFIG_SYSTEM", "BASH_ENV", "ENV", "SHELLOPTS", "IFS",
+        "CDPATH", "PROMPT_COMMAND",
+        "JAVA_TOOL_OPTIONS", "_JAVA_OPTIONS", "JDK_JAVA_OPTIONS",
+        "GIT_SSH_COMMAND", "GIT_SSH",
+        "LD_AUDIT", "OPENSSL_CONF", "SSLKEYLOGFILE",
+    })
+    _ENV_ASSIGNMENT_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+    def collect_modified_vars(self, command: str) -> set[str]:
+        tokens = self._split(command)
+        if not tokens:
+            return set()
+
+        result: set[str] = set()
+        index = 0
+        while index < len(tokens):
+            match = self._ENV_ASSIGNMENT_RE.match(tokens[index])
+            if match:
+                result.add(match.group(1))
+                index += 1
+                continue
+            break
+
+        if index < len(tokens) and tokens[index] == "env":
+            index += 1
+            while index < len(tokens):
+                token = tokens[index]
+                if token == "--":
+                    index += 1
+                    break
+                if token == "-u" and index + 1 < len(tokens):
+                    result.add(tokens[index + 1])
+                    index += 2
+                    continue
+                if token in {"-i", "-0", "-v"}:
+                    index += 1
+                    continue
+                match = self._ENV_ASSIGNMENT_RE.match(token)
+                if match:
+                    result.add(match.group(1))
+                    index += 1
+                    continue
+                break
+        return result
+
+    def evaluate(self, command: str) -> BashHardeningCheckResult | None:
+        modified_vars = self.collect_modified_vars(command)
+        dangerous = sorted(var for var in modified_vars if var in self.BINARY_HIJACK_VARS)
+        if not dangerous:
+            return None
+        joined = ", ".join(dangerous)
+        return BashHardeningCheckResult(
+            behavior="ask",
+            message=(
+                "This command modifies high-risk environment variables that can change "
+                f"which binary or config is used: {joined}."
+            ),
+            policy_id="bash_env_hardening",
+            ask_prompt=(
+                "High-risk environment variable override detected.\n"
+                f"Variables: {joined}\n"
+                "These variables can alter binary resolution or runtime configuration, "
+                "so explicit approval is required."
+            ),
+            rule_code="env.binary_hijack",
+            category="env",
+            extra={"variables": dangerous},
+        )
+
+    @staticmethod
+    def _split(command: str) -> list[str]:
+        try:
+            return shlex.split(command)
+        except ValueError:
+            return command.split()
+
+
+class BashUnicodeRiskChecker:
+    """零宽字符 / RTL 控制符等不可见混淆（跨平台 Unicode 特例）。"""
+
+    _INVISIBLE_OR_RTL = re.compile(r"[\u200b\u200c\u200d\ufeff\u202a-\u202e]")
+
+    def evaluate(self, command: str) -> BashHardeningCheckResult | None:
+        if not self._INVISIBLE_OR_RTL.search(command):
+            return None
+        return BashHardeningCheckResult(
+            behavior="ask",
+            message="Command contains invisible Unicode characters that can obfuscate intent.",
+            policy_id="bash_unicode_obfuscation",
+            ask_prompt=(
+                "Invisible Unicode characters (zero-width / bidi controls) detected.\n"
+                "These can hide flags or path segments; explicit approval is required."
+            ),
+            rule_code="shell.unicode_invisible",
+            category="shell",
+        )
+
+
+class BashExecutionContextChecker:
+    """sudo / chroot / namespace 等改变真实执行身份或根目录。"""
+
+    _CTX = re.compile(
+        r"(?:^|[;&|]|\s|&&|\|\|)"
+        r"(?:sudo|doas|su\b|runuser|chroot|nsenter|strace|ltrace|"
+        r"pkexec|firejail|bwrap|bubblewrap|unshare|systemd-run|machinectl)\s",
+        re.IGNORECASE,
+    )
+
+    def evaluate(self, command: str) -> BashHardeningCheckResult | None:
+        if not self._CTX.search(command):
+            return None
+        return BashHardeningCheckResult(
+            behavior="ask",
+            message="Command uses a privilege or namespace wrapper that can change execution semantics.",
+            policy_id="bash_execution_context",
+            ask_prompt=(
+                "Privilege / chroot / namespace / tracer wrapper detected.\n"
+                "These can bypass normal permission and sandbox assumptions; approve explicitly."
+            ),
+            rule_code="exec.context.privilege_or_namespace",
+            category="execution_context",
+        )
+
+
+class BashCrossPlatformBinaryChecker:
+    """跨 OS 边界执行（Windows / WSL / PowerShell），与 POSIX 沙盒假设不一致。"""
+
+    _CROSS = re.compile(
+        r"(?:^|\s)(?:wsl(?:\.exe)?|cmd(?:\.exe)?|powershell(?:\.exe)?|pwsh(?:\.exe)?)\s",
+        re.IGNORECASE,
+    )
+
+    def evaluate(self, command: str) -> BashHardeningCheckResult | None:
+        if not self._CROSS.search(command):
+            return None
+        return BashHardeningCheckResult(
+            behavior="ask",
+            message="Command invokes a cross-platform shell binary (WSL/cmd/PowerShell), which requires review.",
+            policy_id="bash_cross_platform_shell",
+            ask_prompt=(
+                "Cross-platform shell invocation detected (wsl/cmd/powershell/pwsh).\n"
+                "Paths and permission models differ from POSIX bash; explicit approval is required."
+            ),
+            rule_code="platform.cross_shell",
+            category="platform",
+            extra={
+                "sys_platform_raw": sys.platform,
+                "host_platform": get_host_platform().value,
+            },
+        )
+
+
+class BashRemoteShellPipelineChecker:
+    """远程拉取 / 解码后直接进入解释器的高风险链。"""
+
+    _FETCH_PIPE_SHELL = re.compile(
+        r"(?:curl|wget|fetch)\b[^\n|]*\|\s*(?:bash|sh|zsh|dash)\b",
+        re.IGNORECASE,
+    )
+    _B64_PIPE_SHELL = re.compile(
+        r"base64\b[^\n|]*(?:-d|--decode)[^\n|]*\|\s*(?:bash|sh)\b",
+        re.IGNORECASE,
+    )
+
+    def evaluate(self, command: str) -> BashHardeningCheckResult | None:
+        if self._FETCH_PIPE_SHELL.search(command):
+            return BashHardeningCheckResult(
+                behavior="ask",
+                message="Pipeline fetches remote content directly into a shell interpreter.",
+                policy_id="bash_remote_pipe_shell",
+                ask_prompt=(
+                    "curl/wget/fetch piped into bash/sh detected.\n"
+                    "This is a common remote-code execution pattern; explicit approval is required."
+                ),
+                rule_code="network.fetch_pipe_interpreter",
+                category="network",
+            )
+        if self._B64_PIPE_SHELL.search(command):
+            return BashHardeningCheckResult(
+                behavior="ask",
+                message="Pipeline decodes base64 directly into a shell interpreter.",
+                policy_id="bash_remote_pipe_shell",
+                ask_prompt=(
+                    "base64 decode piped into bash/sh detected.\n"
+                    "This can hide payload from static review; explicit approval is required."
+                ),
+                rule_code="network.base64_pipe_interpreter",
+                category="network",
+            )
+        return None
+
+
+class BashGitCliInjectionChecker:
+    """git -c 覆盖 hooks / SSH 等敏感运行时配置。"""
+
+    _DANGEROUS_GIT_C = re.compile(
+        r"\bgit\s+(?:-\S+\s+)*-c\s+\S*(hooksPath|sshCommand|uploadpack|receivepack)\S*=",
+        re.IGNORECASE,
+    )
+
+    def evaluate(self, command: str) -> BashHardeningCheckResult | None:
+        if not re.search(r"\bgit\b", command):
+            return None
+        if not self._DANGEROUS_GIT_C.search(command):
+            return None
+        return BashHardeningCheckResult(
+            behavior="ask",
+            message="Git command overrides sensitive runtime settings via `-c` (hooks/ssh/pack).",
+            policy_id="bash_git_cli_injection",
+            ask_prompt=(
+                "git -c override for hooksPath/sshCommand/uploadpack/receivepack detected.\n"
+                "These can redirect hooks or transport; explicit approval is required."
+            ),
+            rule_code="git.cli_runtime_override",
+            category="git",
+        )
+
+
+class BashShellRiskChecker:
+    """检测 quoting / heredoc / UNC / WebDAV / eval / process substitution 等模式。"""
+
+    _ANSI_C_QUOTING_RE = re.compile(r"\$'[^']*'")
+    _LOCALE_QUOTING_RE = re.compile(r'\$"[^"]*"')
+    _EMPTY_QUOTES_BEFORE_DASH_RE = re.compile(r"(?:^|\s)(?:''|\"\")+\s*-")
+    _ADJACENT_QUOTED_DASH_RE = re.compile(r'(?:""|\'\')+[\'"]-')
+    _CONSECUTIVE_QUOTES_RE = re.compile(r"(?:^|\s)['\"]{3,}")
+    _HEREDOC_IN_SUBSTITUTION_RE = re.compile(
+        r"(\$\([^)]*<<-?\s*['\"]?[A-Za-z0-9_]+|`[^`]*<<-?\s*['\"]?[A-Za-z0-9_]+)"
+    )
+    _UNC_BACKSLASH_RE = re.compile(r"\\\\[^\\/\s]+\\[^\\/\s]+")
+    _UNC_DEVICE_RE = re.compile(r"//\?/UNC/", re.IGNORECASE)
+    _WEBDAV_RE = re.compile(r"\b(?:dav|davs|webdav|smb)://", re.IGNORECASE)
+    _EVAL_OR_SOURCE_RE = re.compile(
+        r"(?:^|\s)(?:eval|source)\s",
+    )
+    _PROCESS_SUBST_RE = re.compile(r"[<>]\(")
+
+    def pattern_rules(
+        self,
+    ) -> list[tuple[str, re.Pattern[str], str, str]]:
+        return [
+            (
+                "ansi_c_quote",
+                self._ANSI_C_QUOTING_RE,
+                "Command contains ANSI-C quoting which can hide characters.",
+                "bash_shell_obfuscation",
+            ),
+            (
+                "locale_quote",
+                self._LOCALE_QUOTING_RE,
+                "Command contains locale quoting which can hide characters.",
+                "bash_shell_obfuscation",
+            ),
+            (
+                "empty_quotes_dash",
+                self._EMPTY_QUOTES_BEFORE_DASH_RE,
+                "Command contains empty quotes before a dash, which can obfuscate flags.",
+                "bash_shell_obfuscation",
+            ),
+            (
+                "adjacent_quotes_dash",
+                self._ADJACENT_QUOTED_DASH_RE,
+                "Command contains empty quote pairs adjacent to a quoted dash.",
+                "bash_shell_obfuscation",
+            ),
+            (
+                "consecutive_quotes",
+                self._CONSECUTIVE_QUOTES_RE,
+                "Command contains suspicious consecutive quote characters at word start.",
+                "bash_shell_obfuscation",
+            ),
+            (
+                "heredoc_in_subst",
+                self._HEREDOC_IN_SUBSTITUTION_RE,
+                "Command contains heredoc content inside command substitution, which requires review.",
+                "bash_heredoc_substitution",
+            ),
+            (
+                "unc_backslash",
+                self._UNC_BACKSLASH_RE,
+                "Command references a UNC path, which may trigger remote filesystem access.",
+                "bash_remote_path_risk",
+            ),
+            (
+                "unc_device",
+                self._UNC_DEVICE_RE,
+                "Command references a Windows UNC device path, which requires approval.",
+                "bash_remote_path_risk",
+            ),
+            (
+                "webdav",
+                self._WEBDAV_RE,
+                "Command references a WebDAV/SMB-style remote path, which requires approval.",
+                "bash_remote_path_risk",
+            ),
+            (
+                "eval_source",
+                self._EVAL_OR_SOURCE_RE,
+                "Command uses eval/source/. which can execute arbitrary strings.",
+                "bash_dynamic_eval",
+            ),
+            (
+                "process_substitution",
+                self._PROCESS_SUBST_RE,
+                "Command uses process substitution (<(...) / >(...)), which can hide side effects.",
+                "bash_process_substitution",
+            ),
+        ]
+
+    def evaluate(self, command: str) -> BashHardeningCheckResult | None:
+        for rule_id, pattern, message, policy_id in self.pattern_rules():
+            if pattern.search(command):
+                return BashHardeningCheckResult(
+                    behavior="ask",
+                    message=message,
+                    policy_id=policy_id,
+                    ask_prompt=message,
+                    rule_code=f"shell.{rule_id}",
+                    category="shell",
+                )
+        return None
+
+    def probe(self, command: str) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        for rule_id, pattern, message, policy_id in self.pattern_rules():
+            out.append(
+                {
+                    "rule_id": rule_id,
+                    "policy_id": policy_id,
+                    "matched": bool(pattern.search(command)),
+                    "message": message,
+                }
+            )
+        return out
+
+
+class BashGitSecurityChecker:
+    """检测 git-internal 路径、裸仓库和仓库边界混淆。"""
+
+    def __init__(self, extractor_registry: BashPathExtractorRegistry | None = None) -> None:
+        self._extractor_registry = extractor_registry or BashPathExtractorRegistry()
+
+    def evaluate_command(
+        self,
+        *,
+        command: str,
+        analysis: BashAstAnalysis,
+        cwd: str,
+    ) -> BashHardeningCheckResult | None:
+        normalized = set(analysis.normalized_base_commands)
+        if "git" in normalized:
+            risky_subcommand = self._git_risky_subcommand(command)
+            if risky_subcommand is not None:
+                return BashHardeningCheckResult(
+                    behavior="ask",
+                    message=(
+                        "Git command may mutate repository or remote state "
+                        f"(`git {risky_subcommand}`), explicit approval is required."
+                    ),
+                    policy_id="bash_git_high_risk_subcommand",
+                    ask_prompt=(
+                        f"High-risk git subcommand detected: git {risky_subcommand}\n"
+                        "This operation can modify refs/history/remotes, approve explicitly."
+                    ),
+                    rule_code="git.high_risk_subcommand",
+                    category="git",
+                    extra={"subcommand": risky_subcommand},
+                )
+            if self._is_git_internal_dir(cwd):
+                return BashHardeningCheckResult(
+                    behavior="ask",
+                    message="Running git from inside a .git internal directory requires approval.",
+                    policy_id="bash_git_workspace_boundary",
+                    ask_prompt=(
+                        "Git command is running from inside a .git internal directory.\n"
+                        "This can change repository internals in non-obvious ways, so approval is required."
+                    ),
+                    rule_code="git.cwd_inside_dot_git",
+                    category="git",
+                )
+            if self._looks_like_bare_repo(cwd):
+                return BashHardeningCheckResult(
+                    behavior="ask",
+                    message="Running git inside a bare repository requires approval.",
+                    policy_id="bash_git_workspace_boundary",
+                    ask_prompt=(
+                        "Git command appears to target a bare repository.\n"
+                        "Bare repos expose internal refs/config directly, so approval is required."
+                    ),
+                    rule_code="git.bare_repo_cwd",
+                    category="git",
+                )
+
+        if "git" in normalized and self._has_cd_into_git_internal(analysis, cwd):
+            return BashHardeningCheckResult(
+                behavior="ask",
+                message="Compound command changes into a git-internal directory before running git.",
+                policy_id="bash_git_workspace_boundary",
+                ask_prompt=(
+                    "This command changes into a git-internal directory and then runs git.\n"
+                    "Explicit approval is required to avoid repository-boundary confusion."
+                ),
+                rule_code="git.cd_into_internal_then_git",
+                category="git",
+            )
+        return None
+
+    def _git_risky_subcommand(self, command: str) -> str | None:
+        tokens = self._split(command)
+        if not tokens:
+            return None
+        if os.path.basename(tokens[0]) != "git":
+            return None
+        subcommand = ""
+        for token in tokens[1:]:
+            if token.startswith("-"):
+                continue
+            subcommand = token
+            break
+        if not subcommand:
+            return None
+        risky = {
+            "push", "fetch", "pull", "clone", "remote", "submodule", "config",
+            "update-ref", "rebase", "reset", "checkout", "switch", "worktree",
+            "commit", "cherry-pick", "revert", "merge", "apply", "am",
+            "notes", "tag", "branch", "stash",
+        }
+        if subcommand in risky:
+            if subcommand == "remote" and any(t in {"-v", "show"} for t in tokens[2:]):
+                return None
+            return subcommand
+        return None
+
+    def evaluate_segment(
+        self,
+        *,
+        command: str,
+        analysis: BashAstAnalysis,
+        cwd: str,
+    ) -> BashHardeningCheckResult | None:
+        path_info = self._extractor_registry.extract(command, analysis)
+        if path_info is None:
+            return None
+
+        for target in path_info.path_targets:
+            resolved = self._resolve_path(target.raw_path, cwd)
+            if self._is_git_internal_path(resolved):
+                if target.operation_type in {"write", "create"}:
+                    return BashHardeningCheckResult(
+                        behavior="deny",
+                        message="Direct writes to git-internal paths are not allowed.",
+                        policy_id="bash_git_internal_path",
+                        rule_code="git.internal_path_write",
+                        category="git",
+                        extra={"path": resolved},
+                    )
+                return BashHardeningCheckResult(
+                    behavior="ask",
+                    message="Direct access to git-internal paths requires approval.",
+                    policy_id="bash_git_internal_path",
+                    ask_prompt=(
+                        f"Direct access to git-internal path detected: {resolved}\n"
+                        "This requires approval because repository internals may contain hooks or config."
+                    ),
+                    rule_code="git.internal_path_access",
+                    category="git",
+                    extra={"path": resolved},
+                )
+        return None
+
+    def _has_cd_into_git_internal(self, analysis: BashAstAnalysis, cwd: str) -> bool:
+        if "git" not in analysis.normalized_base_commands:
+            return False
+        for simple in analysis.simple_commands:
+            if simple.normalized_base_command != "cd":
+                continue
+            tokens = self._split(simple.text)
+            if len(tokens) < 2:
+                continue
+            resolved = self._resolve_path(tokens[1], cwd)
+            if self._is_git_internal_dir(resolved) or self._looks_like_bare_repo(resolved):
+                return True
+        return False
+
+    @staticmethod
+    def _split(command: str) -> list[str]:
+        try:
+            return shlex.split(command)
+        except ValueError:
+            return command.split()
+
+    @staticmethod
+    def _resolve_path(raw_path: str, cwd: str) -> str:
+        expanded = os.path.expanduser(raw_path.strip("\"'"))
+        absolute = expanded if os.path.isabs(expanded) else os.path.join(cwd, expanded)
+        return os.path.realpath(absolute)
+
+    @staticmethod
+    def _is_git_internal_path(path: str) -> bool:
+        normalized = os.path.normpath(path)
+        parts = normalized.split(os.sep)
+        if ".git" in parts:
+            return True
+        basename = os.path.basename(normalized)
+        return basename == ".gitmodules"
+
+    @staticmethod
+    def _is_git_internal_dir(path: str) -> bool:
+        normalized = os.path.normpath(path)
+        parts = normalized.split(os.sep)
+        return ".git" in parts
+
+    @staticmethod
+    def _looks_like_bare_repo(path: str) -> bool:
+        return (
+            os.path.isdir(path)
+            and os.path.isfile(os.path.join(path, "HEAD"))
+            and os.path.isfile(os.path.join(path, "config"))
+            and os.path.isdir(os.path.join(path, "objects"))
+            and os.path.isdir(os.path.join(path, "refs"))
+            and not os.path.isdir(os.path.join(path, ".git"))
+        )
+
+
+class BashSecurityHardener:
+    """模块 3 总协作者：在 AST/path/policy 链路之外追加防绕过检查。"""
+
+    def __init__(
+        self,
+        *,
+        canonicalizer: BashCommandCanonicalizer | None = None,
+        env_checker: BashEnvSecurityChecker | None = None,
+        unicode_checker: BashUnicodeRiskChecker | None = None,
+        exec_ctx_checker: BashExecutionContextChecker | None = None,
+        cross_platform_checker: BashCrossPlatformBinaryChecker | None = None,
+        remote_pipe_checker: BashRemoteShellPipelineChecker | None = None,
+        git_cli_checker: BashGitCliInjectionChecker | None = None,
+        shell_checker: BashShellRiskChecker | None = None,
+        git_checker: BashGitSecurityChecker | None = None,
+    ) -> None:
+        self._canonicalizer = canonicalizer or BashCommandCanonicalizer()
+        self._env_checker = env_checker or BashEnvSecurityChecker()
+        self._unicode_checker = unicode_checker or BashUnicodeRiskChecker()
+        self._exec_ctx_checker = exec_ctx_checker or BashExecutionContextChecker()
+        self._cross_platform_checker = cross_platform_checker or BashCrossPlatformBinaryChecker()
+        self._remote_pipe_checker = remote_pipe_checker or BashRemoteShellPipelineChecker()
+        self._git_cli_checker = git_cli_checker or BashGitCliInjectionChecker()
+        self._shell_checker = shell_checker or BashShellRiskChecker()
+        self._git_checker = git_checker or BashGitSecurityChecker()
+
+    def canonicalize_for_policy(self, command: str) -> str:
+        canonical = self._canonicalizer.canonicalize(command)
+        return canonical or command
+
+    def check_command(
+        self,
+        *,
+        command: str,
+        analysis: BashAstAnalysis,
+        cwd: str,
+    ) -> AuthorizationDecision | None:
+        for checker in (
+            self._env_checker.evaluate(command),
+            self._unicode_checker.evaluate(command),
+            self._exec_ctx_checker.evaluate(command),
+            self._cross_platform_checker.evaluate(command),
+            self._remote_pipe_checker.evaluate(command),
+            self._shell_checker.evaluate(command),
+            self._git_cli_checker.evaluate(command),
+            self._git_checker.evaluate_command(command=command, analysis=analysis, cwd=cwd),
+        ):
+            if checker is not None:
+                return checker.to_decision()
+        return None
+
+    def check_segment(
+        self,
+        *,
+        command: str,
+        analysis: BashAstAnalysis,
+        cwd: str,
+    ) -> AuthorizationDecision | None:
+        result = self._git_checker.evaluate_segment(command=command, analysis=analysis, cwd=cwd)
+        return result.to_decision() if result is not None else None
+
+    def audit_explain(
+        self,
+        *,
+        command: str,
+        analysis: BashAstAnalysis | None = None,
+        cwd: str = "",
+    ) -> dict[str, Any]:
+        """
+        结构化攻防审计快照（不阻断执行）：用于日志、调试与 UI 对齐 CC 式可观测性。
+        """
+        modified = sorted(self._env_checker.collect_modified_vars(command))
+        dangerous = sorted(
+            v for v in modified if v in self._env_checker.BINARY_HIJACK_VARS
+        )
+        first_block: dict[str, Any] | None = None
+        if analysis is not None:
+            d = self.check_command(command=command, analysis=analysis, cwd=cwd or os.getcwd())
+            if d is not None:
+                first_block = {
+                    "behavior": d.behavior,
+                    "policy_id": d.policy_id,
+                    "metadata": d.metadata,
+                }
+        return {
+            "canonical_command": self.canonicalize_for_policy(command),
+            "sys_platform_raw": sys.platform,
+            "host_platform": get_host_platform().value,
+            "modified_env_vars": modified,
+            "dangerous_env_vars": dangerous,
+            "would_block_or_ask": first_block,
+            "shell_pattern_probe": self._shell_checker.probe(command),
+        }