glovebox-driver 0.1.0__tar.gz

glovebox_driver-0.1.0/.gitignore

@@ -0,0 +1,180 @@
+.worktrees
+.claude/worktrees/
+.agents/
+.codex/
+
+# sbx agent boot trace: a runtime diagnostic the in-VM entrypoint writes into the
+# workspace (read back by bin/checks/sbx/egress.bash); never a committed source file.
+.gb-agent-boot-trace
+
+# Dependencies
+# Tool-managed dirs use the BARE name (no trailing slash). A `foo/` pattern
+# matches only a *directory*, so a symlink named `foo` — e.g. one linked into a
+# git worktree to run tests — slips past it and `git add -A` stages it (how a
+# node_modules symlink twice reached CI this repo's history). The bare name
+# matches the dir AND a same-named symlink/file, so tool output can't be
+# committed by accident. Only applied to names that are never a legitimately
+# tracked file (dependency/venv/cache/report dirs); generic names like dist/ or
+# build/ keep the trailing slash so they don't over-ignore a real file.
+node_modules
+.pnpm-store
+
+# Build outputs
+dist/
+build/
+out/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Coverage
+coverage/
+coverage.json
+.c8-output
+.coverage
+.coverage.*
+htmlcov
+
+# Mutation testing (Stryker): sandbox, HTML report, and the incremental cache
+.stryker-tmp
+reports/
+
+# Generated LaunchAgent (rendered from the .template by setup.bash at install time)
+launchagents/*.generated.plist
+
+# Python
+__pycache__
+*.pyc
+.venv
+.uv
+.pytest_cache
+
+# `uv run` inside inspect-glovebox/ writes a lock beside its pyproject.toml. The wheel is
+# a library, so it pins nothing; committing one adds a `uv.lock -merge` path that
+# scripts/resolve-generated.mjs owns no rule for, which reds the JS suite.
+/inspect-glovebox/uv.lock
+# pytest scratch (repo-relative --basetemp): throwaway fixture files, including
+# fake executables the suite writes (keyprobe, docker stubs). Ignored so they never
+# surface as uncommitted changes or get captured onto a session-end review branch.
+.pytest-tmp
+
+# Fuzzer crash reproducers (jazzer.js / atheris drop these in the repo root, which
+# is their cwd). Anchored with a leading slash: an unanchored `crash-*` matches at
+# ANY depth, so it silently swallowed bin/checks/sbx/crash-resilience-int.bash — a
+# `git add` of a legitimately-named source file that reports success and stages
+# nothing.
+/crash-*
+/timeout-*
+/oom-*
+/leak-*
+
+# cosmic-ray mutation sessions + HTML reports. mutation-floor.sh writes
+# <session>.html at the repo root for the run's artifact, one per tools/mutation/
+# toml, so this is a glob: a per-session list leaves the next session's report
+# untracked-but-not-ignored, which is what egress-filter and mcpgw-derive were.
+*.sqlite
+/*.html
+
+# History working files — each lives on the perf-history or ci-timings branch and is
+# seeded into the checkout by persist-perf-history.sh read or record-setup-timing.sh;
+# never committed to main or a feature branch. A glob, not a list: a tool that walks
+# "tracked plus untracked-not-ignored" takes a seeded file for a repository file, and
+# a per-metric list leaves the next metric's file out of the pattern. That is what
+# widened perf-gates.yaml's generated paths-regex on the runner and nowhere else.
+.github/*-history.json
+.github/*-history.jsonl
+
+# pytest --basetemp droppings (used where /tmp is noexec)
+.pytest-exec-tmp
+
+# sbx agent-entrypoint boot trace — a runtime log appended into the workspace by
+# gb_boot_trace; a diagnostic artifact, never committed.
+.gb-agent-boot-trace
+
+# Hypothesis property-testing example database (regenerated locally; never committed)
+.hypothesis/
+
+# CI timing maps that balance the shard fan-outs. They live in R2 (uploaded only by
+# main runs, fetched best-effort by CI — see .github/ci-durations.json) and are never
+# committed; ignored so a CI fetch or a local `uv run pytest --store-durations` /
+# sbx-live run can't accidentally stage them.
+tests/.gb-test-durations.json
+tests/.gb-kcov-durations.json
+tests/.gb-drvfs-durations.json
+tests/.gb-macos-durations.json
+# The plan job's published shard assignment, one per leg (keyed by that leg's
+# duration-map name): derived from the fetched map, shipped to the shards in the
+# same artifact, never committed.
+tests/.gb-*-shard-assignment.json
+.github/sbx-live/durations.json
+
+# The pinned scanner binary that .github/scripts/python-deps-vuln-scan.sh downloads
+# into the repo root (~56 MB). Running that script locally to reproduce a red
+# osv-scanner check is the documented response to one, so the artifact lands in
+# every contributor's tree; ignored so it can't be staged by a `git add -A`.
+/osv-scanner
+
+# esbuild output of sbx-kit/image/{monitor-dispatch,redact-output}.mjs. The image
+# builds these in its own bundler stage (sbx-kit/image/Dockerfile); the local copies
+# exist so the CT eval harness can subprocess the dispatcher without a docker build.
+sbx-kit/image/monitor-dispatch.bundle.mjs
+sbx-kit/image/redact-output.bundle.mjs
+
+# esbuild output of the host guardrail hooks (scripts/build-hook-bundles.mjs), which
+# settings.json launches. Built once per tree by `pnpm install`'s postinstall, by
+# setup.bash at install time, and in the image's own bundler stage — so the reviewable
+# surface is the hook sources plus pnpm-lock.yaml, not a 12k-line generated diff.
+# The hand-written gate-hooks.bundle.d.mts beside them stays tracked.
+.claude/hooks/*.bundle.mjs
+
+# The pinned kcov binary that tests/install-kcov-local.sh builds into the repo
+# root — the same path .github/actions/install-kcov caches to, so tests/run-kcov.sh
+# finds a local build with no PATH edit. Reproducing a red "Bash coverage (kcov)"
+# check locally is the documented response to one, so the artifact lands in every
+# contributor's tree; ignored so it can't be staged by a `git add -A`.
+/kcov-bin/
+.claude/.hookpin-*/
+
+# synced-deps.test.mjs's untracked-file probe, mkdtemp'd under a synced path on
+# purpose. Ignored so a concurrent `git add -A` elsewhere in this checkout can't
+# stage it mid-test: staged, it would pass trackedUnder()'s check and leave an
+# AD entry in the shared index once the test deletes it from disk.
+.claude/consumer-probe-*/
+
+# `ct settings pull` writes this per-checkout pin cache into the repo root. The pin this
+# harness measures lives in evals/control_tower/ct-settings-pin.txt; a committed copy here
+# would be a second one that drifts.
+.settings.local.yml
+
+# `gh` writes its per-machine state here when it runs with the repo root as the
+# XDG state home — a device identifier, which no checkout should carry.
+/.local/
+
+# Generated doc pages, published to the CDN instead of committed
+# (scripts/render-doc-site.py, .github/workflows/docs-publish.yaml). A committed
+# page is re-derived by every branch that touches its generator's inputs, which
+# made these the busiest files in the history and conflicted branches on bytes
+# nobody typed. Their generators still run, and still refuse a bad input; only
+# the output stays out of the tree.
+/docs/architecture-callgraph.md
+/docs/ci-map.generated.md
+/docs/tla/configs.md
+/docs/tla/reachable-subsets.md
+/docs/tla/diagrams/

glovebox_driver-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: glovebox-driver
+Version: 0.1.0
+Summary: Host-side Python driver for a glovebox microVM session
+Project-URL: Homepage, https://github.com/AlexanderMattTurner/agent-glovebox
+Project-URL: Source, https://github.com/AlexanderMattTurner/agent-glovebox
+Author: AlexanderMattTurner
+License-Expression: Apache-2.0
+Keywords: ai-control,glovebox,microvm,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# glovebox-driver
+
+The host-side Python that drives one [glovebox](https://github.com/AlexanderMattTurner/agent-glovebox) microVM: boot it, run commands in it, read what it let out, and tear it down. It imports no eval framework, so an integration picks the framework and this package holds the VM.
+
+`inspect-glovebox` and `shepherd-glovebox` are both built on it.
+
+## What the host needs
+
+The driver runs the `glovebox` command, which drives Docker's `sbx` sandbox runtime. Install glovebox and sign in to `sbx`, then ask whether this host qualifies:
+
+```bash
+glovebox sandbox preflight
+```
+
+Set `GLOVEBOX_BIN` when the executable is not on `PATH`.
+
+## The modules
+
+| Module       | Owns                                                                    |
+| ------------ | ----------------------------------------------------------------------- |
+| `cli`        | resolving the `glovebox` executable and running one `sandbox` verb      |
+| `config`     | `GloveboxSandboxConfig` — what a VM may be and which hosts it may reach |
+| `session`    | `GloveboxSession` — one live microVM, from boot to teardown             |
+| `wedge`      | booting again when the HOST, not the work, wedged the first attempt     |
+| `guest_exec` | the argv for one command inside the guest, as the de-privileged user    |
+| `evidence`   | reading the policy decision log the sandbox wrote                       |
+| `leak`       | reaping a microVM whose owner died before teardown                      |
+
+## Boot one
+
+```python
+import os
+from pathlib import Path
+
+from glovebox_driver import cli
+from glovebox_driver.session import GloveboxSession
+
+workspace = Path("/path/to/workspace")
+workspace.mkdir(parents=True, exist_ok=True)
+os.chmod(workspace, 0o755)
+ready_path = workspace / ".ready"
+ready_path.touch()
+
+cli.preflight()
+session = GloveboxSession.boot(str(workspace), str(ready_path), boot_timeout=300)
+try:
+    ...
+finally:
+    session.teardown()
+```
+
+`boot` waits for `ready_path` to exist; it never creates it. Every in-tree caller
+touches its own marker first, and the guest user needs permission to traverse the
+workspace, so a freshly created directory needs its mode set too.
+
+Apache-2.0.

glovebox_driver-0.1.0/README.md

@@ -0,0 +1,56 @@
+# glovebox-driver
+
+The host-side Python that drives one [glovebox](https://github.com/AlexanderMattTurner/agent-glovebox) microVM: boot it, run commands in it, read what it let out, and tear it down. It imports no eval framework, so an integration picks the framework and this package holds the VM.
+
+`inspect-glovebox` and `shepherd-glovebox` are both built on it.
+
+## What the host needs
+
+The driver runs the `glovebox` command, which drives Docker's `sbx` sandbox runtime. Install glovebox and sign in to `sbx`, then ask whether this host qualifies:
+
+```bash
+glovebox sandbox preflight
+```
+
+Set `GLOVEBOX_BIN` when the executable is not on `PATH`.
+
+## The modules
+
+| Module       | Owns                                                                    |
+| ------------ | ----------------------------------------------------------------------- |
+| `cli`        | resolving the `glovebox` executable and running one `sandbox` verb      |
+| `config`     | `GloveboxSandboxConfig` — what a VM may be and which hosts it may reach |
+| `session`    | `GloveboxSession` — one live microVM, from boot to teardown             |
+| `wedge`      | booting again when the HOST, not the work, wedged the first attempt     |
+| `guest_exec` | the argv for one command inside the guest, as the de-privileged user    |
+| `evidence`   | reading the policy decision log the sandbox wrote                       |
+| `leak`       | reaping a microVM whose owner died before teardown                      |
+
+## Boot one
+
+```python
+import os
+from pathlib import Path
+
+from glovebox_driver import cli
+from glovebox_driver.session import GloveboxSession
+
+workspace = Path("/path/to/workspace")
+workspace.mkdir(parents=True, exist_ok=True)
+os.chmod(workspace, 0o755)
+ready_path = workspace / ".ready"
+ready_path.touch()
+
+cli.preflight()
+session = GloveboxSession.boot(str(workspace), str(ready_path), boot_timeout=300)
+try:
+    ...
+finally:
+    session.teardown()
+```
+
+`boot` waits for `ready_path` to exist; it never creates it. Every in-tree caller
+touches its own marker first, and the guest user needs permission to traverse the
+workspace, so a freshly created directory needs its mode set too.
+
+Apache-2.0.

glovebox_driver-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "glovebox-driver"
+version = "0.1.0"
+description = "Host-side Python driver for a glovebox microVM session"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "AlexanderMattTurner" }]
+keywords = ["glovebox", "sandbox", "microvm", "ai-control"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+# Only pydantic: this package speaks to the `glovebox` CLI over argv and stdio, so it
+# imports no eval framework and pins no version of one.
+dependencies = ["pydantic>=2"]
+
+[project.urls]
+Homepage = "https://github.com/AlexanderMattTurner/agent-glovebox"
+Source = "https://github.com/AlexanderMattTurner/agent-glovebox"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/glovebox_driver"]

glovebox_driver-0.1.0/src/glovebox_driver/__init__.py

@@ -0,0 +1,8 @@
+"""The host-side lifecycle of one glovebox microVM, with no eval framework attached.
+
+`glovebox sandbox` is the supported contract; this package is the Python that drives it.
+Import the module that owns the step you need: `cli` resolves and runs the executable,
+`config` carries what a VM may be and reach, `session` boots one and tears it down,
+`wedge` retries a boot the host wedged, `guest_exec` builds the in-guest exec argv,
+`evidence` reads the policy decision log, and `leak` reaps a VM whose owner died.
+"""

glovebox_driver-0.1.0/src/glovebox_driver/_bootstrap.py

@@ -0,0 +1,161 @@
+"""Installing the pinned glovebox release when the host has none.
+
+PROBLEM CLASS — `pip install` delivers this driver and nothing it drives: the glovebox
+CLI is a bash tree installed by Homebrew, apt or a git clone. When no
+install resolves, this module downloads the release source tarball the wheel pins, refuses
+it unless its SHA-256 matches the pinned digest, and extracts it into a per-user cache —
+so the pip package is the only thing a user consciously installs. An install the user made
+always wins: the caller consults this only after ``$GLOVEBOX_BIN`` and PATH both miss.
+"""
+
+import hashlib
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+import time
+import urllib.request
+from pathlib import Path
+
+from ._pinned_release import RELEASE_TAG, TARBALL_SHA256
+
+_REPO = "AlexanderMattTurner/agent-glovebox"
+
+# Bounds on the whole download, not on one socket read. A per-read timeout leaves a server
+# that dribbles a byte inside every window free to block the first sample forever, and a
+# response with no end blocks it just as long while the file grows.
+DOWNLOAD_DEADLINE_S = 600
+DOWNLOAD_MAX_BYTES = 256 * 1024 * 1024
+
+
+def _tarball_url(tag: str) -> str:
+    """The GitHub source tarball for one release tag — the same artifact the AUR and Homebrew packages pin."""
+    return f"https://github.com/{_REPO}/archive/refs/tags/{tag}.tar.gz"
+
+
+def _cache_root() -> Path:
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".cache"
+    return base / "inspect-glovebox"
+
+
+class BootstrapFailed(RuntimeError):
+    """Raised when the pinned release could not be downloaded, verified, or extracted."""
+
+
+def ensure_pinned_glovebox() -> str:
+    """The cached pinned release's `bin/glovebox`, downloading and verifying it first when absent."""
+    return str(
+        ensure_glovebox(
+            tag=RELEASE_TAG,
+            sha256=TARBALL_SHA256,
+            url=_tarball_url(RELEASE_TAG),
+            cache_root=_cache_root(),
+        )
+    )
+
+
+def ensure_glovebox(*, tag: str, sha256: str, url: str, cache_root: Path) -> Path:
+    """`bin/glovebox` of the `tag` install under `cache_root`, downloading `url` on a miss.
+
+    The install lands in a per-tag directory, so a wheel upgrade that moves the pin
+    installs beside the old release rather than over it. A concurrent first use is safe:
+    each extracts into its own scratch directory and one rename wins.
+    """
+    wrapper = cache_root / f"glovebox-{tag}" / "bin" / "glovebox"
+    if os.access(wrapper, os.X_OK):
+        return wrapper
+    archive = _fetch_verified(url, sha256)
+    try:
+        _install(archive, wrapper.parent.parent, cache_root)
+    except OSError as exc:
+        # An unwritable or full cache is a host state the caller has a remedy for, so it
+        # reaches them as the same refusal as a bad download rather than as a traceback.
+        raise BootstrapFailed(f"could not install into {cache_root}: {exc}") from exc
+    finally:
+        archive.unlink(missing_ok=True)
+    if not os.access(wrapper, os.X_OK):
+        raise BootstrapFailed(
+            f"the verified {tag} tarball holds no executable bin/glovebox — "
+            f"remove {wrapper.parent.parent} and report this"
+        )
+    return wrapper
+
+
+def _fetch_verified(url: str, sha256: str) -> Path:
+    """Download `url` to a scratch file and return it only when its digest matches `sha256`.
+
+    INVARIANT: no byte of the download is extracted or executed before this digest check
+    passes — the bootstrap runs code from the network, and the wheel-pinned digest is the
+    whole of its authority to do so.
+    """
+    print(
+        f"inspect-glovebox: no glovebox install found — downloading the pinned release "
+        f"({url})",
+        file=sys.stderr,
+    )
+    handle, name = tempfile.mkstemp(prefix="glovebox-bootstrap-", suffix=".tar.gz")
+    archive = Path(name)
+    digest = hashlib.sha256()
+    deadline = time.monotonic() + DOWNLOAD_DEADLINE_S
+    read = 0
+    overran = False
+    try:
+        # The per-read timeout stops a socket that says nothing; the deadline and the size
+        # cap below stop one that says a little forever. TimeoutError is an OSError.
+        # read1, not read: read blocks until it has the whole megabyte, so a server
+        # dribbling smaller pieces holds one call open past the deadline nobody rechecks.
+        with (
+            os.fdopen(handle, "wb") as out,
+            urllib.request.urlopen(url, timeout=60) as response,
+        ):  # noqa: S310  # the https URL is module-built from the pinned tag
+            while chunk := response.read1(1 << 20):
+                read += len(chunk)
+                if read > DOWNLOAD_MAX_BYTES or time.monotonic() > deadline:
+                    overran = True
+                    break
+                digest.update(chunk)
+                out.write(chunk)
+    except OSError as exc:
+        archive.unlink(missing_ok=True)
+        raise BootstrapFailed(f"could not download {url}: {exc}") from exc
+    if overran:
+        archive.unlink(missing_ok=True)
+        raise BootstrapFailed(
+            f"the download from {url} passed its bound ({DOWNLOAD_MAX_BYTES} bytes or "
+            f"{DOWNLOAD_DEADLINE_S}s) at {read} bytes — refusing to keep reading"
+        )
+    if digest.hexdigest() != sha256:
+        archive.unlink(missing_ok=True)
+        raise BootstrapFailed(
+            f"the download from {url} hashes to {digest.hexdigest()}, not the pinned "
+            f"{sha256} — refusing to install unverified bytes"
+        )
+    return archive
+
+
+def _install(archive: Path, dest: Path, cache_root: Path) -> None:
+    """Extract the verified `archive` into `dest`, atomically enough for concurrent callers."""
+    cache_root.mkdir(parents=True, exist_ok=True)
+    scratch = Path(tempfile.mkdtemp(prefix=f"{dest.name}.", dir=cache_root))
+    try:
+        # nosemgrep: tarfile-extractall-traversal — the extractall below passes filter="data", which is the refusal the rule asks for
+        with tarfile.open(archive, "r:gz") as tar:
+            try:
+                # GitHub wraps the tree in one <repo>-<version>/ directory; the data
+                # filter is what refuses absolute paths, `..` and out-of-tree links.
+                tar.extractall(scratch, filter="data")
+            except TypeError as exc:
+                raise BootstrapFailed(
+                    "this Python's tarfile lacks extraction filters (PEP 706; 3.11.4+) — "
+                    "upgrade Python, or install glovebox yourself"
+                ) from exc
+        [tree] = scratch.iterdir()
+        try:
+            tree.rename(dest)
+        except OSError:
+            if not dest.is_dir():
+                raise
+    finally:
+        shutil.rmtree(scratch, ignore_errors=True)

glovebox_driver-0.1.0/src/glovebox_driver/_pinned_release.py

@@ -0,0 +1,13 @@
+"""The glovebox release this wheel bootstraps when no install is found.
+
+GENERATED by glovebox-driver/update-pin.sh — edit nothing here by hand. The updater runs
+from sync-packaging.sh on each release, beside the AUR/Homebrew updaters that pin the same
+tarball, and it verifies the download against `git archive` before writing the digest.
+"""
+
+# The vX.Y.Z release tag whose source tarball the bootstrap downloads.
+RELEASE_TAG = "v0.47.0"
+
+# SHA-256 of that tag's GitHub source tarball. The bootstrap refuses bytes that do not
+# hash to this, so the runtime it installs is exactly the one this wheel was cut against.
+TARBALL_SHA256 = "10482b2f8d224bb1b2e74622cc2658765336dccb19bbe8e9a6fc8d39346234ff"