Open Agent API

安全模型

本文说明在 Open Agent API(OAA)网关里谁能做什么、默认暴露什么、对外开放前必须做什么,以及网关不防护哪些情况。内容对应 0.0.65 版本的代码。漏洞请按 SECURITY.md 的说明报告。

各方与信任边界

角色用什么认证被信任做什么
所有者 / 管理员带 admin 权限的 API 密钥(sk-oaa-…、旧版 oaa_…,或配置文件里的密钥)其所有者名下的一切:发布智能体(包括引擎、模型路由、MCP 服务器、HTTP/A2A 适配器地址、approvals: auto)、创建密钥、登记节点、平台设置。管理员等同于这台机器的运维者。
限定智能体的管理员agents 不是 * 的 admin 密钥只能对它的那些智能体执行管理操作。不能管理节点生命周期、不能读审计记录、不能吊销或重设自己的智能体范围之外的密钥配额(自己的密钥除外)。有配额时,它创建或修改的密钥,每一项限额都不能高于它自己的配额(quota_exceeds_own)。每个这样的密钥有各自的计数,所以几个密钥合起来仍然可以用掉超过一个密钥的配额。
调用方非管理员 API 密钥调用密钥所授权的智能体,权限范围是它持有的权限(invoke、read、files、approve、billing)。只能看到自己的运行、文件、产物、记忆和幂等键(它的主体),除非密钥带 data_scope: owner。
门户用户门户会话 oas_…(开发者平台)只限它自己的账号、密钥、余额、用量和运行。账号密钥只对上架的智能体有 invoke/read/files,执行级别是平台设定的(workspace 或 sandbox)。例外,按上架项区分:所有者打开某个上架项的 host_execution 后,账号密钥可以让那个智能体以 host 级别运行,也就是以网关的操作系统用户身份运行(它的每个委派、移交或回退目标都需要各自的上架项开关)。它的权限请求只由所有者决定;账号密钥没有 approve 权限。开关的变更会被审计(platform_listing_host_execution)。见 platform.md。
执行节点节点令牌 oan_…,经 /v1/nodes/connect运行网关为它登记过的智能体所分派的工作。见下文「执行节点」。
智能体(模型或外部命令行智能体)—自身不被信任做任何事。它的输出是不可信的数据。执行级别为 host 的外部智能体以网关的操作系统用户身份运行,拥有该用户的文件和(继承来的)环境。

在每个入口上都强制执行的边界(OpenAI Chat/Responses、Claude Messages、Gemini、原生 /v1/runs、文件、时间线、事件流):

  • 密钥 → 所有者:每个查询都按密钥的所有者过滤。
  • 密钥 → 主体:运行、文件、产物和记忆的读取按调用方的主体过滤(src/core/contracts.ts 里的 visibleSubject);别人的 ID 返回 404,不暴露它是否存在。取消、恢复、批准和对账用同一个过滤。
  • 密钥 → 智能体:authorize() 对一次运行上的每个读取和操作检查智能体授权。
  • 密钥 → 执行级别:低于 host 的密钥不能启动需要 host 的智能体(外部智能体、主机工具),沿委派链和回退链在任何工作开始前检查(isolation_required)。唯一的放宽是开发者平台的按上架项 host_execution 开关,它只对那一个智能体打开 host,不会对它委派的智能体打开;所有者打开它,就等于接受平台账号可以让那个智能体以网关的操作系统用户身份行动,范围受它的 approvals 策略和工作目录限制。
  • 吊销 / 过期 / 账号停用 在下一个请求生效;已打开的事件流会重新校验它的密钥,密钥失效后就关闭(实测:/v1/catalog/events 流在 DELETE /v1/keys/:id 之后几毫秒内结束)。

执行节点

  • 节点用 Authorization: Bearer oan_… 加 x-oaa-node-id 连接;网关只保存令牌的 SHA-256,并用常数时间比较。它的能力声明必须在登记时给它的能力之内(node_scope_denied)。吊销节点会立即关闭它的套接字;排空则停止派发新工作。
  • 每条消息都做模式校验,单帧上限 24 MiB。只有对网关发给那个套接字、且租约 ID(随机)匹配的请求,才接受结果和事件,所以节点既读不到也答复不了放在别的节点上的工作,也永远拿不到 API 密钥、别的调用方的运行或网关自己的机密。
  • 一个恶意或被攻破的节点能做的事:看到放在它上面的工作的全部内容(智能体指令、调用方输入、输入文件,以及运行用到的调用方自带的 BYOK 模型密钥);为这些运行返回伪造的输出、产物和令牌用量(用量会影响配额和平台计费);声称自己具备实际并未强制执行的隔离级别(workspace/sandbox);为它自己待处理的运行发送大量事件或 24 MiB 的帧。
  • 一个恶意的网关能让节点做的事:以网关选定的提示词、文件和隔离级别,运行节点自己配置并启用的智能体和工具(原生/ACP 智能体、MCP 服务器、scripts 里列出的脚本运行时)。只在节点上启用你愿意让网关管理员在那台机器上运行的东西,并且只连接你信任的网关(非本机网关必须用 wss://)。

外部智能体、ACP 与 MCP

  • ACP 智能体不获得客户端的文件系统或终端能力(fs.readTextFile/writeTextFile: false、terminal: false);任何 fs/* 或 terminal/* 请求都回答「方法不存在」。ACP 智能体用它们自己的工具读写文件、运行命令,在自己的进程里、以网关的操作系统用户身份。它们的 session/request_permission 请求走所有者审批流程,并且只会选「仅允许这一次」的一次性选项。在桥接的一轮里,只有请求标题恰好就是调用方提供的中继工具名时,才会自动批准(标题只是提到中继和某个工具名,例如一条 shell 命令,仍然需要审批)。
  • 智能体报告的文字(标题、工具名、路径、输出)在控制台里用 textContent 显示,绝不作为 HTML。
  • MCP 服务器在 worker 配置里按名字配置:stdio 服务器得到它的 command、MCP SDK 的基本环境(如 PATH、HOME)以及 envNames 里列出的额外变量名;HTTP 服务器要求 https(回环地址除外),并从 tokenEnv 取 bearer 令牌。调用方不能添加或修改服务器;智能体只能使用管理员发布的服务器。MCP 服务器返回的工具描述和结果会原样交给模型:恶意或被攻破的 MCP 服务器可以对智能体做提示词注入。
  • oaa mcp(网关作为 MCP 服务器)是一个本机 stdio 进程,用你给它的 API 密钥调用网关,权限恰好就是那个密钥的权限。调用方工具中继(oaa mcp-relay)通过 0700 目录里的 Unix 套接字通信,并且必须出示每一轮随机生成的令牌。

凭据存储

  • 受管的 API 密钥、门户会话、节点令牌、重置码和兑换码只以 SHA-256 哈希保存;明文只显示一次。配置文件里的密钥在启动时从环境变量或文件读入,只保存在内存里。
  • 比较对哈希使用 timingSafeEqual。
  • 门户密码使用 scrypt(N=32768、r=8、p=3、16 字节盐);不存在的邮箱也同样花一次 scrypt 的代价。修改或重置密码、停用账号,会结束它的全部会话。
  • 登录、注册、密码重置与兑换码试错按客户端 IP、邮箱和账号限速,并持久化存入 SQLite(platform_rate_limits),网关重启后计数不丢失。
  • 配置可选的 platform.verificationWebhookUrl 后,注册与自助密码重置统一返回「请查收验证码」(消除 email_taken 邮箱枚举),并通过签名 HTTPS POST 异步投递验证码事件。
  • 错误信息会经过 redact(),它去掉 sk-…、oaa_…、oan_…、oas_…、Bearer …、Google AIza…、GitHub、Slack 和 AWS 访问密钥格式以及 key=value 形式的机密。脱敏是安全网,不是保证。

浏览器侧

  • 控制台和门户是同源页面,发送 Authorization: Bearer。不使用 cookie,所以没有 CSRF 面。管理员密钥放在 sessionStorage,门户会话放在 localStorage;网关源上的任何 XSS 都能读到它们。
  • 控制台/门户的全部 HTML 和脚本都从固定的允许列表提供,带严格的 CSP(script-src 'self',没有内联脚本和样式,frame-ancestors 'none')。用户可控的文字(智能体输出、输入、名称、错误)用 textContent 渲染。
  • 每个请求的 Host 必须匹配 allowedHosts(默认:127.0.0.1、localhost、[::1]),这能挡住针对本机网关的 DNS 重绑定。Origin 不是它自己主机的请求会被拒绝,除非列在 allowedOrigins 里。
  • 设置了 consoleHosts 后,控制台和管理员密钥只在这些主机上有效。

默认暴露面

一个全新的 oaa init / oaa quickstart 网关(安全档位 local):

  • 只监听 127.0.0.1,allowedHosts 只有回环名;
  • 有一个覆盖整个所有者的管理员密钥;
  • 新密钥的执行级别默认是 host,除非 defaultKeyExecution 另有设定;
  • 外部智能体继承网关的环境(去掉 OAA_*),除非 nativeEnv 设为允许列表;
  • 开发者平台关闭。

桌面应用(macOS 应用、Windows 启动器)在 127.0.0.1 上运行同一个网关,默认端口 8787(取自应用自己 config.json 里的 port;macOS 应用也可以用一个临时数据目录做隔离运行,见 install.md)。macOS 应用在使用端口上已经在运行的网关之前,会先核对这个网关属于它自己的数据目录;它不会连接那个端口上的其他程序,也不会把管理员密钥交给它们。 macOS 应用每次启动,都会把 localWorker.native 里每个可执行文件存在的原生引擎设为 enabled: true(例如 Codex、Claude Code、Antigravity)。这只是让引擎对本机 worker「可用」;仍然要先发布了智能体,任何密钥才能调用它。第一次启动时,它还会发布离线示例智能体 agent/sample(不调用任何模型),装了 agy 时再发布 Antigravity 示例 agent/antigravity,并用一个对话框把启用和发布了什么告诉你一次(见 install.md)。 Windows 启动器运行 oaa quickstart,它还会创建一个覆盖所有智能体(*)、带 approve 权限的调用方密钥(keys\quickstart.key)。因为新密钥的执行级别默认是 host,这样的密钥可以调用你之后发布的任何 host 级智能体,而那个智能体以你的用户身份在你的机器上运行,能触及的文件、命令和环境它都能用。只要网关保持在回环地址上、密钥留在你的机器上,这就是预期的本机用法。一旦端口能被别处访问(端口转发、隧道、host: 0.0.0.0),它就变成对任何持有密钥的人的远程代码执行。为了让控制台自动登录,macOS 应用在每次载入控制台时,把管理员密钥放进页面的 sessionStorage(它属于窗口里的页面,不属于 localStorage 那样的持久网页存储),只在主框架里、只在网关自己的源上注入。早期版本还把它写进了持久的 localStorage(以及另外两个没有任何代码读取的名字);应用现在每次载入控制台时都会删掉这些副本。密钥文件 admin.token 仍留在数据目录里。

对外开放网关之前

  1. 设置 "security": {"profile": "public"}。你的配置里没设置的每一项,它都会取:defaultKeyExecution: workspace、localWorker.nativeEnv: {mode: allowlist}、maxStoredBytesPerSubject: 256 MiB,以及 security.requestTimeoutMs: 120000(接收一个请求的时间;响应和流不受限制)。你显式设置的值优先。默认档位 local 什么都不改。当配置看起来已经暴露(host 不是回环、设了 publicBaseUrl,或平台开放注册)而档位仍是 local 时,oaa doctor 会报告 security_exposure;它看不到运行时才启动的隧道。远程 worker 的配置是单独的文件:自己在那里设置 nativeEnv。
  2. 终止 TLS(内置 tls 或反向代理),并把 allowedHosts 设为你的公开域名。只在你自己控制的代理后面设置 trustProxy: true,否则基于 IP 的限制要么被所有人共用(所有流量看起来都来自代理),要么可以伪造。
  3. 把 consoleHosts 设为一个单独的、不公开的主机名(或仅限 VPN),让管理员密钥和控制台无法从公开域名访问。
  4. 设置 defaultKeyExecution: workspace(或 sandbox),并且不要把 host 级智能体授权给你分发出去的密钥。host 级智能体按设计就是以你的操作系统用户身份进行远程代码执行。
  5. 把 nativeEnv 设为允许列表,让外部智能体看不到你的模型密钥和其他机密。继承环境时,调用方可以让会用工具的智能体把环境打印出来。
  6. 给每个调用方密钥设置配额(rpm、maxRuns、maxTokens、expiresAt),并设置 maxActiveRunsPerSubject 和 maxStoredBytesPerSubject。文件永远不会自动删除;没有 maxStoredBytesPerSubject 时,带 files 权限的调用方(包括每个门户账号密钥)可以把磁盘写满。
  7. 在前面放一个有连接数限制和请求体/请求头超时的反向代理。在 local 档位下,网关不限制接收请求的时间(requestTimeoutMs 未设置),所以缓慢的上传只能由代理限制。无需认证的门户表单(登录、注册、密码重置)在所有档位下最多接受 64 KiB 的请求体。
  8. 把 approvals: auto 当作「没有人在回路里」:该智能体的每次工具调用都不经询问直接运行。它的发布会被审计。
  9. 审查你发布的 MCP 服务器、HTTP/A2A 适配器地址和模型 baseUrl:网关会调用它们(不跟随重定向),也不会拦截私网或元数据地址,因为这些是管理员设置的,不是调用方设置的。

已知缺口(不防护)

  • 提示词注入:调用方的输入和抓取到的内容会到达智能体。有文件、shell 或网络工具的智能体,可以被诱导在它的执行级别和审批范围内使用这些工具。
  • 环境继承(默认):见上面第 4 项。
  • 有配额的限定智能体的管理员可以创建多个密钥,每个都可以用到它自己的配额。
  • 账号枚举(未配置 verificationWebhookUrl 时):未配置外部验证码回调钩子时,门户注册对已存在邮箱返回 email_taken 以便本机/邀请制注册直接返回可用会话;公网部署请配置 platform.verificationWebhookUrl 以启用统一验证码响应。
  • 单机限速范围:门户防爆破限流持久化存入 SQLite,API 密钥的每分钟请求数(rpm)计数仍按单网关进程内存维护。
  • 被攻破的执行节点能看到放在它上面的运行(包括 BYOK 密钥),并且能返回伪造的结果和用量。
  • 存储的数据(SQLite 和文件)没有静态加密;请用文件权限和磁盘加密保护数据目录。
  • macOS 应用的引擎开关不是可以退出的选项:每次启动都会再次把每个可执行文件存在的原生引擎设为 enabled: true,所以在配置文件里把某个引擎关掉不会保留。让引擎不会运行的,是没有发布使用它的智能体。
  • 旧版 macOS 应用留在网页视图 localStorage 里的管理员密钥副本,会在从同一个源(同一个端口)载入控制台时被删除。如果在这样的版本之后改过端口,旧端口那个源下的副本会一直留在应用的网页存储里,直到再次用那个端口打开控制台。
本页内容