65 lines
3.8 KiB
Markdown
65 lines
3.8 KiB
Markdown
|
---
|
||
|
|
id: T-102
|
||
|
|
title: ZIP 软件包安全解压原型
|
||
|
|
phase: 1
|
||
|
|
deps: [T-002]
|
||
|
|
status: DONE
|
||
|
|
created: 2026-07-16
|
||
|
|
issue: null
|
||
|
|
context_ref: 0d6ed05d7e69f4a8e2a20e93051e1fe48a868940
|
||
|
|
claim_branch: null
|
||
|
|
work_branch: agent/codex/T-102
|
||
|
|
write_paths:
|
||
|
|
- docs/tasks/T-102.md
|
||
|
|
- core/installer/
|
||
|
|
- testdata/zip/
|
||
|
|
- docs/api.md
|
||
|
|
- docs/04-architecture.md
|
||
|
|
- docs/current-state.md
|
||
|
|
---
|
||
|
|
|
||
|
|
## 问题 / 背景
|
||
|
|
|
||
|
|
软件包最终会把远端 ZIP 内容写入 staging 并切换为可执行程序。仅依赖 `archive/zip` 默认行为无法防止路径穿越、Windows 盘符/ADS、符号链接、重复覆盖和 zip bomb,必须在写磁盘前完整预检。
|
||
|
|
|
||
|
|
## 方案
|
||
|
|
|
||
|
|
1. 在 `core/installer` 建立 `Extractor`,调用者显式提供条目数、总解压体积和压缩比限制。
|
||
|
|
2. 两阶段处理:先验证整个中央目录和 entrypoint,全部通过后才创建新的 staging 目录并解压 `payload/` 内容。
|
||
|
|
3. 拒绝绝对路径、盘符/冒号、反斜杠、空/NUL/非规范路径、`..`、大小写折叠重复路径、符号链接、特殊文件、加密条目和协议外顶层条目。
|
||
|
|
4. 对每个条目及全包执行压缩比检查,实际复制时再次用剩余总量限制读取,失败清理本次创建的 staging。
|
||
|
|
5. entrypoint 必须是 payload 内安全相对路径,并对应 ZIP 中的普通文件。
|
||
|
|
6. 使用表驱动测试在运行时生成攻击 ZIP;`testdata/zip` 记录样例策略与限制结论。
|
||
|
|
|
||
|
|
## 验收要点
|
||
|
|
|
||
|
|
- 合法包只把 `payload/` 内容解压到新 staging,不复制 `app.json` / `files.json`。
|
||
|
|
- 绝对路径、`../`、反斜杠穿越、盘符/ADS、符号链接、特殊文件和重复路径全部拒绝。
|
||
|
|
- 条目数、总解压体积、单条/总体压缩比超限全部拒绝。
|
||
|
|
- entrypoint 绝对/穿越/payload 外逃或不存在全部拒绝。
|
||
|
|
- 任一预检/复制失败不留下可被误用的 staging 目录。
|
||
|
|
- Go 1.20 core vet/test 和完整双目标闸门通过。
|
||
|
|
|
||
|
|
## 边界（不改什么）
|
||
|
|
|
||
|
|
- 不实现 SHA-256、Catalog/package 身份比对、app.json/files.json Schema(T-302/T-201)。
|
||
|
|
- 不执行任何包内脚本,不处理 prerequisites。
|
||
|
|
- 不切换 current/backup(T-103)。
|
||
|
|
- 默认限制是 Phase 1 原型值,T-302 正式整合时按真实包规模复核。
|
||
|
|
|
||
|
|
## 协作约束
|
||
|
|
|
||
|
|
未启用 Gitea;本任务在 `agent/codex/T-102` 分支串行执行。Extractor 文档明确要求调用者只传入已完成签名与 SHA-256 校验的 ZIP。
|
||
|
|
|
||
|
|
## 执行记录
|
||
|
|
|
||
|
|
- 2026-07-16:在 `core/installer` 建立 Limits/Extractor,采用完整预检后再创建 staging 的两阶段流程;只解压 `payload/`,不复制根部元数据。
|
||
|
|
- 2026-07-16:路径规则拒绝无效 UTF-8、NUL、绝对/UNC、盘符/冒号/ADS、反斜杠、非规范路径与 `..`;大小写折叠后重复路径也拒绝,避免 Windows 覆盖歧义。
|
||
|
|
- 2026-07-16:拒绝符号链接、特殊文件、加密条目、协议外顶层文件;要求 app.json 存在且 entrypoint 是 payload 内精确匹配的普通文件。
|
||
|
|
- 2026-07-16:原型默认限制为 10,000 条目、4 GiB 总展开、单条/总体 200:1 压缩比;实际复制再次按剩余额度限流并核对 header 展开大小。
|
||
|
|
- 2026-07-16:任一复制、CRC 或关闭错误会删除本次新建 staging;已有 destination 直接拒绝,不覆盖未知内容。
|
||
|
|
- 2026-07-16:攻击 ZIP 由表驱动测试运行时生成,策略记录于 `testdata/zip/README.md`;标准库会先解析中央目录再暴露条目列表,如需抵御超大中央目录的预解析内存压力,T-302 应增加 ZIP 文件/中央目录预扫描限制。
|
||
|
|
- 定向测试通过:合法 payload、绝对/盘符/ADS/`../`/反斜杠、加密、symlink、特殊文件、重复路径、协议外文件、条目数、总展开、压缩比、entrypoint 外逃/缺失、已有 staging 和 CRC 损坏清理。
|
||
|
|
- 验证通过:Go 1.20.14 core vet/test。
|
||
|
|
- 验证通过:`./scripts/verify_phase0.ps1`,包含 modern/win7 双目标构建与治理检查。
|