Executor¶

The Executor module safely executes shell commands with safety validation.

Overview¶

The ShellExecutor class handles command execution, safety checks, and result parsing.

Location¶

alpha_bot/executor/shell.py

Class: ShellExecutor¶

Initialization¶

from alpha_bot.executor import ShellExecutor

executor = ShellExecutor(workdir="/path/to/dir")  # Optional workdir

Methods¶

`execute(command, timeout=30)`¶

Execute a shell command safely.

Parameters: - command (str): Shell command to execute - timeout (int): Maximum execution time in seconds

Returns: - dict: Execution result with stdout, stderr, exit_code

Example:

result = executor.execute("ls -la")
# Returns: {
#     "stdout": "...",
#     "stderr": "",
#     "exit_code": 0,
#     "success": True
# }

`is_dangerous(command)`¶

Check if a command is dangerous.

Parameters: - command (str): Command to check

Returns: - bool: True if dangerous

Example:

if executor.is_dangerous("rm -rf /"):
    print("Blocked!")
# Returns: True

`validate_command(command)`¶

Validate command syntax and safety.

Parameters: - command (str): Command to validate

Returns: - tuple: (is_valid, error_message)

Safety Features¶

Dangerous Pattern Blacklist¶

DANGEROUS_PATTERNS = [
    r'rm\s+-rf\s+/',           # Recursive deletion of root
    r'dd\s+if=/dev/zero',       # Disk wipe
    r'mkfs\.',                  # Format filesystem
    r':\(\)\{.*:\|:.*\}',      # Fork bomb
    r'wget.*\|\s*sh',          # Download and execute
    r'curl.*\|\s*bash',        # Download and execute
]

Validation Flow¶

Command Input
    │
    ├─> Blacklist Check
    │       │
    │       └─> Match? → BLOCK
    │
    ├─> Syntax Validation
    │       │
    │       └─> Invalid? → ERROR
    │
    ├─> AI Safety Analysis (optional)
    │       │
    │       └─> Dangerous? → WARN
    │
    └─> Execute

Usage Examples¶

Basic Execution¶

from alpha_bot.executor import ShellExecutor

executor = ShellExecutor()

# Execute command
result = executor.execute("echo 'Hello World'")

if result["success"]:
    print(result["stdout"])
else:
    print(f"Error: {result['stderr']}")

With Safety Check¶

command = "rm -rf /tmp/old_files"

# Check safety first
if executor.is_dangerous(command):
    print("⚠️ Dangerous command detected!")
    # Get user confirmation
else:
    result = executor.execute(command)

Custom Working Directory¶

executor = ShellExecutor(workdir="/var/www/myapp")

# All commands execute in /var/www/myapp
executor.execute("ls -la")

With Timeout¶

# Long-running command with 60s timeout
result = executor.execute(
    "python long_script.py",
    timeout=60
)

Error Handling¶

try:
    result = executor.execute("invalid-command")
    if not result["success"]:
        print(f"Command failed: {result['stderr']}")
except TimeoutError:
    print("Command timed out")
except PermissionError:
    print("Permission denied")