Threat Model

Executive Summary

Codex Quota Monitor is a self-hosted operator dashboard that reads sensitive CLIProxyAPI management state and, when configured, local Codex OAuth auth files. The highest-risk outcomes are management key or OAuth token disclosure, exposing account and quota metadata beyond the intended operator audience, and over-broad deployment choices that turn a local dashboard into an unauthenticated LAN or public endpoint.

Scope And Assumptions

In scope:

Runtime server, browser UI, read-only HTTP API, Prometheus metrics, CLI helpers, SQLite history, benchmark outputs, Docker and NixOS deployment defaults.
Secret-handling behavior for CPA management keys and Codex OAuth auth files.
Operator-controlled self-hosted deployments.

Out of scope:

A malicious root user or a compromised host, Python runtime, container runtime, browser, CLIProxyAPI process, reverse proxy, or upstream provider.
Built-in user login, RBAC, multi-tenant isolation, and SaaS-style access auditing; the project does not implement those controls.
Provider policy decisions and upstream CLIProxyAPI bugs.

Assumptions:

The primary user is a trusted operator or a trusted agent acting for that operator.
LAN or public access, if needed, is protected by firewall rules and an authenticated reverse proxy or access layer.
Support bundles, screenshots, SQLite history, benchmark outputs, and copied API payloads are treated as sensitive until redacted.

Open questions that can change risk ranking:

Whether a deployment is shared with untrusted viewers.
Whether the reverse proxy adds authentication and TLS, or only forwards traffic.
Whether auth file directories or management key files are shared with other local users.

System Model

Primary Components

codex-quota-monitor CLI and HTTP server: parses configuration, runs the local dashboard, exposes mostly read-only endpoints plus the protected manual direct-quota refresh action, and renders assets.
CLIProxyAPI management gateway: provides auth inventory, usage, routing, logs, and health.
Optional Codex auth directory: contains OAuth auth files used for direct quota sampling.
Optional SQLite state DB: stores derived snapshots, capacity history, ETA, and audit events.
Optional benchmark result directory: stores summary.json, CSV/JSONL request records, and Markdown reports.
Optional reverse proxy or access layer: owns LAN/public authentication.

Data Flows And Trust Boundaries

Operator config -> monitor process: CLI/env/TOML/NixOS options; operator controlled; validation covers types, config keys, timezones, locale, ports, and bind address.
Monitor -> CLIProxyAPI management API: local HTTP; management key is sent as Authorization: Bearer; monitor sanitizes configured URLs in logs and print-config.
Browser/operator -> monitor manual refresh: local HTTP POST; the default browser UI supplies an in-page refresh token header and the monitor verifies it before a direct quota refresh is queued. Legacy management-key mode still accepts Authorization: Bearer.
Monitor -> Codex provider usage API: HTTPS; access token is read from local auth files and sent only to the provider usage endpoint.
Monitor -> browser/API clients: local HTTP by default; Host/Origin allowlist is a request-origin guard, not authentication.
Monitor -> SQLite history: local file write; stores derived operational metadata, not raw key or token values.
Benchmark -> result directory: local files; can contain operational metadata and should be redacted before sharing.

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"]

Assets

CPA management key.
Codex OAuth auth files, especially access_token, refresh_token, and account IDs.
Account labels, plan tiers, quota windows, model activity, usage history, and gateway health metadata.
SQLite history and benchmark outputs.
Release artifacts, container images, SBOM/provenance, and signed image digest.

Entry Points

CLI: serve, doctor, print-config, init, and redact.
HTTP: /, /monitor.css, /monitor.js, /healthz, /api/v1/status, /api/v1/recommendations, /api/v1/diagnostics, /api/v1/alerts, and /metrics.
Config: CLI options, environment variables, TOML config, and NixOS module options.
Local files: management key file, auth directory, SQLite DB, benchmark summary, result CSV/JSONL/Markdown files.
Release pipeline: GitHub Actions, GHCR image publication, SBOM/provenance, and optional PyPI publishing.

Threats And Mitigations

Threat	Risk	Existing controls	Gaps and recommendations
Management key or OAuth token appears in API, metrics, history, logs, or support output.	High	Tests cover public endpoints, metrics, doctor JSON, history, and quota sampling; `print-config` sanitizes URLs; `redact` creates sanitized copies.	Keep adding regression tests for every new public field. Treat benchmark/history schema additions as privacy changes.
Dashboard is exposed to LAN/public users without authentication.	High	Python/NixOS default to `127.0.0.1`; NixOS `openFirewall` defaults false; `doctor` warns on non-loopback and allowed-host exposure; docs require authenticated proxy/access layer.	Do not treat Host/Origin checks as auth. Future hardening could add explicit confirmation flags for broad bind addresses.
Over-broad Docker/NixOS mounts expose unrelated secrets.	Medium	Docs require mounting only the management key file and auth directory; auth files stay read-only unless auth live plan sync is explicitly enabled. NixOS uses a dedicated user, hardened systemd settings, and a separate writable sync unit.	Keep examples from mounting whole home or config directories.
SQLite history or benchmark output leaks operational metadata.	Medium	Security docs classify these artifacts as sensitive; `redact` supports JSON, JSONL, CSV, Markdown/text, SQLite copy redaction, and dry-run/apply batch redaction for staged support directories.	Avoid sharing raw history DB or benchmark directories. Add format-specific redaction tests as new benchmark files appear.
Reverse proxy path or host mismatch weakens boundary expectations.	Medium	Allowed-host checks reject unexpected Host/Origin; docs state v1 expects root-path deployment on a dedicated hostname.	Keep reverse proxy examples aligned with root-path assumptions and authenticated access.
CI/release artifact tampering.	Medium	Release images are built from tagged source, Docker base image is pinned by digest, Dependabot updates dependencies, GHCR images include SBOM/provenance and keyless cosign signatures.	Verify release workflow status, image attestations, and tag integrity before announcement.

Manual Review Focus

src/codex_quota_monitor/runtime.py: HTTP endpoints, Host/Origin handling, snapshot construction, management API requests.
src/codex_quota_monitor/quota.py: auth file reading and provider usage requests.
src/codex_quota_monitor/history_store.py: SQLite schema and persisted fields.
src/codex_quota_monitor/redaction.py: support artifact redaction behavior.
src/codex_quota_monitor/cli.py: config parsing, doctor warnings, redaction CLI, and sanitized diagnostic output.
nixos-module.nix: default bind address, firewall behavior, service user, and systemd hardening.
docs/security-audit.md, docs/install.md, and SECURITY.md: public deployment and reporting guidance.

Quality Check

All discovered HTTP endpoints, CLI entry points, file inputs, and deployment surfaces are represented.
Each trust boundary is covered by at least one threat.
Runtime behavior is separated from CI/release tooling.
Assumptions and open questions are explicit.
This model describes maintainer self-review scope, not third-party audit assurance.