Wire MITM hooks into runtime enforcement

Author: evawong-oai

codex-rs/core/src/config/permissions.rs

@@ -127,6 +127,11 @@ fn profile_network_requires_proxy(network: &NetworkToml) -> bool {
         || network.allow_upstream_proxy == Some(true)
         || network.dangerously_allow_non_loopback_proxy == Some(true)
         || network.dangerously_allow_all_unix_sockets == Some(true)
+        || network.mitm == Some(true)
+        || network
+            .mitm_hooks
+            .as_ref()
+            .is_some_and(|hooks| !hooks.is_empty())
         || network.mode.is_some()
         || network
             .domains

codex-rs/core/src/config/permissions_tests.rs

@@ -11,6 +11,8 @@ use codex_config::permissions_toml::NetworkUnixSocketPermissionToml;
 use codex_config::permissions_toml::NetworkUnixSocketPermissionsToml;
 use codex_config::permissions_toml::PermissionProfileToml;
 use codex_config::permissions_toml::PermissionsToml;
+use codex_network_proxy::MitmHookConfig;
+use codex_network_proxy::MitmHookMatchConfig;
 use codex_protocol::permissions::FileSystemAccessMode;
 use codex_protocol::permissions::FileSystemPath;
 use codex_protocol::permissions::FileSystemSandboxEntry;
@@ -246,6 +248,28 @@ fn profile_network_proxy_config_keeps_proxy_disabled_for_bare_network_access() {
     assert!(!config.network.enabled);
 }
 
+#[test]
+fn profile_network_proxy_config_enables_proxy_for_mitm_hooks() {
+    let config = network_proxy_config_from_profile_network(Some(&NetworkToml {
+        enabled: Some(true),
+        mitm: Some(true),
+        mitm_hooks: Some(vec![MitmHookConfig {
+            host: "api.github.com".to_string(),
+            matcher: MitmHookMatchConfig {
+                methods: vec!["POST".to_string()],
+                path_prefixes: vec!["/repos/openai/".to_string()],
+                ..MitmHookMatchConfig::default()
+            },
+            ..MitmHookConfig::default()
+        }]),
+        ..Default::default()
+    }));
+
+    assert!(config.network.enabled);
+    assert!(config.network.mitm);
+    assert_eq!(config.network.mitm_hooks.len(), 1);
+}
+
 #[test]
 fn profile_network_proxy_config_enables_proxy_for_proxy_policy() {
     let config = network_proxy_config_from_profile_network(Some(&NetworkToml {

codex-rs/network-proxy/README.md

@@ -5,7 +5,8 @@
 - an HTTP proxy (default `127.0.0.1:3128`)
 - a SOCKS5 proxy (default `127.0.0.1:8081`, enabled by default)
 
-It enforces an allow/deny policy and a "limited" mode intended for read-only network access.
+It enforces an allow/deny policy, a "limited" mode intended for read-only network access, and
+host-specific HTTPS MITM hooks for request matching and header injection.
 
 ## Quickstart
 
@@ -32,8 +33,9 @@ allow_upstream_proxy = true
 # By default, non-loopback binds are clamped to loopback for safety.
 # If you want to expose these listeners beyond localhost, you must opt in explicitly.
 dangerously_allow_non_loopback_proxy = false
-mode = "full" # default when unset; use "limited" for read-only mode
-# When true, HTTPS CONNECT can be terminated so limited-mode method policy still applies.
+mode = "full" # default when unset; hooks can still clamp specific HTTPS hosts
+# When true, HTTPS CONNECT can be terminated so limited-mode policy and host-specific MITM hooks
+# can inspect inner requests.
 mitm = false
 # CA cert/key are managed internally under $CODEX_HOME/proxy/ (ca.pem + ca.key).
 
@@ -60,6 +62,48 @@ dangerously_allow_all_unix_sockets = false
 # macOS-only: allows proxying to a unix socket when request includes `x-unix-socket: /path`.
 [permissions.workspace.network.unix_sockets]
 "/tmp/example.sock" = "allow"
+
+[[permissions.workspace.network.mitm_hooks]]
+host = "api.github.com"
+
+[permissions.workspace.network.mitm_hooks.match]
+methods = ["POST", "PUT"]
+path_prefixes = ["/repos/openai/"]
+
+[permissions.workspace.network.mitm_hooks.match.headers]
+"x-github-api-version" = ["2022-11-28"]
+
+[permissions.workspace.network.mitm_hooks.actions]
+strip_request_headers = ["authorization"]
+
+[[permissions.workspace.network.mitm_hooks.actions.inject_request_headers]]
+name = "authorization"
+secret_env_var = "CODEX_GITHUB_TOKEN"
+prefix = "Bearer "
+
+# `match.body` is reserved for a future release. Current hooks match only on
+# method/path/query/headers and can mutate outbound request headers.
+# `match.path_prefixes` accepts literal prefixes by default. Prefix path,
+# query, or header matchers with `pattern:` to opt into wildcard matching.
+# Use `literal:` when a literal value must start with a reserved prefix.
+# In paths, `*` and `?` do not match `/`; use `**` when crossing segments is intended.
+```
+
+Matcher syntax example:
+
+```toml
+[permissions.workspace.network.mitm_hooks.match]
+# Literal path prefixes are the default.
+path_prefixes = [
+  "/repos/openai/",
+  "pattern:/repos/*/codex/issues*",
+]
+
+[permissions.workspace.network.mitm_hooks.match.query]
+state = ["open", "pattern:triage*", "literal:pattern:*"]
+
+[permissions.workspace.network.mitm_hooks.match.headers]
+"x-github-api-version" = ["2022-11-28", "pattern:2022*preview"]
 ```
 
 ### 2) Run the proxy
@@ -92,12 +136,16 @@ When a request is blocked, the proxy responds with `403` and includes:
 - `x-proxy-error`: one of:
   - `blocked-by-allowlist`
   - `blocked-by-denylist`
+  - `blocked-by-mitm-hook`
   - `blocked-by-method-policy`
+  - `blocked-by-mitm-required`
   - `blocked-by-policy`
 
 In "limited" mode, only `GET`, `HEAD`, and `OPTIONS` are allowed. HTTPS `CONNECT` requests require
-MITM to enforce limited-mode method policy; otherwise they are blocked. SOCKS5 remains blocked in
-limited mode.
+MITM to enforce limited-mode method policy; otherwise they are blocked. Separately, hosts covered
+by `mitm_hooks` are authoritative even when `mode = "full"`: hooks are evaluated in order, the
+first match wins, and if no hook matches the inner HTTPS request is denied with
+`blocked-by-mitm-hook`. SOCKS5 remains blocked in limited mode.
 
 Websocket clients typically tunnel `wss://` through HTTPS `CONNECT`; those CONNECT targets still go
 through the same host allowlist/denylist checks.

codex-rs/network-proxy/src/http_proxy.rs

@@ -80,6 +80,9 @@ use tracing::error;
 use tracing::info;
 use tracing::warn;
 
+#[derive(Clone, Copy, Debug)]
+struct ConnectMitmEnabled(bool);
+
 pub async fn run_http_proxy(
     state: Arc<NetworkProxyState>,
     addr: SocketAddr,
@@ -256,10 +259,18 @@ async fn http_connect_accept(
             return Err(text_response(StatusCode::INTERNAL_SERVER_ERROR, "error"));
         }
     };
+    let host_has_mitm_hooks = match app_state.host_has_mitm_hooks(&host).await {
+        Ok(has_hooks) => has_hooks,
+        Err(err) => {
+            error!("failed to inspect MITM hooks for {host}: {err}");
+            return Err(text_response(StatusCode::INTERNAL_SERVER_ERROR, "error"));
+        }
+    };
+    let connect_needs_mitm = mode == NetworkMode::Limited || host_has_mitm_hooks;
 
-    if mode == NetworkMode::Limited && mitm_state.is_none() {
-        // Limited mode is designed to be read-only. Without MITM, a CONNECT tunnel would hide the
-        // inner HTTP method/headers from the proxy, effectively bypassing method policy.
+    if connect_needs_mitm && mitm_state.is_none() {
+        // CONNECT needs MITM whenever HTTPS policy depends on inner-request inspection, either for
+        // limited-mode method enforcement or for host-specific MITM hooks.
         emit_http_block_decision_audit_event(
             &app_state,
             BlockDecisionAuditEventArgs {
@@ -286,7 +297,7 @@ async fn http_connect_accept(
                 reason: REASON_MITM_REQUIRED.to_string(),
                 client: client.clone(),
                 method: Some("CONNECT".to_string()),
-                mode: Some(NetworkMode::Limited),
+                mode: Some(mode),
                 protocol: "http-connect".to_string(),
                 decision: Some(details.decision.as_str().to_string()),
                 source: Some(details.source.as_str().to_string()),
@@ -295,14 +306,16 @@ async fn http_connect_accept(
             .await;
         let client = client.as_deref().unwrap_or_default();
         warn!(
-            "CONNECT blocked; MITM required for read-only HTTPS in limited mode (client={client}, host={host}, mode=limited, allowed_methods=GET, HEAD, OPTIONS)"
+            "CONNECT blocked; MITM required to enforce HTTPS policy (client={client}, host={host}, mode={mode:?}, hooked_host={host_has_mitm_hooks})"
         );
         return Err(blocked_text_with_details(REASON_MITM_REQUIRED, &details));
     }
 
     req.extensions_mut().insert(ProxyTarget(authority));
+    req.extensions_mut()
+        .insert(ConnectMitmEnabled(connect_needs_mitm));
     req.extensions_mut().insert(mode);
-    if let Some(mitm_state) = mitm_state {
+    if connect_needs_mitm && let Some(mitm_state) = mitm_state {
         req.extensions_mut().insert(mitm_state);
     }
 
@@ -331,7 +344,10 @@ async fn http_connect_proxy(upgraded: Upgraded) -> Result<(), Infallible> {
         return Ok(());
     };
 
-    if mode == NetworkMode::Limited
+    if upgraded
+        .extensions()
+        .get::<ConnectMitmEnabled>()
+        .is_some_and(|enabled| enabled.0)
         && upgraded
             .extensions()
             .get::<Arc<mitm::MitmState>>()
@@ -1094,6 +1110,42 @@ mod tests {
         assert_eq!(response.status(), StatusCode::OK);
     }
 
+    #[tokio::test]
+    async fn http_connect_accept_blocks_hooked_host_in_full_mode_without_mitm_state() {
+        let mut policy = NetworkProxySettings {
+            mitm: true,
+            mitm_hooks: vec![crate::mitm_hook::MitmHookConfig {
+                host: "api.github.com".to_string(),
+                matcher: crate::mitm_hook::MitmHookMatchConfig {
+                    methods: vec!["POST".to_string()],
+                    path_prefixes: vec!["/repos/openai/".to_string()],
+                    ..crate::mitm_hook::MitmHookMatchConfig::default()
+                },
+                actions: crate::mitm_hook::MitmHookActionsConfig::default(),
+            }],
+            ..Default::default()
+        };
+        policy.set_allowed_domains(vec!["api.github.com".to_string()]);
+        let state = Arc::new(network_proxy_state_for_policy(policy));
+
+        let mut req = Request::builder()
+            .method(Method::CONNECT)
+            .uri("https://api.github.com:443")
+            .header("host", "api.github.com:443")
+            .body(Body::empty())
+            .unwrap();
+        req.extensions_mut().insert(state);
+
+        let response = http_connect_accept(/*policy_decider*/ None, req)
+            .await
+            .unwrap_err();
+        assert_eq!(response.status(), StatusCode::FORBIDDEN);
+        assert_eq!(
+            response.headers().get("x-proxy-error").unwrap(),
+            "blocked-by-mitm-required"
+        );
+    }
+
     #[tokio::test]
     async fn http_proxy_listener_accepts_plain_http1_connect_requests() {
         let target_listener = TokioTcpListener::bind((Ipv4Addr::LOCALHOST, 0))