Metadata-Version: 2.4
Name: hydra-pysandbox
Version: 0.1.0
Summary: Hardened Python sandbox for running untrusted code — subprocess, seccomp, landlock strategies with Z3 formal verification.
Project-URL: Homepage, https://github.com/akaradje/hydra-sandbox
Project-URL: Documentation, https://github.com/akaradje/hydra-sandbox
Project-URL: Repository, https://github.com/akaradje/hydra-sandbox.git
Project-URL: Issues, https://github.com/akaradje/hydra-sandbox/issues
Author: Hydra Sandbox Contributors
Maintainer: Hydra Sandbox Contributors
License: MIT
License-File: LICENSE
Keywords: code-execution,formal-verification,landlock,llm,sandbox,seccomp,security,z3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: landlock>=0.1; extra == 'all'
Requires-Dist: pyseccomp>=0.1; extra == 'all'
Requires-Dist: z3-solver>=4.12.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: landlock
Requires-Dist: landlock>=0.1; extra == 'landlock'
Provides-Extra: seccomp
Requires-Dist: pyseccomp>=0.1; extra == 'seccomp'
Provides-Extra: verify
Requires-Dist: z3-solver>=4.12.0; extra == 'verify'
Description-Content-Type: text/markdown

# hydra-sandbox

[![PyPI](https://img.shields.io/pypi/v/hydra-sandbox)](https://pypi.org/project/hydra-sandbox/)
[![Python](https://img.shields.io/pypi/pyversions/hydra-sandbox)](https://pypi.org/project/hydra-sandbox/)
[![License](https://img.shields.io/pypi/l/hydra-sandbox)](https://github.com/akaradje/hydra-sandbox/blob/main/LICENSE)
[![Tests](https://img.shields.io/github/actions/workflow/status/akaradje/hydra-sandbox/test.yml?label=tests)](https://github.com/akaradje/hydra-sandbox/actions)
[![Coverage](https://img.shields.io/codecov/c/github/akaradje/hydra-sandbox)](https://codecov.io/gh/akaradje/hydra-sandbox)

Hardened Python execution sandbox for running untrusted code.

Built for developers building LLM agents, code review bots, and online
coding platforms who need to execute user-submitted or model-generated
code without risking the host system.

## Features

- **Multiple isolation strategies** — subprocess (cross-platform), seccomp
  (Linux syscall filtering), landlock (Linux filesystem sandbox)
- **Import guard** — blocks dangerous stdlib modules (`subprocess`, `ctypes`,
  `socket`, `multiprocessing`, etc.)
- **Network isolation** — monkey-patches `socket.socket` to block outbound
  connections
- **Resource limits** — CPU time, memory, and file descriptor caps (POSIX)
- **Secret purging** — strips API keys and tokens from the child environment
- **AST signature verification** — validates function name and parameter lists
  before execution (zero latency, no LLM cost)
- **Z3 formal verification** — optional pre/post-condition checking with
  mathematical proofs

## Installation

```bash
pip install hydra-sandbox

# With optional dependencies
pip install hydra-sandbox[verify]       # Z3 formal verification
pip install hydra-sandbox[seccomp]      # Linux seccomp support
pip install hydra-sandbox[landlock]     # Linux landlock support
pip install hydra-sandbox[all]          # everything
```

## Quick start

```python
from hydra_sandbox import execute_python

# Run untrusted code in an isolated subprocess
result = execute_python(
    "print(1 + 1)",
    timeout=5,
)

print(result.success)    # True
print(result.stdout)     # "2"
print(result.exit_code)  # 0
```

## Strategy selection

```python
# Auto-detect the strongest available strategy (default)
result = execute_python(code, strategy="auto")

# Explicit strategies
result = execute_python(code, strategy="subprocess")      # cross-platform
result = execute_python(code, strategy="seccomp")          # Linux only
result = execute_python(code, strategy="seccomp+landlock") # strongest
```

## AST verification

```python
from hydra_sandbox import verify_ast_signature, extract_expected_signature

# Verify a function signature without executing
error = verify_ast_signature(
    "def add(x, y): return x + y",
    "add",
    ["x", "y"],
)
print(error)  # None — signature is correct

# Extract expected signature from a description
sig = extract_expected_signature(
    "Write function 'process(data: bytes, key: str) -> str'"
)
print(sig)  # ("process", ["data", "key"])
```

## Z3 formal verification

```python
from z3 import Int
from hydra_sandbox.verify import check_spec, VerificationSpec

x, y = Ints("x y")
spec = VerificationSpec(
    precondition=x > 0,
    postcondition=x + y > y,
)
result = check_spec(spec)
print(result.valid)  # True — mathematically proven
```

## Security

See [SECURITY.md](SECURITY.md) for the threat model and supported versions.

The `subprocess` strategy provides Python-level isolation suitable for
most use cases. For production deployments handling truly untrusted code,
use `seccomp+landlock` on a Linux host with additional hardening.

## Telemetry

hydra-sandbox includes optional, **opt-in** telemetry. It is **disabled by
default** and sends nothing unless you explicitly enable it.

When enabled, it sends exactly two data points ONCE per process lifetime:
- Package version (`__version__`)
- Strategy selected (`subprocess`, `seccomp`, etc.)

No user code, no environment variables, no PII, no IP address logging.

```bash
export HYDRA_SANDBOX_TELEMETRY=1   # opt in
export HYDRA_SANDBOX_NO_TELEMETRY=1  # explicitly opt out (default)
```

## License

MIT — see [LICENSE](LICENSE) for details.
