威胁模型

摘要

Codex Quota Monitor 是自托管 operator dashboard，会读取敏感的 CLIProxyAPI management 状态，并在配置后读取本地 Codex OAuth auth 文件。最高风险结果是 management key 或 OAuth token 泄露、账号与 quota 运维元数据被不该看到的人看到，以及把本应本地使用的 dashboard 以无鉴权方式暴露到 LAN 或公网。

范围与假设

纳入范围：

Runtime server、浏览器 UI、只读 HTTP API、Prometheus metrics、CLI helper、 SQLite history、benchmark 输出、Docker 和 NixOS 部署默认值。
CPA management key 与 Codex OAuth auth 文件的 secret handling。
Operator 控制的自托管部署。

不纳入范围：

恶意 root 用户，或已经被攻陷的 host、Python runtime、container runtime、 browser、CLIProxyAPI 进程、reverse proxy、上游 provider。
内建用户登录、RBAC、多租户隔离、SaaS 风格访问审计；本项目不实现这些控制。
Provider policy 行为和上游 CLIProxyAPI bug。

假设：

主要用户是可信 operator，或代表 operator 工作的可信 agent。
如需 LAN 或公网访问，会先由 firewall 和带鉴权的 reverse proxy / access layer 保护。
support bundle、截图、SQLite history、benchmark 输出和复制出来的 API payload 在脱敏前都按敏感材料处理。

可能改变风险排序的开放问题：

部署是否会给不可信 viewer 使用。
reverse proxy 是否真的提供鉴权和 TLS，还是只做转发。
auth 文件目录或 management key 文件是否被其它本地用户共享读取。

系统模型

主要组件

codex-quota-monitor CLI 和 HTTP server：解析配置、运行本地 dashboard、暴露基本只读的 endpoint 和受保护的手动 direct quota refresh 动作、渲染静态资源。
CLIProxyAPI management gateway：提供 auth inventory、usage、routing、logs 和 health。
可选 Codex auth directory：保存用于 direct quota sampling 的 OAuth auth 文件。
可选 SQLite state DB：保存派生 snapshot、capacity history、ETA 和 audit event。
可选 benchmark result directory：保存 summary.json、CSV/JSONL request record 和 Markdown report。
可选 reverse proxy 或 access layer：负责 LAN/公网访问鉴权。

数据流与信任边界

Operator config -> monitor process：CLI/env/TOML/NixOS option；由 operator 控制；校验类型、配置 key、时区、locale、端口和 bind address。
Monitor -> CLIProxyAPI management API：本地 HTTP；management key 作为 Authorization: Bearer 发送；monitor 在日志和 print-config 中清理 URL。
Browser/operator -> monitor manual refresh：本地 HTTP POST；默认浏览器 UI 提交页面内 refresh token header，monitor 在排队 direct quota refresh 前校验它。旧的 management-key 模式仍接受 Authorization: Bearer。
Monitor -> Codex provider usage API：HTTPS；access token 从本地 auth 文件读取，只发往 provider usage endpoint。
Monitor -> browser/API clients：默认本地 HTTP；Host/Origin allowlist 是 request-origin guard，不是鉴权。
Monitor -> SQLite history：本地文件写入；保存派生运维元数据，不保存原始 key 或 token 值。
Benchmark -> result directory：本地文件；可能包含运维元数据，共享前应脱敏。

Diagram

flowchart LR
  Operator["Trusted operator"] --> CLI["Monitor CLI and config"]
  CLI --> Server["Monitor HTTP server"]
  Server --> CPA["CLIProxyAPI management"]
  Server --> Auth["Codex auth files"]
  Server --> Provider["Codex usage API"]
  Server --> DB["SQLite history"]
  Server --> Browser["Browser and agents"]
  Proxy["Authenticated proxy"] --> Server
  Benchmark["Benchmark runner"] --> Results["Benchmark outputs"]

资产

CPA management key。
Codex OAuth auth 文件，尤其是 access_token、refresh_token 和 account ID。
账号 label、plan tier、quota window、model activity、usage history 和 gateway health 元数据。
SQLite history 和 benchmark 输出。
Release artifact、container image、SBOM/provenance 和签名后的 image digest。

入口

CLI：serve、doctor、print-config、init、redact。
HTTP：/、/monitor.css、/monitor.js、/healthz、/api/v1/status、 /api/v1/recommendations、/api/v1/diagnostics、/api/v1/alerts、/metrics。
配置：CLI option、环境变量、TOML config、NixOS module option。
本地文件：management key file、auth directory、SQLite DB、benchmark summary、result CSV/JSONL/Markdown。
Release pipeline：GitHub Actions、GHCR image 发布、SBOM/provenance、可选 PyPI 发布。

威胁与缓解

威胁	风险	现有控制	缺口与建议
Management key 或 OAuth token 出现在 API、metrics、history、logs 或 support 输出里。	高	测试覆盖 public endpoint、metrics、doctor JSON、history 和 quota sampling；`print-config` 清理 URL；`redact` 生成脱敏副本。	每次新增 public 字段都继续补回归测试。Benchmark/history schema 新字段按 privacy change 复查。
Dashboard 被无鉴权暴露到 LAN/公网。	高	Python/NixOS 默认 `127.0.0.1`；NixOS `openFirewall` 默认 false；`doctor` 对非 loopback 和 allowed-host 暴露给 warning；文档要求鉴权 proxy/access layer。	不把 Host/Origin check 当成鉴权。后续可考虑对宽 bind address 增加显式确认 flag。
Docker/NixOS mount 过宽导致无关 secret 暴露。	中	文档要求只挂载具体 management key 文件和 auth directory；除非明确启用 auth live plan sync，否则 auth files 保持只读。NixOS 使用专用用户、systemd hardening 和独立可写同步 unit。	示例不能挂载整个 home 或 config 目录。
SQLite history 或 benchmark 输出泄露运维元数据。	中	安全文档把这些 artifact 标为敏感；`redact` 支持 JSON、JSONL、CSV、Markdown/text、SQLite 副本脱敏，以及用于 staging support 目录的 dry-run/apply 批量脱敏。	不共享原始 history DB 或 benchmark 目录。新增 benchmark 文件形态时补脱敏测试。
Reverse proxy path 或 host 配置不匹配削弱边界预期。	中	Allowed-host check 拒绝非预期 Host/Origin；文档说明 v1 期望专用 hostname 根路径部署。	保持 reverse proxy 示例与根路径和鉴权访问一致。
CI/release artifact 被篡改。	中	Release image 从 tag source 构建，Docker base image 用 digest pin，Dependabot 更新依赖，GHCR image 带 SBOM/provenance 和 keyless cosign 签名。	发布前验证 workflow、attestation 和 tag 完整性。

人工复查重点

src/codex_quota_monitor/runtime.py：HTTP endpoint、Host/Origin handling、snapshot construction、management API request。
src/codex_quota_monitor/quota.py：auth file 读取和 provider usage request。
src/codex_quota_monitor/history_store.py：SQLite schema 和持久化字段。
src/codex_quota_monitor/redaction.py：support artifact 脱敏行为。
src/codex_quota_monitor/cli.py：配置解析、doctor warning、redaction CLI 和脱敏诊断输出。
nixos-module.nix：默认 bind address、firewall 行为、service user 和 systemd hardening。
docs/security-audit.zh-CN.md、docs/install.zh-CN.md、SECURITY.md：公开部署和报告指引。

质量检查

已覆盖发现的 HTTP endpoint、CLI 入口、文件输入和部署面。
每条信任边界至少被一个威胁覆盖。
Runtime 行为与 CI/release tooling 已分开。
假设和开放问题已明确。
这份模型描述 maintainer self-review 范围，不等同第三方审计保证。