feat: allow command-specific restrictions for ShellTool (#2605)

1 files changed, 102 insertions, 0 deletions

diff --git a/docs/tools/shell.md b/docs/tools/shell.md
index ff6e574e..cc65b013 100644
--- a/docs/tools/shell.md
+++ b/docs/tools/shell.md
@@ -59,3 +59,105 @@ run_shell_command(command="npm run dev &", description="Start development server
 - **Interactive commands:** Avoid commands that require interactive user input, as this can cause the tool to hang. Use non-interactive flags if available (e.g., `npm init -y`).
 - **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to determine if a command executed successfully.
 - **Background processes:** When a command is run in the background with `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process.
+
+## Command Restrictions
+
+You can restrict the commands that can be executed by the `run_shell_command` tool by using the `coreTools` and `excludeTools` settings in your configuration file.
+
+- `coreTools`: If you want to restrict the `run_shell_command` tool to a specific set of commands, you can add entries to the `coreTools` list in the format `ShellTool(<command>)`. For example, `"coreTools": ["ShellTool(ls -l)"]` will only allow the `ls -l` command to be executed. If you include `ShellTool` as a general entry in the `coreTools` list, it will act as a wildcard and allow any command to be executed, even if you have other specific commands in the list.
+- `excludeTools`: If you want to block specific commands, you can add entries to the `excludeTools` list in the format `ShellTool(<command>)`. For example, `"excludeTools": ["ShellTool(rm -rf /)"]` will block the `rm -rf /` command.
+
+### Command Restriction Examples
+
+Here are some examples of how to use the `coreTools` and `excludeTools` settings to control which commands can be executed.
+
+**Allow only specific commands**
+
+To allow only `ls -l` and `git status`, and block all other commands:
+
+```json
+{
+  "coreTools": ["ShellTool(ls -l)", "ShellTool(git status)"]
+}
+```
+
+- `ls -l`: Allowed
+- `git status`: Allowed
+- `npm install`: Blocked
+
+**Block specific commands**
+
+To block `rm -rf /` and `npm install`, and allow all other commands:
+
+```json
+{
+  "excludeTools": ["ShellTool(rm -rf /)", "ShellTool(npm install)"]
+}
+```
+
+- `rm -rf /`: Blocked
+- `npm install`: Blocked
+- `ls -l`: Allowed
+
+**Allow all commands**
+
+To allow any command to be executed, you can use the `ShellTool` wildcard in `coreTools`:
+
+```json
+{
+  "coreTools": ["ShellTool"]
+}
+```
+
+- `ls -l`: Allowed
+- `npm install`: Allowed
+- `any other command`: Allowed
+
+**Wildcard with specific allowed commands**
+
+If you include the `ShellTool` wildcard along with specific commands, the wildcard takes precedence, and all commands are allowed.
+
+```json
+{
+  "coreTools": ["ShellTool", "ShellTool(ls -l)"]
+}
+```
+
+- `ls -l`: Allowed
+- `npm install`: Allowed
+- `any other command`: Allowed
+
+**Wildcard with a blocklist**
+
+You can use the `ShellTool` wildcard to allow all commands, while still blocking specific commands using `excludeTools`.
+
+```json
+{
+  "coreTools": ["ShellTool"],
+  "excludeTools": ["ShellTool(rm -rf /)"]
+}
+```
+
+- `rm -rf /`: Blocked
+- `ls -l`: Allowed
+- `npm install`: Allowed
+
+**Block all shell commands**
+
+To block all shell commands, you can add the `ShellTool` wildcard to `excludeTools`:
+
+```json
+{
+  "excludeTools": ["ShellTool"]
+}
+```
+
+- `ls -l`: Blocked
+- `npm install`: Blocked
+- `any other command`: Blocked
+
+## Security Note for `excludeTools`
+
+Command-specific restrictions in
+`excludeTools` for `run_shell_command` are based on simple string matching and can be easily bypassed. This feature is **not a security mechanism** and should not be relied upon to safely execute untrusted code. It is recommended to use `coreTools` to explicitly select commands
+that can be executed.