第七章：沙箱终端与安全
沙箱终端架构
Hermes Agent 的沙箱终端是其安全体系的核心组件。它基于 Docker 容器技术构建，为 Agent 的代码执行提供了一个隔离、可控的运行环境。沙箱的设计目标是：在给予 Agent 充分操作能力的同时，严格限制其对宿主机系统的影响范围。
沙箱架构概览
沙箱终端采用分层架构设计：
- 容器层：基于 Docker 的运行隔离，每个会话对应一个独立的容器实例
- 网络层：控制容器与外部网络的通信策略
- 文件系统层：通过挂载卷（Volume）映射控制文件访问
- 策略层：定义允许/禁止的操作规则集合
- 审计层：记录所有执行操作，用于事后追溯与安全审计
# .hermes/sandbox.yaml - 沙箱终端配置
sandbox:
enabled: true
# Docker 配置
docker:
image: "hermes-agent/sandbox:latest"
network_mode: "bridge"
remove_on_exit: true
memory_limit: "2g"
cpu_limit: 2.0
# 卷挂载配置
volumes:
- host_path: /home/user/project
container_path: /workspace
read_only: false
- host_path: /tmp/hermes-cache
container_path: /cache
read_only: true
配置沙箱环境
选择合适的 Docker 镜像
沙箱镜像的选择直接影响 Agent 可用工具的范围和执行效率。Hermes Agent 提供了官方基础镜像，也支持自定义镜像：
# 自定义沙箱 Dockerfile
FROM hermes-agent/sandbox:base
# 安装项目所需依赖
RUN apt-get update && apt-get install -y nodejs npm python3-pip && rm -rf /var/lib/apt/lists/*
# 安装全局工具
RUN npm install -g typescript eslint prettier
RUN pip install pytest black mypy
# 设置工作目录
WORKDIR /workspace
资源限制配置
为了防止 Agent 执行消耗过多系统资源，需要合理配置资源限制：
| 资源类型 | 推荐值 | 说明 |
|---|---|---|
| CPU | 2 核 | 限制容器使用的 CPU 核心数 |
| 内存 | 2 GB | 超过限制的进程将被 OOM Kill |
| 磁盘 | 5 GB | 限制容器可使用的磁盘空间 |
| 网络带宽 | 10 Mbps | 限制容器网络 I/O |
| 进程数 | 100 | 限制容器内可创建的进程总数 |
| 打开文件数 | 1024 | 限制文件描述符数量 |
安全策略
文件系统访问控制
沙箱通过三层文件系统控制来保障安全：
security:
filesystem:
# 第一层：Docker 卷挂载控制
mounts:
- type: bind
source: /workspace
target: /sandbox/workspace
options: [rw, nosuid, nodev]
- type: tmpfs
target: /sandbox/tmp
options: [noexec, size=100m]
# 第二层：Hermes 内部路径白名单
allowed_paths:
- /sandbox/workspace
- /sandbox/tmp
# 第三层：文件操作过滤
forbidden_patterns:
- "*.pem"
- "*.key"
- ".env"
- "credentials*"
网络限制
网络访问控制确保 Agent 只能访问白名单中的外部服务：
security:
network:
# 出站规则
egress:
allowed_ips:
- "0.0.0.0/0" # 允许访问外网
denied_ports:
- 22 # 禁止 SSH
- 3306 # 禁止 MySQL
- 6379 # 禁止 Redis
# DNS 过滤
dns_filter:
enabled: true
blocked_domains:
- "*.malicious.com"
# 入站规则 - 默认禁止所有入站连接
ingress:
enabled: false
沙箱内 vs 沙箱外执行对比
以下表格详细对比了在沙箱内外执行操作的核心差异：
| 对比维度 | 沙箱内执行 | 沙箱外执行 |
|---|---|---|
| 文件访问 | 仅限挂载卷路径 | 全部文件系统 |
| 网络访问 | 受策略控制 | 完整网络访问 |
| 系统命令 | 受限命令集 | 全部系统命令 |
| 执行速度 | 中等（有容器开销） | 快速（直接执行） |
| 隔离性 | 完全隔离 | 无隔离 |
| 环境一致性 | 可重复环境 | 依赖宿主机配置 |
| 资源限制 | 可精确控制 | 依赖系统调度 |
| 审计日志 | 全量记录 | 需要额外配置 |
| 适用场景 | 代码运行、测试执行 | 文件编辑、代码阅读 |
敏感信息保护
Agent 在运行过程中不可避免地会接触到 API Key、密码等敏感信息。Hermes Agent 提供了多层保护机制：
# .hermes/secrets.yaml（需加入 .gitignore）
secrets:
# 环境变量注入（不在日志中显示）
env_vars:
OPENAI_API_KEY: sk-xxxxx
GITHUB_TOKEN: ghp_xxxxx
# 敏感文件保护
protected_files:
- pattern: ".env"
action: block # 阻止读取
- pattern: "config/prod.*"
action: warn # 读取时发出警告
# 日志脱敏规则
redact:
patterns:
- regex: "sk-[A-Za-z0-9]{20,}"
replacement: "sk-****"
- regex: "ghp_[A-Za-z0-9]{36}"
replacement: "ghp_****"
安全最佳实践
- 永远不要将密钥硬编码到提示词或工具配置中：使用环境变量或密钥管理服务
- 启用审计日志：记录所有敏感信息的访问历史
- 定期轮换密钥：设置 API Key 的自动轮换策略
- 最小权限原则：只授予 Agent 完成任务所需的最低权限
- 使用临时凭证：优先使用短期有效的临时凭证而非长期密钥
实战：为项目配置安全的沙箱终端
下面我们为一个实际项目配置完整的沙箱终端环境。
步骤 1：创建项目专属沙箱配置
# .hermes/sandbox.config.yaml
project:
name: "my-web-app"
type: "nextjs"
sandbox:
image:
build:
context: .
dockerfile: .hermes/Dockerfile.sandbox
tags:
- "my-web-app-sandbox:latest"
workspace:
mount_path: /workspace
exclude:
- node_modules
- .next
- .git
environment:
NODE_ENV: development
DATABASE_URL: postgresql://test:test@localhost:5432/test
# API Key 通过外部密钥管理服务注入
OPENAI_API_KEY: ${SECRETS_OPENAI_API_KEY}
步骤 2：创建沙箱入口脚本
#!/bin/bash
# scripts/start-sandbox.sh
set -euo pipefail
SANDBOX_IMAGE="my-web-app-sandbox:latest"
WORKSPACE_DIR=$(pwd)
echo "构建沙箱镜像..."
docker build -t $SANDBOX_IMAGE -f .hermes/Dockerfile.sandbox .
echo "启动沙箱容器..."
docker run -it --rm --name hermes-sandbox --memory="2g" --cpus="2" --network="hermes-net" -v $WORKSPACE_DIR:/workspace:rw -v /tmp/hermes-cache:/cache:ro -e NODE_ENV=development -e OPENAI_API_KEY=${OPENAI_API_KEY:?必须设置 OPENAI_API_KEY} $SANDBOX_IMAGE
步骤 3：验证沙箱安全策略
启动沙箱后，运行以下命令验证安全策略是否生效：
# 测试文件隔离 - 应该被拒绝
cat /etc/shadow
# 输出: cat: /etc/shadow: Permission denied
# 测试网络限制
nc -zv internal.company.com 22
# 输出: 连接超时（根据策略配置）
# 测试资源限制
stress --vm-bytes 3g --vm-keep
# 输出: 进程被 OOM Killer 终止
# 验证工作目录访问
ls /workspace
# 输出: 项目文件列表（正常）
通过以上配置，项目获得了完整的沙箱保护，Agent 可以在安全可控的环境中执行各种操作。合理的沙箱配置既能充分发挥 Agent 的能力，又能确保宿主机的安全。下一章我们将探讨消息网关集成，了解如何将 Hermes Agent 接入聊天和协作平台。