# Phase 2 逐行走读 — 修复总览（开发 SSOT）

> **最后更新**: 2026-05-23  
> **项目阶段**: **开发中，尚未首次部署** — 无生产环境、无 API Key 历史包袱  
> **状态**: Phase 2 **代码修复已闭环** · 首次部署前再跑 E2E 即可  
> **矩阵**: [`audit-phase-2-findings-matrix.md`](../reports/audit-phase-2-findings-matrix.md)  
> **验证**: [`production-verification-checklist.md`](production-verification-checklist.md)

---

## 1. 范围与结论

| 维度 | 说明 |
|------|------|
| 审计方式 | Phase 2a–2j 逐行走读 + P0/P1/P2 分批修复（2026-05-22～23） |
| FINDING 总数 | **63** 条独立 ID |
| ✅ 已修复 | **52** |
| 🟡 部分缓解 | **3**（WebSSH/告警 WS 的 URL 带票、E2E 测试覆盖） |
| 📋 设计接受 | **7**（子机 shell 面、JWT localStorage、重试语义等） |
| — 不适用 | **1**（中心 `/api/agent/exec` 已删除） |
| **代码待办** | **0**（P0/P1 代码项已全部落地） |
| **运维待办** | **0**（未部署；F2f-04 轮换 **不适用**，见 §9） |

与 [`2026-05-23-full-audit-report.md`](../reports/2026-05-23-full-audit-report.md) 的关系：全量报告为 7 部门并行初审清单；本文件记录 **Phase 2 走读已落地** 的修复与 **明确不接受/延后** 的项，避免重复劳动。

---

## 2. 按主题 — 已落地修复

### 2.1 认证与 API 边界

| 主题 | FINDING | 实现要点 |
|------|---------|----------|
| WebSSH IDOR | F2a-01 | `POST /api/auth/webssh-token` 专用短票 + 强制 `server_id` 绑定 |
| 中心 RCE | F2a-02 | 删除中心 `/api/agent/exec` |
| 全局 JWT | F2a-10, F2d-02 | `JwtAuthMiddleware`（`main.py` 注册，位于 `DbSession` 内层） |
| 安装锁 | F2a-08, F2d-03 | 安装后除 `GET /api/install/status` 外 **403**；安装模式 `/ws/` **503** |
| API Key 泄露面 | F2f-04, F2a-12, F2a-16 | 压测改环境变量；生成 key 一次性展示；reveal 需密码+审计 |
| Agent 鉴权 | F2f-02, F2a-03 | 启动强制非空 API Key；`compare_digest` |

**公开路径**（不经 JWT）：`/api/auth/login|refresh|logout`、`/api/agent/*`、`/api/install/*`、`/health`、`/ws/*`、OpenAPI 文档。

### 2.2 注入与危险命令

| 主题 | FINDING | 实现要点 |
|------|---------|----------|
| Sync/SSH 注入 | F2b-01～04, F2a-11/15/17 | `shlex.quote`、路径白名单、危险命令 **400 阻断** |
| 凭据测试注入 | F2b-09 | 不再向 API 返回含密码的 command |
| 子机 kill | F2h-03, F2h-04 | 仅杀 `_running_procs` 内 pid；wait 超时 pop + kill |

### 2.3 脚本执行平台

| 主题 | FINDING | 实现要点 |
|------|---------|----------|
| JSON 解析 | F2g-03, F2i-01 | `_parse_server_ids_json()`；`update_status` Optional + flush 出队 |
| credential 贯通 | F2g-05, F2h-01 | `ScriptExecution.credential_id` + migration + 前端下拉 |
| 回调 HTTPS/限流 | F2g-02, F2g-06, F2h-02 | `agent_url.py`；`script_callback_rate.py` |
| 重试语义 | F2g-04 | 📋 接受：新建 execution id，API 返回 `parent_execution_id` |

**SSOT**: [`script-execution.md`](script-execution.md)

### 2.4 告警与通知

| 主题 | FINDING | 实现要点 |
|------|---------|----------|
| 产品策略 | — | 浏览器 **无声音、无告警列表**；Telegram 主动通知；仪表盘仅刷新状态 |
| 阈值对齐 | — | 中心唯一判告警；子机 `alert_thresholds` 与中心相同 `>` 规则 |
| Telegram 脱敏 | F2d-04, F2c-04 | `sanitize_external_message()`；系统告警固定文案 |
| WS 日志 | F2a-18, F2e-03 | 📋 接受 `?token=`；Nginx `/ws/` 专用 access_log 不记 query |

**SSOT**: [`alert-push-policy.md`](alert-push-policy.md)

### 2.5 前端与安全

| 主题 | FINDING | 实现要点 |
|------|---------|----------|
| XSS | F2e-01/02/07 | `esc()` / `escAttr()` / `data-key` |
| CDN 供应链 | F2e-06 | `web/app/vendor/` 自托管 + `scripts/sync_frontend_vendor.py` |
| 解密失败 | F2c-01 | `decrypt_value` 抛 `ValueError`，不返回密文 |
| stats 实时 | F2a-13 | `stats.online` 优先 Redis `heartbeat:*` |

### 2.6 基础设施

| 主题 | FINDING | 实现要点 |
|------|---------|----------|
| 迁移失败 | F2c-05 | 非 duplicate column 错误 re-raise |
| SSH 主机校验 | F2c-02 | 新装默认 strict |
| sync 时长 | F2b-05 | `total_seconds()` |
| 子机监听 | F2f-03 | 默认 `127.0.0.1` |
| 库名白名单 | F2f-05 | `bootstrap_database.py` |

---

## 3. 明确接受 / 不做的项

| ID | 决策 | 原因 |
|----|------|------|
| F2f-01, F2g-01 | 📋 子机 `/exec` shell 面 | 架构需要；靠网络隔离 + 审计 + 中心危险命令拦截 |
| F2e-03, F2a-18 | 📋 告警 WS `?token=` | 不做 WS 换票；脚本进度用 HTTP 轮询 |
| F2e-04, F2a-05 | 🟡 WebSSH token 在 URL | 浏览器 WS 限制；已用 webssh-token 非 access JWT |
| F2e-05 | 📋 JWT 在 localStorage | 长期改 HttpOnly + CSP |
| F2g-04 | 📋 重试新建 execution id | 已文档化 `parent_execution_id` |
| JumpServer 参考 | 不引入 | 不要录像、不要新增堡垒机组件 |

**不做 WS 换票**（脚本执行、告警 WS 均已确认）：见 `script-execution.md` § 认证。

---

## 4. 运维与部署清单

### 4.1 首次部署前（无历史包袱）

1. 安装向导生成 **全新** `API_KEY` / `SECRET_KEY`（勿复用压测脚本或文档示例）
2. 部署含 **`web/app/vendor/`** 的完整静态资源
3. `supervisorctl restart nexus` + `nginx -s reload`
4. 同步各 Agent **`alert_thresholds`** 与中心 settings
5. 勾选下方验证清单

> **F2f-04**：压测已改环境变量；**未部署则无需轮换**，首次 install 用新 key 即可。

### 4.2 验证

逐项勾选 [`production-verification-checklist.md`](production-verification-checklist.md)。

### 4.3 升级 vendor

```bash
# 修改 scripts/sync_frontend_vendor.py 中 VENDOR_MANIFEST 版本后
python scripts/sync_frontend_vendor.py
```

---

## 5. 测试

| 类型 | 位置 | 说明 |
|------|------|------|
| 单元回归 | `tests/test_security_unit.py` | 17 项：JWT 中间件、脱敏、危险命令、vendor 无 CDN、install 403 |
| E2E | 验证清单 | WebSSH、Telegram、install 锁、Agent 阈值 — **外网执行** |

```bash
pytest tests/test_security_unit.py -q
```

---

## 6. Changelog 索引（2026-05-22～23）

| 文件 | 主题 |
|------|------|
| `changelog/2026-05-22-security-fixes-p0.md` | P0：WebSSH token、删中心 exec、crypto |
| `changelog/2026-05-22-security-fixes-p1.md` | P1：注入、危险命令、Agent |
| `changelog/2026-05-22-audit-p2-fixes.md` | P2 批次：install、stats、migration 等 |
| `changelog/2026-05-22-alert-push-dashboard.md` | 告警策略 + 仪表盘 |
| `changelog/2026-05-22-global-jwt-middleware.md` | 全局 JWT |
| `changelog/2026-05-22-telegram-sanitize-and-security-tests.md` | Telegram 脱敏 + 单测 |
| `changelog/2026-05-22-frontend-vendor-selfhost.md` | 前端 vendor 自托管 |
| `changelog/2026-05-22-script-execution-platform.md` | 脚本执行平台 |
| `changelog/2026-05-23-full-audit-reconciliation-fixes.md` | C2 审计字段 + C9 WS 去重 |
| `changelog/2026-05-23-phase2-docs-sync.md` | 开发文档 SSOT 入库 |
| `changelog/2026-05-23-wsl-integration-guide.md` | WSL 全链路联调指南 + smoke 脚本 |

---

## 7. 报告索引

| 文档 | 用途 |
|------|------|
| [`audit-phase-2-findings-matrix.md`](../reports/audit-phase-2-findings-matrix.md) | 63 条 ID 全量状态表 |
| [`audit-phase-2-walk-closure.md`](../reports/audit-phase-2-walk-closure.md) | 走读闭环 |
| [`audit-phase-2a`～`2j`](../reports/) | 各批次逐行报告 |
| [`2026-05-23-full-audit-report.md`](../reports/2026-05-23-full-audit-report.md) | 7 部门初审 |
| [`audit-full-vs-phase2-reconciliation.md`](../reports/audit-full-vs-phase2-reconciliation.md) | **C1–C12 对照表** |
| [`audit-line-review-cursor-rule.md`](audit-line-review-cursor-rule.md) | Cursor 走读规则 |

---

## 8. 剩余工作（开发阶段口径）

| 优先级 | 项 | 何时做 |
|--------|-----|--------|
| — | API Key 轮换（F2f-04） | **不适用** — 未部署；首次 install 生成新 key 即可 |
| 首次上线前 | E2E 验证清单 | 有 staging / 生产域名后再勾 |
| 开发中可选 | H12 启动校验 SECRET_KEY、H15 Nginx 安全头 | 小改，可并入下次提交 |
| Phase 3 | HttpOnly JWT（F2e-05） | 有前端认证重构排期时 |
| 容量规划 | H4 heartbeat 脏数据、H14 get_all 分页 | 接近 2000 台联调前 |

**Phase 2 开发与代码修复队列已空；「生产就绪」以首次部署 E2E 为准。**

---

## 9. 项目阶段说明（2026-05-23 确认）

- 项目 **仍在开发**，**尚未首次部署**，无生产 API Key、无线上 Agent、无历史 git 泄露需紧急轮换。
- F2f-04 代码侧已完成（密钥不进仓库）；剩余仅为 **首次安装时使用安装向导生成的 key**。
- 外网 E2E 清单定位为 **first-deploy gate**，不是当前开发阻塞项。
- HttpOnly JWT、部分 HIGH 项按 **Phase 3 / 首次上线前** 排期，不占用当前迭代。
