Nexus/docs/reports/2026-06-06-api-audit-b2-sync-files.md

API 巡检 B2 — sync_v2.py + files.py + remote_path_validation.py

日期: 2026-06-06
范围: 22 个 /api/sync/* 端点 + GET /api/files/browse + 路径校验模块

结论

级别	数量	说明
P0	0	—
P1	0	—
P2	1	已修：SyncFiles/SyncVerify server_ids 无上限
H	1	_audit_sync 写失败仅 warning（不阻断业务）

批次结论: PASS

---

覆盖摘要

检查项	结果
全部 sync 端点 JWT	✓ 22/22 get_current_admin
远程路径	✓ normalize_remote_abs_path / remote_join
本地 staging	✓ ensure_under_nexus_upload 限制 /tmp/nexus_upload_*
Shell 拼接	✓ 普遍 shlex.quote
上传限制	✓ 单文件 100MB；ZIP 500MB
剪贴板 copy/move	✓ assert_clipboard_transfer_safe 防 dest 在源子树内
files GET browse	✓ ETag + 路径规范化 + 审计

---

FINDING

P2-02 — SyncFiles / SyncVerify server_ids 无 max_length（已修）

• 风险: 超大列表导致海量协程调度与 DB 查询（verify 虽 Semaphore(5) 仍会创建 N 个 task）。
• 修复: max_length=2000（对齐平台子机规模上限）。
• 文件: server/api/schemas.py

H-04 — _audit_sync 异常时 logger.warning 不向上抛

• 位置: sync_v2.py _audit_sync
• 处置: 接受 — 审计失败不应阻断文件操作；已有 exc_info 日志。

---

安全亮点

• file-ops delete 使用 rm -rf 但路径经 normalize_remote_abs_path 校验
• upload 文件名剥离 / \
• local-file-ops rename 禁止 .. / .
• write-file 5MB 上限 + etag 乐观锁（409）
• read-file 1MB 默认上限

---

下一批: B3 — auth + auth_jwt + dependencies