Nexus/docs/reports/2026-06-06-external-attack-hardening-backlog.md

外网攻击面加固 Backlog（audit_only 产出）

日期：2026-06-06
来源：2026-06-06-external-attack-surface-audit.md
状态：BL-01～BL-05 已实施；BL-06～BL-08 待定（见总报告 §7）

---

P2 — 建议优先

BL-01 收紧 PUBLIC_PREFIXES 前缀匹配 ✅ 已实施

字段	内容
问题	EXT-01 /health/detail、EXT-02 bing-wallpapers/sync 被前缀误放行
方案 A	将 /health 改为精确路径列表；/api/settings/bing-wallpapers 仅匹配 GET（或拆路由前缀）
方案 B	_is_public_path 改为精确匹配 + 显式允许方法
涉及文件	server/api/auth_jwt.py
验收	无 JWT 时 GET /health/detail → 401；POST .../sync → 401
回滚	恢复 PUBLIC_PREFIXES 元组

BL-02 /health/detail 强制鉴权（防御纵深） ✅ 已实施

字段	内容
问题	非 /api/ 路径不走 JwtAuthMiddleware
方案	handler 内显式 if admin is None: raise 401；或把 detail 移到 /api/health/detail
涉及文件	server/api/health.py、server/main.py DbSessionMiddleware 路径列表
验收	生产探测 401

BL-03 bing_wallpapers_sync 拒绝 admin is None ✅ 已实施

字段	内容
方案	Depends(get_current_admin) 返回 None 时 raise 401（与 BL-01 双保险）
涉及文件	server/api/settings.py

---

H — 信息暴露与运维

BL-04 生产关闭 OpenAPI / Swagger / ReDoc ✅ 已实施

字段	内容
问题	EXT-03 全 API schema 公网可读
方案 A	FastAPI(..., docs_url=None, redoc_url=None, openapi_url=None)
方案 B	Nginx/1Panel location deny 或 internal only
验收	GET /openapi.json → 404
备注	开发环境可保留文档

BL-05 已安装后隐藏 install 指纹 ✅ 已实施

字段	内容
实现	_raise_not_found_if_locked()；全部 install 端点锁定后 404
涉及文件	server/api/install.py、tests/test_install_locked_404.py
验收	锁定后所有 /api/install/* → 404

BL-06 Agent per-server key 迁移 ⏸ 待定

字段	内容
问题	global API_KEY legacy 回退（已 risk-acceptance）
方案	批量 POST /api/servers/{id}/agent-key；监控 warning 日志；最终禁用 global 回退
重评条件	见 risk-acceptance-single-operator.md §接受项 2

BL-07 WebSocket 外网探测与反代 ⏸ 待定

字段	内容
问题	外网 WS 403，与应用 4001/4401 不一致
方案	核对 Nginx proxy_set_header Upgrade；内网或 curl upgrade 验证关闭码
备注	WS query JWT 改造 ROI 低，维持 ADR-011 接受项

BL-08 全站 IP 白名单（可选） ⏸ 待定

字段	内容
范围	Nginx 层限制 /api/*（非仅 login）
风险	2000+ 子机 Agent 心跳需放行；需细粒度路径规则

---

验证清单（修复批次）

NEXUS_PROBE_BASE=https://api.synaglobal.vip bash scripts/security_probe_external.sh
# 期望：health/detail 401；bing sync 401；openapi 404（若 BL-04）
bash scripts/local_verify.sh

---

不建议本轮做

项	原因
WS ticket 首帧鉴权	单人运维 ROI 低，已接受
登录暴破 CAPTCHA	已有 15min 锁定
关闭 /agent/install.sh 公网	破坏远程安装流程