SECURITY / GUIDE

安全与权限

了解访问密钥、执行审批、沙箱和插件凭据的配置边界。

本页内容

ExMachina 在接入、身份、工具执行与沙箱之间设置不同边界。各层负责不同问题,需要结合部署环境配置。

#访问本地网关

配置 authKey 后,网关对 REST / WebSocket 启用鉴权,WebUI 提供登录入口。环境变量 EXM_AUTH_KEY 也可用于设置访问密钥。

模型凭据与运行配置默认位于工作区 .exmachina/。这类内容属于实例数据,不应复制到官网静态资源、截图示例或公开仓库。

#纵深防御

层主要职责
入站消毒处理伪装系统指令、隐藏字符与工具结果伪装
通道身份管控约束来源用户、白名单与群聊唤醒范围
工具闸门命令前缀白名单、审批与审计
沙箱执行环境净化、文件与网络边界、资源限制
执行身份约束Linux 子进程降权与工作目录约束

#执行审批

execApproval 定义审批策略:

  • off:白名单外命令按策略拒绝。
  • risky:高风险操作进入人工审批。
  • always:按配置要求进行审批。

批准后由系统代执行,并把结果回灌当前任务;拒绝或超时会作为受阻结果返回。

#授权范围

范围生命周期
本次批准仅当前审批单
本会话允许当前会话,结束或删除后失效
加入白名单持久配置

提权和破坏性命令等特殊操作不能直接套用普通会话授权。具体执行规则以当前宿主配置和实现为准。

#沙箱配置

sandbox.mode 支持 off、workspace 与 strict 等模式。系统还可结合 bubblewrap、内存与子进程数量限制约束工具执行。

沙箱能减少执行面,但它的效果受操作系统、容器权限与启用配置影响。先在自己的运行环境中检查实际生效状态。

#Linux 执行身份

可通过专用用户限制 Agent 终端子进程。以下是配置结构示例:

json
{
  "security": {
    "execUser": "exm",
    "execHome": "/home/exm"
  }
}

使用前需要准备用户与目录权限。网关以非 root 运行时无法任意切换其他 uid;Windows 不使用 Linux uid 语义。部署细节见仓库安全模型。

#插件凭据

在插件管理中配置凭据,敏感字段以掩码回显。不要把真实密钥写进 plugin.json 的公开示例。

进程插件通过配置下发收到的凭据仅用于内存处理,不应在诊断、日志或归档中输出。开发流程见插件开发指南。

需要完整字段、接口和最新版本细节?

查看项目仓库中的《安全模型》↗