Hands Trapezium

A secure shell execution context manager for Python that provides controlled command execution with environment management, command allowlisting, and Docker integration.

🚀 Features

• 🔒 Secure Command Execution: Allowlist-based command execution for enhanced security
• 🌍 Environment Management: Load and manage environment variables from files
• 🐳 Docker Integration: Execute commands inside Docker containers seamlessly
• 🎯 Context Management: Clean global function injection for script-like usage
• ✨ Rich Output: Beautiful console output using Rich library
• 🔍 Type Safety: Full type hints for better development experience
• ⚡ Easy to Use: Both object-oriented and functional interfaces

📦 Installation

pip install hands-trapezium

🏃‍♂️ Quick Start

Basic Usage

from hands_trapezium import ShellContext

# Basic usage with context manager
with ShellContext() as shell:
    # Allow specific commands for security
    shell.allow("echo")
    shell.allow("ls")
    
    # Execute commands securely
    result = shell.run("echo 'Hello, World!'")
    print(result.stdout)  # Output: Hello, World!
    
    # Change directory
    shell.cd("/tmp")
    
    # List files
    result = shell.run("ls -la")
    print(result.stdout)

Script-Style Usage

from hands_trapezium import ShellContext

# Use global functions for script-like experience
with ShellContext():
    # Functions are available globally within the context
    allow("git")
    allow("echo")
    
    cd("/path/to/project")
    run("git status")
    run("echo 'Build complete'")

Docker Integration

from hands_trapezium import ShellContext

with ShellContext() as shell:
    shell.allow("docker")
    
    # Execute commands in containers
    result = shell.run_in("mycontainer", "ls /app")
    
    # Check if containers are running
    shell.depends_on(["web", "database"])

Environment Management

from hands_trapezium import ShellContext

# Load environment from file
with ShellContext(env_file=".env") as shell:
    db_url = shell.get_env_var("DATABASE_URL")
    
    # Set additional variables
    shell.set_env_var("DEPLOYMENT", "production")

🛡️ Security Model

Hands Trapezium uses an allowlist-based security model:

1. No commands are allowed by default 🚫
2. Commands must be explicitly allowed using allow() ✅
3. Only the command name is checked, not arguments
4. Commands are validated to exist on the system

with ShellContext() as shell:
    # This will fail - command not allowed
    try:
        shell.run("rm -rf /")
    except PermissionError:
        print("Security working! 🛡️")
    
    # Allow the command first
    shell.allow("echo")
    shell.run("echo 'This works!'")  # ✅ This succeeds

📚 Documentation

For comprehensive documentation, visit: https://42sol-eu.github.io/hands_trapezium

🎯 Use Cases

• Deployment Scripts: Secure automation scripts with command validation
• CI/CD Pipelines: Controlled command execution in build processes
• System Administration: Safe system management scripts
• Docker Workflows: Seamless container command execution
• Development Tools: Build tools and development automation

🧪 Example: Deployment Script

#!/usr/bin/env python3
"""
Simple deployment script using Hands Trapezium
"""
from hands_trapezium import ShellContext

def deploy_application():
    with ShellContext(cwd="/app") as shell:
        # Allow required commands
        for cmd in ["git", "docker", "echo"]:
            shell.allow(cmd)
        
        try:
            # Deploy workflow
            shell.run("git pull origin main")
            shell.run("docker build -t myapp:latest .")
            shell.depends_on(["database", "redis"])  # Check dependencies
            shell.run("docker run -d --name myapp myapp:latest")
            
            print("✅ Deployment successful!")
            
        except Exception as e:
            print(f"❌ Deployment failed: {e}")
            return False
    
    return True

if __name__ == "__main__":
    deploy_application()

🔧 Requirements

• Python 3.11+
• Rich library for console output
• Click for CLI interface

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

git clone https://github.com/42sol-eu/hands_trapezium.git
cd hands_trapezium
pip install -e ".[dev]"

Running Tests

pytest

Building Documentation

mkdocs serve

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Andreas Häberle - 42sol-eu

🌟 Support

If you find this project helpful, please consider giving it a star on GitHub! ⭐

📝 Changelog

See CHANGELOG.md for a list of changes and version history.