5 · 审批与安全红线 ★

tools/approval.py，5,802 行。这是整个项目里对抗性思维最密集的一个文件。

5.1 整体结构

5.2 12 条硬红线

HARDLINE_PATTERNS = [
  # rm 递归删除根文件系统或受保护的根目录
  (_RM_FLAG_PREFIX + _hardline_rm_path(r'/(?:(?:\.\.?)?/)*(?:\.\.?)?\**|/ \*'),
                                          "recursive delete of root filesystem"),
  (_RM_FLAG_PREFIX + _hardline_rm_path(_HARDLINE_SYSTEM_DIRS),
                                          "recursive delete of system directory"),
  (_RM_FLAG_PREFIX + _hardline_rm_path(r'(?:~|\$\{?HOME\}?)(?:/?|/\*)?'),
                                          "recursive delete of home directory"),
  # 格式化文件系统
  (_CMDPOS + r'mkfs(\.[a-z0-9]+)?\b',     "format filesystem (mkfs)"),
  # 直接往裸磁盘设备写数据
  (_CMDPOS + r'dd\b[^\n]*\bof=/dev/(sd|nvme|hd|mmcblk|vd|xvd)[a-z0-9]*',
                                          "dd to raw block device"),
  (r'>\s*/dev/(sd|nvme|hd|mmcblk|vd|xvd)[a-z0-9]*\b',
                                          "redirect to raw block device"),
  # 分叉炸弹：无限自我复制进程，直接卡死机器
  (r':\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:',        "fork bomb"),
  # 杀死系统所有进程
  (_CMDPOS + r'kill\s+(-[^\s]+\s+)*-1\b', "kill all processes"),
  # 关机 / 重启（四种写法）
  (_CMDPOS + r'(shutdown|reboot|halt|poweroff)\b',      "system shutdown/reboot"),
  (_CMDPOS + r'init\s+[06]\b',                          "init 0/6"),
  (_CMDPOS + r'systemctl\s+(poweroff|reboot|halt|kexec)\b', "systemctl poweroff/reboot"),
  (_CMDPOS + r'telinit\s+[06]\b',                       "telinit 0/6"),
]

_HARDLINE_SYSTEM_DIRS = (
    r'/home|/home/\*|/root|/root/\*|/etc|/etc/\*|/usr|/usr/\*|'
    r'/var|/var/\*|/bin|/bin/\*|/sbin|/sbin/\*|/boot|/boot/\*|/lib|/lib/\*'
)

hermes-agent/tools/approval.py

「无条件」的意思是：用户配了什么都没用，这些命令永远不会被执行。

5.3 真正的难点：区分「命令」和「数据」

一个真实的事故

最朴素的实现是 if "rm -rf /" in command: 拦截。源码注释记录了它造成的问题：

解法：命令位置锚点

_CMDPOS = (
    # 行首 / 命令分隔符之后 / 子 shell 开启符之后 / sudo|env|exec 包装之后
    ...
)

# rm 加上它的标志组，被三条 rm 规则共享。保持成普通的字符串拼接
# （而不是 f-string），这样正则里的反斜杠永远不会出现在 f-string 的
# 替换字段里 —— 那在 Python 3.11 下不支持。
_RM_FLAG_PREFIX = _CMDPOS + r'rm\s+(-[^\s]*\s+)*'

_CMDPOS 只在这几个位置匹配：

而在 --title "block rm -rf / spellings" 里，rm 前面是空格和引号，不属于上述任何一种位置 —— 所以不匹配，命令正常执行。

路径归一化：哪些写法其实等于根目录

那条根目录规则的正则是 /(?:(?:\.\.?)?/)*(?:\.\.?)?\**|/ \*，注释解释了它的设计：

注释里还提到：「显式的 "/ \*" 分支保留了「斜杠-空格-通配符」这种写法（rm -rf / *，shell 看到的是两个参数：/ 和通配符 *）」 —— 这是一个经典的手滑事故写法（本来想删 /tmp/*，多打了个空格）。

5.4 引号遮蔽：但要给「真会执行的部分」留后门

有两条红线规则没有命令名可以锚定 —— 重定向符号 > /dev/sda 和分叉炸弹的函数定义，它们在命令行任意位置都有效。

_QUOTE_MASKED_HARDLINE_DESCRIPTIONS = frozenset({
    "redirect to raw block device",
    "fork bomb",
})

HARDLINE_PATTERNS_COMPILED = [
    (re.compile(pattern, _RE_FLAGS),
     description,
     description in _QUOTE_MASKED_HARDLINE_DESCRIPTIONS)     # ★ 第三个字段：要不要遮蔽
    for pattern, description in HARDLINE_PATTERNS
]

遮蔽函数的精确语义

def _mask_quoted_prose(command: str) -> str:
    """Blank out quoted string CONTENT for positionless hardline matching.

    Detection-only rewrite used by the quote-masked hardline rules
    (redirect-to-block-device, fork bomb): text inside single or double
    quotes is data the shell passes as an argument, so `echo "cat f >
    /dev/sda"` must not trip the unconditional floor. Structure is
    preserved: the quote characters themselves stay, and inside double
    quotes `$(...)` command substitutions and backtick spans are kept RAW
    because the shell really executes them (`echo "$(cat f > /dev/sda)"`
    remains a true positive). Unquoted text is untouched.
    """

译：为那些无位置的红线规则，把引号里的内容清空。这是一次仅用于检测的重写……引号里的文字是 shell 作为参数传递的数据，所以 echo "cat f > /dev/sda" 不该撞上无条件红线。结构会被保留：引号字符本身留着，而且双引号里的 $(...) 命令替换和反引号片段保持原样不遮蔽，因为 shell 真的会执行它们。未加引号的文字不动。

5.5 引号不能成为绕过手段

_SHELL_CARRIER_NAMES = frozenset({
    "eval", "sh", "bash", "zsh", "ksh", "dash", "source", ".",
})

def _contains_shell_carrier(command: str) -> bool:
    """Return whether any command-position word is a shell-carrying command."""
    for _, _, word in _iter_shell_command_word_spans(command):
        name = os.path.basename(
            _deobfuscate_shell_word_for_detection(word)     # ★ 反混淆
        ).lower()
        if name in _SHELL_CARRIER_NAMES:
            return True
    return False

逻辑：如果命令里出现了 sh -c "..."、bash -c "..."、eval "..." 这类「把引号内容交给另一个 shell 执行」的命令，那么引号里的东西就是代码而不是散文 —— 遮蔽规则整个失效，必须扫描原始字符串。

注释一句话总结：「quoting is not a bypass」（加引号不是绕过手段）。

三层防御的叠加

还有反混淆

_deobfuscate_shell_word_for_detection（为检测目的对 shell 词做反混淆）处理的是这类写法：

5.6 敏感路径与写入目标

除了危险命令，还有一组针对敏感文件写入的模式：

_SSH_SENSITIVE_PATH   = r'(?:~|\$home|\$\{home\})/\.ssh(?:/|$)'
_HERMES_ENV_PATH      = ...        # ~/.hermes/.env（智能体自己的凭据）
_HERMES_CONFIG_PATH   = ...        # ~/.hermes/config.yaml（智能体自己的配置）
_PROJECT_ENV_PATH     = r'(?:(?:/|\.{1,2}/)?(?:[^\s/"\'`]+/)*\.env(?:\.[^/\s"\'`]+)*)'
_PROJECT_CONFIG_PATH  = r'(?:(?:/|\.{1,2}/)?(?:[^\s/"\'`]+/)*config\.yaml)'
_SHELL_RC_FILES       = (...)      # .bashrc / .zshrc 等 shell 启动脚本
_CREDENTIAL_FILES     = (...)
_MACOS_PRIVATE_SYSTEM_PATH = r'/private/(?:etc|var|tmp|home)/'
_SYSTEM_CONFIG_PATH   = (...)

_SENSITIVE_WRITE_TARGET         = (...)
_USER_SENSITIVE_WRITE_TARGET    = (...)
_PROJECT_SENSITIVE_WRITE_TARGET = rf'(?:{_PROJECT_ENV_PATH}|{_PROJECT_CONFIG_PATH})'

_COMMAND_TAIL           = r'(?:\s*(?:&&|\|\||;).*)?$'
_WRITE_TARGET_BOUNDARY  = r'(?=[\s;&|<>"\']|$)'

另外两个正则值得注意：

• _COMMAND_TAIL —— 匹配「命令后面还跟着更多命令」的情况（&&、||、;）。防止 echo ok && rm -rf / 这种把危险命令藏在后面的写法。
• _WRITE_TARGET_BOUNDARY —— 一个前瞻断言，要求写入目标后面必须是空白、分隔符或行尾。防止 .env 误匹配 .envrc 这类不同的文件。

5.7 sudo 标准输入守卫

_SUDO_STDIN_RE = re.compile(...)
def _check_sudo_stdin_guard(command: str) -> tuple: ...
def _sudo_stdin_block_result(description: str) -> dict: ...

这防的是 echo 密码 | sudo -S 危险命令 这种写法 —— sudo -S 表示「从标准输入读密码」，所以可以把密码通过管道喂进去，完全绕过交互式的密码确认。

而交互式密码确认本来是最后一道人工闸门。绕过它意味着智能体可以在用户毫不知情的情况下执行任意特权命令。

5.8 性能：预编译的理由

# 在模块加载时构建这些，可以消除每个进程第一次调用 terminal() 时
# 约 2.6 毫秒的冷缓存 re.compile 扇出开销
# （12 条 HARDLINE + 47 条 DANGEROUS 模式，每一条都可能因为程序其他
#  地方无关的正则操作，而被 Python 那个只有 512 项的 re._cache 挤出去）。
_RE_FLAGS = re.IGNORECASE | re.DOTALL
HARDLINE_PATTERNS_COMPILED = [...]

两层问题：

1. 首次编译开销 —— 59 条正则第一次使用时要现场编译，约 2.6 毫秒
2. 缓存被挤出 —— Python 内置的正则缓存只有 512 项。程序其他地方一忙（比如日志格式化、文本处理），这些安全正则就会被挤出去，导致反复重新编译

预编译成模块级常量之后，两个问题都消失了。

5.9 被拦截命令的留存

def _save_blocked_payload(command: str) -> Optional[str]: ...
def _hardline_block_result(description: str, command: str = "") -> dict: ...
def _user_deny_block_result(pattern: str) -> dict: ...

_save_blocked_payload（保存被拦截的载荷）把被拦下来的命令存起来。用途有两个：

• 取证 —— 如果真的发生了攻击，可以回溯攻击者试图执行什么
• 误报分析 —— 如果用户抱怨「正常命令被拦了」，可以看到具体是哪条规则命中了什么

5.10 智能审批：可选的模型判断

def _prepare_smart_approval_observer(...)
def _observe_smart_approval_verdict(payload: dict | None, verdict: str) -> None
def _fire_approval_hook(hook_name: str, **kwargs) -> None

除了确定性规则，Hermes 还有一个可选的「智能审批」—— 用模型来判断某个操作安不安全。

注意函数名里的 observer（观察者）和 verdict（裁决）：这套机制被设计成可观测的，每次裁决都会被记录。这样才能评估「智能审批的准确率是多少、误判了哪些」。

5.11 上下文感知：不同场景不同策略

def set_hermes_interactive_context(interactive: bool) -> contextvars.Token
def reset_hermes_interactive_context(token: contextvars.Token) -> None
def _is_interactive_cli() -> bool
def _is_cron_approval_context() -> bool
def _is_single_query_approval_context() -> bool
def _is_gateway_approval_context() -> bool
def _get_session_platform() -> str
def _resolve_cli_approval_callback(approval_callback=None)
def _should_fall_through_to_cli_approval(...)

def set_current_session_key(session_key: str) -> contextvars.Token[str]
def get_current_session_key(default: str = "default") -> str
def set_current_observability_context(...)

用的是 Python 的 contextvars（上下文变量）—— 一种「在异步调用链里自动传递、且各协程互不干扰」的变量机制。

而不同场景的策略差异是：

5.12 这一层的定位：最外面也最薄