vps-commander/docs/VPS_COMMANDER_V2_1_SECURITY_HARDENING_SPEC.md

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 <hex> 启动参数。虽然生产机器均为自有 root 主机且风险可控，但 token 会出现在 ps 等进程信息中。

4.2 目标

生产 Agent 默认从受保护环境或配置文件读取 credential，命令行不再出现明文 token。 推荐优先级：systemd EnvironmentFile / LoadCredential > root-only 配置文件 > 其他安全存储。

4.3 实现要求

• 支持 VPS_COMMANDER_AGENT_TOKEN 环境变量。
• systemd ExecStart 不得包含 -token <secret>。
• 若保留 -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/<pid>/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