codex-lb安全加固清单：密码、TOTP双因素、角色权限与Step-Up认证的4层防护-迪斯科星球

codex-lb安全加固清单：密码、TOTP双因素、角色权限与Step-Up认证的4层防护

【免费下载链接】codex-lbCodex/ChatGPT multiple account load balancer & proxy with usage tracking, dashboard, and OpenCode-compatible endpoints项目地址: https://gitcode.com/gh_mirrors/co/codex-lb

codex-lb 是一个 Codex/ChatGPT 多账号负载均衡器与反向代理，内置用量追踪、管理面板（Dashboard）和 OpenAI 兼容端点。面板里存着上游账号凭证、API 密钥和安全策略，一旦泄露损失很大。本文用一份实操清单，带你按「密码 → TOTP 双因素 → 角色权限 → Step-Up 再认证」的顺序完成 codex-lb 管理面板的 4 层安全加固。

📖 完整规则参考官方文档：docs/authentication.md

一、第一层：设置强密码，开启登录限流

管理面板默认使用内置密码认证（CODEX_LB_DASHBOARD_AUTH_MODE=standard），每个账号独立持有密码，服务端使用 bcrypt 存储哈希。

这一层自带的保护机制：

🛡️统一拒绝响应：用户名错误与密码错误返回完全相同的401 invalid_credentials，耗时也一致，杜绝枚举攻击；
⏱️登录限流：每个客户端每分钟最多 8 次失败尝试（429），超限即锁 1 分钟，但账号本身永不锁定，不会把自己锁在门外；
🔒会话绑定账号：禁用账号或修改密码后，其所有浏览器会话在下次请求即失效，还可一键「在所有设备登出」。

操作建议：

首次启动后尽快通过引导页设置初始密码（远程首次设置需一次性 bootstrap token）；
邀请团队成员时使用邀请链接（24 小时有效、仅一次），让每个人自行设置密码，密码永远不经过管理员之手；
保留一个可改名的admin应急账号（admin用户名永久保留，防止救援流程歧义）。

🔍 相关实现：app/modules/dashboard_auth/service.py、测试 tests/integration/test_dashboard_password_auth.py

二、第二层：为所有账号启用 TOTP 双因素认证

密码只防「猜」，双因素才防「偷」。在Settings → Access → My sign-in中即可为每个账号开启 TOTP（兼容任意标准验证器 App，无需额外配置）。

面板提供两个全局强制开关，建议按需打开：

开关	作用	适合场景
Require TOTP on login（`totp_required_on_login`）	所有持密码账号登录都必须输入动态码	多人共用、公网可达
Require two-factor for administrators（`totpRequiredForAdminRole`）	仅强制 Admin 级别账号（持有特权权限的账号）启用双因素	内部小团队，减负普通成员

两个值得注意的细节：

⚠️注册门禁：打开强制开关后，尚未注册 TOTP 的账号会被「拦在注册门槛」——只能访问 TOTP 设置等少数路由，其余全部403 totp_enrollment_required，直到完成注册；设置响应会提前告诉你还有几个账号/管理员（usersWithoutTotpCount/adminsWithoutTotpCount）需要补注册；
🔑反向代理账号也能注册双因素：通过企业登录（trusted-header）进来的账号没有本地密码，但仍可在 My sign-in 中注册自己的验证器密钥——这是后续 Step-Up 认证的前提，docs/sso.md 特别提醒「先注册双因素，再开始加人」。

🔍 相关实现：app/modules/dashboard_auth/api.py（/totp/setup/start、/totp/verify）、app/core/auth/totp.py

三、第三层：用角色权限落实「最小权限」

codex-lb 内置 5 个角色，授权粒度细到资源:动作级别（如security:write、users:manage、accounts:export），权限定义见 app/core/auth/dashboard_access.py：

角色	能做什么	不能做什么
Admin	一切（用户、安全设置、凭证导出、审计日志）	—
Operator	日常运维：上游账号、API 密钥、模型源、自动化	人员管理、安全设置、会话/审计读取（`403 permission_required`）
Viewer	只读：总览、报表、脱敏请求日志	一切写操作
Guest	共享只读会话（可选开启）	不能导出凭证、看不到 API 密钥等敏感区

内建的安全约束（无需配置即生效）：

📏委托规则：你只能授予「权限是你子集」的角色——非 Admin 无法提拔新 Admin（403 insufficient_delegation）；
🛑最后一位 Admin 保护：账号不能自禁、不能自改角色，且系统内永远至少保留一个活跃 Admin（409 last_admin_protected），两名 Admin 同时互禁也只会剩一个；
👁️越权即拒绝：缺少具体权限时 API 返回403 permission_required并在param字段点明缺失项，前端对无权限控件直接置灰或隐藏。

🔍 角色预置数据与路由权限矩阵：app/modules/dashboard_roles/seed.py、tests/integration/test_dashboard_route_permission_matrix.py、tests/integration/test_dashboard_users_api.py

四、第四层：Step-Up 认证——敏感操作「5 分钟内再证明一次身份」

前三层防的是「进不来」，第四层防的是「会话 Cookie 被盗」。codex-lb 对改变谁能登录的操作（安全设置、账号、邀请、角色、登录提供方）以及导出上游账号凭证（accounts:export）额外要求：调用方必须在最近 5 分钟内重新证明过身份（STEP_UP_PERMISSIONS，见 app/core/auth/dashboard_access.py）。

它是怎么工作的：

⏰ 触发敏感操作时，若 5 分钟窗口内无有效验证，API 返回403 step_up_required，并附带details.methods说明需要出示哪些凭证（密码账号出示密码＋动态码，纯反向代理账号只出示动态码）；
🧾 刚登录时若已出示了全部凭证，直接计入窗口，不会连续弹两次；
❓ 既无密码又无 TOTP 的账号返回403 step_up_unavailable，提示先去 My sign-in 注册双因素——没有任何静默豁免；
📝 每次成功确认都写入审计日志step_up_verified，错误尝试同样受 8 次/分钟限流约束。

核心逻辑非常精炼，全部集中在 app/core/auth/step_up.py（300 秒窗口常量、凭证判定、新鲜度检查），设计思路可阅读 openspec/changes/step-up-auth/proposal.md，行为覆盖测试见 tests/integration/test_step_up_auth.py。

📋 加固完成自查清单

#	检查项	验证方式
1	所有账号使用强密码，无默认密码	设置 → Access 中逐一核对
2	至少开启「管理员双因素」，公网部署建议全量强制 TOTP	尝试用未注册账号访问受保护路由，应得`totp_enrollment_required`
3	普通成员使用 Operator/Viewer 而非 Admin	路由权限矩阵：越权请求应返回`403 permission_required`
4	敏感操作会弹出 Step-Up 确认框	改一次安全设置，观察审计日志出现`step_up_verified`
5	存在「合格的应急账号」（break-glass：指定 + 活跃 + Admin + 双因素 + 本地密码）	参考 docs/sso.md 的 host 恢复命令（`admin reset-password`等）

企业官网建设流程全解析