42 lines
3.3 KiB
Markdown
42 lines
3.3 KiB
Markdown
# Security boundaries
|
||
|
||
## Trust model
|
||
|
||
Pi 没有内置 Sandbox。Project Trust 只控制项目资源加载，不隔离进程、文件系统或网络。Pi、Extension 与 Tool 都继承 Node 进程权限。本项目是安全教学基线，不是恶意代码隔离器。
|
||
|
||
## Credentials and logs
|
||
|
||
- API Key 只经同源 body 进入服务端；Pi 运行时仍使用 Session 专属 `InMemoryCredentialStore`。
|
||
- 前端提交的 API Key 使用 `MODEL_CREDENTIAL_ENCRYPTION_KEY` 提供的 32-byte master key 做 AES-256-GCM 加密，采用随机 96-bit IV、认证标签和模型连接 identity AAD；密文文件使用 `0600` 权限与临时文件原子 rename。master key 只来自 `.env`/进程环境，绝不写入密文文件。
|
||
- 浏览器刷新创建新 Session 时，只提交非敏感模型 identity；服务端按 identity 解密恢复对应凭证。删除 Session 不删除持久凭证，只有 Clear Credentials 会删除。
|
||
- 浏览器 localStorage 只保存白名单模型元数据；保存前主动移除 `apiKey` 并用不接受额外字段的 Zod schema 校验。损坏或超限数据会删除。
|
||
- 不写 Pi 全局 auth/models 文件，不执行 `!command`，不接受自定义 headers。
|
||
- 响应仅回传配置状态和末四位 hint；SSE、事件、日志和测试快照禁止原始 key。
|
||
- Fastify 只记录安全元数据并对 Authorization/API Key 路径 redaction；生产错误不返回 stack/绝对路径。
|
||
|
||
## Filesystem
|
||
|
||
- 每个 Session 独立 canonical cwd；resolve 后必须仍在 root 内。
|
||
- `realpath` 验证父目录，拒绝 `..`、绝对路径逃逸与符号链接路径。
|
||
- `.env`、`.git`、SSH、用户主目录和系统路径受到 preflight 保护。
|
||
- `save_report_draft` 目标固定为 `report.md`，临时排他创建后原子 rename；审批不能替代路径检查。
|
||
- 默认不注册 shell、write、edit。
|
||
|
||
课堂实现使用 Node 文件 API，无法完全消除恶意同机进程造成的 TOCTOU。生产版应把每个任务放进独立 mount namespace / micro-VM，并使用只读输入卷和受控输出卷。
|
||
|
||
## Images
|
||
|
||
multipart 流有字节上限；扩展名、MIME、magic bytes 三重匹配。Sharp 限制像素、解码并重新编码，自动旋转且移除多余 metadata。随机文件名仅写 Session attachments，预览不提供任意路径静态服务。事件仅记录 ID、MIME、大小和尺寸。
|
||
|
||
## Model Base URL and SSRF
|
||
|
||
默认 HTTPS；拒绝 URL credentials、fragment、危险 credential query、畸形 URL、metadata hostname，以及 DNS 解析得到的 private/loopback/link-local 地址。开发环境可使用 loopback HTTP，企业内网必须显式 opt-in。DNS rebinding、重定向逐跳策略和出口 DNS 固定应由生产 egress proxy 强制执行。
|
||
|
||
## Approval
|
||
|
||
审批发生在 Pi `tool_call` preflight，Tool 尚未执行。Broker 校验当前 Session/Run、响应 abort、释放 timer/Promise，并将 approve/deny/expired/cancelled 作为服务器事实发送。未知工具 deny，未注册高风险工具无法被模型调用。
|
||
|
||
## Required production isolation
|
||
|
||
不可信 Skill、仓库、脚本、附件解析或无人值守 Agent 必须在 Docker（配合 seccomp/AppArmor 和无特权用户）、VM、micro-VM 或远程 Sandbox 运行，并施加 CPU/内存/磁盘/时间/网络配额。Project Trust 不能替代这些措施。
|