安全模型

Moltbot 的安全策略和权限控制

概述

Moltbot 连接到真实的消息渠道，因此必须将入站 DM 视为不受信任的输入。安全模型提供多层保护，包括 DM 配对、允许列表、工具权限、沙箱隔离等。

安全层次

  1. DM 策略: 控制对未认证 DM 的访问
  2. 允许列表: 白名单机制
  3. 设备配对: 防止设备仿冒
  4. 工具权限: 细粒度的工具访问控制
  5. 沙箱隔离: 非主会话在 Docker 中运行
  6. 执行批准: 敏感命令需要用户批准

DM 策略

策略类型

类型: DmPolicy = "open" | "pairing" | "closed"

export type DmPolicy = "open" | "pairing" | "closed";

策略说明

策略行为安全等级推荐场景
open所有 DM 都接受🔴 低仅在允许列表中配置 "*" 时使用
pairing未知发送者需要配对码🟡 中推荐用于生产环境
closed拒绝所有 DM🟢 高完全禁用 DM

配置示例

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing"
    },
    telegram: {
      dmPolicy: "pairing",
      allowFrom: ["+1234567890"] // 允许列表覆盖
    },
    discord: {
      dmPolicy: "closed" // 完全禁用
    }
  }
}

配对流程

允许列表匹配

Allowlist 匹配类型

文件: src/channels/allowlist-match.ts

export type AllowlistMatchSource =
  | "wildcard"
  | "id"
  | "name"
  | "tag"
  | "username"
  | "prefixed-id"
  | "prefixed-user"
  | "prefixed-name"
  | "prefixed-tag";

匹配逻辑

export function matchAllowlist(params: {
  cfg: MoltbotConfig;
  channel: string;
  accountId?: string | null;
  targetId: string;
  targetName?: string | null;
  targetTag?: string | null;
  targetUsername?: string | null;
}): AllowlistMatch

匹配优先级

  1. 通配符: * 匹配所有
  2. 裸 ID: 1234567890 匹配特定用户
  3. 前缀 ID: telegram:123456789 匹配特定渠道用户
  4. 名称: username 匹配显示名称
  5. 前缀名称: telegram:username 匹配特定渠道名称
  6. 标签: @tag 匹配标签
  7. 前缀标签: telegram:@tag 匹配特定渠道标签
  8. 用户名: @username 匹配用户名

配置示例

{
  channels: {
    telegram: {
      // 多种匹配方式
      allowFrom: [
        "*",                          // 所有用户
        "123456789",                   // 特定用户 ID
        "telegram:987654321",           // Telegram 用户
        "alice",                       // 显示名称
        "telegram:@family",             // Telegram 家族标签
        "alice@telegram.com"           // 邮箱 (某些渠道)
      ]
    }
  }
}

设备配对

配对机制

Gateway 支持设备签名和配对，防止设备仿冒攻击。

配对流程

配对管理

WebSocket 方法:

方法说明
device.pair.list列出待批准的设备
device.pair.approve批准设备配对
device.pair.reject拒绝设备配对
device.token.rotate旋转设备令牌
device.token.revoke撤销设备令牌

工具权限

工具策略

文件: src/agents/tool-policy.ts

export type ToolPolicy = {
  allow?: string[];    // 允许的 glob 模式
  deny?: string[];     // 拒绝的 glob 模式
};

策略层次

  1. Profile 策略: tools.profile
  2. Provider Profile 策略: tools.byProvider[{provider}].profile
  3. Agent 策略: agents[{id}].tools.allow
  4. Agent Provider 策略: agents[{id}].tools.byProvider[{provider}].allow
  5. Group 策略: channel/group 特定
  6. Sandbox 策略: tools.sandbox.tools.allow
  7. Subagent 策略: subagent 专用

配置示例

{
  agents: {
    defaults: {
      // 全局工具策略
      tools: {
        profile: {
          allow: ["*"],
          deny: ["system.run", "system.notify"]
        }
      }
    },
    list: {
      work: {
        // Agent 特定策略
        tools: {
          allow: ["bash", "read", "write", "edit", "browser"],
          deny: ["process", "sessions_*"]
        }
      }
    }
  }
}

Glob 模式

// 匹配所有 bash 工具
"bash*"

// 匹配 sessions 开头的工具
"sessions_*"

// 匹配 system.run 和 system.notify
"system.{run,notify}"

// 匹配除了 session 开头的所有工具
"!sessions_*"

沙箱隔离

Sandbox 模式

文件: src/agents/sandbox/types.ts

export type SandboxMode = "off" | "all" | "non-main";

模式说明

模式行为适用场景
off不启用沙箱开发环境，完全信任
all所有会话都启用沙箱最大安全隔离
non-main仅非主会话启用沙箱推荐：主会话有完全访问，其他会话受限

配置示例

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        workspaceAccess: "ro",  // 只读访问宿主工作区
        pruneMinutes: 60          // 60 分钟后清理
      },
      tools: {
        sandbox: {
          tools: {
            allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send"],
            deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
          }
        }
      }
    }
  }
}

工作空间访问

export type SandboxWorkspaceAccess = "none" | "ro" | "rw";
模式挂载点说明
none/workspace完全隔离，无宿主访问
ro/agent:ro + /workspace只读宿主工作区
rw/agent:rw + /workspace读写宿主工作区

执行批准

批准机制

敏感命令（如 system.run）需要用户批准后执行。

批准策略

{
  agents: {
    defaults: {
      tools: {
        exec: {
          approvalMode: "always",  // "always" | "per-session" | "once"
          notify: true,
          timeoutMs: 300000      // 5 分钟超时
        }
      }
    }
  }
}

群组消息安全

Mention Gating

默认情况下，群组消息需要 @mention bot 才处理。

{
  channels: {
    discord: {
      groups: {
        "*": {
          requireMention: true,
          mentionPattern: "@bot"
        }
      }
    }
  }
}

群组工具策略

群组中的工具访问可以单独配置。

{
  agents: {
    defaults: {
      tools: {
        groups: {
          "*": {
            allow: ["read", "write", "edit"],
            deny: ["bash", "process", "browser", "canvas"]
          }
        }
      }
    }
  }
}

安全检查命令

Doctor 命令

moltbot doctor

Doctor 会检查：

  • ❌ 风险的 DM 策略（dmPolicy: "open" 而 allowList 包含 "*"）
  • ❌ 未配置的通道
  • ❌ 配置问题
  • ✅ 正常的安全配置

最佳实践

1. 使用 pairing 模式

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing"  // ✅ 推荐
    }
  }
}

2. 细粒度的工具控制

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main"  // ✅ 主会话全访问，其他受限
      },
      tools: {
        sandbox: {
          tools: {
            deny: ["browser", "canvas", "nodes"]  // ✅ 危险工具默认拒绝
          }
        }
      }
    }
  }
}

3. 使用执行批准

{
  agents: {
    defaults: {
      tools: {
        exec: {
          approvalMode: "always"  // ✅ 敏感命令需批准
        }
      }
    }
  }
}

4. 运行 Doctor

moltbot doctor  # ✅ 定期检查配置

代码路径引用

功能文件路径
Allowlist 匹配src/channels/allowlist-match.ts
DM 策略src/channels/channel-config.ts
设备配对src/gateway/server/device-pairing.ts
工具策略src/agents/tool-policy.ts
Sandboxsrc/agents/sandbox/
执行批准src/infra/exec-approval-forwarder.ts
Doctorsrc/commands/doctor.ts