安全与权限

工具系统的安全控制机制。

安全层级

┌─────────────────────────────────────────────────┐
│ 1. 全局配置过滤                                  │
│    启用/禁用工具类别和具体工具                    │
├─────────────────────────────────────────────────┤
│ 2. 预设过滤                                      │
│    预设级别的工具白名单/黑名单                    │
├─────────────────────────────────────────────────┤
│ 3. 危险工具控制                                  │
│    危险工具需要特殊授权                          │
├─────────────────────────────────────────────────┤
│ 4. 用户权限检查                                  │
│    管理员专属工具                                │
└─────────────────────────────────────────────────┘

全局配置

启用/禁用类别

builtinTools:
  enabledCategories:
    - basic
    - user
    - web
  # 未列出的类别将被禁用

禁用特定工具

builtinTools:
  disabledTools:
    - execute_command
    - delete_file

预设级过滤

白名单模式

# 预设文件
tools:
  mode: whitelist
  allowedTools:
    - get_time
    - get_weather
    - search_web

黑名单模式

tools:
  mode: blacklist
  excludedTools:
    - send_message
    - kick_member

危险工具

标记危险工具

// 工具定义中
{
  name: 'execute_command',
  description: '执行系统命令',
  dangerous: true,  // 标记为危险
  
  async execute(args) {
    // ...
  }
}

危险工具配置

mcp:
  security:
    # 是否允许危险工具
    allowDangerous: false
    
    # 危险工具列表
    dangerousTools:
      - execute_command
      - delete_file
      - write_file
      - format_disk

临时授权

某些场景需要临时允许危险工具：

const agent = await createSkillsAgent({
  event: e,
  allowDangerous: true  // 临时授权
})

管理员工具

标记管理员专属

{
  name: 'kick_member',
  description: '踢出群成员',
  adminOnly: true,  // 需要管理员权限
  
  async execute(args, context) {
    if (!context.isAdmin) {
      throw new Error('需要管理员权限')
    }
    // ...
  }
}

配置管理员工具

mcp:
  security:
    adminOnlyTools:
      - kick_member
      - ban_member
      - set_group_admin

参数验证

工具执行前自动验证参数：

{
  parameters: {
    type: 'object',
    properties: {
      userId: {
        type: 'string',
        pattern: '^[0-9]+$'  // 只允许数字
      },
      count: {
        type: 'integer',
        minimum: 1,
        maximum: 100
      }
    },
    required: ['userId']
  }
}

速率限制

工具级限制

{
  name: 'expensive_tool',
  rateLimit: {
    maxCalls: 10,
    windowMs: 60000  // 每分钟最多 10 次
  }
}

用户级限制

mcp:
  rateLimit:
    perUser:
      maxCalls: 100
      windowMs: 3600000  # 每小时 100 次

日志审计

记录工具调用

mcp:
  logging:
    enabled: true
    level: info
    retention: 30  # 保留 30 天

日志内容

{
  "id": "uuid",
  "toolName": "send_message",
  "args": {"target": "123", "content": "..."},
  "result": "success",
  "userId": "456",
  "timestamp": "2024-12-15T06:30:00.000Z",
  "duration": 150
}

查看日志

# 命令
#工具日志

# API
GET /api/tools/logs?limit=100&toolName=send_message

最佳实践

1. 最小权限原则

只启用必需的工具，禁用不需要的功能。

2. 使用白名单

预设中使用白名单模式，明确列出允许的工具。

3. 禁用危险工具

生产环境务必设置 allowDangerous: false。

4. 定期审计

定期检查工具调用日志，发现异常行为。

5. 参数校验

严格定义参数 Schema，防止注入攻击。

安全检查清单

• [ ] 已禁用不需要的工具类别
• [ ] 危险工具已禁用或受控
• [ ] 管理员工具已正确配置
• [ ] 预设使用白名单模式
• [ ] 日志审计已启用
• [ ] 速率限制已配置

下一步

• 工具开发概述 - 返回概述
• MCP 配置 - MCP 配置详情