better-dsh 0.2.4 → 0.2.5-a

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

@@ -0,0 +1,664 @@
+---
+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` 选择其他后端。