# 主计划执行审计 — 文件管理 / POSIX / 二期

| 项 | 内容 |
|----|------|
| 日期 | 2026-06-01 |
| 触发 | 主待办长计划 Phase A～E 连续执行 |
| 关联 | [2026-06-01-master-backlog-plan.md](../project/2026-06-01-master-backlog-plan.md) |

## 审计范围（改动文件清单）

| 文件 | 状态 |
|------|------|
| server/utils/posix_paths.py | ☑ 已审 |
| server/api/remote_path_validation.py | ☑ 已审 |
| server/api/schema_path_validators.py | ☑ 已审 |
| server/api/schemas.py | ☑ 已审 |
| server/api/sync_v2.py | ☑ 已审 |
| server/api/servers.py | ☑ 已审 |
| server/application/services/sync_engine_v2.py | ☑ 已审 |
| server/infrastructure/ssh/asyncssh_pool.py | ☑ 已审 |
| server/infrastructure/ssh/remote_shell.py | ☑ 已审 |
| server/infrastructure/ssh/remote_archive.py | ☑ 已审 |
| server/infrastructure/ssh/files_capability.py | ☑ 已审 |
| server/utils/files_elevation.py | ☑ 已审 |
| server/utils/files_chmod_policy.py | ☑ 已审 |
| server/utils/unix_ls.py | ☑ 已审 |
| frontend/src/utils/remotePath.ts | ☑ 已审 |
| frontend/src/utils/fileMode.ts | ☑ 已审 |
| frontend/src/utils/fileBrowse.ts | ☑ 已审 |
| frontend/src/utils/filePreload.ts | ☑ 已审 |
| frontend/src/components/FileDirectoryTree.vue | ☑ 已审 |
| frontend/src/components/FileEditorWorkbench.vue | ☑ 已审 |
| frontend/src/components/FilePermissionDialog.vue | ☑ 已审 |
| frontend/src/composables/useFilesClipboard.ts | ☑ 已审 |
| frontend/src/api/index.ts | ☑ 已审 |
| frontend/src/components/MonacoEditor.vue | ☑ 已审 |
| frontend/src/pages/FilesPage.vue | ☑ 已审 |
| frontend/src/pages/ServersPage.vue | ☑ 已审 |
| frontend/src/types/api.ts | ☑ 已审 |
| tests/test_posix_paths.py | ☑ 已审 |
| tests/test_remote_path_validation.py | ☑ 已审 |
| tests/test_schema_path_validators.py | ☑ 已审 |
| tests/test_unix_ls.py | ☑ 已审 |
| tests/test_file_permissions.py | ☑ 已审 |
| tests/test_files_elevation.py | ☑ 已审 |
| tests/test_api.py | ☑ 已审（pytest 不收集；门控用 `python tests/test_api.py`） |
| docs/deploy/nexus-files-sudoers.example | ☑ 已审 |
| deploy/pre_deploy_check.sh | ☑ 已审（CRLF→LF 修复） |

## Step 3 规则扫描（H）

| H | 规则 | 结论 |
|---|------|------|
| H1 | 命令注入 | PASS — 远程 path `shlex.quote` + `normalize_remote_abs_path` |
| H2 | 提权滥用 | PASS — `files_elevation` 三档；禁止 `/` 等递归 chmod |
| H3 | 凭据泄露 | PASS — API 不返回密码；capability 不泄露 sudoers 内容 |
| H4 | 架构分层 | PASS — 解析/策略在 utils；API 编排 |
| H5 | 跨层直连 | PASS — API→infra SSH，无 ORM 内 SQL |
| H6 | 静默失败 | PASS — chmod/browse 返回明确 error |
| H7 | 路径 Windows | PASS — `posix_paths` SSOT；前端 `remotePath.ts` |
| H8 | 批量 chmod | PASS — 递归需目录+确认+系统路径黑名单 |

## Step 4 Closure 表

| H | 判定 | 依据 |
|---|------|------|
| H1 | SAFE | sync_v2.py chmod/browse 均 quote |
| H2 | SAFE | remote_shell.py:34-61 elevation 分支 |
| H3 | SAFE | files_capability.py 仅返回布尔与 message |
| H4 | SAFE | 无 Service 层绕过 |
| H5 | SAFE | — |
| H6 | SAFE | sync_v2 browse 返回 error 字段 |
| H7 | SAFE | rg server 无远程 os.path.join |
| H8 | SAFE | files_chmod_policy.py FORBIDDEN_* |

## Step 5 入口表

| 入口 | 认证 | 说明 |
|------|------|------|
| POST /api/sync/browse | JWT | ls 只读 |
| POST /api/sync/chmod | JWT | mode/owner/recursive |
| POST /api/sync/read-file | JWT | cat+sudo 回退 |
| GET /api/servers/{id}/files-capability | JWT | SSH 探测 |
| PUT /api/servers/{id} | JWT | files_elevation→extra_attrs |

## Step 6 输入 → Sink

| 输入 | 校验 | Sink |
|------|------|------|
| path | coerce_remote_abs_path | SSH 命令 |
| mode | `^[0-7]{3,4}$` | chmod |
| owner/group | `[a-zA-Z0-9_.-]+` | chown |
| recursive | bool + test -d + policy | chmod -R |

## Step 7 归类

```
remote_shell.py       64行  8H  0 FINDING
files_capability.py   63行  8H  0 FINDING
files_chmod_policy.py 30行  8H  0 FINDING
sync_v2.py (chmod)   ~80行  8H  0 FINDING
────────────────────────────────────────
总计                  8H   0 FINDING
```

## Step 8 DoD

- [x] Phase A 单测 44 passed（posix+file 套件）
- [x] ruff server/ 全规则（Windows 开发机）
- [x] import server.main
- [x] bandit 0 HIGH（MEDIUM 不阻断门控）
- [ ] Gate 3 test_api — 需运行中后端（本地 503 = 安装模式/未启动）
- [ ] Gate 7 Review — 本地 git HEAD~1 跨多历史提交，生产部署后以服务器仓库为准
- [ ] Phase B 生产部署 — 待 push + ssh
- [ ] Phase C 浏览器 L1-L4 — 待人工

## FINDING 列表

无（0 FINDING）。

## 批次 POSIX-13 结论

| 文件 | 结论 |
|------|------|
| remote_shell.py | ✅ sudo 经 `shlex.quote(command)` 包装 |
| files_capability.py | ✅ 固定探测命令，无用户输入拼接 |
| files_chmod_policy.py | ✅ 路径白名单集合 |

## 结论

☑ 代码审计通过，0 FINDING。  
☑ 可合并；**部署前**在生产机执行 `pre_deploy_check.sh`（需 Nexus 进程 + `.env` + test 凭据）。
