feat(network-proxy): experimental local credential broker (#28034)

## Why

Codex child processes can inherit injectable local credentials directly,
which lets commands read and exfiltrate the real values. This
experimental slice keeps supported workflows working while moving those
credentials behind the managed network proxy.

This PR contains only the proxy-owned broker implementation. The Codex
config and runtime integration is stacked separately in #29752.

## What changed

- discover supported credentials during child setup, retain real values
only in the in-memory proxy broker, and replace them with shaped dummy
values
- require a presented dummy to select a stored credential and preserve
unrelated explicit authorization headers
- bind GitHub cloud, GitHub Enterprise, and OpenAI credentials to their
intended hosts
- inject credentials only into TLS traffic by default; plaintext
injection requires the explicit dangerous opt-in
- use TLS ClientHello routing for CONNECT so non-TLS protocols remain
opaque tunnels
- expose a pure API that identifies environment keys still holding
broker-generated dummies without mutating the caller's environment

## Scope

- supported credentials: `GH_TOKEN`, `GITHUB_TOKEN`,
`GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN`, and `OPENAI_API_KEY`
- GitHub cloud credentials match `github.com`, `api.github.com`, and
`*.ghe.com`
- GitHub Enterprise credentials match only the normalized non-cloud
`GH_HOST`
- OpenAI API keys match only `api.openai.com`
- this does not cover SSH agents, kube client certificates, filesystem
secret discovery, or context-injected secret scrubbing

## Validation

- `just test -p codex-network-proxy` (191 passed)
- focused opaque CONNECT, plaintext opt-in, dummy-selection, and
child-isolation regressions passed
- scoped Clippy check for `codex-network-proxy` passed

---------

Co-authored-by: viyatb-oai <viyatb@openai.com>
Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
authored and GitHub committed 2026-06-24 13:21:16 -07:00
1 parent 8057603d0c
commit 989f55defa
16 files changed
+1380 -114

No files matched your search

+125 -23
View File
@@ -17,6 +17,7 @@ use crate::reasons::REASON_MITM_REQUIRED;
use crate::reasons::REASON_PROXY_DISABLED;
use crate::responses::PolicyDecisionDetails;
use crate::responses::blocked_message_with_policy;
use crate::runtime::HostMitmRequirement;
use crate::state::BlockedRequest;
use crate::state::BlockedRequestArgs;
use crate::state::NetworkProxyState;
@@ -341,10 +342,10 @@ async fn handle_socks5_tcp(
}
}
let host_has_mitm_hooks = match app_state.host_has_mitm_hooks(&host).await {
Ok(has_hooks) => has_hooks,
let host_mitm_requirement = match app_state.host_mitm_requirement(&host).await {
Ok(requirement) => requirement,
Err(err) => {
error!("failed to inspect MITM hooks for {host}: {err}");
error!("failed to inspect MITM requirements for {host}: {err}");
return Err(io::Error::other("proxy error").into());
}
};
@@ -355,10 +356,19 @@ async fn handle_socks5_tcp(
return Err(io::Error::other("proxy error").into());
}
};
let socks_needs_mitm =
socks5_tcp_target_is_https && (mode == NetworkMode::Limited || host_has_mitm_hooks);
if (host_has_mitm_hooks && !socks5_tcp_target_is_https)
|| (socks_needs_mitm && mitm_state.is_none())
let socks_mitm_mode = if mode == NetworkMode::Limited {
SocksMitmMode::Enabled
} else {
match host_mitm_requirement {
HostMitmRequirement::None => SocksMitmMode::Disabled,
HostMitmRequirement::Tls => SocksMitmMode::DetectTls,
HostMitmRequirement::Always => SocksMitmMode::Enabled,
}
};
let unsupported_hook_protocol =
host_mitm_requirement == HostMitmRequirement::Always && !socks5_tcp_target_is_https;
if unsupported_hook_protocol
|| (socks_mitm_mode != SocksMitmMode::Disabled && mitm_state.is_none())
{
emit_socks_block_decision_audit_event(
&app_state,
@@ -392,23 +402,35 @@ async fn handle_socks5_tcp(
.await;
let client = client.as_deref().unwrap_or_default();
warn!(
"SOCKS blocked; MITM required to enforce HTTPS policy (client={client}, host={host}, mode={mode:?}, hooked_host={host_has_mitm_hooks}, https_target={socks5_tcp_target_is_https})"
"SOCKS blocked; MITM required to enforce HTTPS policy (client={client}, host={host}, mode={mode:?}, host_mitm_requirement={host_mitm_requirement:?}, https_target={socks5_tcp_target_is_https})"
);
return Err(policy_denied_error(REASON_MITM_REQUIRED, &details).into());
}
if socks_needs_mitm && let Some(mitm_state) = mitm_state {
if let Some(mitm_state) = mitm_state {
let client = client.as_deref().unwrap_or_default();
info!("SOCKS MITM enabled (client={client}, host={host}, port={port}, mode={mode:?})");
return Ok(EstablishedClientConnection {
input: req,
conn: Socks5TcpConnection::Mitm {
let conn = match socks_mitm_mode {
SocksMitmMode::Disabled => None,
SocksMitmMode::Enabled => Some(Socks5TcpConnection::Mitm {
target,
mode,
mitm: mitm_state,
extensions: Extensions::new(),
},
});
}),
SocksMitmMode::DetectTls => Some(Socks5TcpConnection::DetectTls {
target,
mode,
mitm: mitm_state,
state: app_state,
extensions: Extensions::new(),
}),
};
if let Some(conn) = conn {
info!(
"SOCKS MITM selected (client={client}, host={host}, port={port}, mode={mode:?}, mitm_mode={socks_mitm_mode:?})"
);
return Ok(EstablishedClientConnection { input: req, conn });
}
}
info!("SOCKS upstream dial started (host={host}, port={port})");
@@ -435,6 +457,13 @@ async fn handle_socks5_tcp(
/// Internal connector output for SOCKS5 TCP. MITM requests do not dial upstream before the
/// inner HTTPS request is inspected, so they carry the target metadata instead of a socket.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum SocksMitmMode {
Disabled,
Enabled,
DetectTls,
}
#[derive(Debug)]
enum Socks5TcpConnection {
Direct(TcpStream),
@@ -444,6 +473,13 @@ enum Socks5TcpConnection {
mitm: Arc<mitm::MitmState>,
extensions: Extensions,
},
DetectTls {
target: HostWithPort,
mode: NetworkMode,
mitm: Arc<mitm::MitmState>,
state: Arc<NetworkProxyState>,
extensions: Extensions,
},
}
impl AsyncRead for Socks5TcpConnection {
@@ -454,7 +490,7 @@ impl AsyncRead for Socks5TcpConnection {
) -> Poll<io::Result<()>> {
match self.get_mut() {
Self::Direct(stream) => Pin::new(stream).poll_read(cx, buf),
Self::Mitm { .. } => Poll::Ready(Ok(())),
Self::Mitm { .. } | Self::DetectTls { .. } => Poll::Ready(Ok(())),
}
}
}
@@ -467,21 +503,21 @@ impl AsyncWrite for Socks5TcpConnection {
) -> Poll<io::Result<usize>> {
match self.get_mut() {
Self::Direct(stream) => Pin::new(stream).poll_write(cx, buf),
Self::Mitm { .. } => Poll::Ready(Ok(buf.len())),
Self::Mitm { .. } | Self::DetectTls { .. } => Poll::Ready(Ok(buf.len())),
}
}
fn poll_flush(self: Pin<&mut Self>, cx: &mut TaskContext<'_>) -> Poll<io::Result<()>> {
match self.get_mut() {
Self::Direct(stream) => Pin::new(stream).poll_flush(cx),
Self::Mitm { .. } => Poll::Ready(Ok(())),
Self::Mitm { .. } | Self::DetectTls { .. } => Poll::Ready(Ok(())),
}
}
fn poll_shutdown(self: Pin<&mut Self>, cx: &mut TaskContext<'_>) -> Poll<io::Result<()>> {
match self.get_mut() {
Self::Direct(stream) => Pin::new(stream).poll_shutdown(cx),
Self::Mitm { .. } => Poll::Ready(Ok(())),
Self::Mitm { .. } | Self::DetectTls { .. } => Poll::Ready(Ok(())),
}
}
}
@@ -490,14 +526,14 @@ impl Socket for Socks5TcpConnection {
fn local_addr(&self) -> io::Result<SocketAddr> {
match self {
Self::Direct(stream) => stream.local_addr(),
Self::Mitm { .. } => Ok(SocketAddr::from(([0, 0, 0, 0], 0))),
Self::Mitm { .. } | Self::DetectTls { .. } => Ok(SocketAddr::from(([0, 0, 0, 0], 0))),
}
}
fn peer_addr(&self) -> io::Result<SocketAddr> {
match self {
Self::Direct(stream) => stream.peer_addr(),
Self::Mitm { .. } => Ok(SocketAddr::from(([0, 0, 0, 0], 0))),
Self::Mitm { .. } | Self::DetectTls { .. } => Ok(SocketAddr::from(([0, 0, 0, 0], 0))),
}
}
}
@@ -506,7 +542,7 @@ impl ExtensionsRef for Socks5TcpConnection {
fn extensions(&self) -> &Extensions {
match self {
Self::Direct(stream) => stream.extensions(),
Self::Mitm { extensions, .. } => extensions,
Self::Mitm { extensions, .. } | Self::DetectTls { extensions, .. } => extensions,
}
}
}
@@ -515,7 +551,7 @@ impl ExtensionsMut for Socks5TcpConnection {
fn extensions_mut(&mut self) -> &mut Extensions {
match self {
Self::Direct(stream) => stream.extensions_mut(),
Self::Mitm { extensions, .. } => extensions,
Self::Mitm { extensions, .. } | Self::DetectTls { extensions, .. } => extensions,
}
}
}
@@ -537,6 +573,41 @@ async fn proxy_socks5_tcp(
source.extensions_mut().insert(mitm);
mitm::mitm_stream(source).await.map_err(Into::into)
}
Socks5TcpConnection::DetectTls {
target,
mode,
mitm,
state,
..
} => {
source.extensions_mut().insert(ProxyTarget(target.clone()));
source.extensions_mut().insert(mode);
source.extensions_mut().insert(mitm);
let (is_tls, source) = mitm::peek_tls_prefix(source)
.await
.map_err(|err| -> BoxError { err.into() })?;
if is_tls {
mitm::mitm_stream(source).await.map_err(Into::into)
} else {
info!("SOCKS opaque upstream dial started (target={target})");
let connect_started_at = Instant::now();
let EstablishedClientConnection { conn: upstream, .. } =
TargetCheckedTcpConnector::new(state)
.serve(TcpRequest::new(target.clone()))
.await?;
info!(
"SOCKS opaque upstream dial established (target={target}, elapsed_ms={})",
connect_started_at.elapsed().as_millis()
);
StreamForwardService::default()
.serve(ProxyRequest {
source,
target: upstream,
})
.await
.map_err(Into::into)
}
}
}
}
@@ -752,6 +823,7 @@ mod tests {
use rama_net::address::HostWithPort;
use rama_net::address::SocketAddress;
use rama_socks5::server::udp::RelayDirection;
use std::collections::HashMap;
use std::net::IpAddr;
use std::net::Ipv4Addr;
use std::sync::Arc;
@@ -908,6 +980,36 @@ mod tests {
assert_eq!(event.field("client.address"), Some("unknown"));
}
#[tokio::test(flavor = "current_thread")]
async fn handle_socks5_tcp_detects_tls_for_brokered_nonstandard_port_in_full_mode() {
let mut settings = NetworkProxySettings {
enabled: true,
mode: NetworkMode::Full,
mitm: true,
credential_broker: true,
..NetworkProxySettings::default()
};
settings.set_allowed_domains(vec!["api.openai.com".to_string()]);
let state = state_for_settings(settings);
let mut env = HashMap::from([("OPENAI_API_KEY".to_string(), "sk-real".to_string())]);
state.virtualize_child_credentials(&mut env);
let mut request = TcpRequest::new(
HostWithPort::try_from("api.openai.com:8443").expect("valid authority"),
);
request.extensions_mut().insert(state.clone());
let result = handle_socks5_tcp(
request,
TargetCheckedTcpConnector::new(state),
/*policy_decider*/ None,
/*environment_id*/ None,
)
.await
.expect("brokered TLS should defer MITM until protocol detection");
assert!(matches!(result.conn, Socks5TcpConnection::DetectTls { .. }));
}
#[tokio::test(flavor = "current_thread")]
async fn handle_socks5_tcp_blocks_limited_mode_without_mitm_state() {
let mut settings = NetworkProxySettings {