brycewang-stanford/sandbox-execution-guide

Sandbox Execution Guide

A skill for setting up and using sandboxed code execution environments for research computing. Covers containerized execution, security considerations, resource management, and integration with research workflows.

Why Sandboxed Execution?

Research code often requires:

• Isolation from the host system for security
• Reproducible environments across machines
• Resource limits to prevent runaway computations
• Multi-language support (Python, R, Julia, MATLAB)

Docker-Based Sandboxes

Creating a Research Container

# Dockerfile for a reproducible research environment
FROM python:3.11-slim

# System dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    gfortran \
    libopenblas-dev \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user for security
RUN useradd -m -s /bin/bash researcher
USER researcher
WORKDIR /home/researcher

# Pin all dependencies
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# Copy project files
COPY --chown=researcher:researcher . /home/researcher/project
WORKDIR /home/researcher/project

# Resource limits set at runtime, not build time
CMD ["python", "main.py"]

Running with Resource Limits

# Run with CPU, memory, and time constraints
docker run \
  --cpus="2.0" \
  --memory="4g" \
  --memory-swap="4g" \
  --pids-limit=100 \
  --network=none \
  --read-only \
  --tmpfs /tmp:size=512m \
  --timeout 3600 \
  research-sandbox:latest python analysis.py

# Mount data as read-only, output directory as writable
docker run \
  -v /data/raw:/data:ro \
  -v /data/results:/output:rw \
  --cpus="4.0" \
  --memory="16g" \
  research-sandbox:latest python pipeline.py

Python Sandbox with Resource Limits

Process-Level Isolation

import subprocess
import resource
import signal
import tempfile
import os

def run_sandboxed(code: str, timeout: int = 60,
                   max_memory_mb: int = 512) -> dict:
    """
    Execute Python code in a sandboxed subprocess with resource limits.

    Args:
        code: Python code string to execute
        timeout: Maximum execution time in seconds
        max_memory_mb: Maximum memory in megabytes
    """
    with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
        f.write(code)
        script_path = f.name

    try:
        result = subprocess.run(
            ['python', '-u', script_path],
            capture_output=True,
            text=True,
            timeout=timeout,
            env={
                'PATH': '/usr/bin:/usr/local/bin',
                'HOME': '/tmp',
                'PYTHONDONTWRITEBYTECODE': '1'
            }
        )
        return {
            'stdout': result.stdout,
            'stderr': result.stderr,
            'returncode': result.returncode,
            'timed_out': False
        }
    except subprocess.TimeoutExpired:
        return {
            'stdout': '',
            'stderr': f'Execution timed out after {timeout}s',
            'returncode': -1,
            'timed_out': True
        }
    finally:
        os.unlink(script_path)

# Example usage
result = run_sandboxed("""
import numpy as np
data = np.random.randn(1000)
print(f"Mean: {data.mean():.4f}")
print(f"Std:  {data.std():.4f}")
""", timeout=30, max_memory_mb=256)
print(result['stdout'])

Nix-Based Reproducible Environments

For maximum reproducibility, use Nix to pin every dependency including system libraries:

# shell.nix for a research project
{ pkgs ? import (fetchTarball {
    url = "https://github.com/NixOS/nixpkgs/archive/nixos-23.11.tar.gz";
  }) {} }:

pkgs.mkShell {
  buildInputs = with pkgs; [
    python311
    python311Packages.numpy
    python311Packages.scipy
    python311Packages.pandas
    python311Packages.matplotlib
    python311Packages.scikit-learn
    R
    rPackages.ggplot2
    rPackages.dplyr
  ];

  shellHook = ''
    echo "Research sandbox activated"
    echo "Python: $(python --version)"
    echo "R: $(R --version | head -1)"
  '';
}

# Enter the reproducible environment
nix-shell shell.nix

# Or use flakes for even better reproducibility
nix develop

Security Best Practices

When running untrusted or third-party code:

1. Network isolation: Use --network=none in Docker to prevent data exfiltration
2. Filesystem restrictions: Mount data as read-only, limit writable paths
3. Resource caps: Always set CPU, memory, and time limits
4. User isolation: Run as non-root user inside the container
5. Syscall filtering: Use seccomp profiles to restrict system calls
6. Output sanitization: Validate and sanitize all output before processing

Integration with CI/CD

Automate research pipeline execution with GitHub Actions:

name: Research Pipeline
on:
  push:
    paths: ['src/**', 'data/**']

jobs:
  run-analysis:
    runs-on: ubuntu-latest
    container:
      image: research-sandbox:latest
      options: --cpus 4 --memory 8g
    steps:
      - uses: actions/checkout@v4
      - run: python src/01_preprocess.py
      - run: python src/02_analyze.py
      - run: python src/03_visualize.py
      - uses: actions/upload-artifact@v4
        with:
          name: results
          path: output/

This ensures every commit triggers a fresh, sandboxed execution of the full pipeline, catching environment-dependent bugs and ensuring reproducibility.