Shell Operations

The shell operations module provides utilities for executing shell commands, managing processes, and working with the command line interface.

Module Overview

Secure shell command execution utilities.

SECURITY NOTE: This module previously contained critical vulnerabilities. All shell execution now includes proper validation and sanitization.

siege_utilities.files.shell.run_subprocess(command_list, allow_list=None, timeout=30)

Run a shell command as a subprocess with security validation.

SECURITY: This function now validates all commands against a whitelist and blocks dangerous operations. Only read-only commands are allowed by default.

Parameters:

• command_list (str | List[str]) – The command to run, as a list or string

• allow_list (set | None) – Optional custom whitelist of allowed commands

• timeout (int) – Command timeout in seconds (default: 30)

Returns:

The command output (stdout if successful, stderr if failed)

Raises:

• SecurityError – If command fails security validation

• ValueError – If command is invalid

• subprocess.TimeoutExpired – If command times out

Return type:

str

Example

>>> output = run_subprocess("ls -la")
>>> output = run_subprocess("rm -rf /")

Security Changes:

• Previously used shell=True with no validation (CRITICAL VULNERABILITY)

• Now validates all commands against whitelist

• Blocks command injection, path traversal, sensitive file access

• Uses shell=False by default for safety

siege_utilities.files.shell.validate_command_safety(command, allow_list=None)

Validate that a command is safe to execute.

Parameters:

• command (str | List[str]) – Command string or list to validate

• allow_list (set | None) – Optional custom whitelist of allowed commands

Returns:

Validated command as list of strings

Raises:

• SecurityError – If command contains forbidden elements

• ValueError – If command is invalid

Return type:

List[str]

Security checks: - Validates command against whitelist - Blocks command injection characters (;, &, |, $, `, newlines) - Blocks path traversal attempts - Blocks access to sensitive system files

exception siege_utilities.files.shell.SecurityError

Bases: Exception

Raised when a security violation is detected.

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.