hydra-sandbox 0.1.0__tar.gz

hydra_sandbox-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install mkdocs-material mkdocstrings[python]
+
+      - name: Build docs
+        run: mkdocs build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

hydra_sandbox-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true
+          files: dist/*

hydra_sandbox-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,55 @@
+name: Test
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        exclude:
+          # Reduce matrix size — skip some combos for speed
+          - os: macos-latest
+            python-version: "3.10"
+          - os: macos-latest
+            python-version: "3.11"
+          - os: windows-latest
+            python-version: "3.10"
+          - os: windows-latest
+            python-version: "3.11"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,verify]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: pip install mypy && mypy src/hydra_sandbox --ignore-missing-imports || true
+
+      - name: Run tests with coverage
+        run: pytest tests/ -v --cov=src/hydra_sandbox --cov-report=xml --cov-report=term --ignore=tests/benchmarks
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          flags: ${{ matrix.os }},python${{ matrix.python-version }}
+        continue-on-error: true

hydra_sandbox-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+# Build artifacts
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/

hydra_sandbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to hydra-sandbox will be documented in this file.
+
+## [0.1.0] — Unreleased
+
+### Added
+- `execute_python()` with subprocess, seccomp, and landlock strategies
+- Import guard blocking dangerous stdlib modules
+- AST signature verification (`verify_ast_signature`, `extract_expected_signature`)
+- Z3 formal specification checker (`check_spec`, `VerificationSpec`, `VerificationResult`)
+- `verified_execute()` combining sandbox execution with Z3 proofs
+- Merkle audit trail (`AuditLog`)
+- CLI entry point (`hydra-sandbox`)
+- Escape attempt test suite

hydra_sandbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hydra Sandbox Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hydra_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: hydra-sandbox
+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.

hydra_sandbox-0.1.0/README.md

@@ -0,0 +1,131 @@
+# 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.

hydra_sandbox-0.1.0/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Threat Model
+
+hydra-sandbox is designed to protect against:
+
+1. **Malicious code execution** — code that attempts to access the filesystem,
+   network, or spawn subprocesses
+2. **Resource exhaustion** — CPU, memory, and file descriptor limits
+3. **Import-based escapes** — using `__import__`, `importlib`, or `ctypes` to
+   bypass restrictions
+4. **Information disclosure** — leaking environment variables, secrets, or
+   host filesystem paths
+
+## Limitations
+
+- **subprocess strategy** (default, cross-platform): Relies on Python-level
+  import guards and socket monkey-patching. Determined attackers may bypass
+  via AST manipulation or compiled extensions.
+- **seccomp strategy** (Linux only): Kernel-level syscall filtering. Requires
+  `libseccomp` and the `pyseccomp` package.
+- **landlock strategy** (Linux 5.13+): Filesystem access control at the
+  kernel level. Requires the `landlock` Python package.
+
+For production deployments handling truly untrusted code, use the
+`seccomp+landlock` strategy on a Linux host with additional hardening
+(container, VM, or dedicated machine).
+
+## Reporting a Vulnerability
+
+If you discover a sandbox bypass or security vulnerability, please
+open a GitHub Security Advisory at:
+https://github.com/akaradje/hydra-sandbox/security/advisories
+
+Do NOT open a public issue for security vulnerabilities.

hydra_sandbox-0.1.0/docs/BENCHMARKS.md

@@ -0,0 +1,34 @@
+# Benchmarks
+
+All benchmarks measured on Windows 11, Python 3.13, Intel Core i7.
+
+Run with: `pytest tests/benchmarks --benchmark-only`
+
+## AST Signature Verification
+
+| Test | Mean | OPS/sec | Target |
+|------|------|---------|--------|
+| `verify_ast_signature` (valid) | 24.5 μs | 40,837 | >10,000 ✅ |
+| `verify_ast_signature` (mismatch) | 23.0 μs | 43,506 | >10,000 ✅ |
+
+The AST verifier runs in **~24 microseconds** — zero latency, zero LLM cost.
+At 40,000+ operations per second it can gate every code generation call
+without becoming a bottleneck.
+
+## Sandbox Execution Roundtrip
+
+| Test | Mean | Baseline |
+|------|------|----------|
+| Raw `subprocess.run` | 26.2 ms | — |
+| `execute_python` (auto strategy) | 36.3 ms | +39% |
+| `execute_python` (subprocess strategy) | 43.9 ms | +68% |
+
+The sandbox adds **10-18 ms** overhead over raw `subprocess.run`, primarily
+from the import guard preamble compilation and environment setup. This is
+well within acceptable bounds for interactive use cases.
+
+## Strategy Overhead
+
+The `auto` strategy has ~3 ms detection overhead at first call (probing
+seccomp/landlock availability), cached for subsequent calls. Explicit
+strategy selection (`strategy="subprocess"`) skips the probe entirely.