# 安全模型

## 信任边界

- 控制面管理员是高权限主体，可以查看客户链接并下发配置。
- Agent 拥有其绑定服务器的配置权限，但不能领取其他服务器任务。
- sing-box 独立运行；控制面不承载客户数据流量。
- 服务器 root 用户仍可读取本机凭据和流量日志，这是自托管系统无法消除的权限边界。

## 已实现控制

- 管理密码和控制面侧 Agent Key 只保存 scrypt 哈希；Agent 本机用 `0600` 环境文件保存自己的密钥。
- Agent Key 带 SHA-256 指纹索引，候选匹配后仍执行 scrypt 校验，避免心跳全表慢哈希。
- 注册令牌为高熵随机值、单次使用、30 分钟到期。
- 管理 Cookie 使用 HttpOnly、SameSite=Strict、Secure。
- 状态变更 API 校验 CSRF Token。
- 登录失败按来源地址限速。
- Reality 私钥在 Agent 本机生成，不回传控制面。
- Agent 配置采用“候选配置校验 → 原子切换 → 失败回滚”。
- systemd 控制面启用 `NoNewPrivileges`、`ProtectSystem=strict` 和最小可写目录。
- 日志和已完成任务按保留期自动清理。
- Agent 重新注册会撤销该设备的所有旧密钥并重新下发期望资源。

## 当前限制

- 客户协议凭据和待执行配置任务保存在权限为 `0600` 的控制面数据文件中，尚未做字段级静态加密。备份同样包含这些凭据。
- 节点 IP 上限依赖 sing-box 已认证会话日志的滚动观察，并非精确的同时在线连接数；修改日志格式、关闭日志、UDP-only 流量或客户端经过同一 NAT 会影响结果。
- 设备上限按订阅请求的 `X-Device-ID`、`X-Client-ID` 或 User-Agent 估计，只拒绝新的订阅下载。已导入的节点凭据可以继续使用，客户端也可自行更换标识；尚无每设备凭据与撤销机制。
- 订阅令牌是高熵随机值，但控制面数据/备份中为便于管理员查看而保存明文；必须保护备份及管理员会话。重置订阅地址不会撤销客户已经导入的节点凭据。
- IP/流量限制依赖 Agent 周期性日志与上报，不能作为瞬时硬限制；共享 NAT、动态 IP 会影响统计。需要严格设备隔离时应给每台设备发不同凭据。
- Agent 到控制面依赖公开 CA 的 HTTPS 校验，尚未增加双向 TLS。
- sing-box 构建产物目前随发布包分发；未来如改走 Release 下载，需校验发布包的签名或预期哈希。

## 部署建议

- 控制面只允许 HTTPS，域名开启 HSTS。
- 使用独立管理域名，不与订阅或客户流量共用。
- 缩小服务器端口池，并仅在云安全组/防火墙中放行实际需要的 TCP/UDP 范围。
- 定期离线保存 `ng backup` 生成的文件，并对备份再次加密。
- 不要在聊天、工单或公开仓库中粘贴注册令牌、Agent Key、备份或客户链接。
- 首次上线前在测试链路验证 sing-box 版本、Reality SNI、UDP 和回滚行为。