convez.ai
MCP ServerSegurançaIntermediário
LostSyscall

py-sandbox

LostSyscall/pysandbox

Executor Python seguro em sandbox com suporte MCP para agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Executor de código Python isolado em sandbox com suporte a MCP (Model Context Protocol). Fornece um ambiente seguro para executar código Python arbitrário com validação AST, restrições de built-ins, whitelist de importações e limites de recursos (timeout, memória, output).

Instalação

$npx convez-ai LostSyscall/pysandbox

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar código Python não confiável de forma segura em agentes IA
  • Avaliar e testar snippets de código com isolamento de recursos
  • Plataformas de execução de código com proteção contra exploits

Veredito

Solução robusta para execução segura de código Python em ambientes não confiáveis. Implementa múltiplas camadas de proteção (AST, builtins restritos, whitelist, isolamento de processo) e integra-se nativamente com o ecossistema Claude via MCP, sendo ideal para agentes que precisam executar código arbitrário.

README

A tradução para o português deste README ainda está na fila.

py-sandbox

A cross-platform sandboxed Python code executor with MCP (Model Context Protocol) server support.

Overview

py-sandbox provides a secure environment for executing arbitrary Python code with strict resource limits and security constraints. It is designed for use in AI agent systems, code evaluation platforms, and any scenario where untrusted Python code needs to be run safely.

The sandbox operates through a multi-layered security model:

  1. AST Validation — Rejects dangerous code patterns before execution
  2. Restricted Builtins — Limits available built-in functions inside the sandbox
  3. Import Whitelist — Only safe modules (math, json, re, etc.) can be imported
  4. Subprocess Isolation — Code runs in a separate process, not the host
  5. Resource Limits — Timeout, memory, and output size are all enforced

Features

  • Cross-platform — Works on Windows, macOS, and Linux
    • Windows: Job Objects + watchdog for memory/timeout enforcement
    • Unix: setrlimit via preexec_fn + watchdog
  • MCP Server — Expose run_python tool to AI agents via stdio or SSE transport
  • CLI Tool — Direct sandbox execution from the command line
  • Variable Inspection — Inspect named variables after execution
  • Output Limiting — Truncate excessive stdout to prevent resource abuse
  • No External Dependencies — Core sandbox uses only Python stdlib (ctypes on Windows)

Installation

# Core sandbox (no MCP server)
pip install py-sandbox

# With MCP server support
pip install py-sandbox[mcp]

# Using uv
uv pip install py-sandbox
uv pip install py-sandbox[mcp]

For development:

git clone https://github.com/LostSyscall/pysandbox.git
cd py-sandbox-mcp
uv sync

Usage

CLI

# Execute inline code
py-sandbox "print('hello world')"

# Execute from a file
py-sandbox -f script.py

# With resource limits
py-sandbox -t 10 -m 128 "import math; print(math.pi)"

# Inspect variables
py-sandbox -v x -v y "x = 42; y = [1, 2, 3]"

Options:

OptionDefaultMaxDescription
-t / --timeout3060Timeout in seconds
-m / --memory2561024Memory limit in MB
-o / --output-limit65536262144Output limit in bytes
-v / --variables——Variable names to inspect

Python API

from py_sandbox import execute

result = execute("import math; print(math.sqrt(16))")
print(result["stdout"])      # "4.0"
print(result["return_code"]) # 0

result = execute("x = 42", inspect_variables=["x"])
print(result["variables"])   # {"x": 42}

result = execute("import os")
print(result["error"])       # "Import of module 'os' is not allowed..."
print(result["return_code"]) # -1

MCP Server

Start the MCP server for AI agent integration:

# stdio transport (default, for CLI-based agents)
py-sandbox-mcp

# SSE transport (for HTTP-based agents)
py-sandbox-mcp sse

The server exposes a run_python tool with the same parameters as the execute() function.

Example MCP client configuration (for Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "python-sandbox": {
      "command": "py-sandbox-mcp",
      "args": []
    }
  }
}

Security Model

Layer 1: AST Validation

The AST validator rejects code before it ever reaches execution. Blocked patterns include:

  • Dangerous imports — os, sys, subprocess, socket, ctypes, pickle, etc.
  • Dangerous builtins — exec, eval, compile, open, __import__, getattr, etc.
  • Dunder escapes — __class__, __subclasses__, __globals__, __builtins__, etc.
  • Dynamic class creation — type() with 3 arguments
  • Relative imports — Not allowed (sandbox code has no package context)
  • String-based dunder references — hasattr(obj, "__class__") is blocked

Layer 2: Restricted Builtins

The sandbox worker replaces __builtins__ with a safe subset. Only essential functions like len, range, print, sorted, isinstance, etc. are available. Dangerous builtins like open, exec, eval, getattr are removed.

Layer 3: Import Whitelist

Only these modules can be imported inside the sandbox:

  • Math: math, cmath, decimal, fractions, statistics
  • Data: json, re, string, textwrap, unicodedata, difflib
  • Time: datetime, calendar
  • Collections: collections, itertools, functools, operator, enum, dataclasses, typing, copy
  • Encoding: hashlib, base64, random, uuid, struct
  • Utility: pprint

All other imports raise ImportError.

Layer 4: Subprocess Isolation

Code executes in a separate subprocess, not the host process. This means:

  • The sandbox process cannot access the host's memory or state
  • When the host kills the sandbox process, all its resources are reclaimed
  • No shared file descriptors, no signal leakage

Layer 5: Resource Limits

ResourceEnforcement
TimeoutWatchdog thread + Unix RLIMIT_CPU / Windows Job Object time limit
MemoryWatchdog polling + Unix RLIMIT_AS / Windows Job Object memory limit
OutputByte-counted stdout truncation inside the worker
File descriptorsUnix RLIMIT_NOFILE (limited to 64)

Architecture

flowchart TB
    subgraph host["Host Process"]
        entry["CLI / MCP Server"]
        executor["Executor (Orchestrator)"]
        ast["AST Validator\n(reject or accept)"]
        platform["Platform Utils\n(Job Object / setrlimit)"]
        watchdog["ResourceWatchdog\n(timeout / memory)"]
    end

    subgraph worker["Sandbox Worker (subprocess)"]
        builtins["Restricted __builtins__\n+ Import Whitelist"]
        exec_code["exec(code, namespace)"]
        output["Output limiting (byte count)\nVariable serialization"]
    end

    entry --> executor
    executor --> ast
    executor --> platform
    executor --> watchdog
    executor -- "spawn subprocess\nstdin: JSON envelope" --> worker
    worker -- "stdout: JSON result" --> executor

Execution Flow

  1. CLI or MCP Server receives code to execute
  2. Executor validates code through the AST Validator — if rejected, returns error immediately
  3. Platform Utils sets up OS-level resource limits (Job Object on Windows, setrlimit on Unix)
  4. Executor spawns a Sandbox Worker subprocess, sending a JSON envelope via stdin
  5. ResourceWatchdog monitors the subprocess for timeout and memory violations
  6. Inside the subprocess, the Sandbox Worker runs code with restricted builtins and import whitelist
  7. Results (stdout, variables, errors) are serialized as JSON and sent back via stdout

Project Structure

py-sandbox-mcp/
├── LICENSE
├── README.md
├── pyproject.toml
├── src/
│   └── py_sandbox/
│       ├── __init__.py          # Package entry, exports execute() and ExecutionResult
│       ├── ast_validator.py     # AST-based security gate
│       ├── builtin_policy.py    # Safe builtins dict and import whitelist
│       ├── cli.py               # CLI entry point (py-sandbox command)
│       ├── config.py            # Default limits and blocked/allowed lists
│       ├── executor.py          # Orchestrator: validation → spawn → capture
│       ├── platform_utils.py    # Windows Job Object / Unix setrlimit + watchdog
│       ├── sandbox_worker.py    # Subprocess worker: restricted exec environment
│       └── server.py            # MCP server (py-sandbox-mcp command)
├── tests/
│   ├── __init__.py
│   ├── test_ast_validator.py
│   ├── test_builtin_policy.py
│   └── test_executor.py

Running Tests

uv run pytest

License

MIT

Ver o original no GitHub

Bom para

Relacionados