Pass ambiguous network triggers to Guardian

This commit is contained in:
Winston Howes
2026-06-23 01:38:56 -04:00
parent e0ac5d3c15
commit e1f25c36f9
6 changed files with 335 additions and 42 deletions
@@ -55,6 +55,7 @@ pub(crate) enum GuardianApprovalRequest {
protocol: NetworkApprovalProtocol,
port: u16,
trigger: Option<GuardianNetworkAccessTrigger>,
possible_triggers: Vec<GuardianNetworkAccessTrigger>,
},
McpToolCall {
id: String,
@@ -158,6 +159,8 @@ struct NetworkAccessApprovalAction<'a> {
port: u16,
#[serde(skip_serializing_if = "Option::is_none")]
trigger: Option<&'a GuardianNetworkAccessTrigger>,
#[serde(skip_serializing_if = "Option::is_none")]
possible_triggers: Option<&'a [GuardianNetworkAccessTrigger]>,
}
#[derive(Serialize)]
@@ -327,6 +330,7 @@ pub(crate) fn guardian_approval_request_to_json(
protocol,
port,
trigger,
possible_triggers,
} => serialize_guardian_action(NetworkAccessApprovalAction {
tool: "network_access",
target,
@@ -334,6 +338,8 @@ pub(crate) fn guardian_approval_request_to_json(
protocol: *protocol,
port: *port,
trigger: trigger.as_ref(),
possible_triggers: (!possible_triggers.is_empty())
.then_some(possible_triggers.as_slice()),
}),
GuardianApprovalRequest::McpToolCall {
id: _,
@@ -409,6 +415,7 @@ pub(crate) fn guardian_assessment_action(
protocol,
port,
trigger: _trigger,
possible_triggers: _possible_triggers,
} => GuardianAssessmentAction::NetworkAccess {
target: target.clone(),
host: host.clone(),
+10 -1
View File
@@ -198,7 +198,11 @@ pub(crate) async fn build_guardian_prompt_items_with_parent_turn(
push_text(">>> PARENT TURN PERMISSION CONTEXT END\n".to_string());
}
match &request {
GuardianApprovalRequest::NetworkAccess { trigger, .. } => {
GuardianApprovalRequest::NetworkAccess {
trigger,
possible_triggers,
..
} => {
push_text(">>> APPROVAL REQUEST START\n".to_string());
push_text("Below is a proposed network access request under review.\n".to_string());
if trigger.is_some() {
@@ -206,6 +210,11 @@ pub(crate) async fn build_guardian_prompt_items_with_parent_turn(
"The network access was triggered by the action in the `trigger` entry. When assessing this request, focus primarily on whether the triggering command is authorised by the user and whether it is within the rules. The user does not need to have explicitly authorised this exact network connection, as long as the network access is a reasonable consequence of the triggering command.\n\n"
.to_string(),
);
} else if !possible_triggers.is_empty() {
push_text(
"The proxy could not identify which active command triggered the network access. The `possibleTriggers` entry contains every candidate command that was active in the same execution environment when the request was observed. Approve if at least one candidate is authorised by the user and the network access is a reasonable consequence of that candidate. Do not require every candidate to explain the request. Deny if none provide a plausible authorised explanation.\n\n"
.to_string(),
);
} else {
push_text(
"No trigger action was captured for this network access request. When performing the assessment, use the retained transcript and network access JSON to evaluate user authorization and risk.\n\n"
+4
View File
@@ -974,6 +974,7 @@ fn guardian_approval_request_to_json_renders_network_access_trigger() -> serde_j
justification: Some("Fetch the release metadata.".to_string()),
tty: None,
}),
possible_triggers: Vec::new(),
};
assert_eq!(
@@ -1024,6 +1025,7 @@ async fn build_guardian_prompt_items_explains_network_access_review_scope() -> a
justification: Some("Fetch the release metadata.".to_string()),
tty: None,
}),
possible_triggers: Vec::new(),
},
GuardianPromptMode::Full,
)
@@ -1099,6 +1101,7 @@ fn guardian_request_turn_id_prefers_network_access_owner_turn() {
protocol: NetworkApprovalProtocol::Https,
port: 443,
trigger: None,
possible_triggers: Vec::new(),
};
let apply_patch = GuardianApprovalRequest::ApplyPatch {
id: "patch-1".to_string(),
@@ -1137,6 +1140,7 @@ fn guardian_request_target_item_id_omits_network_access_trigger_call_id() {
justification: None,
tty: None,
}),
possible_triggers: Vec::new(),
};
assert_eq!(guardian_request_target_item_id(&network_access), None);
+73 -17
View File
@@ -27,6 +27,7 @@ use codex_protocol::protocol::Event;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::ReviewDecision;
use codex_protocol::protocol::WarningEvent;
use codex_utils_output_truncation::approx_tokens_from_byte_count;
use indexmap::IndexMap;
use std::collections::HashMap;
use std::collections::HashSet;
@@ -39,6 +40,11 @@ use tokio_util::sync::CancellationToken;
use tracing::warn;
use uuid::Uuid;
// Keep ambiguous attribution bounded before adding every candidate to model-visible context.
const MAX_GUARDIAN_NETWORK_ACCESS_TRIGGER_CANDIDATES: usize = 16;
// Leave room in the 10K-token action item for network metadata and JSON formatting.
const MAX_GUARDIAN_NETWORK_ACCESS_TRIGGER_TOKENS: u64 = 8_000;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum NetworkApprovalMode {
Immediate,
@@ -238,7 +244,12 @@ struct ActiveNetworkApprovalCall {
enum ActiveNetworkApprovalAttribution {
None,
Single(Arc<ActiveNetworkApprovalCall>),
Ambiguous,
Ambiguous(Vec<Arc<ActiveNetworkApprovalCall>>),
}
enum ActiveNetworkApprovalCallScope<'a> {
AllEnvironments,
Environment(&'a str),
}
#[derive(Default)]
@@ -315,15 +326,29 @@ impl NetworkApprovalService {
None
}
async fn resolve_active_call_attribution(&self) -> ActiveNetworkApprovalAttribution {
async fn resolve_active_call_attribution(
&self,
scope: ActiveNetworkApprovalCallScope<'_>,
) -> ActiveNetworkApprovalAttribution {
let calls = self.calls.lock().await;
match calls.active_calls.len() {
let candidates = calls
.active_calls
.values()
.filter(|call| match scope {
ActiveNetworkApprovalCallScope::AllEnvironments => true,
ActiveNetworkApprovalCallScope::Environment(environment_id) => {
call.environment_id == environment_id
}
})
.cloned()
.collect::<Vec<_>>();
match candidates.len() {
0 => ActiveNetworkApprovalAttribution::None,
1 => calls.active_calls.values().next().cloned().map_or(
1 => candidates.into_iter().next().map_or(
ActiveNetworkApprovalAttribution::None,
ActiveNetworkApprovalAttribution::Single,
),
_ => ActiveNetworkApprovalAttribution::Ambiguous,
_ => ActiveNetworkApprovalAttribution::Ambiguous(candidates),
}
}
@@ -431,24 +456,37 @@ impl NetworkApprovalService {
NetworkProtocol::Socks5Tcp => NetworkApprovalProtocol::Socks5Tcp,
NetworkProtocol::Socks5Udp => NetworkApprovalProtocol::Socks5Udp,
};
let (owner_call, active_environment_id) =
let (owner_call, possible_trigger_calls, active_environment_id) =
if let Some(environment_id) = request.environment_id.clone() {
let owner_call = match self.resolve_active_call_attribution().await {
ActiveNetworkApprovalAttribution::Single(call) => {
(call.environment_id == environment_id).then_some(call)
match self
.resolve_active_call_attribution(ActiveNetworkApprovalCallScope::Environment(
&environment_id,
))
.await
{
ActiveNetworkApprovalAttribution::None => {
(None, Vec::new(), Some(environment_id))
}
ActiveNetworkApprovalAttribution::None
| ActiveNetworkApprovalAttribution::Ambiguous => None,
};
(owner_call, Some(environment_id))
ActiveNetworkApprovalAttribution::Single(call) => {
(Some(call), Vec::new(), Some(environment_id))
}
ActiveNetworkApprovalAttribution::Ambiguous(calls) => {
(None, calls, Some(environment_id))
}
}
} else {
match self.resolve_active_call_attribution().await {
ActiveNetworkApprovalAttribution::None => (None, None),
match self
.resolve_active_call_attribution(
ActiveNetworkApprovalCallScope::AllEnvironments,
)
.await
{
ActiveNetworkApprovalAttribution::None => (None, Vec::new(), None),
ActiveNetworkApprovalAttribution::Single(call) => {
let environment_id = call.environment_id.clone();
(Some(call), Some(environment_id))
(Some(call), Vec::new(), Some(environment_id))
}
ActiveNetworkApprovalAttribution::Ambiguous => {
ActiveNetworkApprovalAttribution::Ambiguous(_) => {
return NetworkDecision::deny(REASON_NOT_ALLOWED);
}
}
@@ -567,6 +605,23 @@ impl NetworkApprovalService {
}
}
let use_guardian = routes_approval_to_guardian(&turn_context);
let possible_triggers = possible_trigger_calls
.iter()
.map(|call| call.trigger.clone())
.collect::<Vec<_>>();
if use_guardian {
let candidates_fit = possible_triggers.len()
<= MAX_GUARDIAN_NETWORK_ACCESS_TRIGGER_CANDIDATES
&& serde_json::to_vec_pretty(&possible_triggers).is_ok_and(|encoded| {
approx_tokens_from_byte_count(encoded.len())
<= MAX_GUARDIAN_NETWORK_ACCESS_TRIGGER_TOKENS
});
if !candidates_fit {
pending.set_decision(PendingApprovalDecision::Deny).await;
self.pending_host_approvals.lock().await.remove(&key);
return NetworkDecision::deny(REASON_NOT_ALLOWED);
}
}
let guardian_review_id = use_guardian.then(new_guardian_review_id);
let approval_decision = if let Some(review_id) = guardian_review_id.clone() {
review_approval_request(
@@ -583,6 +638,7 @@ impl NetworkApprovalService {
protocol,
port: key.port,
trigger: owner_call.as_ref().map(|call| call.trigger.clone()),
possible_triggers,
},
Some(policy_denial_message.clone()),
)
@@ -349,15 +349,63 @@ async fn active_call_preserves_triggering_command_context() {
}
#[tokio::test]
async fn multiple_active_calls_are_ambiguous_even_in_the_same_environment() {
async fn multiple_active_calls_in_the_same_environment_return_all_candidates() {
let service = NetworkApprovalService::default();
register_call_with_default_shell_trigger(&service, "registration-1").await;
register_call_with_default_shell_trigger(&service, "registration-2").await;
match service.resolve_active_call_attribution().await {
ActiveNetworkApprovalAttribution::Ambiguous => {}
match service
.resolve_active_call_attribution(ActiveNetworkApprovalCallScope::Environment("local"))
.await
{
ActiveNetworkApprovalAttribution::Ambiguous(calls) => {
assert_eq!(
calls
.iter()
.map(|call| call.registration_id.as_str())
.collect::<Vec<_>>(),
vec!["registration-1", "registration-2"]
);
}
ActiveNetworkApprovalAttribution::None | ActiveNetworkApprovalAttribution::Single(_) => {
panic!("multiple active calls should be ambiguous")
panic!("multiple active calls should return every candidate")
}
}
}
#[tokio::test]
async fn active_call_attribution_is_filtered_by_environment() {
let service = NetworkApprovalService::default();
register_call_with_default_shell_trigger(&service, "registration-local").await;
service
.register_call(
"registration-remote".to_string(),
"turn-1".to_string(),
GuardianNetworkAccessTrigger {
call_id: "call-remote".to_string(),
tool_name: "shell_command".to_string(),
command: vec!["curl".to_string(), "https://example.com".to_string()],
cwd: test_path_buf("/tmp").abs(),
sandbox_permissions: SandboxPermissions::UseDefault,
additional_permissions: None,
justification: None,
tty: None,
},
"curl https://example.com".to_string(),
"remote".to_string(),
CancellationToken::new(),
)
.await;
match service
.resolve_active_call_attribution(ActiveNetworkApprovalCallScope::Environment("remote"))
.await
{
ActiveNetworkApprovalAttribution::Single(call) => {
assert_eq!(call.registration_id, "registration-remote");
}
ActiveNetworkApprovalAttribution::None | ActiveNetworkApprovalAttribution::Ambiguous(_) => {
panic!("one matching environment call should resolve exactly")
}
}
}
+189 -20
View File
@@ -10,6 +10,7 @@ use codex_features::Feature;
use codex_protocol::approvals::NetworkApprovalContext;
use codex_protocol::approvals::NetworkApprovalProtocol;
use codex_protocol::models::PermissionProfile;
use codex_protocol::permissions::FileSystemSandboxPolicy;
use codex_protocol::permissions::NetworkSandboxPolicy;
use codex_protocol::protocol::AskForApproval;
use codex_protocol::protocol::EventMsg;
@@ -56,6 +57,140 @@ use tempfile::TempDir;
const NETWORK_TEST_HOST: &str = "codex-network-test.invalid";
const NETWORK_TEST_TARGET: &str = "http://codex-network-test.invalid:80";
#[derive(Clone, Copy)]
enum ManagedNetworkTestEnvironments {
Local,
RemoteAndLocal,
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn guardian_receives_all_possible_triggers_for_concurrent_network_requests() -> Result<()> {
skip_if_wine_exec!(Ok(()), "uses the POSIX/Python network fixture");
skip_if_no_network!(Ok(()));
skip_if_sandbox!(Ok(()));
skip_if_windows!(Ok(()));
let server = start_mock_server().await;
let permission_profile = PermissionProfile::from_runtime_permissions(
&FileSystemSandboxPolicy::unrestricted(),
NetworkSandboxPolicy::Enabled,
);
let test = managed_network_unified_exec_test(
&server,
permission_profile.clone(),
ManagedNetworkTestEnvironments::Local,
)
.await?;
let barrier_dir = TempDir::new()?;
let first_marker = barrier_dir.path().join("first");
let second_marker = barrier_dir.path().join("second");
let first_command = concurrent_network_fetch_command(&first_marker, &second_marker);
let second_command = concurrent_network_fetch_command(&second_marker, &first_marker);
let first_args = network_exec_args(LOCAL_ENVIRONMENT_ID, &first_command);
let second_args = network_exec_args(LOCAL_ENVIRONMENT_ID, &second_command);
let responses = mount_sse_sequence(
&server,
vec![
sse(vec![
ev_response_created("resp-network-concurrent"),
ev_function_call(
"exec-network-first",
"exec_command",
&serde_json::to_string(&first_args)?,
),
ev_function_call(
"exec-network-second",
"exec_command",
&serde_json::to_string(&second_args)?,
),
ev_completed("resp-network-concurrent"),
]),
sse(vec![
ev_response_created("resp-network-guardian"),
ev_assistant_message(
"msg-network-guardian",
&json!({
"risk_level": "low",
"user_authorization": "high",
"outcome": "allow",
"rationale": "At least one candidate explains the requested access.",
})
.to_string(),
),
ev_completed("resp-network-guardian"),
]),
sse(vec![
ev_response_created("resp-network-done"),
ev_assistant_message("msg-network-done", "done"),
ev_completed("resp-network-done"),
]),
],
)
.await;
submit_managed_network_turn(
&test,
"run both network requests",
vec![local(test.config.cwd.clone())],
AskForApproval::OnRequest,
ApprovalsReviewer::AutoReview,
permission_profile,
)
.await?;
wait_for_turn_complete(&test).await;
let guardian_request = responses
.requests()
.into_iter()
.find(|request| {
request.body_json()["client_metadata"]["x-openai-subagent"].as_str() == Some("guardian")
})
.expect("expected Guardian network review request");
let user_texts = guardian_request.message_input_texts("user");
let action = user_texts
.iter()
.find_map(|text| {
let action = serde_json::from_str::<Value>(text.trim()).ok()?;
(action["tool"].as_str() == Some("network_access")).then_some(action)
})
.context("expected network access JSON in Guardian request")?;
assert_eq!(action.get("trigger"), None);
let possible_triggers = action["possibleTriggers"]
.as_array()
.context("expected possible network access triggers")?;
let mut call_ids = possible_triggers
.iter()
.map(|trigger| {
trigger["callId"]
.as_str()
.context("expected possible trigger call id")
})
.collect::<Result<Vec<_>>>()?;
call_ids.sort_unstable();
assert_eq!(call_ids, vec!["exec-network-first", "exec-network-second"]);
let mut commands = possible_triggers
.iter()
.map(|trigger| {
trigger["command"]
.as_array()
.and_then(|command| command.last())
.and_then(Value::as_str)
.context("expected possible trigger command")
})
.collect::<Result<Vec<_>>>()?;
commands.sort_unstable();
let mut expected_commands = vec![first_command.as_str(), second_command.as_str()];
expected_commands.sort_unstable();
assert_eq!(commands, expected_commands);
assert!(
user_texts
.concat()
.contains("Approve if at least one candidate")
);
Ok(())
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn approved_network_host_for_one_environment_still_prompts_in_another() -> Result<()> {
skip_if_wine_exec!(Ok(()), "uses the POSIX/Python network fixture");
@@ -67,7 +202,18 @@ async fn approved_network_host_for_one_environment_still_prompts_in_another() ->
};
let server = start_mock_server().await;
let test = managed_network_unified_exec_test(&server).await?;
let permission_profile = PermissionProfile::workspace_write_with(
&[],
NetworkSandboxPolicy::Enabled,
/*exclude_tmpdir_env_var*/ false,
/*exclude_slash_tmp*/ false,
);
let test = managed_network_unified_exec_test(
&server,
permission_profile.clone(),
ManagedNetworkTestEnvironments::RemoteAndLocal,
)
.await?;
let local_cwd = TempDir::new()?;
let remote_cwd = PathBuf::from(format!(
"/tmp/codex-network-approval-{}",
@@ -101,6 +247,9 @@ async fn approved_network_host_for_one_environment_still_prompts_in_another() ->
&test,
"fetch from the local environment",
environments.clone(),
AskForApproval::OnFailure,
ApprovalsReviewer::User,
permission_profile.clone(),
)
.await?;
let approval = expect_network_approval(&test, LOCAL_ENVIRONMENT_ID).await?;
@@ -124,6 +273,9 @@ async fn approved_network_host_for_one_environment_still_prompts_in_another() ->
&test,
"fetch from the remote environment",
environments.clone(),
AskForApproval::OnFailure,
ApprovalsReviewer::User,
permission_profile,
)
.await?;
let approval = expect_network_approval(&test, REMOTE_ENVIRONMENT_ID).await?;
@@ -150,7 +302,11 @@ async fn approved_network_host_for_one_environment_still_prompts_in_another() ->
Ok(())
}
async fn managed_network_unified_exec_test(server: &wiremock::MockServer) -> Result<TestCodex> {
async fn managed_network_unified_exec_test(
server: &wiremock::MockServer,
permission_profile: PermissionProfile,
environments: ManagedNetworkTestEnvironments,
) -> Result<TestCodex> {
let home = Arc::new(TempDir::new()?);
fs::write(
home.path().join("config.toml"),
@@ -165,13 +321,6 @@ mode = "limited"
allow_local_binding = true
"#,
)?;
let approval_policy = AskForApproval::OnFailure;
let permission_profile = PermissionProfile::workspace_write_with(
&[],
NetworkSandboxPolicy::Enabled,
/*exclude_tmpdir_env_var*/ false,
/*exclude_slash_tmp*/ false,
);
let permission_profile_for_config = permission_profile.clone();
let mut builder = test_codex()
.with_home(home)
@@ -182,13 +331,18 @@ allow_local_binding = true
.features
.enable(Feature::UnifiedExec)
.expect("test config should allow feature update");
config.permissions.approval_policy = Constrained::allow_any(approval_policy);
config.permissions.approval_policy = Constrained::allow_any(AskForApproval::OnFailure);
config
.permissions
.set_permission_profile(permission_profile_for_config)
.expect("set permission profile");
});
let test = builder.build_with_remote_and_local_env(server).await?;
let test = match environments {
ManagedNetworkTestEnvironments::Local => builder.build(server).await?,
ManagedNetworkTestEnvironments::RemoteAndLocal => {
builder.build_with_remote_and_local_env(server).await?
}
};
assert!(
test.config.managed_network_requirements_enabled(),
"expected managed network requirements to be enabled"
@@ -227,26 +381,41 @@ async fn mount_exec_network_turn(
}
fn network_fetch_args(environment_id: &str) -> Value {
let command = format!(
"python3 -c \"import urllib.request; opener = urllib.request.build_opener(urllib.request.ProxyHandler()); print('OK:' + opener.open('http://{NETWORK_TEST_HOST}', timeout=2).read().decode(errors='replace'))\""
);
network_exec_args(environment_id, &command)
}
fn network_exec_args(environment_id: &str, command: &str) -> Value {
json!({
"shell": "/bin/sh",
"cmd": format!("python3 -c \"import urllib.request; opener = urllib.request.build_opener(urllib.request.ProxyHandler()); print('OK:' + opener.open('http://{NETWORK_TEST_HOST}', timeout=2).read().decode(errors='replace'))\""),
"cmd": command,
"login": false,
"yield_time_ms": 1_000,
"environment_id": environment_id,
})
}
fn concurrent_network_fetch_command(
marker: &std::path::Path,
peer_marker: &std::path::Path,
) -> String {
format!(
"touch '{}' && while [ ! -e '{}' ]; do sleep 0.01; done && python3 -c \"import urllib.request; opener = urllib.request.build_opener(urllib.request.ProxyHandler()); opener.open('http://{NETWORK_TEST_HOST}', timeout=10).read()\"",
marker.display(),
peer_marker.display(),
)
}
async fn submit_managed_network_turn(
test: &TestCodex,
prompt: &str,
environments: Vec<TurnEnvironmentSelection>,
approval_policy: AskForApproval,
approvals_reviewer: ApprovalsReviewer,
permission_profile: PermissionProfile,
) -> Result<()> {
let permission_profile = PermissionProfile::workspace_write_with(
&[],
NetworkSandboxPolicy::Enabled,
/*exclude_tmpdir_env_var*/ false,
/*exclude_slash_tmp*/ false,
);
let (sandbox_policy, permission_profile) =
turn_permission_fields(permission_profile, test.config.cwd.as_path());
let turn_environment_selections =
@@ -263,8 +432,8 @@ async fn submit_managed_network_turn(
additional_context: Default::default(),
thread_settings: codex_protocol::protocol::ThreadSettingsOverrides {
environments: Some(turn_environment_selections),
approval_policy: Some(AskForApproval::OnFailure),
approvals_reviewer: Some(ApprovalsReviewer::User),
approval_policy: Some(approval_policy),
approvals_reviewer: Some(approvals_reviewer),
sandbox_policy: Some(sandbox_policy),
permission_profile,
collaboration_mode: Some(codex_protocol::config_types::CollaborationMode {