feat: introduce support for shell_environment_policy in config.toml (#1061)

To date, when handling `shell` and `local_shell` tool calls, we were
spawning new processes using the environment inherited from the Codex
process itself. This means that the sensitive `OPENAI_API_KEY` that
Codex needs to talk to OpenAI models was made available to everything
run by `shell` and `local_shell`. While there are cases where that might
be useful, it does not seem like a good default.

This PR introduces a complex `shell_environment_policy` config option to
control the `env` used with these tool calls. It is inevitably a bit
complex so that it is possible to override individual components of the
policy so without having to restate the entire thing.

Details are in the updated `README.md` in this PR, but here is the
relevant bit that explains the individual fields of
`shell_environment_policy`:

| Field | Type | Default | Description |
| ------------------------- | -------------------------- | ------- |
-----------------------------------------------------------------------------------------------------------------------------------------------
|
| `inherit` | string | `core` | Starting template for the
environment:<br>`core` (`HOME`, `PATH`, `USER`, …), `all` (clone full
parent env), or `none` (start empty). |
| `ignore_default_excludes` | boolean | `false` | When `false`, Codex
removes any var whose **name** contains `KEY`, `SECRET`, or `TOKEN`
(case-insensitive) before other rules run. |
| `exclude` | array&lt;string&gt; | `[]` | Case-insensitive glob
patterns to drop after the default filter.<br>Examples: `"AWS_*"`,
`"AZURE_*"`. |
| `set` | table&lt;string,string&gt; | `{}` | Explicit key/value
overrides or additions – always win over inherited values. |
| `include_only` | array&lt;string&gt; | `[]` | If non-empty, a
whitelist of patterns; only variables that match _one_ pattern survive
the final step. (Generally used with `inherit = "all"`.) |


In particular, note that the default is `inherit = "core"`, so:

* if you have extra env variables that you want to inherit from the
parent process, use `inherit = "all"` and then specify `include_only`
* if you have extra env variables where you want to hardcode the values,
the default `inherit = "core"` will work fine, but then you need to
specify `set`

This configuration is not battle-tested, so we will probably still have
to play with it a bit. `core/src/exec_env.rs` has the critical business
logic as well as unit tests.

Though if nothing else, previous to this change:

```
$ cargo run --bin codex -- debug seatbelt -- printenv OPENAI_API_KEY
# ...prints OPENAI_API_KEY...
```

But after this change it does not print anything (as desired).

One final thing to call out about this PR is that the
`configure_command!` macro we use in `core/src/exec.rs` has to do some
complex logic with respect to how it builds up the `env` for the process
being spawned under Landlock/seccomp. Specifically, doing
`cmd.env_clear()` followed by `cmd.envs(&$env_map)` (which is arguably
the most intuitive way to do it) caused the Landlock unit tests to fail
because the processes spawned by the unit tests started failing in
unexpected ways! If we forgo `env_clear()` in favor of updating env vars
one at a time, the tests still pass. The comment in the code talks about
this a bit, and while I would like to investigate this more, I need to
move on for the moment, but I do plan to come back to it to fully
understand what is going on. For example, this suggests that we might
not be able to spawn a C program that calls `env_clear()`, which would
be...weird. We may still have to fiddle with our Landlock config if that
is the case.

Author: bolinfest

.github/workflows/rust-ci.yml

@@ -100,6 +100,8 @@ jobs:
         id: test
         continue-on-error: true
         run: cargo test --all-features --target ${{ matrix.target }}
+        env:
+          RUST_BACKTRACE: 1
 
       # Fail the job if any of the previous steps failed.
       - name: verify all steps passed

codex-rs/Cargo.lock

@@ -222,6 +222,49 @@ Currently, customers whose accounts are set to use Zero Data Retention (ZDR) mus
 disable_response_storage = true
 ```
 
+### shell_environment_policy
+
+Codex spawns subprocesses (e.g. when executing a `local_shell` tool-call suggested by the assistant). By default it passes **only a minimal core subset** of your environment to those subprocesses to avoid leaking credentials. You can tune this behavior via the **`shell_environment_policy`** block in
+`config.toml`:
+
+```toml
+[shell_environment_policy]
+# inherit can be "core" (default), "all", or "none"
+inherit = "core"
+# set to true to *skip* the filter for `"*KEY*"` and `"*TOKEN*"`
+ignore_default_excludes = false
+# exclude patterns (case-insensitive globs)
+exclude = ["AWS_*", "AZURE_*"]
+# force-set / override values
+set = { CI = "1" }
+# if provided, *only* vars matching these patterns are kept
+include_only = ["PATH", "HOME"]
+```
+
+| Field                     | Type                       | Default | Description                                                                                                                                     |
+| ------------------------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inherit`                 | string                     | `core`  | Starting template for the environment:<br>`core` (`HOME`, `PATH`, `USER`, …), `all` (clone full parent env), or `none` (start empty).           |
+| `ignore_default_excludes` | boolean                    | `false` | When `false`, Codex removes any var whose **name** contains `KEY`, `SECRET`, or `TOKEN` (case-insensitive) before other rules run.              |
+| `exclude`                 | array&lt;string&gt;        | `[]`    | Case-insensitive glob patterns to drop after the default filter.<br>Examples: `"AWS_*"`, `"AZURE_*"`.                                           |
+| `set`                     | table&lt;string,string&gt; | `{}`    | Explicit key/value overrides or additions – always win over inherited values.                                                                   |
+| `include_only`            | array&lt;string&gt;        | `[]`    | If non-empty, a whitelist of patterns; only variables that match _one_ pattern survive the final step. (Generally used with `inherit = "all"`.) |
+
+The patterns are **glob style**, not full regular expressions: `*` matches any
+number of characters, `?` matches exactly one, and character classes like
+`[A-Z]`/`[^0-9]` are supported. Matching is always **case-insensitive**. This
+syntax is documented in code as `EnvironmentVariablePattern` (see
+`core/src/config_types.rs`).
+
+If you just need a clean slate with a few custom entries you can write:
+
+```toml
+[shell_environment_policy]
+inherit = "none"
+set = { PATH = "/usr/bin", MY_FLAG = "1" }
+```
+
+Currently, `CODEX_SANDBOX_NETWORK_DISABLED=1` is also added to the environment, assuming network is disabled. This is not configurable.
+
 ### notify
 
 Specify a program that will be executed to get notified about events generated by Codex. Note that the program will receive the notification argument as a string of JSON, e.g.:

codex-rs/README.md

@@ -3,27 +3,29 @@
 //! On Linux the command is executed inside a Landlock + seccomp sandbox by
 //! calling the low-level `exec_linux` helper from `codex_core::linux`.
 
+use codex_core::config::Config;
 use codex_core::exec::StdioPolicy;
 use codex_core::exec::spawn_child_sync;
 use codex_core::exec_linux::apply_sandbox_policy_to_current_thread;
-use codex_core::protocol::SandboxPolicy;
 use std::process::ExitStatus;
 
 use crate::exit_status::handle_exit_status;
 
 /// Execute `command` in a Linux sandbox (Landlock + seccomp) the way Codex
 /// would.
-pub fn run_landlock(command: Vec<String>, sandbox_policy: SandboxPolicy) -> anyhow::Result<()> {
+pub fn run_landlock(command: Vec<String>, config: &Config) -> anyhow::Result<()> {
     if command.is_empty() {
         anyhow::bail!("command args are empty");
     }
 
     // Spawn a new thread and apply the sandbox policies there.
+    let env = codex_core::exec_env::create_env(&config.shell_environment_policy);
+    let sandbox_policy = config.sandbox_policy.clone();
     let handle = std::thread::spawn(move || -> anyhow::Result<ExitStatus> {
         let cwd = std::env::current_dir()?;
 
         apply_sandbox_policy_to_current_thread(&sandbox_policy, &cwd)?;
-        let mut child = spawn_child_sync(command, cwd, &sandbox_policy, StdioPolicy::Inherit)?;
+        let mut child = spawn_child_sync(command, cwd, &sandbox_policy, StdioPolicy::Inherit, env)?;
         let status = child.wait()?;
         Ok(status)
     });

codex-rs/cli/src/landlock.rs

@@ -10,13 +10,19 @@ fn main() -> anyhow::Result<()> {
     use codex_cli::LandlockCommand;
     use codex_cli::create_sandbox_policy;
     use codex_cli::landlock;
+    use codex_core::config::Config;
+    use codex_core::config::ConfigOverrides;
 
     let LandlockCommand {
         full_auto,
         sandbox,
         command,
     } = LandlockCommand::parse();
     let sandbox_policy = create_sandbox_policy(full_auto, sandbox);
-    landlock::run_landlock(command, sandbox_policy)?;
+    let config = Config::load_with_overrides(ConfigOverrides {
+        sandbox_policy: Some(sandbox_policy),
+        ..Default::default()
+    })?;
+    landlock::run_landlock(command, &config)?;
     Ok(())
 }

codex-rs/cli/src/linux-sandbox/main.rs

@@ -4,6 +4,8 @@ use codex_cli::SeatbeltCommand;
 use codex_cli::create_sandbox_policy;
 use codex_cli::proto;
 use codex_cli::seatbelt;
+use codex_core::config::Config;
+use codex_core::config::ConfigOverrides;
 use codex_exec::Cli as ExecCli;
 use codex_tui::Cli as TuiCli;
 
@@ -86,7 +88,11 @@ async fn main() -> anyhow::Result<()> {
                 full_auto,
             }) => {
                 let sandbox_policy = create_sandbox_policy(full_auto, sandbox);
-                seatbelt::run_seatbelt(command, sandbox_policy).await?;
+                let config = Config::load_with_overrides(ConfigOverrides {
+                    sandbox_policy: Some(sandbox_policy),
+                    ..Default::default()
+                })?;
+                seatbelt::run_seatbelt(command, &config).await?;
             }
             #[cfg(unix)]
             DebugCommand::Landlock(LandlockCommand {
@@ -95,7 +101,11 @@ async fn main() -> anyhow::Result<()> {
                 full_auto,
             }) => {
                 let sandbox_policy = create_sandbox_policy(full_auto, sandbox);
-                codex_cli::landlock::run_landlock(command, sandbox_policy)?;
+                let config = Config::load_with_overrides(ConfigOverrides {
+                    sandbox_policy: Some(sandbox_policy),
+                    ..Default::default()
+                })?;
+                codex_cli::landlock::run_landlock(command, &config)?;
             }
             #[cfg(not(unix))]
             DebugCommand::Landlock(_) => {

codex-rs/cli/src/main.rs

@@ -1,16 +1,21 @@
+use codex_core::config::Config;
 use codex_core::exec::StdioPolicy;
 use codex_core::exec::spawn_command_under_seatbelt;
-use codex_core::protocol::SandboxPolicy;
+use codex_core::exec_env::create_env;
 
 use crate::exit_status::handle_exit_status;
 
-pub async fn run_seatbelt(
-    command: Vec<String>,
-    sandbox_policy: SandboxPolicy,
-) -> anyhow::Result<()> {
+pub async fn run_seatbelt(command: Vec<String>, config: &Config) -> anyhow::Result<()> {
     let cwd = std::env::current_dir()?;
-    let mut child =
-        spawn_command_under_seatbelt(command, &sandbox_policy, cwd, StdioPolicy::Inherit).await?;
+    let env = create_env(&config.shell_environment_policy);
+    let mut child = spawn_command_under_seatbelt(
+        command,
+        &config.sandbox_policy,
+        cwd,
+        StdioPolicy::Inherit,
+        env,
+    )
+    .await?;
     let status = child.wait().await?;
     handle_exit_status(status);
 }

codex-rs/cli/src/seatbelt.rs

@@ -46,6 +46,7 @@ tracing = { version = "0.1.41", features = ["log"] }
 tree-sitter = "0.25.3"
 tree-sitter-bash = "0.23.3"
 uuid = { version = "1", features = ["serde", "v4"] }
+wildmatch = "2.4.0"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 libc = "0.2.172"
@@ -58,6 +59,7 @@ openssl-sys = { version = "*", features = ["vendored"] }
 
 [dev-dependencies]
 assert_cmd = "2"
+maplit = "1.0.2"
 predicates = "3"
 pretty_assertions = "1.4.1"
 tempfile = "3"

codex-rs/core/Cargo.toml

@@ -37,6 +37,7 @@ use crate::client::ModelClient;
 use crate::client_common::Prompt;
 use crate::client_common::ResponseEvent;
 use crate::config::Config;
+use crate::config_types::ShellEnvironmentPolicy;
 use crate::conversation_history::ConversationHistory;
 use crate::error::CodexErr;
 use crate::error::Result as CodexResult;
@@ -45,6 +46,7 @@ use crate::exec::ExecParams;
 use crate::exec::ExecToolCallOutput;
 use crate::exec::SandboxType;
 use crate::exec::process_exec_tool_call;
+use crate::exec_env::create_env;
 use crate::flags::OPENAI_STREAM_MAX_RETRIES;
 use crate::mcp_connection_manager::McpConnectionManager;
 use crate::mcp_connection_manager::try_parse_fully_qualified_tool_name;
@@ -171,6 +173,7 @@ pub(crate) struct Session {
     instructions: Option<String>,
     approval_policy: AskForApproval,
     sandbox_policy: SandboxPolicy,
+    shell_environment_policy: ShellEnvironmentPolicy,
     writable_roots: Mutex<Vec<PathBuf>>,
 
     /// Manager for external MCP servers/tools.
@@ -634,6 +637,7 @@ async fn submission_loop(
                     instructions,
                     approval_policy,
                     sandbox_policy,
+                    shell_environment_policy: config.shell_environment_policy.clone(),
                     cwd,
                     writable_roots,
                     mcp_connection_manager,
@@ -1124,6 +1128,7 @@ fn to_exec_params(params: ShellToolCallParams, sess: &Session) -> ExecParams {
         command: params.command,
         cwd: sess.resolve_path(params.workdir.clone()),
         timeout_ms: params.timeout_ms,
+        env: create_env(&sess.shell_environment_policy),
     }
 }
 

codex-rs/core/src/codex.rs

@@ -1,6 +1,8 @@
 use crate::config_profile::ConfigProfile;
 use crate::config_types::History;
 use crate::config_types::McpServerConfig;
+use crate::config_types::ShellEnvironmentPolicy;
+use crate::config_types::ShellEnvironmentPolicyToml;
 use crate::config_types::Tui;
 use crate::config_types::UriBasedFileOpener;
 use crate::flags::OPENAI_DEFAULT_MODEL;
@@ -37,6 +39,8 @@ pub struct Config {
 
     pub sandbox_policy: SandboxPolicy,
 
+    pub shell_environment_policy: ShellEnvironmentPolicy,
+
     /// Disable server-side response storage (sends the full conversation
     /// context with every request). Currently necessary for OpenAI customers
     /// who have opted into Zero Data Retention (ZDR).
@@ -108,6 +112,9 @@ pub struct ConfigToml {
     /// Default approval policy for executing commands.
     pub approval_policy: Option<AskForApproval>,
 
+    #[serde(default)]
+    pub shell_environment_policy: ShellEnvironmentPolicyToml,
+
     // The `default` attribute ensures that the field is treated as `None` when
     // the key is omitted from the TOML. Without it, Serde treats the field as
     // required because we supply a custom deserializer.
@@ -302,6 +309,8 @@ impl Config {
             })?
             .clone();
 
+        let shell_environment_policy = cfg.shell_environment_policy.into();
+
         let resolved_cwd = {
             use std::env;
 
@@ -336,6 +345,7 @@ impl Config {
                 .or(cfg.approval_policy)
                 .unwrap_or_else(AskForApproval::default),
             sandbox_policy,
+            shell_environment_policy,
             disable_response_storage: disable_response_storage
                 .or(config_profile.disable_response_storage)
                 .or(cfg.disable_response_storage)
@@ -677,6 +687,7 @@ disable_response_storage = true
                 model_provider: fixture.openai_provider.clone(),
                 approval_policy: AskForApproval::Never,
                 sandbox_policy: SandboxPolicy::new_read_only_policy(),
+                shell_environment_policy: ShellEnvironmentPolicy::default(),
                 disable_response_storage: false,
                 instructions: None,
                 notify: None,
@@ -714,6 +725,7 @@ disable_response_storage = true
             model_provider: fixture.openai_chat_completions_provider.clone(),
             approval_policy: AskForApproval::UnlessAllowListed,
             sandbox_policy: SandboxPolicy::new_read_only_policy(),
+            shell_environment_policy: ShellEnvironmentPolicy::default(),
             disable_response_storage: false,
             instructions: None,
             notify: None,
@@ -766,6 +778,7 @@ disable_response_storage = true
             model_provider: fixture.openai_provider.clone(),
             approval_policy: AskForApproval::OnFailure,
             sandbox_policy: SandboxPolicy::new_read_only_policy(),
+            shell_environment_policy: ShellEnvironmentPolicy::default(),
             disable_response_storage: true,
             instructions: None,
             notify: None,