better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/security.md

@@ -1,664 +0,0 @@
----
-sidebar_position: 8
-title: "安全"
-description: "安全模型、危险命令审批、用户授权、容器隔离及生产部署最佳实践"
----
-
-# 安全
-
-Hermes Agent 采用纵深防御安全模型。本页涵盖所有安全边界——从命令审批到容器隔离，再到消息平台上的用户授权。
-
-## 概述
-
-安全模型共有七层：
-
-1. **用户授权** — 谁可以与 Agent 通信（允许列表、DM 配对）
-2. **危险命令审批** — 针对破坏性操作的人工审核环节
-3. **容器隔离** — Docker/Singularity/Modal 沙箱及加固配置
-4. **MCP 凭据过滤** — MCP 子进程的环境变量隔离
-5. **上下文文件扫描** — 检测项目文件中的 prompt（提示词）注入
-6. **跨会话隔离** — 会话之间无法访问彼此的数据或状态；cron 任务存储路径已针对路径遍历攻击进行加固
-7. **输入清理** — 终端工具后端中的工作目录参数会经过允许列表验证，以防止 shell 注入
-
-## 危险命令审批
-
-在执行任何命令之前，Hermes 会将其与一份精心维护的危险模式列表进行比对。若匹配，用户必须明确批准。
-
-### 审批模式
-
-审批系统支持三种模式，通过 `~/.hermes/config.yaml` 中的 `approvals.mode` 配置：
-
-```yaml
-approvals:
-  mode: smart     # smart | manual | off
-  timeout: 300    # 等待用户响应的秒数（默认：300）
-```
-
-| 模式 | 行为 |
-|------|----------|
-| **smart**（默认） | 使用辅助 LLM 评估风险。低风险命令（如 `python -c "print('hello')"`）仅对当前命令自动批准，真正危险的命令自动拒绝，不确定的情况升级为手动提示。 |
-| **manual** | 始终提示用户审批危险命令。 |
-| **off** | 禁用所有审批检查——等同于使用 `--yolo` 运行。所有命令无需提示即可执行。 |
-
-:::warning
-设置 `approvals.mode: off` 将禁用所有安全提示。仅在受信任的环境（CI/CD、容器等）中使用。
-:::
-
-### YOLO 模式
-
-YOLO 模式会绕过当前会话中**所有**危险命令审批提示。可通过以下三种方式激活：
-
-1. **CLI 标志**：使用 `hermes --yolo` 或 `hermes chat --yolo` 启动会话
-2. **斜杠命令**：在会话中输入 `/yolo` 以切换开/关
-3. **环境变量**：设置 `HERMES_YOLO_MODE=1`
-
-`/yolo` 命令是一个**切换开关**——每次使用都会翻转模式的开/关状态：
-
-```
-> /yolo
-  ⚡ YOLO mode ON — all commands auto-approved. Use with caution.
-
-> /yolo
-  ⚠ YOLO mode OFF — dangerous commands will require approval.
-```
-
-YOLO 模式在 CLI 和 gateway 会话中均可使用。在内部，它会设置 `HERMES_YOLO_MODE` 环境变量，该变量在每次命令执行前都会被检查。
-
-当 YOLO 激活时，Hermes 会显示两个持久的视觉提醒，以确保用户不会忘记审批提示已被绕过：
-
-- 当 YOLO 已激活时，会话开始时显示一条红色横幅：`⚠ YOLO mode — all approval prompts bypassed`。YOLO 关闭时隐藏，以保持默认横幅整洁。
-- 状态栏中所有宽度层级均显示 `⚠ YOLO` 片段，随着 YOLO 的切换实时更新（富文本渲染器和纯文本回退均支持）。
-
-:::danger
-YOLO 模式会禁用会话中**所有**危险命令安全检查——**但硬性黑名单除外**（见下文）。仅在完全信任所生成命令的情况下使用（例如，在一次性环境中经过充分测试的自动化脚本）。
-:::
-
-对于破坏性会话斜杠命令（`/clear`、`/new` / `/reset`、`/undo`、`/exit --delete`），CLI 在执行前也会提示确认。参见[斜杠命令——破坏性命令的确认提示](../reference/slash-commands.md#confirmation-prompts-for-destructive-commands)。
-
-### 硬性黑名单（始终生效的底线）
-
-某些命令极具破坏性——不可逆的文件系统清除、fork 炸弹、直接写入块设备——无论以下任何情况，Hermes 都**拒绝**执行：
-
-- `--yolo` / `/yolo` 已开启
-- `approvals.mode: off`
-- Cron 任务以无头 `approve` 模式运行
-- 用户明确点击"始终允许"
-
-黑名单是 `--yolo` 之下的底线。它在审批层看到命令**之前**就会触发，且没有任何覆盖标志。当前涵盖的模式（非详尽列表；与 `tools/approval.py::UNRECOVERABLE_BLOCKLIST` 保持同步）：
-
-| 模式 | 为何列为硬性规则 |
-|---|---|
-| `rm -rf /` 及明显变体 | 清除文件系统根目录 |
-| `rm -rf --no-preserve-root /` | 明确表示"我就是要删根目录"的变体 |
-| `:(){ :\|:& };:` （bash fork 炸弹） | 使主机挂起直至重启 |
-| `mkfs.*` 作用于已挂载的根设备 | 格式化运行中的系统 |
-| `dd if=/dev/zero of=/dev/sd*` | 清零物理磁盘 |
-| 将不受信任的 URL 通过管道传给 `sh`（作用于根文件系统顶层） | 远程代码执行攻击面过大，无法批准 |
-
-若触发黑名单，工具调用会向 Agent 返回一条说明性错误，且不执行任何操作。如果某个合法工作流确实需要这些命令（例如，你是一个清除并重装流水线的操作者），请在 Agent 外部运行。
-
-### 审批超时
-
-当危险命令提示出现时，用户有一段可配置的时间来响应。若在超时内未响应，命令将**默认被拒绝**（故障关闭）。
-
-在 `~/.hermes/config.yaml` 中配置超时：
-
-```yaml
-approvals:
-  timeout: 300  # 秒（默认：300）
-```
-
-### 触发审批的条件
-
-以下模式会触发审批提示（定义于 `tools/approval.py`）：
-
-| 模式 | 描述 |
-|---------|-------------|
-| `rm -r` / `rm --recursive` | 递归删除 |
-| `rm ... /` | 在根路径下删除 |
-| `chmod 777/666` / `o+w` / `a+w` | 全局/其他用户可写权限 |
-| `chmod --recursive` 配合不安全权限 | 递归全局/其他用户可写（长标志） |
-| `chown -R root` / `chown --recursive root` | 递归 chown 为 root |
-| `mkfs` | 格式化文件系统 |
-| `dd if=` | 磁盘复制 |
-| `> /dev/sd` | 写入块设备 |
-| `DROP TABLE/DATABASE` | SQL DROP |
-| `DELETE FROM`（不含 WHERE） | 不含 WHERE 的 SQL DELETE |
-| `TRUNCATE TABLE` | SQL TRUNCATE |
-| `> /etc/` | 覆盖系统配置 |
-| `systemctl stop/restart/disable/mask` | 停止/重启/禁用系统服务 |
-| `kill -9 -1` | 杀死所有进程 |
-| `pkill -9` | 强制杀死进程 |
-| Fork 炸弹模式 | Fork 炸弹 |
-| `bash -c` / `sh -c` / `zsh -c` / `ksh -c` | 通过 `-c` 标志执行 shell 命令（包括组合标志如 `-lc`） |
-| `python -e` / `perl -e` / `ruby -e` / `node -c` | 通过 `-e`/`-c` 标志执行脚本 |
-| `curl ... \| sh` / `wget ... \| sh` | 将远程内容通过管道传给 shell |
-| `bash <(curl ...)` / `sh <(wget ...)` | 通过进程替换执行远程脚本 |
-| `tee` 写入 `/etc/`、`~/.ssh/`、`~/.hermes/.env` | 通过 tee 覆盖敏感文件 |
-| `>` / `>>` 写入 `/etc/`、`~/.ssh/`、`~/.hermes/.env` | 通过重定向覆盖敏感文件 |
-| `xargs rm` | xargs 配合 rm |
-| `find -exec rm` / `find -delete` | find 配合破坏性操作 |
-| `cp`/`mv`/`install` 写入 `/etc/` | 复制/移动文件到系统配置目录 |
-| `sed -i` / `sed --in-place` 作用于 `/etc/` | 就地编辑系统配置 |
-| `pkill`/`killall` hermes/gateway | 防止自我终止 |
-| `gateway run` 配合 `&`/`disown`/`nohup`/`setsid` | 防止在服务管理器外启动 gateway |
-
-:::info
-**容器绕过**：在 `docker`、`singularity`、`modal`、`daytona` 或 `vercel_sandbox` 后端运行时，危险命令检查会被**跳过**，因为容器本身就是安全边界。容器内的破坏性命令不会危害宿主机。
-:::
-
-### 审批流程（CLI）
-
-在交互式 CLI 中，危险命令会显示内联审批提示：
-
-```
-  ⚠️  DANGEROUS COMMAND: recursive delete
-      rm -rf /tmp/old-project
-
-      [o]nce  |  [s]ession  |  [a]lways  |  [d]eny
-
-      Choice [o/s/a/D]:
-```
-
-四个选项：
-
-- **once** — 仅允许本次执行
-- **session** — 在本次会话剩余时间内允许此模式
-- **always** — 添加到永久允许列表（保存至 `config.yaml`）
-- **deny**（默认） — 阻止该命令
-
-### 审批流程（Gateway/消息平台）
-
-在消息平台上，Agent 会将危险命令详情发送到聊天中，并等待用户回复：
-
-- 回复 **yes**、**y**、**approve**、**ok** 或 **go** 以批准
-- 回复 **no**、**n**、**deny** 或 **cancel** 以拒绝
-
-运行 gateway 时，`HERMES_EXEC_ASK=1` 环境变量会自动设置。
-
-### 永久允许列表
-
-通过"always"批准的命令会保存到 `~/.hermes/config.yaml`：
-
-```yaml
-# 永久允许的危险命令模式
-command_allowlist:
-  - rm
-  - systemctl
-```
-
-这些模式在启动时加载，并在所有后续会话中静默批准。
-
-:::tip
-使用 `hermes config edit` 查看或删除永久允许列表中的模式。
-:::
-
-## 用户授权（Gateway）
-
-运行消息 gateway 时，Hermes 通过分层授权系统控制谁可以与机器人交互。
-
-### 授权检查顺序
-
-`_is_user_authorized()` 方法按以下顺序检查：
-
-1. **每平台允许所有用户标志**（如 `DISCORD_ALLOW_ALL_USERS=true`）
-2. **DM 配对已批准列表**（通过配对码批准的用户）
-3. **平台专属允许列表**（如 `TELEGRAM_ALLOWED_USERS=12345,67890`）
-4. **全局允许列表**（`GATEWAY_ALLOWED_USERS=12345,67890`）
-5. **全局允许所有用户**（`GATEWAY_ALLOW_ALL_USERS=true`）
-6. **默认：拒绝**
-
-### 平台允许列表
-
-在 `~/.hermes/.env` 中以逗号分隔的值设置允许的用户 ID：
-
-```bash
-# 平台专属允许列表
-TELEGRAM_ALLOWED_USERS=123456789,987654321
-DISCORD_ALLOWED_USERS=111222333444555666
-WHATSAPP_ALLOWED_USERS=15551234567
-SLACK_ALLOWED_USERS=U01ABC123
-
-# 跨平台允许列表（对所有平台均检查）
-GATEWAY_ALLOWED_USERS=123456789
-
-# 每平台允许所有用户（谨慎使用）
-DISCORD_ALLOW_ALL_USERS=true
-
-# 全局允许所有用户（极度谨慎使用）
-GATEWAY_ALLOW_ALL_USERS=true
-```
-
-:::warning
-若**未配置任何允许列表**且未设置 `GATEWAY_ALLOW_ALL_USERS`，则**所有用户均被拒绝**。Gateway 在启动时会记录警告：
-
-```
-No user allowlists configured. All unauthorized users will be denied.
-Set GATEWAY_ALLOW_ALL_USERS=true in ~/.hermes/.env to allow open access,
-or configure platform allowlists (e.g., TELEGRAM_ALLOWED_USERS=your_id).
-```
-:::
-
-### DM 配对系统
-
-为实现更灵活的授权，Hermes 提供了基于验证码的配对系统。无需预先提供用户 ID，未知用户会收到一次性配对码，由机器人所有者通过 CLI 批准。
-
-**工作原理：**
-
-1. 未知用户向机器人发送 DM
-2. 机器人回复一个 8 位配对码
-3. 机器人所有者在 CLI 上运行 `hermes pairing approve <platform> <code>`
-4. 该用户在该平台上获得永久批准
-
-在 `~/.hermes/config.yaml` 中控制未授权私信的处理方式：
-
-```yaml
-unauthorized_dm_behavior: pair
-
-whatsapp:
-  unauthorized_dm_behavior: ignore
-```
-
-- `pair` 为默认值。未授权的 DM 会收到配对码回复。
-- `ignore` 静默丢弃未授权的 DM。
-- 平台部分会覆盖全局默认值，因此可以在 Telegram 上保持配对，同时让 WhatsApp 保持静默。
-
-**安全特性**（基于 OWASP + NIST SP 800-63-4 指南）：
-
-| 特性 | 详情 |
-|---------|---------|
-| 验证码格式 | 8 位字符，来自 32 位无歧义字母表（不含 0/O/1/I） |
-| 随机性 | 密码学安全（`secrets.choice()`） |
-| 验证码有效期 | 1 小时过期 |
-| 速率限制 | 每用户每 10 分钟 1 次请求 |
-| 待处理上限 | 每平台最多 3 个待处理验证码 |
-| 锁定 | 5 次失败的批准尝试 → 1 小时锁定 |
-| 文件安全 | 所有配对数据文件执行 `chmod 0600` |
-| 日志 | 验证码永不记录到 stdout |
-
-**配对 CLI 命令：**
-
-```bash
-# 列出待处理和已批准的用户
-hermes pairing list
-
-# 批准配对码
-hermes pairing approve telegram ABC12DEF
-
-# 撤销用户访问权限
-hermes pairing revoke telegram 123456789
-
-# 清除所有待处理验证码
-hermes pairing clear-pending
-```
-
-**存储：** 配对数据存储于 `~/.hermes/pairing/`，按平台分为独立的 JSON 文件：
-- `{platform}-pending.json` — 待处理的配对请求
-- `{platform}-approved.json` — 已批准的用户
-- `_rate_limits.json` — 速率限制和锁定追踪
-
-## 容器隔离
-
-使用 `docker` 终端后端时，Hermes 对每个容器应用严格的安全加固。
-
-### Docker 安全标志
-
-每个容器均使用以下标志运行（定义于 `tools/environments/docker.py`）：
-
-```python
-_SECURITY_ARGS = [
-    "--cap-drop", "ALL",                          # 丢弃所有 Linux capabilities
-    "--cap-add", "DAC_OVERRIDE",                  # root 可写入绑定挂载目录
-    "--cap-add", "CHOWN",                         # 包管理器需要文件所有权
-    "--cap-add", "FOWNER",                        # 包管理器需要文件所有权
-    "--security-opt", "no-new-privileges",         # 阻止权限提升
-    "--pids-limit", "256",                         # 限制进程数量
-    "--tmpfs", "/tmp:rw,nosuid,size=512m",         # 有大小限制的 /tmp
-    "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=256m",  # 禁止执行的 /var/tmp
-    "--tmpfs", "/run:rw,noexec,nosuid,size=64m",   # 禁止执行的 /run
-]
-```
-
-### 资源限制
-
-容器资源可在 `~/.hermes/config.yaml` 中配置：
-
-```yaml
-terminal:
-  backend: docker
-  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
-  docker_forward_env: []  # 仅显式允许列表；空值可防止密钥进入容器
-  container_cpu: 1        # CPU 核心数
-  container_memory: 5120  # MB（默认 5GB）
-  container_disk: 51200   # MB（默认 50GB，需要 XFS 上的 overlay2）
-  container_persistent: true  # 跨会话持久化文件系统
-```
-
-### 文件系统持久化
-
-- **持久模式**（`container_persistent: true`）：从 `~/.hermes/sandboxes/docker/<task_id>/` 绑定挂载 `/workspace` 和 `/root`
-- **临时模式**（`container_persistent: false`）：工作区使用 tmpfs——清理后所有内容丢失
-
-:::tip
-对于生产 gateway 部署，使用 `docker`、`modal`、`daytona` 或 `vercel_sandbox` 后端，将 Agent 命令与宿主机系统隔离。这样可以完全消除危险命令审批的需要。
-:::
-
-:::warning
-若向 `terminal.docker_forward_env` 添加名称，这些变量会被有意注入容器供终端命令使用。这对于任务专属凭据（如 `GITHUB_TOKEN`）很有用，但也意味着容器内运行的代码可以读取并泄露这些变量。
-:::
-
-## 终端后端安全对比
-
-| 后端 | 隔离 | 危险命令检查 | 适用场景 |
-|---------|-----------|-------------------|----------|
-| **local** | 无——在宿主机上运行 | ✅ 是 | 开发、受信任用户 |
-| **ssh** | 远程机器 | ✅ 是 | 在独立服务器上运行 |
-| **docker** | 容器 | ❌ 跳过（容器即边界） | 生产 gateway |
-| **singularity** | 容器 | ❌ 跳过 | HPC 环境 |
-| **modal** | 云沙箱 | ❌ 跳过 | 可扩展的云隔离 |
-| **daytona** | 云沙箱 | ❌ 跳过 | 持久化云工作区 |
-| **vercel_sandbox** | 云微虚拟机 | ❌ 跳过 | 带快照持久化的云执行 |
-
-## 环境变量透传 {#environment-variable-passthrough}
-
-`execute_code` 和 `terminal` 都会从子进程中剥离敏感环境变量，以防止 LLM 生成的代码泄露凭据。但是，声明了 `required_environment_variables` 的技能（skill）确实需要访问这些变量。
-
-### 工作原理
-
-两种机制允许特定变量通过沙箱过滤器：
-
-**1. 技能作用域透传（自动）**
-
-当技能通过 `skill_view` 或 `/skill` 命令加载，且声明了 `required_environment_variables` 时，环境中实际已设置的这些变量会自动注册为透传变量。尚未设置（仍处于待配置状态）的变量**不会**被注册。
-
-```yaml
-# 在技能的 SKILL.md frontmatter 中
-required_environment_variables:
-  - name: TENOR_API_KEY
-    prompt: Tenor API key
-    help: Get a key from https://developers.google.com/tenor
-```
-
-加载此技能后，`TENOR_API_KEY` 会透传到 `execute_code`、`terminal`（本地）**以及远程后端（Docker、Modal）**——无需手动配置。
-
-:::info Docker & Modal
-在 v0.5.1 之前，Docker 的 `forward_env` 与技能透传是独立的系统。现在它们已合并——技能声明的环境变量会自动转发到 Docker 容器和 Modal 沙箱，无需手动添加到 `docker_forward_env`。
-:::
-
-**2. 基于配置的透传（手动）**
-
-对于未被任何技能声明的环境变量，将其添加到 `config.yaml` 中的 `terminal.env_passthrough`：
-
-```yaml
-terminal:
-  env_passthrough:
-    - MY_CUSTOM_KEY
-    - ANOTHER_TOKEN
-```
-
-### 凭据文件透传（OAuth token 等） {#credential-file-passthrough}
-
-某些技能需要在沙箱中访问**文件**（而非仅环境变量）——例如，Google Workspace 将 OAuth token 存储为活跃 profile 的 `HERMES_HOME` 下的 `google_token.json`。技能在 frontmatter 中声明这些文件：
-
-```yaml
-required_credential_files:
-  - path: google_token.json
-    description: Google OAuth2 token (created by setup script)
-  - path: google_client_secret.json
-    description: Google OAuth2 client credentials
-```
-
-加载后，Hermes 会检查这些文件是否存在于活跃 profile 的 `HERMES_HOME` 中，并将其注册为挂载：
-
-- **Docker**：只读绑定挂载（`-v host:container:ro`）
-- **Modal**：在沙箱创建时挂载，并在每次命令前同步（处理会话中途的 OAuth 配置）
-- **本地**：无需操作（文件已可访问）
-
-也可以在 `config.yaml` 中手动列出凭据文件：
-
-```yaml
-terminal:
-  credential_files:
-    - google_token.json
-    - my_custom_oauth_token.json
-```
-
-路径相对于 `~/.hermes/`。文件在容器内挂载到 `/root/.hermes/`。
-
-### 各沙箱的过滤规则
-
-| 沙箱 | 默认过滤 | 透传覆盖 |
-|---------|---------------|---------------------|
-| **execute_code** | 阻止名称中包含 `KEY`、`TOKEN`、`SECRET`、`PASSWORD`、`CREDENTIAL`、`PASSWD`、`AUTH` 的变量；仅允许安全前缀变量通过 | ✅ 透传变量绕过两项检查 |
-| **terminal**（本地） | 阻止明确的 Hermes 基础设施变量（提供商密钥、gateway token、工具 API 密钥） | ✅ 透传变量绕过黑名单 |
-| **terminal**（Docker） | 默认不传入宿主机环境变量 | ✅ 透传变量 + `docker_forward_env` 通过 `-e` 转发 |
-| **terminal**（Modal） | 默认不传入宿主机环境/文件 | ✅ 凭据文件挂载；环境变量通过同步透传 |
-| **MCP** | 阻止所有变量，仅允许安全系统变量 + 显式配置的 `env` | ❌ 不受透传影响（改用 MCP `env` 配置） |
-
-### 安全注意事项
-
-- 透传仅影响你或你的技能明确声明的变量——任意 LLM 生成代码的默认安全态势不变
-- 凭据文件以**只读**方式挂载到 Docker 容器中
-- Skills Guard 在安装前会扫描技能内容中的可疑环境变量访问模式
-- 缺失/未设置的变量永远不会被注册（不存在的内容无法泄露）
-- Hermes 基础设施密钥（提供商 API 密钥、gateway token）不应添加到 `env_passthrough`——它们有专用机制
-
-## MCP 凭据处理
-
-MCP（Model Context Protocol）服务器子进程接收**经过过滤的环境**，以防止意外泄露凭据。
-
-### 安全环境变量
-
-从宿主机传递到 MCP stdio 子进程的变量仅限以下几项：
-
-```
-PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
-```
-
-以及所有 `XDG_*` 变量。所有其他环境变量（API 密钥、token、密钥）均被**剥离**。
-
-在 MCP 服务器的 `env` 配置中显式定义的变量会被透传：
-
-```yaml
-mcp_servers:
-  github:
-    command: "npx"
-    args: ["-y", "@modelcontextprotocol/server-github"]
-    env:
-      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."  # 仅此变量被传递
-```
-
-### 凭据脱敏
-
-MCP 工具的错误消息在返回给 LLM 之前会经过清理。以下模式会被替换为 `[REDACTED]`：
-
-- GitHub PAT（`ghp_...`）
-- OpenAI 风格密钥（`sk-...`）
-- Bearer token
-- `token=`、`key=`、`API_KEY=`、`password=`、`secret=` 参数
-
-### 网站访问策略
-
-你可以限制 Agent 通过其 Web 和浏览器工具可访问的网站。这对于防止 Agent 访问内部服务、管理面板或其他敏感 URL 非常有用。
-
-```yaml
-# 在 ~/.hermes/config.yaml 中
-security:
-  website_blocklist:
-    enabled: true
-    domains:
-      - "*.internal.company.com"
-      - "admin.example.com"
-    shared_files:
-      - "/etc/hermes/blocked-sites.txt"
-```
-
-当请求被阻止的 URL 时，工具会返回一条错误，说明该域名已被策略阻止。黑名单在 `web_search`、`web_extract`、`browser_navigate` 及所有支持 URL 的工具中均强制执行。
-
-完整详情请参见配置指南中的[网站黑名单](/user-guide/configuration#website-blocklist)。
-
-### SSRF 防护
-
-所有支持 URL 的工具（网页搜索、网页提取、视觉、浏览器）在获取 URL 之前都会进行验证，以防止服务器端请求伪造（SSRF）攻击。被阻止的地址包括：
-
-- **私有网络**（RFC 1918）：`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`
-- **回环地址**：`127.0.0.0/8`、`::1`
-- **链路本地地址**：`169.254.0.0/16`（包括 `169.254.169.254` 处的云元数据）
-- **CGNAT / 共享地址空间**（RFC 6598）：`100.64.0.0/10`（Tailscale、WireGuard VPN）
-- **云元数据主机名**：`metadata.google.internal`、`metadata.goog`
-- **保留地址、多播地址和未指定地址**
-
-SSRF 防护对面向互联网的使用始终有效，DNS 失败被视为阻止（故障关闭）。重定向链在每一跳都会重新验证，以防止基于重定向的绕过。
-
-#### 有意允许私有 URL
-
-某些场景确实需要访问私有/内部 URL——将 `home.arpa` 解析到 RFC 1918 空间的家庭网络、仅限局域网的 Ollama/llama.cpp 端点、内部 wiki、云元数据调试等。对于这些情况，提供了一个全局选项：
-
-```yaml
-security:
-  allow_private_urls: true   # 默认：false
-```
-
-开启后，Web 工具、浏览器、视觉 URL 获取和 gateway 媒体下载不再拒绝 RFC 1918 / 回环 / 链路本地 / CGNAT / 云元数据目标。**这是一个有意为之的信任边界**——仅在 Agent 针对本地网络执行任意 prompt 注入 URL 属于可接受风险的机器上启用。面向公众的 gateway 应保持关闭。
-
-主机子字符串防护（即使底层 IP 是公共的，也能阻止 Unicode 同形字域名欺骗）无论此设置如何均保持开启。
-
-### Tirith 预执行安全扫描
-
-Hermes 集成了 [tirith](https://github.com/sheeki03/tirith) 用于在执行前进行内容级命令扫描。Tirith 能检测单纯模式匹配所遗漏的威胁：
-
-- 同形字 URL 欺骗（国际化域名攻击）
-- 管道传解释器模式（`curl | bash`、`wget | sh`）
-- 终端注入攻击
-
-Tirith 在首次使用时从 GitHub Releases 自动安装，并进行 SHA-256 校验和验证（若 cosign 可用，还会进行 cosign 来源验证）。
-
-```yaml
-# 在 ~/.hermes/config.yaml 中
-security:
-  tirith_enabled: true       # 启用/禁用 tirith 扫描（默认：true）
-  tirith_path: "tirith"      # tirith 二进制路径（默认：PATH 查找）
-  tirith_timeout: 5          # 子进程超时（秒）
-  tirith_fail_open: true     # tirith 不可用时允许执行（默认：true）
-```
-
-当 `tirith_fail_open` 为 `true`（默认）时，若 tirith 未安装或超时，命令照常执行。在高安全性环境中，将其设置为 `false` 可在 tirith 不可用时阻止命令执行。
-
-Tirith 为 Linux（x86_64 / aarch64）和 macOS（x86_64 / arm64）提供预构建二进制文件。在没有预构建二进制文件的平台（Windows 等）上，tirith 会被静默跳过——模式匹配防护仍然运行，CLI 不会显示"不可用"横幅。若要在 Windows 上使用 tirith，请在 WSL 下运行 Hermes。
-
-Tirith 的判定与审批流程集成：安全命令直接通过，可疑和被阻止的命令会触发用户审批，并附上完整的 tirith 发现（严重性、标题、描述、更安全的替代方案）。用户可以批准或拒绝——默认选择为拒绝，以确保无人值守场景的安全。
-
-### 上下文文件注入防护
-
-上下文文件（AGENTS.md、.cursorrules、SOUL.md）在被纳入系统 prompt 之前会扫描 prompt 注入。扫描器检查以下内容：
-
-- 指示忽略/无视先前指令的内容
-- 含有可疑关键词的隐藏 HTML 注释
-- 尝试读取密钥（`.env`、`credentials`、`.netrc`）
-- 通过 `curl` 泄露凭据
-- 不可见 Unicode 字符（零宽空格、双向覆盖）
-
-被阻止的文件会显示警告：
-
-```
-[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
-```
-
-## 生产部署最佳实践
-
-### Gateway 部署检查清单
-
-1. **设置明确的允许列表** — 生产环境中切勿使用 `GATEWAY_ALLOW_ALL_USERS=true`
-2. **使用容器后端** — 在 config.yaml 中设置 `terminal.backend: docker`
-3. **限制资源上限** — 设置合适的 CPU、内存和磁盘限制
-4. **安全存储密钥** — 将 API 密钥保存在具有适当文件权限的 `~/.hermes/.env` 中
-5. **启用 DM 配对** — 尽可能使用配对码，而非硬编码用户 ID
-6. **审查命令允许列表** — 定期审计 config.yaml 中的 `command_allowlist`
-7. **设置 `MESSAGING_CWD`** — 不要让 Agent 在敏感目录中操作
-8. **以非 root 用户运行** — 切勿以 root 身份运行 gateway
-9. **监控日志** — 检查 `~/.hermes/logs/` 中的未授权访问尝试
-10. **保持更新** — 定期运行 `hermes update` 以获取安全补丁
-
-### 保护 API 密钥
-
-```bash
-# 为 .env 文件设置适当权限
-chmod 600 ~/.hermes/.env
-
-# 为不同服务使用独立密钥
-# 切勿将 .env 文件提交到版本控制
-```
-
-### 网络隔离
-
-为获得最高安全性，请在独立的机器或虚拟机上运行 gateway。在 `config.yaml` 中设置 `terminal.backend: ssh`，然后通过 `~/.hermes/.env` 中的环境变量提供主机详情：
-
-```yaml
-# ~/.hermes/config.yaml
-terminal:
-  backend: ssh
-```
-
-```bash
-# ~/.hermes/.env
-TERMINAL_SSH_HOST=agent-worker.local
-TERMINAL_SSH_USER=hermes
-TERMINAL_SSH_KEY=~/.ssh/hermes_agent_key
-```
-
-SSH 连接详情保存在 `.env`（而非 `config.yaml`）中，以避免随 profile 导出时被检入或共享。这样可以将 gateway 的消息连接与 Agent 的命令执行分离。
-
-## 供应链安全公告检查
-
-Hermes 内置了一个公告扫描器，用于标记活跃 venv 中与已知受损版本目录匹配的 Python 包（例如 2026 年 5 月的 `mistralai 2.4.6` 供应链投毒事件）。实现位于 `hermes_cli/security_advisories.py`。
-
-运行方式：
-
-- **CLI 启动横幅。** 若有任何公告匹配，会打印一行警告，并指向 `hermes doctor` 获取完整修复方案。
-- **`hermes doctor`。** 显示所有活跃公告的版本详情和 2-4 步修复说明。
-- **Gateway 启动。** 记录到 `gateway.log`；第一条交互消息会附带简短的操作者横幅。
-
-每条公告都有一个稳定 ID。阅读并处理后，可以永久忽略它：
-
-```bash
-hermes doctor --ack <advisory-id>
-```
-
-确认信息持久化到 `config.security.acked_advisories`，重启后仍有效。旧公告**不会**从目录中删除——保留它们可以确保新安装的用户收到关于历史受损版本的警告，这些版本可能仍缓存在私有镜像中。
-
-检查本身仅使用标准库，每条公告执行一次 `importlib.metadata.version()` 查找，因此在每次启动时运行是安全的。
-
-### 可选依赖的懒加载安装
-
-许多功能（Mistral TTS、ElevenLabs、Honcho 记忆、Bedrock、Slack、Matrix 等）依赖并非每个用户都需要的 Python 包。Hermes 在首次使用时**懒加载**安装这些包，而非在 `hermes-agent[all]` 下急切安装。实现位于 `tools/lazy_deps.py`。
-
-此方案解决的权衡问题：
-
-- **脆弱性。** 当某个额外依赖的传递依赖在 PyPI 上不可用时（因恶意软件被隔离、被撤回、上传损坏），整个 `[all]` 解析会失败，新安装会静默回退到精简版本——同时丢失 10 个以上不相关的额外功能。懒加载安装将每个后端隔离，使一个受损依赖不会破坏不相关的功能。
-- **臃肿。** 只使用一个提供商的用户不再需要拉取数百个永远不会导入的包。
-
-工作原理：
-
-1. 后端模块在其首次导入路径的顶部调用 `ensure("feature.name")`。
-2. 若依赖缺失，`ensure` 检查 `config.yaml` 中的 `security.allow_lazy_installs`（默认 `true`），并为允许列表中的规格运行 venv 作用域的 `pip install`。
-3. 若安装失败或用户已禁用懒加载安装，调用会抛出 `FeatureUnavailable`，附带实际的 pip stderr 和指向 `hermes tools` 的提示。
-
-`tools/lazy_deps.py` 强制执行的安全保证：
-
-| 保证 | 含义 |
-|---|---|
-| 仅限 venv 作用域 | 安装目标为活跃 venv 中的 `sys.executable`——绝不安装到系统 Python |
-| 仅按名称从 PyPI 安装 | 规格接受 `"package>=1.0,<2"` 语法。不允许 `--index-url`、`git+https://` 或 `file:` 路径——恶意的 `config.yaml` 无法重定向安装 |
-| 允许列表 | 只有出现在内置 `LAZY_DEPS` 映射中的规格才能通过此路径安装。功能名称中的拼写错误**不会**获得任意安装语义 |
-| 可选退出 | 设置 `security.allow_lazy_installs: false` 可完全禁用运行时安装。适用于受限网络或严格安全态势 |
-| 无静默重试 | 失败以 `FeatureUnavailable` 形式呈现——不缓存错误状态，不发生重试风暴 |
-
-禁用运行时安装：
-
-```yaml
-# ~/.hermes/config.yaml
-security:
-  allow_lazy_installs: false
-```
-
-禁用后，需要可选依赖的后端会提示用户手动运行安装（`pip install …`）或通过 `hermes tools` 选择其他后端。