NexusGate/docs/SECURITY.md

安全模型

信任边界

• 控制面管理员是高权限主体，可以查看客户链接并下发配置。
• Agent 拥有其绑定服务器的配置权限，但不能领取其他服务器任务。
• Xray-core 与 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 上限依赖 Xray 访问日志及 sing-box 已认证会话日志的滚动观察，并非精确的同时在线连接数；修改日志格式、关闭访问日志、UDP-only 流量或客户端经过同一 NAT 会影响结果。
• 设备上限按订阅请求的 X-Device-ID、X-Client-ID 或 User-Agent 估计，只拒绝新的订阅下载。已导入的节点凭据可以继续使用，客户端也可自行更换标识；尚无每设备凭据与撤销机制。
• 订阅令牌是高熵随机值，但控制面数据/备份中为便于管理员查看而保存明文；必须保护备份及管理员会话。重置订阅地址不会撤销客户已经导入的节点凭据。
• IP/流量限制依赖 Agent 周期性日志与上报，不能作为瞬时硬限制；共享 NAT、动态 IP 会影响统计。需要严格设备隔离时应给每台设备发不同凭据。
• Agent 到控制面依赖公开 CA 的 HTTPS 校验，尚未增加双向 TLS。
• Xray Release 下载目前依赖 GitHub HTTPS，尚未校验发布包的签名或预期哈希。

部署建议

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