diff --git a/CHANGELOG.md b/CHANGELOG.md index 30a5df1..f03b840 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [0.6.0] - 2026-09-14 + +### Added +- Real default-deny egress on Linux when possible: wrap runs with `unshare --net` (preferred) or `bwrap --unshare-net` +- Run response includes `network_isolated` so callers know whether netns wrapping applied + +### Notes +- macOS and hosts without `unshare`/`bwrap` still scrub credentials only (`network_isolated: false`) + ## [0.5.0] - 2026-09-14 ### Added diff --git a/README.md b/README.md index 1124584..8358e29 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Self-hosted **code execution sandbox** for AI agents — one `docker compose up` [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![CI](https://github.com/yashshah9/agentbox/actions/workflows/ci.yml/badge.svg)](https://github.com/yashshah9/agentbox/actions/workflows/ci.yml) -> **Status:** v0.5 — Python + Node subprocess sandbox, timeouts, `limits.memory_mb` / `oom_killed` / `limits_applied`, TypeScript client, workspace snapshots. +> **Status:** v0.6 — Python + Node subprocess sandbox, timeouts, memory limits, Linux default-deny egress (`unshare`/`bwrap`) with `network_isolated`, TypeScript client, workspace snapshots. ## 60-second try @@ -34,16 +34,17 @@ curl -s -X POST http://localhost:8080/v1/run \ Every agent that writes and runs code needs a safe execution environment. Teams either YOLO in shared containers or pay per-second for hosted sandboxes. Self-hosting gVisor/Firecracker is weeks of work. -## Key features (v0.5) +## Key features (v0.6) - HTTP API: `POST /v1/run` executes Python or JavaScript - Per-request `limits.timeout_seconds` (HTTP 408 on timeout) - Per-request `limits.memory_mb` (sets `RLIMIT_AS`; 16–8192); response includes `limits_applied` + `oom_killed` - `AGENTBOX_MAX_MEMORY_MB` clamps requested memory +- Default-deny egress when possible: Linux wraps with `unshare --net` or `bwrap --unshare-net`; response includes `network_isolated` - Workspace snapshots: `"snapshot": true` then `"snapshot_id"` - Python SDK + TypeScript client (`sdk/ts/client.ts`) - Docker image includes Node.js for the JS runtime -- Credential stripping when the backend is not `unrestricted` +- Credential stripping when the backend is not `unrestricted` (macOS stays scrub-only) ## Architecture @@ -135,17 +136,18 @@ pytest tests/ -v - [x] Node.js runtime + TypeScript client + per-run timeout - [x] Filesystem snapshot/restore (tar workspaces) - [x] `limits.memory_mb` via `RLIMIT_AS` +- [x] Default-deny egress via Linux netns (`unshare`/`bwrap`) when available - [ ] gVisor runsc backend with warm pool -- [ ] Default-deny egress with allowlists (kernel netns) +- [ ] Egress allowlists (beyond all-or-nothing netns) ## License MIT -## Known limitations (v0.4) +## Known limitations (v0.6) - Subprocess sandbox only — **not production-grade isolation** - `RLIMIT_AS` is a soft address-space cap, not a cgroup memory controller -- Credential stripping is not a network namespace +- Default-deny egress uses Linux `unshare`/`bwrap` when present; **macOS stays credential-scrub only** (`network_isolated: false`) - Single-node, no warm pool - TypeScript client is source-only (not published to npm) diff --git a/pyproject.toml b/pyproject.toml index bf509a5..ce22bbd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "agentbox-sandbox" -version = "0.5.0" +version = "0.6.0" description = "Self-hosted code execution sandbox for AI agents" readme = "README.md" license = "MIT" diff --git a/sdk/ts/client.ts b/sdk/ts/client.ts index 17956f1..a2cfccb 100644 --- a/sdk/ts/client.ts +++ b/sdk/ts/client.ts @@ -17,6 +17,7 @@ export type RunResult = { snapshot_id?: string | null; limits_applied: LimitsApplied; oom_killed: boolean; + network_isolated: boolean; }; export class AgentboxClient { diff --git a/src/agentbox/__init__.py b/src/agentbox/__init__.py index 3128ee1..de80609 100644 --- a/src/agentbox/__init__.py +++ b/src/agentbox/__init__.py @@ -1,3 +1,3 @@ """Self-hosted code execution sandbox for AI agents.""" -__version__ = "0.5.0" +__version__ = "0.6.0" diff --git a/src/agentbox/api/app.py b/src/agentbox/api/app.py index a12f1c4..fad0ecc 100644 --- a/src/agentbox/api/app.py +++ b/src/agentbox/api/app.py @@ -50,6 +50,7 @@ class RunResponse(BaseModel): snapshot_id: str | None = None limits_applied: LimitsApplied oom_killed: bool = False + network_isolated: bool = False @app.get("/health") @@ -97,4 +98,5 @@ def run_code(req: RunRequest) -> RunResponse: snapshot_id=result.snapshot_id, limits_applied=LimitsApplied(timeout_seconds=timeout, memory_mb=memory_mb), oom_killed=result.oom_killed, + network_isolated=result.network_isolated, ) diff --git a/src/agentbox/sandbox/runner.py b/src/agentbox/sandbox/runner.py index 001f474..00122e5 100644 --- a/src/agentbox/sandbox/runner.py +++ b/src/agentbox/sandbox/runner.py @@ -23,6 +23,7 @@ class RunResult: duration_ms: int snapshot_id: str | None = None oom_killed: bool = False + network_isolated: bool = False class Sandbox(Protocol): @@ -33,6 +34,9 @@ class Sandbox(Protocol): class SubprocessSandbox: """MVP sandbox: isolated temp directory + subprocess timeout + optional memory cap. + When deny_egress is set, also tries Linux network-namespace isolation via + unshare/bwrap when available. macOS stays credential-scrub only. + ponytail: not production isolation — upgrade path is gVisor/docker backend. """ @@ -81,6 +85,9 @@ class SubprocessSandbox: argv = [node, str(script)] else: raise ValueError(f"Unsupported language: {language}") + network_isolated = False + if self.deny_egress: + argv, network_isolated = wrap_deny_egress(argv) preexec = _memory_preexec(mem) if mem else None try: proc = subprocess.run( @@ -107,6 +114,7 @@ class SubprocessSandbox: duration_ms=duration, snapshot_id=new_snapshot, oom_killed=_likely_oom(exit_code, stdout, stderr, mem), + network_isolated=network_isolated, ) def run_python(self, code: str) -> RunResult: @@ -125,6 +133,55 @@ class SubprocessSandbox: return env +def wrap_deny_egress(argv: list[str]) -> tuple[list[str], bool]: + """Wrap argv with a network namespace when unshare or bwrap can isolate. + + Prefer ``unshare --net``; fall back to ``bwrap --unshare-net``. Probes first so + we do not wrap when the binary exists but lacks privileges (common in + unprivileged containers). Returns ``(argv, network_isolated)``. + """ + unshare = shutil.which("unshare") + if unshare and _can_isolate([unshare, "--net", "true"]): + return [unshare, "--net", "--", *argv], True + bwrap = shutil.which("bwrap") + if bwrap: + probe = [ + bwrap, + "--unshare-net", + "--bind", + "/", + "/", + "--dev", + "/dev", + "--proc", + "/proc", + "--", + "true", + ] + if _can_isolate(probe): + return [ + bwrap, + "--unshare-net", + "--bind", + "/", + "/", + "--dev", + "/dev", + "--proc", + "/proc", + "--", + *argv, + ], True + return argv, False + + +def _can_isolate(cmd: list[str]) -> bool: + try: + return subprocess.run(cmd, capture_output=True, timeout=2, check=False).returncode == 0 + except (OSError, subprocess.TimeoutExpired): + return False + + def _likely_oom(exit_code: int, stdout: str, stderr: str, memory_mb: int | None) -> bool: """Heuristic: true when the process likely hit a memory cap. diff --git a/src/agentbox/sdk/client.py b/src/agentbox/sdk/client.py index 2faa958..a7020f7 100644 --- a/src/agentbox/sdk/client.py +++ b/src/agentbox/sdk/client.py @@ -24,7 +24,7 @@ class AgentboxClient: snapshot_id: str | None = None, memory_mb: int | None = None, ) -> dict[str, object]: - """Run code; response includes limits_applied and oom_killed.""" + """Run code; response includes limits_applied, oom_killed, network_isolated.""" payload: dict[str, object] = {"code": code, "language": language} limits: dict[str, object] = {} if timeout_seconds is not None: diff --git a/tests/test_api.py b/tests/test_api.py index 815b4bc..ebb0552 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -31,6 +31,8 @@ def test_run_python(client: TestClient) -> None: assert body["limits_applied"]["timeout_seconds"] >= 1 assert "memory_mb" in body["limits_applied"] assert body["oom_killed"] is False + assert "network_isolated" in body + assert isinstance(body["network_isolated"], bool) def test_run_rejects_unknown_language(client: TestClient) -> None: diff --git a/tests/test_network_isolation.py b/tests/test_network_isolation.py new file mode 100644 index 0000000..3e6aff8 --- /dev/null +++ b/tests/test_network_isolation.py @@ -0,0 +1,111 @@ +"""Tests for deny_egress network-namespace wrapping.""" + +from __future__ import annotations + +import shutil +import sys +from collections.abc import Iterator + +import pytest +from fastapi.testclient import TestClient + +from agentbox.api.app import app +from agentbox.sandbox.runner import SubprocessSandbox, wrap_deny_egress + + +@pytest.fixture +def client() -> Iterator[TestClient]: + with TestClient(app) as test_client: + yield test_client + + +def test_wrap_prefers_unshare(monkeypatch: pytest.MonkeyPatch) -> None: + def fake_which(name: str) -> str | None: + return {"unshare": "/usr/bin/unshare", "bwrap": "/usr/bin/bwrap"}.get(name) + + monkeypatch.setattr(shutil, "which", fake_which) + monkeypatch.setattr( + "agentbox.sandbox.runner._can_isolate", lambda cmd: cmd[0].endswith("unshare") + ) + argv, isolated = wrap_deny_egress(["python3", "main.py"]) + assert isolated is True + assert argv == ["/usr/bin/unshare", "--net", "--", "python3", "main.py"] + + +def test_wrap_falls_back_to_bwrap(monkeypatch: pytest.MonkeyPatch) -> None: + def fake_which(name: str) -> str | None: + return {"bwrap": "/usr/bin/bwrap"}.get(name) + + monkeypatch.setattr(shutil, "which", fake_which) + monkeypatch.setattr("agentbox.sandbox.runner._can_isolate", lambda cmd: True) + argv, isolated = wrap_deny_egress(["python3", "main.py"]) + assert isolated is True + assert argv[:3] == ["/usr/bin/bwrap", "--unshare-net", "--bind"] + assert argv[-3:] == ["--", "python3", "main.py"] + + +def test_wrap_skips_when_probe_fails(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(shutil, "which", lambda name: "/usr/bin/unshare") + monkeypatch.setattr("agentbox.sandbox.runner._can_isolate", lambda cmd: False) + argv, isolated = wrap_deny_egress(["python3", "main.py"]) + assert isolated is False + assert argv == ["python3", "main.py"] + + +def test_wrap_noop_without_tools(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(shutil, "which", lambda _name: None) + cmd = ["python3", "main.py"] + argv, isolated = wrap_deny_egress(cmd) + assert isolated is False + assert argv == cmd + + +def test_run_reports_network_isolated_false_without_tools( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(shutil, "which", lambda name: "python3" if name == "python3" else None) + box = SubprocessSandbox(deny_egress=True, timeout_seconds=5) + result = box.run("print('ok')") + assert result.exit_code == 0 + assert result.network_isolated is False + assert "ok" in result.stdout + + +def test_api_includes_network_isolated(client: TestClient) -> None: + resp = client.post("/v1/run", json={"code": "print(1)"}) + assert resp.status_code == 200 + body = resp.json() + assert "network_isolated" in body + assert isinstance(body["network_isolated"], bool) + + +@pytest.mark.skipif(sys.platform != "linux", reason="netns isolation is Linux-only") +@pytest.mark.skipif( + shutil.which("unshare") is None and shutil.which("bwrap") is None, + reason="unshare/bwrap not installed", +) +def test_live_network_isolation_blocks_egress() -> None: + """Optional: real isolation when running on Linux with unshare/bwrap privileges.""" + from agentbox.sandbox.runner import wrap_deny_egress + + _, can = wrap_deny_egress(["true"]) + if not can: + pytest.skip("unshare/bwrap present but cannot create netns (need privileges)") + box = SubprocessSandbox(deny_egress=True, timeout_seconds=10) + code = ( + "import socket\n" + "s = socket.socket()\n" + "try:\n" + " s.settimeout(2)\n" + " s.connect(('1.1.1.1', 80))\n" + " print('CONNECTED')\n" + "except OSError as e:\n" + " print('BLOCKED')\n" + " print(type(e).__name__)\n" + "finally:\n" + " s.close()\n" + ) + result = box.run(code) + assert result.network_isolated is True + assert "CONNECTED" not in result.stdout + assert "BLOCKED" in result.stdout or result.exit_code != 0 diff --git a/tests/test_scenarios_v05.py b/tests/test_scenarios_v05.py index ee678df..75a0963 100644 --- a/tests/test_scenarios_v05.py +++ b/tests/test_scenarios_v05.py @@ -20,13 +20,13 @@ def client() -> Iterator[TestClient]: yield test_client -def test_health_version_050(client: TestClient) -> None: +def test_health_version_060(client: TestClient) -> None: resp = client.get("/health") assert resp.status_code == 200 body = resp.json() assert body["status"] == "ok" - assert body["version"] == "0.5.0" - assert __version__ == "0.5.0" + assert body["version"] == "0.6.0" + assert __version__ == "0.6.0" def test_python_success(client: TestClient) -> None: @@ -202,6 +202,7 @@ def test_sdk_client_run_response_fields(client: TestClient) -> None: assert body["limits_applied"]["memory_mb"] == 64 assert body["limits_applied"]["timeout_seconds"] == 10 assert "oom_killed" in body + assert "network_isolated" in body captured: dict[str, object] = {} @@ -229,6 +230,7 @@ def test_sdk_client_run_response_fields(client: TestClient) -> None: } assert result["limits_applied"]["memory_mb"] == 64 assert "oom_killed" in result + assert "network_isolated" in result finally: sdk.close() diff --git a/uv.lock b/uv.lock index 11d6823..3a3beca 100644 --- a/uv.lock +++ b/uv.lock @@ -8,7 +8,7 @@ resolution-markers = [ [[package]] name = "agentbox-sandbox" -version = "0.5.0" +version = "0.6.0" source = { editable = "." } dependencies = [ { name = "fastapi" },