agent/docs/security-boundaries.md

安全边界

信任模型

浏览器输入、模型输出、工具参数、上传文件名、MIME、Base URL、Skill 额外路径和 SSE cursor 都是不可信输入。Zod / TypeBox 负责结构校验，Harness 负责语义与权限校验，操作系统仍是最终权限边界。

已实现的课堂版保护

凭证

• Session 配置覆盖服务器环境变量；没有配置时明确报错。
• API Key 只保存在 Server 内存和 Pi InMemoryCredentialStore。
• 响应只返回 keyHint，不会返回原值或长度。
• 不写浏览器 Storage、日志、事件、URL、Pi 用户目录或仓库文件。
• 运行中禁止修改模型；清除凭证幂等。

Base URL / SSRF

• 使用 WHATWG URL，默认仅 HTTPS。
• 拒绝 userinfo、fragment、非 HTTP(S)、异常端口和含凭证 query。
• DNS 结果若命中 loopback、private、link-local、unspecified、multicast 或 metadata 范围则拒绝。
• 开发模式只对显式 localhost HTTP 开例外；企业内网需要服务器管理员设置环境变量。
• 当前请求策略要求同源重定向，不能依赖首次 URL 校验后任意跳转。

路径与写入

• 每个 Session 使用独立随机目录。
• 已发现的 Skill 正文复制到 Session 内只读快照；Pi 仅使用该快照清单，不向模型工具开放项目或用户目录。Drama Minis 额外复制明确白名单内的两份参考文档、主题、渲染脚本及两份结构示例；逐段拒绝符号链接，单文件上限 1 MiB。其他 Skill 默认仍只复制正文。
• realpath + relative containment 防止 .. 和绝对路径逃逸。
• 逐段拒绝符号链接，并保护 .env、.git、.ssh 和常见私钥名。
• write tool 只能调用 SafeWorkspace.writeReportDraft，目标固定为 report.md，临时文件以独占创建并原子 rename。
• 删除 Session 会取消 run 和审批，并清除附件和整个 Session 目录。

图片

• 只收 JPEG、PNG、WebP；同时检查扩展名、MIME 和 magic bytes。
• 流式字节上限、宽高上限与总像素上限阻止常见资源耗尽输入。
• Sharp 自动旋转并重新编码，去掉不需要的元数据。
• 随机服务端文件名，权限 0600；不提供任意路径下载或静态目录。
• base64 只在 Server 构造 Pi prompt 的最后阶段短暂存在。

工具与审批

• allowlist 只开放课堂所需 read-only 工具。
• 未知工具默认拒绝。
• save_report_draft、真实指标查询 metrics_semantic_query、报告生成 generate_minis_report 在 Pi tool preflight 阶段等待服务器 Broker。查询审批展示实际参数与第三方模型数据处理提示。
• 审批绑定 approvalId、runId 和 toolCallId；支持 approve、deny、expired、cancelled。
• Browser 点击不是最终事实，只有 approval.resolved 事件能改变投影状态。

Drama Minis 真实数据与报告

• 服务端使用官方 MCP SDK，固定 swads HTTPS 地址，禁止重定向，只开放身份、目录和语义查询；未开放广告修改接口。
• swads token 仅由服务端环境注入，缺失时明确失败。源工具结果按 token 精确脱敏，不使用模拟数据替代失败。
• 报告必须引用同一 Session 已成功的真实查询 ID，JSON 保存查询参数和原始返回；这提供可追溯性，但不自动证明模型计算的每个字段正确。
• 仅运行管理员指定 Skill 中的固定 Python 渲染脚本，模型不能指定任意命令。Python/Chrome 子进程不继承 API 凭证。Chrome 禁止背景网络并使用临时 profile；这不是通用网络隔离。
• 当前原始渲染器的图表单位固定为 USD，因此其他币种明确拒绝生成，不静默换算或合并。
• 下载限定 Session、注册 report ID 与 json/html/pdf 三种格式；no-store、nosniff、attachment、沙盒 CSP。PDF 失败时仅返回 HTML/JSON 及明确提示。
• 仍是单用户 localhost 原型，无用户级身份认证。不得直接暴露公网或作为多租户生产服务。

不提供的隔离

Pi 没有内置 Sandbox，Project Trust 也不是 Sandbox。Pi Agent、Extension、Sharp 和所有 Node 依赖继承启动进程的用户权限与网络权限。应用层路径校验和审批不能防御依赖漏洞、Node 进程逃逸、同用户数据读取或不受控的出站模型请求。

因此不要用该课堂版处理生产密钥、不可信租户代码或敏感业务文件。真正部署至少需要：低权限系统用户、只读基础镜像、每 Session 容器或 microVM、挂载白名单、seccomp、出站网络 allowlist、资源配额和销毁验证。

部署前仍需补齐

• 登录、Session 所有权、租户授权和管理员权限。
• SameSite Secure cookie、CSRF、防点击劫持和严格 CSP。
• API、上传、run 和审批的速率限制与配额。
• KMS / Secret Manager，不在应用堆中长期保存明文凭证。
• 持久化且防篡改的审计日志。
• 恶意图片扫描、对象存储隔离和生命周期策略。
• 分布式锁、幂等键、Broker 持久化和崩溃恢复。