50 lines
4.9 KiB
Markdown
50 lines
4.9 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 不能替代这些措施。
|
||
|
||
## SW Ads read-only facade and artifacts
|
||
|
||
- `SWADS_MCP_TOKEN` 仅存在服务端配置和出站 Authorization Header。URL 不允许凭据/query/fragment；fetch 禁止 redirect，避免 Header 转发。Gateway 原始错误正文、Headers 和 Token 不进入模型/SSE/日志/下载，返回固定 `SWADS_*` 错误分类。响应中的 Token 精确值及敏感键在模型交付前脱敏。
|
||
- `swads_cli` 只允许约定九个 command。参数拒绝任意 URL/Header/Token/tool name 和未知顶层字段；语义 query 允许有界嵌套 JSON，但不能提供传输控制项。Tool 必须存在并声明只读；非只读 `runtime_findings` 禁止执行。缺少所需 TikTok 能力时 fail closed，不用 mock 数据兜底。
|
||
- `render_swads_daily_report` 不接收路径、命令或 Chrome 参数。strict schema 限制字符串/数组长度、真实 ISO 日期、有限数值/null、倍率/百分比与恰好三条建议。动态 HTML 字段全部转义，CSS 无外部字体；CSP 禁止脚本/网络资源，Chrome 使用独立临时 profile、固定参数和进程超时。
|
||
- Artifact URL 仅按 accountKey、ISO 日期、UUID 和 png/html/json enum 定位；逐段拒绝 symlink，无目录枚举。PNG inline、HTML/JSON attachment，准确 MIME、nosniff、限制性 CSP、private no-store。随机 ID 不是身份授权，现有单进程无认证应用仅适合内部/本地边界；公网多租户部署需要独立授权设计。
|
||
- JSON/HTML 即使 PNG 失败仍保留。PNG 超时、缺浏览器、截断分别返回 warning；取消 Run 则清理未发布临时目录。报告不随 Session 删除，部署方需管理持久目录容量。
|