shell¶

Secure Shell Command Execution Module.

This module provides a secure way to execute shell commands with enforced security restrictions. It includes path permission checking, command validation, and structured result handling.

The security features include: - Path-based access control for file operations - Command timeout enforcement - Structured output for both successful and failed commands - Protection against dangerous commands

Examples

>>> from haive.tools.toolkits.dev.shell.shell import SecureShellExecutor
>>> shell = SecureShellExecutor()
>>> result = shell.run('ls -la')
>>> if result.success:
...     print(result.stdout)
... else:
...     print(f"Error: {result.error}")

Classes¶

`CommandExecutionResult`	Represents the result of a shell command execution.
`SecureShellExecutor`	Shell command executor with enforced security restrictions.

Module Contents¶

class shell.CommandExecutionResult(/, **data: Any)¶

Bases: pydantic.BaseModel

Represents the result of a shell command execution.

This model provides a structured way to capture and access the results of shell command execution, including success status, outputs, and any error information.

success¶

Indicates if the command executed successfully.

Type:: bool

command¶

The original command that was executed.

Type:: str

stdout¶

Standard output captured from the command execution.

Type:: str

stderr¶

Standard error output captured from the command execution.

Type:: str

exit_code¶

The exit code returned by the command (0 typically means success).

Type:: int

error¶

Human-readable error message if the command failed.

Type:: str

command: str = None¶

error: str = None¶

exit_code: int = None¶

stderr: str = None¶

stdout: str = None¶

success: bool = None¶

class shell.SecureShellExecutor¶

Shell command executor with enforced security restrictions.

This class provides a secure way to execute shell commands with path-based permission checking, command validation, and structured result handling. It uses the PermissionsManager to enforce read/write access control on paths.

permissions_manager¶

Manager that handles path permissions.

Type:: PermissionsManager

run(command: str, timeout: int = 30) → CommandExecutionResult¶

Execute a command with security enforcement.

Runs the provided shell command with security checks for file access permissions and command timeouts. Command execution is handled safely with proper error capture.

Parameters:

command (str) – The shell command to execute.
timeout (int, optional) – Maximum execution time in seconds. Defaults to 30.

Returns:

Structured result with execution details.

Return type:

CommandExecutionResult

Raises:

No exceptions are raised; all errors are captured in the result object. –

permissions_manager¶