Codex Network Proxy Design

This document describes the Codex network proxy that runs outside the sandbox and enforces an allow-only network policy for sandboxed subprocesses. The proxy is a single binary with HTTP proxying, SOCKS5, and an admin API. Codex owns the policy state in ~/.codex/config.toml; the proxy reads that configuration and applies it at the network edge.

Goals

Enforce allow-only network access with denylist precedence.
Support wildcard domain patterns, including apex match for *.domain.tld.
Allow two modes: limited (read-only) and full (all methods).
Provide optional MITM to enforce read-only on HTTPS.
Allow hot-reloaded configuration via admin API.
Provide clear audit logging of allow/deny decisions and policy changes.
Enable a single binary with HTTP proxy, SOCKS5 proxy, and admin API.

Non-Goals

Enterprise policy distribution or centralized multi-tenant orchestration.
Deep packet inspection beyond the supported HTTP/HTTPS interception modes.
Perfect protocol coverage for all network traffic types.

Architecture

flowchart LR
  subgraph Sandbox["Codex (sandboxed)"]
    Tools["commands / tools<br/>curl, git, python"]
    SocksClients["SOCKS clients"]
  end

  subgraph Proxy["codex-network-proxy (host process)"]
    HttpProxy["HTTP Proxy :3128<br/>CONNECT tunnel<br/>MITM (optional)"]
    SocksProxy["SOCKS5 Proxy :8081"]
    Admin["Admin API :8080<br/>/health /config /blocked<br/>/reload /mode"]
  end

  Config["~/.codex/config.toml<br/>[network_proxy.*]"]

  Tools -->|HTTP| HttpProxy
  SocksClients -->|SOCKS5| SocksProxy
  Admin -->|reads + reloads| Config

Configuration Model

The proxy reads ~/.codex/config.toml:

[network_proxy] for endpoints, mode, and toggles.
[network_proxy.policy] for allowedDomains / deniedDomains.
[network_proxy.mitm] for MITM CA paths and inspection settings.

Codex is the source of truth. Approval actions update the config and trigger a proxy reload.

Enforcement Model

Allow/deny precedence: denylist wins; allowlist is required for access.
Limited mode: only GET/HEAD/OPTIONS are permitted. HTTPS requires MITM to enforce method constraints; otherwise CONNECT is blocked with a clear reason.
Full mode: all methods allowed; CONNECT tunneling is permitted without MITM.

Logging and Auditability

The proxy logs:

Allow/deny decisions (host, client, reason).
Policy updates (allowlist/denylist adds/removes).
Mode changes and config reloads.
MITM lifecycle events (CA generated, TLS established).

Decision to Make: Preflight Strictness

Codex performs a preflight check before running some commands. Preflight currently scans CLI args for URLs on known network tools (curl, git, etc.) and shell -c snippets.

We need to decide how strict preflight should be:

Option A: Heuristic preflight (current)

Pros: catches obvious curl https://... style commands early.
Cons: misses dynamic URLs inside scripts; can still overprompt on shell snippets.

Option B: Strict preflight

Only preflight when a URL argument is present in the command.
For everything else, rely on the proxy /blocked prompt at connect time.
Pros: fewer false positives, clearer user experience.
Cons: fewer early prompts; approvals shift to runtime events.

Decision: TBD. We should choose a configuration flag (network_proxy.preflight_mode = "heuristic" | "strict") and default based on observed UX.

Open Items

Finalize preflight strictness and expose a config toggle if needed.
Confirm documentation for MITM trust steps and CA injection into sandboxed commands.

3.6 KiB Raw Blame History