🔒 Python Sandbox Environment

A robust Python-based sandbox environment for executing untrusted code with comprehensive resource limits, process isolation, and real-time monitoring capabilities.

📋 Table of Contents

• Overview
• Features
• Architecture
• Directory Structure
• Installation
• Usage
• Configuration
• Monitoring & Analysis
• Security Features
• Examples
• Troubleshooting
• Contributing
• License

---

🎯 Overview

This sandbox environment provides a secure, isolated execution environment for running Python scripts with strict resource constraints. It implements multiple layers of security including process isolation, resource limits, file system restrictions, and comprehensive monitoring.

Key Capabilities

• Resource Control: CPU time and memory usage limits
• Process Isolation: Fork-based process separation
• File System Security: Chroot jail implementation
• Real-time Monitoring: Live CPU and memory tracking
• Persistent Logging: Timestamped execution logs
• Visual Analytics: Memory usage graphs and statistics

---

✨ Features

Core Features

✅ CPU Time Limiting

• Set maximum CPU execution time in seconds
• Automatic process termination on timeout
• Uses resource.setrlimit(RLIMIT_CPU)

✅ Memory Limiting

• Control maximum memory allocation (MB)
• Prevents memory exhaustion attacks
• Uses resource.setrlimit(RLIMIT_AS)

✅ Process Isolation

• Fork-based execution in child process
• Parent process monitoring and control
• Clean separation of execution contexts

✅ File System Isolation

• Chroot jail implementation
• Restricts file system access
• Optional --no-chroot mode for testing

✅ Real-time Monitoring

• Live CPU percentage tracking
• Memory usage monitoring (MB)
• 0.1-second polling interval

✅ Comprehensive Logging

• Timestamped log files (YYYYMMDD_HHMMSS)
• Detailed execution metrics
• Process lifecycle tracking
• Exit status recording

Analysis Tools

📊 Memory Visualization

• Generate PNG graphs of memory usage over time
• Track memory trends during execution
• Identify memory spikes and patterns

📈 Statistical Analysis

• Average CPU and memory usage
• Peak resource consumption
• Process duration metrics
• Visual ASCII charts

---

🏗️ Architecture

System Design

┌─────────────────────────────────────────────────────────────┐
│                    SANDBOX ENVIRONMENT                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────────┐         ┌─────────────────┐            │
│  │  Parent Process │◄────────┤  User Command   │            │
│  │   (Monitor)     │         └─────────────────┘            │
│  └────────┬────────┘                                         │
│           │                                                  │
│           │ fork()                                           │
│           ▼                                                  │
│  ┌────────────────────────────────────────┐                │
│  │        Child Process (Sandboxed)       │                │
│  ├────────────────────────────────────────┤                │
│  │  1. Set Resource Limits (CPU/Memory)   │                │
│  │  2. Apply Chroot Jail (Optional)       │                │
│  │  3. Execute User Code                  │                │
│  │  4. Report Status                      │                │
│  └────────────────────────────────────────┘                │
│           │                                                  │
│           │ Real-time Monitoring (psutil)                   │
│           ▼                                                  │
│  ┌────────────────────────────────────────┐                │
│  │      Monitoring & Logging System       │                │
│  ├────────────────────────────────────────┤                │
│  │  • CPU Usage Tracking                  │                │
│  │  • Memory Usage Tracking               │                │
│  │  • Timestamped Logging                 │                │
│  │  • Process State Management            │                │
│  └────────────────────────────────────────┘                │
│           │                                                  │
│           ▼                                                  │
│  ┌────────────────────────────────────────┐                │
│  │        Log Files & Reports              │                │
│  │  logs/sandbox_run_YYYYMMDD_HHMMSS.log  │                │
│  └────────────────────────────────────────┘                │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Execution Flow

User Command
     │
     ▼
Parse Arguments (--cpu, --mem, --no-chroot)
     │
     ▼
Fork Process
     ├─────────────────┐
     │                 │
     ▼                 ▼
Parent Process    Child Process
(Monitor)         (Execute)
     │                 │
     │                 ├─ Set CPU Limit
     │                 ├─ Set Memory Limit
     │                 ├─ Apply Chroot (optional)
     │                 ├─ Execute Code
     │                 └─ Exit with Status
     │
     ├─ Monitor CPU/Memory (0.1s intervals)
     ├─ Log Metrics
     ├─ Check Timeout
     └─ Wait for Child & Report

---

📁 Directory Structure

sandbox_project/
│
├── 📄 README.md                          # This file - Complete project documentation
├── 📄 SETUP_INSTRUCTIONS.md              # Detailed setup and installation guide
├── 📄 GITHUB_PUSH_INSTRUCTIONS.md        # Git and GitHub setup instructions
├── 📄 IMPLEMENTATION_STATUS.md           # Feature implementation status
├── 📄 requirements.txt                   # Python dependencies list
├── 📄 .gitignore                         # Git ignore configuration
│
├── 🔧 setup_sandbox.sh                   # Automated sandbox setup script
├── 🔧 setup_jail.sh                      # Chroot jail setup helper
├── 🔧 test_script.py                     # Sample test script (infinite loop)
│
├── 📂 src/                               # Main source code directory
│   ├── 📄 __init__.py                    # Package initialization
│   ├── 🐍 sandbox.py                     # Main sandbox implementation (with chroot)
│   │                                     #   • Resource limiting
│   │                                     #   • Process isolation
│   │                                     #   • Chroot jail support
│   │                                     #   • Real-time monitoring
│   │                                     #   • Logging system
│   │
│   └── 🐍 sandbox_test.py                # Test sandbox (optional chroot)
│                                         #   • --no-chroot flag support
│                                         #   • Testing without root privileges
│
├── 📂 tests/                             # Test directory
│   └── 📄 __init__.py                    # Test package initialization
│
├── 📂 docs/                              # Documentation directory
│   ├── 📄 logging_visualization.md       # Logging system documentation
│   │                                     #   • Log format specification
│   │                                     #   • Visualization guide
│   │                                     #   • Analysis tools usage
│   │
│   └── 📄 setup_guide.md                 # Detailed setup guide
│                                         #   • System requirements
│                                         #   • Installation steps
│                                         #   • Configuration options
│
├── 📂 logs/                              # Execution logs (auto-generated, gitignored)
│   └── sandbox_run_YYYYMMDD_HHMMSS.log  # Timestamped execution logs
│                                         #   Format: sandbox_run_20251011_143022.log
│
├── 📂 sandbox_root/                      # Chroot jail directory (gitignored)
│   ├── python3                          # Python binary (copied)
│   ├── test_script.py                   # Scripts to execute
│   └── (additional binaries/libs)       # Required libraries
│
├── 📂 venv/                              # Virtual environment (gitignored)
│   └── (Python packages)                # Isolated dependencies
│
├── 🔍 visualize_log.py                   # Memory usage graph generator
│                                         #   • Parses log files
│                                         #   • Creates PNG graphs
│                                         #   • Shows memory trends
│
└── 📊 analyze_log.py                     # Log analysis and statistics tool
                                          #   • CPU/Memory statistics
                                          #   • Peak usage detection
                                          #   • ASCII chart visualization

Key Files Description

File	Purpose	Key Functions
src/sandbox.py	Main sandbox implementation	Resource limits, process isolation, chroot jail, monitoring
src/sandbox_test.py	Test version with optional chroot	Same as sandbox.py + --no-chroot flag
visualize_log.py	Memory usage visualization	Parses logs, generates graphs (PNG)
analyze_log.py	Log analysis tool	Statistics, peak detection, ASCII charts
setup_jail.sh	Chroot setup automation	Creates jail, copies binaries
test_script.py	Sample test script	Infinite loop for testing limits
requirements.txt	Python dependencies	psutil, matplotlib, etc.

---

🚀 Installation

Prerequisites

• Python: 3.12 or higher
• Operating System: Linux (Ubuntu/Debian recommended)
• Privileges: Root access required for chroot functionality
• Disk Space: ~500MB (including dependencies)

System Requirements

# Check Python version
python3 --version  # Should be 3.12+

# Required system tools
sudo apt update
sudo apt install python3 python3-pip python3-venv git

Quick Installation

# 1. Clone the repository
git clone git@github.com:Divyansh-9/sandbox-project.git
cd sandbox-project

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Linux/Mac
# OR
venv\Scripts\activate     # On Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Create necessary directories
mkdir -p logs sandbox_root

# 5. (Optional) Setup chroot jail
bash setup_jail.sh

Dependencies

The project requires the following Python packages:

psutil==7.1.0        # Process and system monitoring
matplotlib==3.10.6   # Graph generation
numpy==2.2.1         # Numerical operations

---

💻 Usage

Basic Usage

# Activate virtual environment first
source venv/bin/activate

# Run sandbox with default limits
python3 src/sandbox.py --cpu 5 --mem 50 python3 test_script.py

# Run with custom limits
python3 src/sandbox.py --cpu 10 --mem 100 python3 your_script.py

Command-Line Arguments

Usage: python3 src/sandbox.py [OPTIONS] COMMAND

Options:
  --cpu SECONDS     CPU time limit in seconds (default: 5)
  --mem MEGABYTES   Memory limit in megabytes (default: 50)
  --no-chroot       Disable chroot isolation (for testing)
  
Arguments:
  COMMAND          The command to execute in the sandbox
                   Example: python3 script.py

Examples:
  python3 src/sandbox.py --cpu 5 --mem 50 python3 test_script.py
  python3 src/sandbox_test.py --cpu 10 --mem 100 --no-chroot python3 script.py

Running Without Root (Testing Mode)

# Use sandbox_test.py with --no-chroot flag
python3 src/sandbox_test.py --cpu 5 --mem 50 --no-chroot python3 test_script.py

---

⚙️ Configuration

Resource Limits

CPU Limit

# Set CPU time limit (in seconds)
--cpu 5   # Process will be terminated after 5 seconds of CPU time

How it works:

• Uses resource.RLIMIT_CPU
• Kills process when CPU time exceeds limit
• Timeout protection adds 2 extra seconds for graceful shutdown

Memory Limit

# Set memory limit (in megabytes)
--mem 50  # Process can use maximum 50MB of memory

How it works:

• Uses resource.RLIMIT_AS (address space)
• Prevents memory allocation beyond limit
• Protects against memory exhaustion attacks

Logging Configuration

Logs are automatically created in the logs/ directory with the format:

logs/sandbox_run_YYYYMMDD_HHMMSS.log

Log Contents:

• Start timestamp
• PID of sandboxed process
• Real-time CPU and memory metrics
• Exit status and signal information
• End timestamp

---

📊 Monitoring & Analysis

Memory Visualization

Generate memory usage graphs from log files:

# Generate graph for latest log
python3 visualize_log.py logs/sandbox_run_20251011_143022.log

# Output: memory_usage_graph.png

Statistical Analysis

Analyze logs with detailed statistics:

# Analyze a specific log file
python3 analyze_log.py logs/sandbox_run_20251011_143022.log

---

🔐 Security Features

Multi-Layer Security

┌─────────────────────────────────────┐
│     Security Layer 1: Process       │
│         Isolation (fork)            │
├─────────────────────────────────────┤
│   ✓ Separate process space          │
│   ✓ Independent execution context   │
│   ✓ Parent-child communication      │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│    Security Layer 2: Resource       │
│           Limiting                  │
├─────────────────────────────────────┤
│   ✓ CPU time restrictions           │
│   ✓ Memory allocation limits        │
│   ✓ Automatic termination           │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│    Security Layer 3: File System    │
│         Isolation (chroot)          │
├─────────────────────────────────────┤
│   ✓ Restricted file access          │
│   ✓ Isolated directory tree         │
│   ✓ Limited system exposure         │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│    Security Layer 4: Monitoring     │
│         & Logging                   │
├─────────────────────────────────────┤
│   ✓ Real-time behavior tracking     │
│   ✓ Audit trail creation            │
│   ✓ Anomaly detection capability    │
└─────────────────────────────────────┘

Limitations & Warnings

⚠️ Important Security Notes:

• This sandbox is NOT a complete security solution
• It provides defense in depth but shouldn't be the only security measure
• Chroot can be escaped by privileged processes
• Resource limits can be bypassed in some scenarios
• Always run untrusted code in additional isolation (VMs, containers)

---

📚 Examples

Example 1: Basic CPU-Intensive Task

# cpu_test.py
while True:
    pass  # Infinite CPU loop

# Run with 5-second CPU limit
python3 src/sandbox.py --cpu 5 --mem 50 python3 cpu_test.py

# Expected: Process killed due to timeout

Example 2: Normal Execution

# normal_script.py
import time

for i in range(5):
    print(f"Count: {i}")
    time.sleep(1)
print("Completed successfully!")

# Run with adequate limits
python3 src/sandbox.py --cpu 10 --mem 100 python3 normal_script.py

---

🐛 Troubleshooting

Common Issues

1. Permission Denied Error

Solution:

# Use sudo for chroot operations
sudo python3 src/sandbox.py --cpu 5 --mem 50 python3 script.py

# OR use --no-chroot flag
python3 src/sandbox_test.py --cpu 5 --mem 50 --no-chroot python3 script.py

2. ModuleNotFoundError

Solution:

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Chroot: No such file or directory

Solution:

# Setup chroot jail
bash setup_jail.sh

# OR manually copy Python binary
sudo cp /usr/bin/python3 sandbox_root/

---

�� Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📜 License

This project is licensed under the MIT License.

---

👥 Authors

• Divyansh - Initial work - Divyansh-9

---

📞 Contact

• GitHub: @Divyansh-9
• Project Link: https://github.com/Divyansh-9/sandbox-project

---

🔄 Version History

• v1.0.0 (2025-10-11)
  • Initial release
  • Core sandbox functionality
  • Resource limiting (CPU, Memory)
  • Process isolation
  • Chroot jail support
  • Real-time monitoring
  • Logging system
  • Analysis tools

---

📌 Quick Reference Card

# INSTALLATION
git clone git@github.com:Divyansh-9/sandbox-project.git
cd sandbox-project
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# BASIC USAGE
python3 src/sandbox.py --cpu 5 --mem 50 python3 script.py

# WITHOUT ROOT
python3 src/sandbox_test.py --cpu 5 --mem 50 --no-chroot python3 script.py

# ANALYSIS
python3 analyze_log.py logs/sandbox_run_*.log
python3 visualize_log.py logs/sandbox_run_*.log

---

⬆ Back to Top

Made with ❤️ for secure code execution