Shell Command Execution

As of 0.9.11 the ShellAccess toolset is no longer available. The shell_command tool is a now a system-level tool which can be enabled using a session configuration property documented here

shell_command

Executes one of the allowed shell commands within the current project’s root directory and returns the shell command’s output.

Heads up! The tool tries to err on the side of caution and detect and prompt you for confirmation even when you’ve approved commands but built-in (and custom) restricted strings are detected. Regardless, you and only you are responsible for the outcome of any commands run via this tool.

Parameters

• command (String, required): The shell command(s) to execute. Multiple commands can be supplied separated by supported delimiters.

Tool Settings

Settings for shell_command can be specified in the config file under the tool_settings: section:

tool_settings:
  shell_command:
    SETTING: VALUE

The following settings are available:

• allowed_commands

  • An array of executable names that are permitted.
  • If unset, falls back to the ENKAIDU_ALLOWED_EXECUTABLES environment variable (space‑separated).
  • Defaults to ls cat grep whoami file wc find when not set.

• approved_commands

  • An array of executables that can run without user confirmation.
  • If not set, falls back to the ENKAIDU_APPROVED_EXECUTABLES environment variable (space‑separated).
  • Defaults to an empty list.

• restricted_terms

  • Additional strings that, when present anywhere in the command, require user confirmation
  • If not set, checks ENKAIDU_RESTRICTED_TERMS environment variable or a config entry.
  • The following OS‑specific terms are always included (checking is case insensitive):
    • Windows: RM, DEL, EVAL, FOR, --EXPRESSION, -E , -E=, |, ;
    • Unix: RM, EVAL, $(, --EXPRESSION, -E , -E=, |, ;

• network_allowed_commands New in 0.9.14

  • An array of commands that are allowed to run with network access when running inside the cordon.
  • Commands here are typically a subset of allowed_commands — a command must still be allowed to run at all. All other allowed commands run without network access.
  • Commands are matched by prefix, so you can allow a command broadly, then grant network access only when it is invoked with a particular subcommand (e.g. allow ops, but grant network only to ops test).
  • The cordon policy’s allow_network setting must be true for this setting to have any effect. When allow_network is false (the default), nothing running in the cordon gets network access.
  • Example:

    tool_settings:
      shell_command:
        allowed_commands: ["ops", "ruby"]
        # Only "ops test" runs with network; other "ops" subcommands won't.
        network_allowed_commands: ["ops test"]

• execute_through_shell New in 0.9.11 is false by default.

  • When enabled, this allows commands that use redirection, piping and more in shell commands.

• skip_confirm_with_cordon New in 0.9.11 is false by default.

  • Dangerous without caution.
  • If set to true and shell command execution is cordoned (i.e. not unsafe), user confirmation is skipped for restricted terms and allowed-but-not-approved commands.
  • Logs a warning if required confirmation is skipped.

Notes

• Forbidden strings:

  • On Unix the characters &, <, >, .. are forbidden.
  • On Windows & is allowed (it separates commands), while .., < and > remain forbidden.

• Multi‑command splitting:

  • An internal platform-specific regex is used to split commands in case there are multiple
  • Each split command is checked for safety

• Safety checks:

  • Commands must start with one of the allowed executables (exact match or followed by a space).
  • It must not contain any forbidden substrings (.., <, >, & on Unix).
  • Commands that include any restricted terms or that are not approved require user confirmation before execution.
  • The tool raises PermissionError if the user denies the confirmation, and SafetyError for unsafe commands.

• Network inside the cordon New in 0.9.14:

  • Networking inside the cordon is still gated by the cordon policy’s allow_network flag — when it is false (the default) nothing run in the cordon gets network access.
  • When allow_network is true, network access is now granted per command: only commands that prefix-match an entry in network_allowed_commands run with network access; every other allowed command runs without it.