Nexus/docs/reports/2026-06-06-api-audit-b1-servers-webssh.md

API 巡检 B1 — servers.py + webssh.py

日期: 2026-06-06
范围: server/api/servers.py（28 端点）、server/api/webssh.py（1 WS）
方法: 8 维清单（认证/越权/注入/路径/凭据/输入/错误/审计）

结论

级别	数量	说明
P0	0	—
P1	0	—
P2	1	已修：ServerCheck.server_ids 无上限 → DoS
H	3	已记录/接受，见下表

批次结论: PASS（修复已合入工作区）

---

端点覆盖

全部 29 个路由均要求 get_current_admin（REST）或 WebSSH 专用 JWT（purpose=webssh + server_id 绑定）。

模块	端点	认证	审计 CUD	备注
servers	CRUD / /{id}	JWT	✓	_server_to_dict 不返明文密码/私钥
servers	/stats /categories /logs	JWT	—	只读；stats 有 online 封顶
servers	/import	JWT	✓	1MB/500 行；CSV 注入防护 _sanitize_csv_cell
servers	/batch/*	JWT	✓	server_ids max 50；SSH shlex.quote
servers	/add-by-ip /pending/*	JWT	✓（已补 retry 失败）	轮询失败写 pending + 审计
servers	/agent-key /agent-install-cmd	JWT + 密码复核	✓	不回落全局 API_KEY
servers	/install-agent	JWT	✓	服务端 SSH 可用全局 KEY 作 fallback（H）
servers	/check	JWT	—	已修 max 50 server_ids
webssh	/ws/terminal/{id}	JWT query	connect/disconnect	server_id 绑定；命令审计 + 危险命令检测

---

FINDING 明细

P2-01 — POST /api/servers/check 无 server_ids 上限（已修）

• 风险: 传入数千 ID 触发并行 SSH 探测，资源耗尽。
• 修复: ServerCheck.server_ids 增加 max_length=50（与 BatchAgentAction 一致）。
• 文件: server/api/schemas.py

H-01 — WebSSH 遗留 token 无 tv 字段时回退 updated_at 宽限

• 位置: webssh.py _verify_webssh_token
• 影响: 改密后 5 秒内旧 WebSSH token 仍可能有效（新签发 token 均含 tv）。
• 处置: 接受（单人运维模型）；新 token 路径已安全。

H-02 — install-agent 无 per-server key 时回落 settings.API_KEY

• 位置: servers.py install_agent_remote
• 影响: 仅用于 SSH 下发安装命令，不向 API 响应暴露全局 KEY。
• 处置: 接受；与 Agent 安装运维模型一致。

H-03 — retry_pending 失败与 delete_pending 审计字段不完整（已修）

• 修复: 失败重试写 retry_pending_server_failed 审计；删除前读取 pending 写入 detail。
• 文件: server/api/servers.py

---

安全亮点（无需改动）

• _server_to_dict: password_set / ssh_key_private_set / agent key 预览
• update_server: ALLOWED_FIELDS 白名单，禁止 mass-assign agent_api_key
• _sudo_wrap: 临时 sudoers 白名单命令 + 事后清理
• setup-files-sudo: 密码经 stdin 喂 sudo -S，不进 argv
• WebSSH: token server_id 与路径参数必须一致（防 IDOR）
• CSV import: 大小/行数限制 + formula injection 防护

---

验证

.venv/bin/pytest tests/test_credential_poller.py tests/test_security_unit.py -q

---

下一批: B2 — sync_v2.py + files.py + remote_path_validation.py