安全机制

本文档介绍 MateClaw 的安全体系，包括 JWT 认证、工具守卫（ToolGuard）、文件守卫（FileGuard）、审计日志（AuditLog）和技能安全扫描等。

JWT 认证

认证流程

1. 用户提交用户名/密码 -> POST /api/v1/auth/login
2. 服务端验证通过 -> 生成 JWT Token（含用户 ID、角色）
3. 客户端存储 Token -> 后续请求携带 Authorization: Bearer <token>
4. 服务端拦截器验证 Token -> 解析用户信息注入上下文

登录接口

http

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

响应：

json

{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expiresIn": 86400
  }
}

滑动窗口续期

MateClaw 实现了 JWT 滑动窗口续期机制：

Token 有效期默认 24 小时
当 Token 剩余有效期不足 50% 时，响应头中自动返回新 Token
客户端检测到 X-New-Token 响应头后自动替换本地存储的 Token
无需用户重新登录，实现无感续期

统一错误处理

HTTP 状态码	场景	说明
401 Unauthorized	Token 缺失或过期	前端跳转登录页
403 Forbidden	权限不足	提示无权访问

前端全局拦截器统一处理 401/403 响应：

typescript

// http.ts 中的响应拦截器
axios.interceptors.response.use(
  (response) => {
    // 检查滑动窗口续期
    const newToken = response.headers['x-new-token']
    if (newToken) {
      localStorage.setItem('token', newToken)
    }
    return response
  },
  (error) => {
    if (error.response?.status === 401) {
      router.push('/login')
    }
    return Promise.reject(error)
  }
)

默认账户

系统初始化时自动创建管理员账户：

用户名：admin
密码：admin123

强烈建议首次登录后立即修改密码。

ToolGuard 工具守卫

ToolGuard 是 MateClaw 的工具执行安全层，在 Agent 调用工具前进行审批控制。

工作机制

Agent 请求调用工具 -> ToolGuard 检查策略 -> 通过/拒绝/等待审批 -> 执行工具

审批策略

策略	说明	适用场景
`auto_approve`	自动通过	低风险工具（如日期查询）
`manual_approve`	需人工审批	高风险工具（如文件写入）
`deny`	直接拒绝	禁用的工具

配置示例

在工具管理中可为每个工具设置审批策略：

json

{
  "toolName": "file_write",
  "approvalPolicy": "manual_approve",
  "description": "写入文件需要人工确认"
}

审批流程

Agent 决定调用某个需要审批的工具
系统暂停执行，向用户发送审批通知
用户在前端查看工具调用详情（工具名、参数）
用户选择批准或拒绝
批准后工具继续执行，拒绝后 Agent 收到拒绝信息并调整策略

UI 管理

在前端的「安全」页面中，可以查看和管理 ToolGuard 配置，包括查看已配置的审批策略、修改工具的审批级别、查看历史审批记录等。

FileGuard 文件访问控制

FileGuard 提供文件系统级别的访问控制，限制 Agent 和工具对文件系统的访问范围，防止未授权的文件读写操作。

工作机制

当工具或技能请求访问文件系统时，FileGuard 会检查以下规则：

文件访问请求 -> 路径规范化 -> 白名单检查 -> 黑名单检查 -> 允许/拒绝

访问控制规则

规则	说明
工作空间隔离	默认只能访问工作空间目录内的文件
系统路径禁止	禁止访问 `/etc`、`/usr`、`/bin` 等系统目录
敏感文件保护	禁止访问 `.ssh`、`.config`、`.env` 等敏感文件
路径遍历防护	检测并阻止 `../` 路径遍历攻击
符号链接检查	检测通过符号链接绕过路径限制的企图

配置

yaml

mateclaw:
  security:
    file-guard:
      enabled: true
      allowed-paths:
        - "${user.dir}/workspace"
        - "${java.io.tmpdir}/mateclaw"
      denied-paths:
        - "/etc"
        - "/usr"
        - "${user.home}/.ssh"
        - "${user.home}/.config"
        - "${user.home}/.env"

UI 管理

在前端的「安全」页面中，FileGuard 区域提供可视化的路径规则管理界面，可以添加、编辑和删除允许/禁止的路径规则。

AuditLog 安全审计日志

AuditLog 记录系统中所有安全相关的操作，提供完整的操作追踪能力，用于安全审计和问题排查。

记录范围

AuditLog 记录以下类型的操作：

操作类型	说明
工具调用	记录每次工具调用的工具名、参数、执行结果、耗时
ToolGuard 审批	记录审批请求、审批结果（通过/拒绝）、审批人
FileGuard 事件	记录文件访问请求、路径、访问结果（允许/拒绝）
技能执行	记录技能调用的技能名、参数、关联的 Agent
登录事件	记录用户登录成功/失败、登录 IP
配置变更	记录安全相关配置的变更

日志结构

每条审计日志包含以下信息：

字段	说明
`timestamp`	操作时间
`user_id`	操作用户
`action`	操作类型
`resource`	操作对象（工具名/文件路径/技能名）
`details`	操作详情（JSON 格式）
`result`	操作结果（成功/失败/拒绝）
`ip_address`	请求来源 IP

UI 查看

在前端的「安全」页面中，AuditLog 区域提供审计日志查询界面，支持按时间范围、操作类型、用户等条件筛选，方便进行安全审计。

技能安全扫描

SkillSecurityService

安装或更新技能时，SkillSecurityService 自动执行安全扫描，检测以下风险：

代码注入检测

扫描技能代码中是否包含：

动态代码执行（eval、exec、Runtime.exec）
反射调用（Class.forName、Method.invoke）
脚本引擎调用（ScriptEngine）
不安全的反序列化

IO 漏洞检测

文件读写操作（FileInputStream、FileOutputStream）
路径遍历风险（../ 模式）
临时文件创建
系统属性访问

网络访问检测

HTTP 客户端调用（HttpClient、OkHttp、RestTemplate）
Socket 连接
URL 连接
外部 API 调用

安全发现严重级别

级别	说明	处理方式
`CRITICAL`	严重安全风险	阻止安装，必须修复
`HIGH`	高风险	警告并需要管理员确认
`MEDIUM`	中风险	显示警告信息
`LOW`	低风险	仅记录日志
`INFO`	信息提示	仅记录日志

扫描结果示例

json

{
  "skillId": 1,
  "scanResult": {
    "passed": false,
    "findings": [
      {
        "severity": "CRITICAL",
        "category": "CODE_INJECTION",
        "message": "检测到 Runtime.exec() 调用，存在命令注入风险",
        "location": "skill.js:15"
      },
      {
        "severity": "HIGH",
        "category": "NETWORK_ACCESS",
        "message": "检测到外部 HTTP 请求",
        "location": "skill.js:28"
      }
    ]
  }
}

SkillFileAccessPolicy

SkillFileAccessPolicy 控制技能对文件系统的访问权限。

路径保护规则

规则	说明
工作空间隔离	技能只能访问自身工作空间目录
系统路径禁止	禁止访问 `/etc`、`/usr`、`/bin` 等系统目录
用户目录限制	限制对用户主目录敏感文件的访问
相对路径解析	所有相对路径解析到工作空间根目录
符号链接检查	检测并阻止通过符号链接绕过路径限制

配置

yaml

mateclaw:
  skill:
    file-access:
      allowed-paths:
        - "${user.dir}/workspace"
        - "${java.io.tmpdir}/mateclaw"
      denied-paths:
        - "/etc"
        - "/usr"
        - "${user.home}/.ssh"
        - "${user.home}/.config"

SkillDependencyChecker

技能安装时，SkillDependencyChecker 检查技能声明的依赖项：

检查内容

版本兼容性：检查依赖的 MateClaw 版本是否兼容
循环依赖：检测技能之间是否存在循环依赖
缺失依赖：检查所需的其他技能或工具是否已安装
版本冲突：检测多个技能依赖同一库的不同版本

依赖声明格式

在 SKILL.md 中声明依赖：

markdown

---
name: my-skill
version: 1.0.0
dependencies:
  mateclaw: ">=1.0.0"
  skills:
    - name: web-search
      version: ">=1.0.0"
---

安全页面

MateClaw 前端提供统一的「安全」管理页面，集中展示和管理所有安全相关功能：

ToolGuard 管理：查看和配置工具审批策略，查看审批历史
FileGuard 管理：管理文件访问控制规则，查看拦截记录
AuditLog 查看：查询和筛选审计日志，导出日志数据
技能安全扫描：查看已安装技能的安全扫描报告

安全最佳实践

修改默认密码：首次部署后立即修改 admin 的默认密码
最小权限原则：只启用 Agent 实际需要的工具
审批高风险操作：对文件写入、命令执行等工具启用人工审批
配置 FileGuard：限制文件访问范围，保护敏感目录
定期审查审计日志：通过 AuditLog 定期查看安全相关事件
定期审查技能：定期查看已安装技能的安全扫描报告
API Key 安全：使用环境变量管理 API Key，避免硬编码
网络隔离：生产环境中限制 Ollama 等本地服务的网络访问
日志监控：定期查看安全相关日志，关注异常工具调用

安全相关配置

yaml

mateclaw:
  security:
    jwt:
      secret: ${JWT_SECRET:your-secret-key-at-least-32-chars}
      expiration: 86400          # Token 有效期（秒）
      sliding-window-ratio: 0.5  # 续期触发阈值
    tool-guard:
      enabled: true
      default-policy: auto_approve
    file-guard:
      enabled: true
      allowed-paths:
        - "${user.dir}/workspace"
      denied-paths:
        - "/etc"
        - "${user.home}/.ssh"
    audit-log:
      enabled: true
      retention-days: 90         # 审计日志保留天数
    skill:
      security-scan:
        enabled: true
        block-critical: true     # 阻止安装有严重风险的技能

安全机制 ​

JWT 认证 ​

认证流程 ​

登录接口 ​

滑动窗口续期 ​

统一错误处理 ​

默认账户 ​

ToolGuard 工具守卫 ​

工作机制 ​

审批策略 ​

配置示例 ​

审批流程 ​

UI 管理 ​

FileGuard 文件访问控制 ​

工作机制 ​

访问控制规则 ​

配置 ​

UI 管理 ​

AuditLog 安全审计日志 ​

记录范围 ​

日志结构 ​

UI 查看 ​

技能安全扫描 ​

SkillSecurityService ​

代码注入检测 ​

IO 漏洞检测 ​

网络访问检测 ​

安全发现严重级别 ​

扫描结果示例 ​

SkillFileAccessPolicy ​

路径保护规则 ​

配置 ​

SkillDependencyChecker ​

检查内容 ​

依赖声明格式 ​

安全页面 ​

安全最佳实践 ​

安全相关配置 ​

安全机制

JWT 认证

认证流程

登录接口

滑动窗口续期

统一错误处理

默认账户

ToolGuard 工具守卫

工作机制

审批策略

配置示例

审批流程

UI 管理

FileGuard 文件访问控制

工作机制

访问控制规则

配置

UI 管理

AuditLog 安全审计日志

记录范围

日志结构

UI 查看

技能安全扫描

SkillSecurityService

代码注入检测

IO 漏洞检测

网络访问检测

安全发现严重级别

扫描结果示例

SkillFileAccessPolicy

路径保护规则

配置

SkillDependencyChecker

检查内容

依赖声明格式

安全页面

安全最佳实践

安全相关配置