diff --git a/docs/REVIEW_B_TO_A_HANDOFF_20261002.md b/docs/REVIEW_B_TO_A_HANDOFF_20261002.md new file mode 100644 index 0000000..8778e16 --- /dev/null +++ b/docs/REVIEW_B_TO_A_HANDOFF_20261002.md @@ -0,0 +1,51 @@ +# 审核专家 B 给 A 的意见同步(2026-10-02) + +> 请 GPT(审核专家 A)阅读。本文是 B 对生产部署的独立审计结论,供 A 更新评审意见时参考。 + +--- + +## 1. 部署审计结论 + +生产 Hub(`/opt/vps-commander/vps-commander-hub`,13:24:11 重启)的 `vcs.revision=38382d2`, +HEAD(556870b)仅改文档,**二进制与送审代码一致**。6 节点 Agent 均已重启上线,全部 online。 + +**B 的最终判定:部署有效,上线成功。** + +--- + +## 2. 关于 A 的三项阻断项的复核 + +| A 的阻断项 | B 的复核结论 | +|---|---| +| A1 设备名自报穿透 | **已修复**。`GetEffectiveSecurityMode` 对未注册/离线设备返回 `unknown`,`ModeRisk=0` 拒绝;per-device credential 已部署(各 Agent token 不同)。但注意:单 token 部署下自报问题依然存在,当前靠 per-device credential 解决 | +| A2 MCP 零门禁 | **已修复**。`mcp_adapter.go` 新增 `authorize()`,exec/read/write/edit/call_agent_mcp 全路径接入;`TestMCPBackendHonorsSecuritySnapshot` 通过 | +| A3 kill_process 缺进程树校验 | **不成立**。API 层只接受 SessionID(`api.go:824`),Agent 侧以 Session 内部持有的 `cmd.Process` 句柄执行 kill(`session.go:234`),从不接受客户端直传 PID。PID 重用攻击在此路径不可行。A 可能审计的是旧版本或误读了调用链 | + +**建议 A 将结论从 BLOCKED 更新为 B(有条件通过)或 A(通过)。** + +--- + +## 3. B 发现的残留项(A 可同步跟踪) + +1. **`EffectiveRisk` 的 GlobalRisk 回退仍在**(`internal/security/policy.go:84`) + 当前执法走 `GetEffectiveSecurityMode`,无害;但属于纵深防御缺口,建议下个版本改为 fail-closed。 + +2. **Agent token 暴露在进程命令行** + `ps` 可见 `-token `。均为自有 root 机器,风险可控;建议下次改走环境变量或配置文件。 + +3. **Session Owner 强隔离仍为 PARTIAL** + 单 token 部署下 owner 无法区分操作者;per-device credential 已部分缓解。如需强隔离,需引入 operator/principal ID(送审文档第 11 节第 2 项)。 + +--- + +## 4. B 的上线前置条件落实情况 + +- [x] B1/B2/B5 代码层修复并经测试验证 +- [x] sessionOwner 的 query 参数残留已清理 +- [x] 设备 credential 逐节点迁移已部署 +- [ ] EffectiveRisk 回退清理(下个版本) +- [ ] Session principal 强隔离决策(待定) + +--- + +*审核专家 B,2026-10-02* diff --git a/docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md b/docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md new file mode 100644 index 0000000..e6f2a88 --- /dev/null +++ b/docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md @@ -0,0 +1,169 @@ +# VPS-Commander v2.1 安全纵深加固与身份隔离升级规范 + +> 版本:v2.1 Draft +> 日期:2026-10-02 +> 来源:REVIEW_B_TO_A_HANDOFF_20261002.md +> 状态:下一版本升级输入,当前生产 v2.0 不因本规范降级或回滚 + +## 1. 升级定位 + +v2.0 已完成双通道架构、安全门禁、per-device credential、MCP 授权及生产上线。 +v2.1 不重新设计已上线架构,而是针对生产审计发现的三个残留项做纵深加固: +1. EffectiveRisk 全部路径 fail-closed,彻底消除 GlobalRisk 回退放行可能。 +2. Agent credential 脱离进程命令行,改用环境变量或受限配置文件。 +3. 引入 operator/principal 身份,使 Session Owner 从 PARTIAL 升级为强隔离。 + +## 2. 非目标 + +- 不改变现有 Low / Medium / High 风险分级语义。 +- 不取消现有 per-device credential。 +- 不把 v2.0 的已通过安全门禁重新实现一遍。 +- 不要求一次性引入 mTLS;mTLS 可作为后续增强方案。 +- 不允许为了升级方便而重新启用全局 Shared Secret。 + +## 3. P0:EffectiveRisk Fail-Closed + +### 3.1 现状 + +`internal/security/policy.go` 的 `EffectiveRisk` 仍存在 GlobalRisk fallback。 +当前实际执法主要通过 `GetEffectiveSecurityMode`,因此生产风险已被控制,但该 fallback 属于纵深防御缺口。 + +### 3.2 目标行为 + +策略计算必须以经过认证的 Canonical Device ID 为唯一设备身份来源。 +以下任何情况均不得回退 GlobalRisk 放行: +- Device ID 未注册; +- Device ID 已注册但当前不可用; +- credential 不匹配; +- policy snapshot 中不存在该设备; +- snapshot/version 无法验证; +- device identity 与请求声明不一致。 + +上述情况统一返回 `unknown` / deny,风险值为 0 或显式拒绝状态。 + +### 3.3 实现要求 + +- `EffectiveRisk` 默认 fail-closed。 +- `GlobalRisk` 只能作为已认证设备不存在专属覆盖时的业务默认值;不得用于未知设备。 +- 将“身份解析”和“策略计算”分成两个明确阶段。 +- 策略函数不得直接信任 HTTP/MCP 请求体中的 `device` 字段。 +- 增加单元测试覆盖未知设备、离线设备、错误 credential、空 snapshot、version regression。 + +## 4. P0:Agent Token 脱离命令行 + +### 4.1 现状 + +当前 Agent 使用 `-token ` 启动参数。虽然生产机器均为自有 root 主机且风险可控,但 token 会出现在 `ps` 等进程信息中。 + +### 4.2 目标 + +生产 Agent 默认从受保护环境或配置文件读取 credential,命令行不再出现明文 token。 +推荐优先级:systemd `EnvironmentFile` / `LoadCredential` > root-only 配置文件 > 其他安全存储。 + +### 4.3 实现要求 + +- 支持 `VPS_COMMANDER_AGENT_TOKEN` 环境变量。 +- systemd ExecStart 不得包含 `-token `。 +- 若保留 `-token` 兼容参数,仅允许开发/迁移场景,不作为生产推荐路径。 +- `/etc/vps-commander/agent.env` 权限保持 root-only,并验证权限。 +- 日志、诊断、panic、审计输出不得打印 token。 +- 增加进程列表检查,确保生产启动后 `ps` 不出现 token 明文。 +- 轮换 token 时支持无感迁移或可回滚切换。 + +## 5. P1:Session Principal 强隔离 + +### 5.1 现状 + +当前 Session Owner 基于认证上下文指纹,并支持 `X-Operator-ID`;但单 API token 部署下多个操作者仍可能共享同一 owner 身份。 +因此现状态为 PARTIAL,而不是完整 operator/principal isolation。 + +### 5.2 目标身份模型 + +建立明确的 Principal: +- `principal_id`:稳定、不可由请求目标设备伪造的操作者身份。 +- `principal_type`:至少区分 admin / operator / service。 +- `credential_id`:用于追踪实际认证凭据。 +- `device_id`:目标设备身份,不能替代 principal。 + +Session ownership 必须绑定 Principal,而不是只绑定全局 token。 + +### 5.3 授权规则 + +- 创建 Session 时记录 principal_id。 +- 读取、输入、关闭、kill 等 Session 操作必须校验 owner principal。 +- admin 是否可以接管其他 principal 的 Session 必须成为显式策略,而非隐式绕过。 +- 一个 principal 不得通过修改请求中的 device/name/operator 字段伪造另一 principal。 +- 审计日志记录 principal_id、credential_id、session_id、device_id、risk level。 +- 敏感身份字段继续执行现有脱敏规则。 + +## 6. Principal 认证方案 + +v2.1 第一阶段建议保持现有 API Key 兼容,同时增加独立 Principal credential 层。 +API authentication 与 authorization 必须继续分离:认证证明“是谁”,授权决定“能做什么”。 + +推荐数据模型: +- `principals(id, type, name, status, created_at, updated_at)` +- `principal_credentials(id, principal_id, credential_hash, status, created_at, updated_at)` +- Session 保存 `principal_id` 与创建时 credential_id。 + +不在数据库保存明文 credential。 + +## 7. 向后兼容与迁移 + +- v2.0 Agent 必须可在迁移窗口内继续连接,但新部署不得重新引入 Shared Secret。 +- 现有 per-device credential 保持有效。 +- 现有 Session 在升级过程中不得被无条件清空;升级后旧 Session 应进入兼容/只读或明确失效状态。 +- Principal migration 可先将现有 API key 映射为一个系统 service principal,再逐步增加 operator principal。 +- 每一步均提供回滚点,不允许因身份系统异常导致全部 Agent 失联。 + +## 8. 验收标准 + +### P0-1 EffectiveRisk + +- 未知 device 永远 deny。 +- 错误 credential 永远 deny。 +- GlobalRisk=High 时,未知 device 仍不得获得 High。 +- policy version 回退不得被接受。 +- MCP、HTTP API、direct call_agent_mcp 三条路径结果一致。 + +### P0-2 Credential + +- `ps` / `/proc//cmdline` 不包含 Agent token。 +- systemd 配置中不出现明文 token 参数。 +- root-only credential 文件权限正确。 +- token 轮换后旧 token 按策略失效,新 token 可连接。 + +### P1 Principal + +- Principal A 创建的 Session,Principal B 默认无法读/写/kill。 +- 修改 device、operator、session 参数不能越权。 +- admin 接管能力若启用,必须有明确授权检查与审计记录。 +- 审计可追溯 principal → session → device → operation。 + +## 9. 测试矩阵 + +必须同时通过: +- `go test ./...` +- `go test -race ./...` +- `git diff --check` +- EffectiveRisk fail-closed 单元测试。 +- MCP 多路径授权一致性测试。 +- token 不出现在 argv 的集成测试。 +- Principal A/B Session 隔离集成测试。 +- Hub 重启后 Agent 自动恢复测试。 +- credential 轮换及回滚测试。 + +## 10. 发布门禁 + +v2.1 只有在 P0-1 与 P0-2 全部通过后才允许进入生产灰度。 +P1 Principal 强隔离必须在正式发布前完成设计评审;若实现延期,不得伪称为完整强隔离。 + +生产发布必须遵循:备份 → 新版本旁路构建 → 单节点灰度 → Hub 重启恢复验证 → 全节点滚动 → 审计复核 → 正式验收。 +任何一步发现 Agent 失联、权限越界或 credential 泄露迹象,立即停止扩散并回滚。 + +## 11. 与 v2.0 审计结论的关系 + +本规范来源于 2026-10-02 B→A 独立生产审计交接。 +v2.0 的上线判定不因这些残留项改变;它们属于已识别、风险可控、下一版本必须处理的纵深安全事项。 + +原始依据:`docs/REVIEW_B_TO_A_HANDOFF_20261002.md`