diff options
Diffstat (limited to 'docs/tools/shell.md')
| -rw-r--r-- | docs/tools/shell.md | 77 |
1 files changed, 26 insertions, 51 deletions
diff --git a/docs/tools/shell.md b/docs/tools/shell.md index cc65b013..021cede1 100644 --- a/docs/tools/shell.md +++ b/docs/tools/shell.md @@ -64,96 +64,71 @@ run_shell_command(command="npm run dev &", description="Start development server 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. +- `coreTools`: To restrict `run_shell_command` to a specific set of commands, add entries to the `coreTools` list in the format `run_shell_command(<command>)`. For example, `"coreTools": ["run_shell_command(git)"]` will only allow `git` commands. Including the generic `run_shell_command` acts as a wildcard, allowing any command not explicitly blocked. +- `excludeTools`: To block specific commands, add entries to the `excludeTools` list in the format `run_shell_command(<command>)`. For example, `"excludeTools": ["run_shell_command(rm)"]` will block `rm` commands. -### 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: +The validation logic is designed to be secure and flexible: -```json -{ - "excludeTools": ["ShellTool(rm -rf /)", "ShellTool(npm install)"] -} -``` +1. **Command Chaining Disabled**: The tool automatically splits commands chained with `&&`, `||`, or `;` and validates each part separately. If any part of the chain is disallowed, the entire command is blocked. +2. **Prefix Matching**: The tool uses prefix matching. For example, if you allow `git`, you can run `git status` or `git log`. +3. **Blocklist Precedence**: The `excludeTools` list is always checked first. If a command matches a blocked prefix, it will be denied, even if it also matches an allowed prefix in `coreTools`. -- `rm -rf /`: Blocked -- `npm install`: Blocked -- `ls -l`: Allowed +### Command Restriction Examples -**Allow all commands** +**Allow only specific command prefixes** -To allow any command to be executed, you can use the `ShellTool` wildcard in `coreTools`: +To allow only `git` and `npm` commands, and block all others: ```json { - "coreTools": ["ShellTool"] + "coreTools": ["run_shell_command(git)", "run_shell_command(npm)"] } ``` -- `ls -l`: Allowed +- `git status`: Allowed - `npm install`: Allowed -- `any other command`: Allowed +- `ls -l`: Blocked -**Wildcard with specific allowed commands** +**Block specific command prefixes** -If you include the `ShellTool` wildcard along with specific commands, the wildcard takes precedence, and all commands are allowed. +To block `rm` and allow all other commands: ```json { - "coreTools": ["ShellTool", "ShellTool(ls -l)"] + "coreTools": ["run_shell_command"], + "excludeTools": ["run_shell_command(rm)"] } ``` -- `ls -l`: Allowed +- `rm -rf /`: Blocked +- `git status`: Allowed - `npm install`: Allowed -- `any other command`: Allowed -**Wildcard with a blocklist** +**Blocklist takes precedence** -You can use the `ShellTool` wildcard to allow all commands, while still blocking specific commands using `excludeTools`. +If a command prefix is in both `coreTools` and `excludeTools`, it will be blocked. ```json { - "coreTools": ["ShellTool"], - "excludeTools": ["ShellTool(rm -rf /)"] + "coreTools": ["run_shell_command(git)"], + "excludeTools": ["run_shell_command(git push)"] } ``` -- `rm -rf /`: Blocked -- `ls -l`: Allowed -- `npm install`: Allowed +- `git push origin main`: Blocked +- `git status`: Allowed **Block all shell commands** -To block all shell commands, you can add the `ShellTool` wildcard to `excludeTools`: +To block all shell commands, add the `run_shell_command` wildcard to `excludeTools`: ```json { - "excludeTools": ["ShellTool"] + "excludeTools": ["run_shell_command"] } ``` - `ls -l`: Blocked -- `npm install`: Blocked - `any other command`: Blocked ## Security Note for `excludeTools` |