docs: files迭代审计报告

docs/audit/2026-05-30-files-iteration.md

@@ -0,0 +1,93 @@
+# 审计记录 — files.html + sync_v2.py 全面迭代
+
+## 审计信息
+
+- **日期**: 2026-05-30
+- **审计人**: Claude (AI) + 用户确认
+- **触发原因**: 文件管理器全面迭代（15项改进）
+
+## 审计范围
+
+| 文件 | 行数 | 状态 |
+|------|------|------|
+| web/app/files.html | 439 | ☑ 已审 |
+| server/api/sync_v2.py | 1200 | ☑ 已审 |
+| server/api/schemas.py | 215 | ☑ 已审 |
+
+## 审计8步结果
+
+### Step 1: 登记 ✅
+### Step 2: 全文Read ✅
+### Step 3: 规则扫描H — 30 项
+### Step 4: Closure表
+
+| H-xx | 严重度 | Closure | 说明 |
+|------|--------|---------|------|
+| H-01 | HIGH | **ACCEPTED_RISK** | 远程路径无限制 — 用户明确决策"不加限制" |
+| H-02 | LOW | **FINDING→已修** | Content-Disposition filename sanitize |
+| H-03 | LOW | ACCEPTED_RISK | base64 echo 单引号，RFC 4648 字母表安全 |
+| H-04 | LOW | FALSE_POSITIVE | upload 路径穿越检查充分 |
+| H-05 | N/A | FALSE_POSITIVE | 无 SQL 操作 |
+| H-06 | INFO | FALSE_POSITIVE | esc() 覆盖完整，无 XSS |
+| H-07 | N/A | FALSE_POSITIVE | 无 HTTP 客户端 |
+| H-08 | N/A | FALSE_POSITIVE | 无明文密码 |
+| H-09 | N/A | FALSE_POSITIVE | 无硬编码密钥 |
+| H-10 | INFO | FALSE_POSITIVE | 审计失败降级合理 |
+| H-11 | N/A | FALSE_POSITIVE | JWT 全覆盖 |
+| H-12 | LOW | **FINDING→已修** | path 字段加 max_length=4096 |
+| H-13 | N/A | FALSE_POSITIVE | 全部有审计日志 |
+| H-14 | INFO | FALSE_POSITIVE | Bearer token 免疫 CSRF |
+| H-15 | MEDIUM | **FINDING→已修** | download 加 100MB 大小限制 |
+| H-16 | LOW | ACCEPTED_RISK | batchDelete is_dir 不影响结果 |
+| H-17 | LOW | ACCEPTED_RISK | 竞态概率极低 |
+| H-18 | INFO | FALSE_POSITIVE | parseInt 源数据安全 |
+| H-19 | N/A | FALSE_POSITIVE | Pydantic 自动校验 |
+| H-20 | N/A | FALSE_POSITIVE | JS pop() 安全 |
+| H-21 | N/A | FALSE_POSITIVE | 线性遍历无循环风险 |
+| H-22 | INFO | FALSE_POSITIVE | async with + finally 双重保护 |
+| H-23 | LOW | **FINDING→已修** | 同 H-15，合并修复 |
+| H-24 | INFO | FALSE_POSITIVE | async 架构 |
+| H-25 | N/A | FALSE_POSITIVE | 无 DB 密集操作 |
+| H-26 | INFO | ACCEPTED_RISK | ls 截断 10000 字符足够 |
+| H-27 | LOW | **FINDING→已修** | doPreview 保存失败解析错误详情 |
+| H-28 | INFO | ACCEPTED_RISK | 错误处理整体一致 |
+| H-29 | INFO | **FINDING→已修** | esc() 加注释 |
+| H-30 | INFO | ACCEPTED_RISK | ls -la 解析器正确 |
+
+### Step 5: 入口表 ✅
+全部 API 端点已检查（download/read-file/write-file/browse/file-ops/upload）。
+
+### Step 6: 输入→Sink ✅
+所有用户输入路径已追踪：
+- download: path → sftp.stat → StreamingResponse
+- read-file: path → stat -c%s → cat
+- write-file: path + content → base64 + tee
+- file-ops: path → shlex.quote → SSH exec
+- upload: remote_path + filename → SFTP put
+
+### Step 7: 归类
+
+```
+web/app/files.html                  439行  10H  2FINDING → 0FINDING
+server/api/sync_v2.py              1200行  12H  3FINDING → 0FINDING (1 ACCEPTED_RISK)
+server/api/schemas.py               215行   8H  1FINDING → 0FINDING
+──────────────────────────────────────────────────────────────────
+总计                                  6 FINDING → 0FINDING (全部已修或 ACCEPTED_RISK)
+```
+
+### Step 8: DoD ✅
+
+## FINDING 列表
+
+| 编号 | 严重度 | 描述 | 修复方式 |
+|------|--------|------|----------|
+| H-01 | HIGH | 远程端点无路径限制 | ACCEPTED_RISK — 用户决策 |
+| H-15 | MEDIUM | download 无大小限制 | 加 100MB stat.size 检查 → 413 |
+| H-02 | LOW | Content-Disposition 头注入 | re.sub 替换特殊字符 |
+| H-12 | LOW | path 无 max_length | 三个 schema 加 max_length=4096 |
+| H-27 | LOW | doPreview 保存错误丢失详情 | 解析 wr.json() 显示 detail |
+| H-29 | INFO | esc() 缺注释 | 加 /** HTML-escape */ 注释 |
+
+## 结论
+
+☑ 审计通过，6 FINDING 全部已处理（5 修复 + 1 ACCEPTED_RISK），0 遗留，可部署