Shell Operations
The shell operations module provides utilities for executing shell commands, managing processes, and working with the command line interface.
Module Overview
Execute argv commands with an allow-list and conservative argument checks.
These checks are a guardrail, not a sandbox or a guarantee of read-only behavior.
- siege_utilities.files.shell.run_subprocess(command_list, allow_list=None, timeout=30)[source]
Run an argv command after applying validate_command_safety.
Execution uses shell=False, so shell syntax is not interpreted. Validation restricts command names and selected argument patterns; it does not promise read-only behavior or exhaustive validation of each program’s options.
- Parameters:
- Returns:
The command output (stdout if successful, stderr if failed, with an error logged for a nonzero exit status). Arguments and output are omitted from logs. Raised diagnostics omit command details and captured output, which may contain credentials.
- Return type:
- Raises:
SecurityError – If the command fails validation.
ValueError – If the command is invalid.
subprocess.TimeoutExpired – If the command times out.
OSError – If the command cannot be executed.
Examples
>>> output = run_subprocess("ls -la")
- siege_utilities.files.shell.validate_command_safety(command, allow_list=None, cwd=None)[source]
Apply command-name, character, traversal, and known sensitive-path checks.
Operands and attached option values are checked using literal, expanded, normalized and resolved path forms relative to cwd, but returned unchanged. Process-relative /proc links (/proc/<pid>/cwd, root, fd, task, map_files) are rejected because they resolve differently in the child. This is not a filesystem sandbox: command options, recursive reads and filesystem changes after validation are not controlled. A custom allow-list delegates command semantics to the caller.
- Parameters:
command (str or list[str]) – Command string or argv list to validate.
allow_list (set, optional) – Custom allowed command names, replacing the default allow-list.
cwd (str or os.PathLike, optional) – Working directory used for execution and relative path checks. Defaults to the current process directory.
- Returns:
Validated argv with argument text unchanged.
- Return type:
- Raises:
SecurityError – If the command contains forbidden elements.
ValueError – If the command is empty or has invalid quoting.
Notes
Validates command against whitelist
Rejects selected shell metacharacters, including redirection characters
Rejects ‘..’ path components
Rejects known sensitive paths and .ssh path components, including aliases
Functions
Usage Examples
Basic command execution:
Shell command execution:
Background process management:
Complex shell operations:
Error handling:
Unit Tests
The shell operations module has comprehensive test coverage:
Test Results: All shell operation tests pass successfully with comprehensive coverage.