mirror of
https://github.com/openai/codex.git
synced 2026-11-18 22:20:48 +00:00
Add codex-network-proxy crate
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
# 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
|
||||
|
||||
1. Enforce allow-only network access with denylist precedence.
|
||||
2. Support wildcard domain patterns, including apex match for `*.domain.tld`.
|
||||
3. Allow two modes: **limited** (read-only) and **full** (all methods).
|
||||
4. Provide optional **MITM** to enforce read-only on HTTPS.
|
||||
5. Allow hot-reloaded configuration via admin API.
|
||||
6. Provide clear audit logging of allow/deny decisions and policy changes.
|
||||
7. 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
|
||||
|
||||
```mermaid
|
||||
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 `allowed_domains` / `denied_domains` (and, on macOS, optional local IPC allowances).
|
||||
- `[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.
|
||||
|
||||
## macOS Sandbox Integration (Seatbelt)
|
||||
|
||||
On macOS, Codex uses Seatbelt (`sandbox-exec`) for OS-level enforcement.
|
||||
|
||||
Key points:
|
||||
|
||||
- **Per-domain gating happens in the proxy**, not in Seatbelt: Seatbelt network rules are intentionally limited to loopback proxy ports (e.g. `localhost:3128` / `localhost:8081`) so all outbound traffic is forced through the proxy, which then applies the allow/deny policy and prompts.
|
||||
- **Local IPC is deny-by-default** when proxy-restricted network access is active. Some tools rely on Unix domain sockets (e.g. the SSH agent). These are blocked unless explicitly allowed via:
|
||||
- `network_proxy.policy.allow_unix_sockets` (absolute socket paths, `$SSH_AUTH_SOCK`, or the `ssh-agent` preset), and/or
|
||||
- `network_proxy.policy.allow_local_binding` (if you need to bind/listen on localhost ports).
|
||||
|
||||
When approvals are enabled, Codex can preflight commands that appear to require the SSH agent and prompt to allow the SSH agent socket before running.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,93 @@
|
||||
# Codex Network Proxy Quickstart (Local)
|
||||
|
||||
This is a compact guide to build and validate the Codex network proxy locally.
|
||||
|
||||
## Build
|
||||
|
||||
From the Codex repo:
|
||||
|
||||
```bash
|
||||
cd /Users/viyatb/code/codex/codex-rs
|
||||
cargo build -p codex-network-proxy
|
||||
```
|
||||
|
||||
For MITM support:
|
||||
|
||||
```bash
|
||||
cargo build -p codex-network-proxy --features mitm
|
||||
```
|
||||
|
||||
## Configure
|
||||
|
||||
Add this to `~/.codex/config.toml`:
|
||||
|
||||
```toml
|
||||
[network_proxy]
|
||||
enabled = true
|
||||
proxy_url = "http://127.0.0.1:3128"
|
||||
admin_url = "http://127.0.0.1:8080"
|
||||
mode = "limited" # or "full"
|
||||
poll_interval_ms = 1000
|
||||
|
||||
[network_proxy.policy]
|
||||
allowed_domains = ["example.com", "*.github.com"]
|
||||
denied_domains = ["metadata.google.internal", "169.254.*"]
|
||||
# macOS only: allow specific local IPC when proxy-restricted.
|
||||
allow_local_binding = false
|
||||
# Example: allow SSH agent socket for git/ssh.
|
||||
allow_unix_sockets = ["$SSH_AUTH_SOCK"]
|
||||
|
||||
[network_proxy.mitm]
|
||||
enabled = false
|
||||
```
|
||||
|
||||
## Run the proxy
|
||||
|
||||
```bash
|
||||
cd /Users/viyatb/code/codex/codex-rs
|
||||
cargo run -p codex-network-proxy -- proxy
|
||||
```
|
||||
|
||||
With MITM:
|
||||
|
||||
```bash
|
||||
cargo run -p codex-network-proxy --features mitm -- proxy
|
||||
```
|
||||
|
||||
## Test with curl
|
||||
|
||||
HTTP/HTTPS via proxy:
|
||||
|
||||
```bash
|
||||
export HTTP_PROXY="http://127.0.0.1:3128"
|
||||
export HTTPS_PROXY="http://127.0.0.1:3128"
|
||||
curl -sS https://example.com
|
||||
```
|
||||
|
||||
Limited mode + HTTPS requires MITM. If MITM is on, trust the generated CA:
|
||||
|
||||
```bash
|
||||
security add-trusted-cert -d -r trustRoot \
|
||||
-k ~/Library/Keychains/login.keychain-db \
|
||||
~/.codex/network_proxy/mitm/ca.pem
|
||||
```
|
||||
|
||||
Or pass the CA directly:
|
||||
|
||||
```bash
|
||||
curl --cacert ~/.codex/network_proxy/mitm/ca.pem -sS https://example.com
|
||||
```
|
||||
|
||||
## Admin endpoints
|
||||
|
||||
Reload config after edits:
|
||||
|
||||
```bash
|
||||
curl -fsS -X POST http://127.0.0.1:8080/reload
|
||||
```
|
||||
|
||||
Switch modes:
|
||||
|
||||
```bash
|
||||
curl -fsS -X POST http://127.0.0.1:8080/mode -d '{"mode":"full"}'
|
||||
```
|
||||
Reference in New Issue
Block a user