Safe Python Script Execution Service

A secure Flask-based service that safely executes Python scripts using nsjail for sandboxing. The service executes the user-provided script, calls its main() function, and returns only the return value of main() (as JSON) plus the script's stdout separately.

Features

• 🔒 Secure Execution: Uses nsjail for sandboxing and resource limits
• 📦 Lightweight Docker: Optimized container with minimal dependencies
• 🛡️ Input Validation: Comprehensive code validation and security checks
• 📚 Library Support: Includes pandas, numpy, and other essential libraries
• ⚡ Fast Deployment: Single docker run command to start the service
• 🔍 Health Monitoring: Built-in health checks and monitoring

Quick Start

Using Docker (Recommended)

1. Build the Docker image:

   docker build -t python-executor .

2. Run the service:

   docker run -p 8080:8080 python-executor

3. Test the service:

   curl -s -X POST \
     -H "Content-Type: application/json" \
     -d '{"script":"def main():\n    print(\"hello\")\n    return {\"ok\": True}\n"}' \
     http://localhost:8080/execute

Cloud Run Deployment

For Google Cloud Run deployment, replace the URL below with your Cloud Run service URL:

# Test with the deployed service
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"script":"def main():\n    return {\"message\": \"Hi from Cloud Run\"}\n"}' \
  https://python-executor-xxxxx-uc.a.run.app/execute

API Endpoints

POST /execute

Execute a Python script containing a main() function.

Request:

• Method: POST
• Content-Type: application/json
• Body: { "script": "def main(): ..." }

Response:

{
  "result": { "ok": true },
  "stdout": "any printed output from the script"
}

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "python-executor"
}

GET /

API documentation and service information.

Example Usage

1. Basic Data Processing Script

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"script":"import pandas as pd\nimport numpy as np\n\ndef main():\n    data = {\"numbers\": [1,2,3,4,5]}\n    df = pd.DataFrame(data)\n    print(\"Mean:\", float(np.mean(df[\"numbers\"])) )\n    return {\"count\": int(df.shape[0])}\n"}' \
  https://python-executor-xxxxx-uc.a.run.app/execute

2. Mathematical Operations

Create a file math_example.py:

import numpy as np

def main():
    # Generate random data
    data = np.random.randn(100)
    
    # Calculate statistics
    mean = np.mean(data)
    std = np.std(data)
    
    print(f"Mean: {mean:.4f}")
    print(f"Standard Deviation: {std:.4f}")
    
    # Find outliers
    outliers = data[np.abs(data) > 2 * std]
    print(f"Found {len(outliers)} outliers")

Execute:

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"script":"import numpy as np\n\ndef main():\n    data = np.random.randn(10)\n    print(\"std\", float(np.std(data)))\n    return {\"mean\": float(np.mean(data))}\n"}' \
  https://python-executor-xxxxx-uc.a.run.app/execute

3. Data Analysis Example

Create a file analysis.py:

import pandas as pd
import numpy as np

def main():
    # Create sample dataset
    np.random.seed(42)
    data = {
        'product': ['A', 'B', 'C', 'D', 'E'] * 20,
        'sales': np.random.randint(100, 1000, 100),
        'region': ['North', 'South', 'East', 'West'] * 25
    }
    
    df = pd.DataFrame(data)
    
    # Group by product and calculate statistics
    summary = df.groupby('product')['sales'].agg(['mean', 'std', 'count'])
    print("Product Sales Summary:")
    print(summary)
    
    # Find top performing products
    top_products = summary.sort_values('mean', ascending=False).head(3)
    print("\nTop 3 Products by Average Sales:")
    print(top_products)

Execute:

curl -X POST -F "file=@analysis.py" https://python-executor-xxxxx-uc.a.run.app/execute

Security Features

Sandboxing with nsjail

• Memory Limits: 128MB maximum memory usage
• CPU Limits: 1 second maximum execution time
• File System: Restricted access to /tmp only
• Process Limits: Maximum 10 processes
• Network Isolation: No network access

Code Validation

• Dangerous Function Detection: Blocks subprocess, networking (socket, urllib, http)
• Execution Prevention: Prevents eval(), exec(), compile() usage
• File Access Control: Blocks file operations via validation; nsjail enforces FS isolation
• Size Limits: Reasonable max script size

Input Validation

• Content-Type: application/json
• Body: { "script": "def main(): ..." }
• Content Length: Reasonable size limits
• Main Function Detection: Requires main() function presence

Supported Libraries

The service includes these pre-installed libraries:

• pandas: Data manipulation and analysis
• numpy: Numerical computing
• Standard Library: Most safe Python standard library modules

Error Handling

The service provides comprehensive error handling:

• Validation Errors: Clear messages for invalid input
• Execution Errors: Detailed error output in response
• Timeout Handling: Graceful timeout management
• Resource Limits: Clear messages when limits are exceeded

Development

Local Development

1. Install dependencies:

   pip install -r requirements.txt

2. Run locally:

   python app.py

3. Test with JSON script:

   curl -s -X POST -H "Content-Type: application/json" \
     -d '{"script":"def main():\n    return {\"ok\": True}\n"}' \
     http://localhost:8080/execute

Building for Production

# Build optimized image
docker build -t python-executor:latest .

# Run with production settings
docker run -p 8080:8080 --name python-executor python-executor:latest

Monitoring and Logging

• Health Checks: Built-in health monitoring
• Request Logging: Comprehensive request/response logging
• Error Tracking: Detailed error logging and stack traces
• Resource Monitoring: Memory and CPU usage tracking

Limitations

• Execution Time: Maximum ~10 seconds per request
• Memory Usage: Limited to ~256MB per execution
• Network Access: No network access from executed code
• File System: Read-only except for temporary working directory

Troubleshooting

Common Issues

1. "No main function found"

   • Ensure your script contains a def main(): function
   • Check function indentation and syntax

2. "Code validation failed"

   • Remove dangerous imports like subprocess, socket, urllib, http
   • Avoid using eval(), exec(), or compile()

3. "Execution timeout"

   • Optimize your code for faster execution
   • Reduce data processing complexity

4. "Memory limit exceeded"

   • Process data in smaller chunks
   • Use more memory-efficient algorithms

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

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

Support

For issues and questions:

• Create an issue in the repository
• Check the troubleshooting section
• Review the API documentation

---

Note: This service is designed for safe execution of trusted Python scripts. Always validate and sanitize input before processing in production environments.