第九章：安全机制
🔒 本章详细介绍 MiniClaw 的安全机制，包括命令执行沙箱、数据隐私保护和安全最佳实践。
9.1 安全机制概述
9.1.1 安全设计理念
MiniClaw 的安全机制遵循 最小权限原则 和 防御性编程 理念。
┌─────────────────────────────────────────────────────────────────────┐
│ 安全设计理念 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 传统 AI 助手 MiniClaw 安全机制 │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ │ │ │ │
│ │ 无限制执行 │ │ 白名单沙箱 │ │
│ │ 数据可能泄露 │ │ 本地存储 │ │
│ │ 无安全边界 │ │ 多层防护 │ │
│ │ │ │ │ │
│ └───────────────────┘ └───────────────────┘ │
│ │
│ ❌ 可能执行危险命令 ✅ 仅允许安全命令 │
│ ❌ 数据上传云端 ✅ 数据本地存储 │
│ ❌ 无访问控制 ✅ 多层安全边界 │
│ │
└─────────────────────────────────────────────────────────────────────┘9.1.2 安全架构
┌─────────────────────────────────────────────────────────────────────┐
│ 安全架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ 用户请求 │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 第一层：输入验证 │ │
│ │ │ │
│ │ • 参数类型检查 (Zod Schema) │ │
│ │ • 参数长度限制 │ │
│ │ • 特殊字符过滤 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 第二层：权限检查 │ │
│ │ │ │
│ │ • 命令白名单检查 │ │
│ │ • 文件路径验证 │ │
│ │ • 操作类型限制 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 第三层：执行沙箱 │ │
│ │ │ │
│ │ • 超时控制 (10s) │ │
│ │ • 输出截断 (1MB) │ │
│ │ • 工作目录限制 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 第四层：数据保护 │ │
│ │ │ │
│ │ • 本地存储 │ │
│ │ • 敏感信息脱敏 │ │
│ │ • 会话隔离 │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.2 命令执行沙箱
9.2.1 命令白名单
┌─────────────────────────────────────────────────────────────────────┐
│ 命令白名单 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ✅ 允许的命令 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 文件操作（只读）： │ │
│ │ • ls, cat, find, grep, head, tail, wc, tree │ │
│ │ • file, stat, du, df │ │
│ │ │ │
│ │ Git 命令（只读）： │ │
│ │ • git status, git log, git diff, git branch │ │
│ │ • git show, git remote, git config (读取) │ │
│ │ │ │
│ │ 包管理器： │ │
│ │ • npm, node, npx, pnpm, yarn │ │
│ │ • python, pip, python3, pip3 │ │
│ │ │ │
│ │ 系统信息： │ │
│ │ • echo, date, uname, which, pwd, ps, env │ │
│ │ • whoami, hostname, uptime │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ❌ 禁止的命令 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 破坏性操作： │ │
│ │ • rm, rmdir, del │ │
│ │ • mv, cp (可能覆盖文件) │ │
│ │ • chmod, chown │ │
│ │ • dd, shred │ │
│ │ │ │
│ │ 权限提升： │ │
│ │ • sudo, su, doas │ │
│ │ • pkexec, gksudo │ │
│ │ │ │
│ │ 网络操作： │ │
│ │ • curl, wget (可能泄露数据) │ │
│ │ • nc, netcat, telnet │ │
│ │ │ │
│ │ 进程管理： │ │
│ │ • kill, pkill, killall │ │
│ │ • systemctl, service │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.2.2 白名单实现
┌─────────────────────────────────────────────────────────────────────┐
│ 白名单实现 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ const ALLOWED_COMMANDS = [ │
│ 'ls', 'cat', 'find', 'grep', 'head', 'tail', 'wc', │
│ 'git', 'npm', 'node', 'npx', 'pnpm', 'yarn', │
│ 'python', 'pip', 'python3', 'pip3', │
│ 'echo', 'date', 'uname', 'which', 'pwd', 'ps', │
│ ]; │
│ │
│ function isCommandAllowed(command: string): boolean { │
│ const baseCommand = command.split(' ')[0]; │
│ return ALLOWED_COMMANDS.includes(baseCommand); │
│ } │
│ │
│ async function executeCommand(command: string): Promise<string> { │
│ // 1. 检查命令是否在白名单中 │
│ if (!isCommandAllowed(command)) { │
│ throw new Error(`Command not allowed: ${command}`); │
│ } │
│ │
│ // 2. 执行命令（带超时和输出限制） │
│ // ... │
│ } │
│ │
└─────────────────────────────────────────────────────────────────────┘9.2.3 执行限制
┌─────────────────────────────────────────────────────────────────────┐
│ 执行限制 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ⏱️ 超时限制：10 秒 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ const TIMEOUT_MS = 10000; │ │ │
│ │ │ │ │ │
│ │ │ 防止长时间运行的命令占用资源 │ │ │
│ │ │ 超时后自动终止进程 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 📊 输出截断：1MB │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ const MAX_OUTPUT_SIZE = 1024 * 1024; // 1MB │ │ │
│ │ │ │ │ │
│ │ │ 防止大量输出导致内存问题 │ │ │
│ │ │ 超过限制时截断并提示 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 📁 工作目录限制 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ 命令只能在当前项目目录中执行 │ │ │
│ │ │ 防止访问系统敏感目录 │ │ │
│ │ │ cwd: process.cwd() │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.3 数据隐私保护
9.3.1 本地存储策略
┌─────────────────────────────────────────────────────────────────────┐
│ 本地存储策略 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 设计原则：所有用户数据存储在本地，永不上传云端 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ☁️ 云端交互 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ 仅发送： │ │ │
│ │ │ • 对话内容（用于 AI 响应） │ │ │
│ │ │ • 编译后的上下文 │ │ │
│ │ │ │ │ │
│ │ │ 不发送： │ │ │
│ │ │ • 原始文件内容 │ │ │
│ │ │ • 用户个人信息 │ │ │
│ │ │ • 环境配置 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 💻 本地存储 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ ~/.miniclaw/ │ │ │
│ │ │ ├── AGENTS.md (工作空间章程) │ │ │
│ │ │ ├── SOUL.md (性格定义) │ │ │
│ │ │ ├── USER.md (用户画像) │ │ │
│ │ │ ├── MEMORY.md (长期记忆) │ │ │
│ │ │ ├── entities.json (实体图谱) │ │ │
│ │ │ └── memory/ (每日日志) │ │ │
│ │ │ │ │ │
│ │ │ 所有数据仅存在于用户本地机器 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.3.2 敏感信息处理
┌─────────────────────────────────────────────────────────────────────┐
│ 敏感信息处理 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 敏感信息类型： │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 🔑 密钥和令牌 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ • API Keys │ │ │
│ │ │ • Access Tokens │ │ │
│ │ │ • Passwords │ │ │
│ │ │ │ │ │
│ │ │ 处理方式： │ │ │
│ │ │ • 不存储在文件中 │ │ │
│ │ │ • 使用环境变量 │ │ │
│ │ │ • 显示时脱敏 (sk-***...***) │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 📧 个人信息 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ • 姓名、邮箱、电话 │ │ │
│ │ │ • 地址、身份证号 │ │ │
│ │ │ │ │ │
│ │ │ 处理方式： │ │ │
│ │ │ • 仅存储在 MEMORY.md（主会话专用） │ │ │
│ │ │ • 不在共享上下文中加载 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ 🏢 工作信息 │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ • 公司内部 IP │ │ │
│ │ │ • 内部服务器地址 │ │ │
│ │ │ • 项目机密 │ │ │
│ │ │ │ │ │
│ │ │ 处理方式： │ │ │
│ │ │ • 存储在 TOOLS.md 时脱敏 │ │ │
│ │ │ • 示例：192.168.*.* │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.3.3 会话隔离
┌─────────────────────────────────────────────────────────────────────┐
│ 会话隔离 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 主会话 vs 共享上下文 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ✅ 主会话 (Main Session) │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ • 用户直接与 Agent 聊天 │ │ │
│ │ │ • 加载所有文件，包括 MEMORY.md │ │ │
│ │ │ • 可以访问个人上下文 │ │ │
│ │ │ • 完整功能 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ❌ 共享上下文 (Shared Context) │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ • 群聊、与其他人的会话 │ │ │
│ │ │ • 不加载 MEMORY.md │ │ │
│ │ │ • 仅使用公开上下文 │ │ │
│ │ │ • 保护个人隐私 │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 实现方式： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ // MEMORY.md 的 frontmatter │ │
│ │ --- │ │
│ │ read_when: │ │
│ │ - Main session only │ │
│ │ --- │ │
│ │ │ │
│ │ // 加载时检查 │ │
│ │ if (isMainSession && file.read_when.includes('Main...')) { │ │
│ │ loadFile(file); │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.4 输入验证
9.4.1 Zod Schema 验证
┌─────────────────────────────────────────────────────────────────────┐
│ Zod Schema 验证 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ miniclaw_update 工具参数验证 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ const UpdateSchema = z.object({ │ │
│ │ file: z.enum([ │ │
│ │ 'AGENTS.md', │ │
│ │ 'SOUL.md', │ │
│ │ 'IDENTITY.md', │ │
│ │ 'USER.md', │ │
│ │ 'TOOLS.md', │ │
│ │ 'MEMORY.md', │ │
│ │ 'HEARTBEAT.md', │ │
│ │ ]), │ │
│ │ content: z.string().max(50000), // 最大 50KB │ │
│ │ mode: z.enum(['append', 'replace']).optional(), │ │
│ │ }); │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ miniclaw_exec 工具参数验证 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ const ExecSchema = z.object({ │ │
│ │ command: z.string() │ │
│ │ .max(500) // 最大 500 字符 │ │
│ │ .refine(cmd => !cmd.includes(';'), { │ │
│ │ message: 'No command chaining allowed', │ │
│ │ }), │ │
│ │ }); │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ miniclaw_entity 工具参数验证 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ const EntitySchema = z.object({ │ │
│ │ action: z.enum(['add', 'remove', 'link', 'query', 'list']),│ │
│ │ name: z.string().max(100).optional(), │ │
│ │ type: z.enum(['person', 'project', 'tool', 'concept', │ │
│ │ 'place', 'other']).optional(), │ │
│ │ relation: z.string().max(100).optional(), │ │
│ │ }); │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.4.2 验证流程
┌─────────────────────────────────────────────────────────────────────┐
│ 验证流程 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 用户请求 │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 1. 参数类型验证 │ │
│ │ • 检查必填参数是否存在 │ │
│ │ • 检查参数类型是否正确 │ │
│ │ • 检查参数值是否在允许范围内 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 2. 参数长度验证 │ │
│ │ • 字符串长度限制 │ │
│ │ • 数组长度限制 │ │
│ │ • 文件大小限制 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 3. 特殊字符过滤 │ │
│ │ • SQL 注入防护 │ │
│ │ • 命令注入防护 │ │
│ │ • XSS 防护 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 验证通过，执行操作 │
│ │
└─────────────────────────────────────────────────────────────────────┘9.5 安全最佳实践
9.5.1 用户安全建议
┌─────────────────────────────────────────────────────────────────────┐
│ 用户安全建议 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🔐 密钥管理 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ✅ 推荐做法： │ │
│ │ • 使用环境变量存储密钥 │ │
│ │ • 使用 .env 文件（不提交到 Git） │ │
│ │ • 定期轮换密钥 │ │
│ │ │ │
│ │ ❌ 避免做法： │ │
│ │ • 将密钥写入配置文件 │ │
│ │ • 将密钥提交到版本控制 │ │
│ │ • 在对话中直接粘贴密钥 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 📁 文件权限 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ✅ 推荐做法： │ │
│ │ • ~/.miniclaw/ 目录权限设为 700 │ │
│ │ • 敏感文件权限设为 600 │ │
│ │ • 定期检查文件权限 │ │
│ │ │ │
│ │ chmod 700 ~/.miniclaw/ │ │
│ │ chmod 600 ~/.miniclaw/MEMORY.md │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 🔄 定期维护 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ • 定期审查 MEMORY.md 内容 │ │
│ │ • 清理不需要的敏感信息 │ │
│ │ • 更新过时的配置 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.5.2 开发者安全建议
┌─────────────────────────────────────────────────────────────────────┐
│ 开发者安全建议 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🛡️ 代码安全 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ • 所有用户输入必须经过验证 │ │
│ │ • 使用参数化查询，避免拼接字符串 │ │
│ │ • 不信任任何外部输入 │ │
│ │ • 使用最小权限原则 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 📝 日志安全 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ • 不在日志中记录敏感信息 │ │
│ │ • 对敏感数据进行脱敏处理 │ │
│ │ • 限制日志文件访问权限 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 🔧 依赖安全 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ • 定期更新依赖版本 │ │
│ │ • 使用 npm audit 检查漏洞 │ │
│ │ • 审查第三方依赖的安全性 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘9.6 安全事件响应
9.6.1 常见安全问题
┌─────────────────────────────────────────────────────────────────────┐
│ 常见安全问题及处理 │
├─────────────────┬───────────────────────────────────────────────────┤
│ 问题 │ 处理方式 │
├─────────────────┼───────────────────────────────────────────────────┤
│ 命令注入尝试 │ 白名单检查直接拒绝，记录日志 │
├─────────────────┼───────────────────────────────────────────────────┤
│ 路径遍历尝试 │ 路径验证，限制在允许目录内 │
├─────────────────┼───────────────────────────────────────────────────┤
│ 敏感信息泄露 │ 自动脱敏，提醒用户检查 │
├─────────────────┼───────────────────────────────────────────────────┤
│ 超限输入 │ 参数验证拒绝，返回错误信息 │
├─────────────────┼───────────────────────────────────────────────────┤
│ 异常行为检测 │ 记录日志，必要时通知用户 │
└─────────────────┴───────────────────────────────────────────────────┘9.6.2 安全日志
┌─────────────────────────────────────────────────────────────────────┐
│ 安全日志示例 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ [2026-02-12 14:30:00] WARN: Blocked command attempt: rm -rf / │
│ [2026-02-12 14:30:05] WARN: Path traversal attempt: ../../../etc │
│ [2026-02-12 14:30:10] INFO: Input validation failed: content > 50KB│
│ [2026-02-12 14:30:15] INFO: Session isolation active: shared ctx │
│ │
└─────────────────────────────────────────────────────────────────────┘本章小结
┌─────────────────────────────────────────────────────────────────────┐
│ 第九章 核心要点 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🔒 四层安全架构 │
│ • 输入验证 → 权限检查 → 执行沙箱 → 数据保护 │
│ │
│ 📋 命令白名单 │
│ • 仅允许安全的只读命令 │
│ • 禁止破坏性操作和权限提升 │
│ │
│ ⏱️ 执行限制 │
│ • 超时：10 秒 │
│ • 输出截断：1MB │
│ • 工作目录限制 │
│ │
│ 💾 数据隐私 │
│ • 所有数据本地存储 │
│ • 敏感信息脱敏 │
│ • 会话隔离 │
│ │
│ ✅ Zod Schema 验证 │
│ • 参数类型、长度、范围验证 │
│ │
└─────────────────────────────────────────────────────────────────────┘下一章：MCP 协议实现 →