harbor-glovebox 0.1.0__tar.gz

harbor_glovebox-0.1.0/.gitignore

@@ -0,0 +1,192 @@
+.worktrees
+.claude/worktrees/
+.agents/
+.codex/
+
+# vm agent-entrypoint boot trace — a runtime log appended into the workspace by
+# gb_boot_trace; a diagnostic artifact, never committed.
+.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.*
+.py-coverage.lock
+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/, glovebox-monitor/ or glovebox-driver/ writes a lock
+# beside that pyproject.toml. Each wheel is a library, so it pins nothing; committing one
+# adds a `uv.lock -merge` path that scripts/lib-regen-rules.mjs owns no rule for, which
+# reds the JS suite.
+/inspect-glovebox/uv.lock
+/glovebox-monitor/uv.lock
+/glovebox-driver/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/vm/crash-resilience-int.bash — a
+# `git add` of a legitimately-named source file that reports success and stages
+# nothing.
+/crash-*
+/timeout-*
+/oom-*
+/leak-*
+
+# 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.
+.github/*-history.json
+.github/*-history.jsonl
+
+# pytest --basetemp droppings (used where /tmp is noexec)
+.pytest-exec-tmp
+
+# 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` /
+# vm-live run can't accidentally stage them.
+tests/.gb-test-durations.json
+tests/.gb-test-uninstrumented-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
+tests/.gb-select-maps.json
+.github/vm-live/durations.json
+.github/kata-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 — every artifact scripts/build-hook-bundles.mjs or
+# scripts/build-vm-dispatcher.mjs writes, wherever its home. Built once per tree by
+# `pnpm install`'s postinstall, by setup.bash at install time, in the nix buildPhase and
+# in the image's own bundler stage, so the reviewable surface is the sources plus
+# pnpm-lock.yaml. Suffix, not a directory or a member list: a bundle whose home the
+# pattern misses leaves every tree that builds it permanently dirty.
+*.bundle.mjs
+
+# Sharded mutation configs are deterministic build output. The planner and
+# `pnpm install` render them from config/mutation-sessions.json.
+/tools/mutation/*of*.toml
+
+# 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/inspect-evals-coverage.generated.md
+/docs/tla/configs.md
+/docs/tla/reachable-subsets.md
+/docs/tla/diagrams/
+/docs/tla/modules/
+# TLC's own scratch metadir, written here by a run given no -metadir.
+/docs/tla/states/
+
+# The eval time series live on the `metrics-history` branch, which `main` never
+# merges (.github/scripts/eval-series.sh). A tracker or a local run materializes its
+# own working copy here; committing one would put the series back on the merge path.
+metrics/monitor-eval.jsonl
+metrics/sabotage-eval.jsonl
+metrics/breakout-ctf.jsonl
+
+# `nix build` links its output here.
+/result
+/result-*
+
+# go build output of the guest network daemon
+bin/lib/kata/netd/netd

harbor_glovebox-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: harbor-glovebox
+Version: 0.1.0
+Summary: Run a Harbor trial in a hypervisor-isolated, egress-filtered glovebox microVM
+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,evals,harbor,microvm,sandbox,terminal-bench
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: glovebox-driver>=0.6.0
+Requires-Dist: harbor<0.24,>=0.23
+Description-Content-Type: text/markdown
+
+# harbor-glovebox
+
+Run a [Harbor](https://github.com/harbor-framework/harbor) trial inside a glovebox microVM instead of a shared-kernel container. Each trial boots one hardware-isolated VM behind glovebox's outgoing-traffic filter, and the filter's records land beside the trial's other artifacts.
+
+## Status
+
+The `harbor-trial` live check drives one trial's environment calls on a real microVM in CI, then runs `harbor run` with Harbor's oracle agent over a one-task dataset through this environment. No run over a published dataset with a model-backed agent has used it yet.
+
+## Use
+
+Install the released package:
+
+```bash
+pip install harbor-glovebox
+```
+
+To run the unreleased code on `main` instead, install all three packages from the repository at one revision. That needs `git` on the machine. Set `R` to the same tag or full commit for all three, since two people who install `main` on different days get different code. `--upgrade --force-reinstall` replaces a released `glovebox-driver` or `glovebox-hosts` that already satisfies the version pins:
+
+```bash
+R=git+https://github.com/AlexanderMattTurner/agent-glovebox.git@<tag-or-full-commit>
+pip install --upgrade --force-reinstall \
+  "glovebox-hosts @ $R#subdirectory=glovebox-hosts" \
+  "glovebox-driver @ $R#subdirectory=glovebox-driver" \
+  "harbor-glovebox @ $R#subdirectory=harbor-glovebox"
+```
+
+Then run a trial:
+
+```bash
+harbor run --dataset <dataset> --agent claude-code \
+  --env harbor_glovebox.environment:GloveboxEnvironment
+```
+
+The host needs what any glovebox launch needs. `glovebox sandbox preflight` checks it, and each trial runs that check before it builds anything.
+
+## Users
+
+A command runs as the `user` Harbor names, else the task's `[agent].user` or `[verifier].user`. With neither named, it runs as glovebox's de-privileged account, never as the image's own `USER`. Before that account's first command, it takes over the image's working directory and what the image's `USER` owned in its home. A task that names the image's own account keeps those files as they are. Every command inherits the image's `ENV`, as `docker exec` would carry it. Harbor names root itself for its own setup steps, such as installing the agent. Every command, root's included, sends its traffic through the in-VM filter and then the host filter outside the VM.
+
+## What it refuses, and why
+
+- **`network_mode = "public"`.** glovebox has no unfiltered mode. Use `allowlist` and list every host the task needs. Put the agent's model endpoint in Harbor's `extra_allowed_hosts`.
+- **Wildcard and IP allowlist entries.** The filter matches hostnames only. Harbor rejects such a task before it starts.
+- **A bare top-level name as an allowlist entry**, such as `com`. A public suffix with a dot, such as `github.io`, is accepted, but it reaches that one host alone. An ordinary entry also reaches one label below it, so `example.com` admits `api.example.com`. Under a public suffix that label is a stranger's name.
+- **A download larger than 1 GiB.** The guest's archive arrives in the host's memory whole, so the transfer fails rather than grow without bound.
+- **A task image that already ships `/logs`, `/tests`, `/solution` or `/harbor`.** The guest's root is read-only, so each of Harbor's fixed trees is a link onto the guest's writable `/tmp` disk, and the image build refuses to replace a tree the image carries.
+- **Multi-container tasks** (a `docker-compose.yaml` in the task's environment directory). <!-- # allow-dangling-path: a file in a Harbor task's own directory, not in this repo -->
+
+`storage_mb` is ignored, as Harbor's own Docker environment ignores it.

harbor_glovebox-0.1.0/README.md

@@ -0,0 +1,49 @@
+# harbor-glovebox
+
+Run a [Harbor](https://github.com/harbor-framework/harbor) trial inside a glovebox microVM instead of a shared-kernel container. Each trial boots one hardware-isolated VM behind glovebox's outgoing-traffic filter, and the filter's records land beside the trial's other artifacts.
+
+## Status
+
+The `harbor-trial` live check drives one trial's environment calls on a real microVM in CI, then runs `harbor run` with Harbor's oracle agent over a one-task dataset through this environment. No run over a published dataset with a model-backed agent has used it yet.
+
+## Use
+
+Install the released package:
+
+```bash
+pip install harbor-glovebox
+```
+
+To run the unreleased code on `main` instead, install all three packages from the repository at one revision. That needs `git` on the machine. Set `R` to the same tag or full commit for all three, since two people who install `main` on different days get different code. `--upgrade --force-reinstall` replaces a released `glovebox-driver` or `glovebox-hosts` that already satisfies the version pins:
+
+```bash
+R=git+https://github.com/AlexanderMattTurner/agent-glovebox.git@<tag-or-full-commit>
+pip install --upgrade --force-reinstall \
+  "glovebox-hosts @ $R#subdirectory=glovebox-hosts" \
+  "glovebox-driver @ $R#subdirectory=glovebox-driver" \
+  "harbor-glovebox @ $R#subdirectory=harbor-glovebox"
+```
+
+Then run a trial:
+
+```bash
+harbor run --dataset <dataset> --agent claude-code \
+  --env harbor_glovebox.environment:GloveboxEnvironment
+```
+
+The host needs what any glovebox launch needs. `glovebox sandbox preflight` checks it, and each trial runs that check before it builds anything.
+
+## Users
+
+A command runs as the `user` Harbor names, else the task's `[agent].user` or `[verifier].user`. With neither named, it runs as glovebox's de-privileged account, never as the image's own `USER`. Before that account's first command, it takes over the image's working directory and what the image's `USER` owned in its home. A task that names the image's own account keeps those files as they are. Every command inherits the image's `ENV`, as `docker exec` would carry it. Harbor names root itself for its own setup steps, such as installing the agent. Every command, root's included, sends its traffic through the in-VM filter and then the host filter outside the VM.
+
+## What it refuses, and why
+
+- **`network_mode = "public"`.** glovebox has no unfiltered mode. Use `allowlist` and list every host the task needs. Put the agent's model endpoint in Harbor's `extra_allowed_hosts`.
+- **Wildcard and IP allowlist entries.** The filter matches hostnames only. Harbor rejects such a task before it starts.
+- **A bare top-level name as an allowlist entry**, such as `com`. A public suffix with a dot, such as `github.io`, is accepted, but it reaches that one host alone. An ordinary entry also reaches one label below it, so `example.com` admits `api.example.com`. Under a public suffix that label is a stranger's name.
+- **A download larger than 1 GiB.** The guest's archive arrives in the host's memory whole, so the transfer fails rather than grow without bound.
+- **A task image that already ships `/logs`, `/tests`, `/solution` or `/harbor`.** The guest's root is read-only, so each of Harbor's fixed trees is a link onto the guest's writable `/tmp` disk, and the image build refuses to replace a tree the image carries.
+- **Multi-container tasks** (a `docker-compose.yaml` in the task's environment directory). <!-- # allow-dangling-path: a file in a Harbor task's own directory, not in this repo -->
+
+`storage_mb` is ignored, as Harbor's own Docker environment ignores it.

harbor_glovebox-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "harbor-glovebox"
+version = "0.1.0"
+description = "Run a Harbor trial in a hypervisor-isolated, egress-filtered glovebox microVM"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [{ name = "AlexanderMattTurner" }]
+keywords = ["harbor", "terminal-bench", "evals", "sandbox", "ai-control", "microvm"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+# Harbor is pinned to one minor release: it is pre-1.0 and its environment interface moves
+# between minors, so a wider range would admit a release this adapter was never run against.
+dependencies = ["harbor>=0.23,<0.24", "glovebox-driver>=0.6.0"]
+
+[project.urls]
+Homepage = "https://github.com/AlexanderMattTurner/agent-glovebox"
+Source = "https://github.com/AlexanderMattTurner/agent-glovebox"
+
+[build-system]
+requires = ["hatchling==1.32.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/harbor_glovebox"]

harbor_glovebox-0.1.0/src/harbor_glovebox/__init__.py

@@ -0,0 +1,6 @@
+"""Run a Harbor trial inside a glovebox microVM instead of a shared-kernel container.
+
+Harbor loads the environment with `--env harbor_glovebox.environment:GloveboxEnvironment`.
+That module is the only one that imports Harbor, so importing this package needs neither
+Harbor nor a glovebox host.
+"""

harbor_glovebox-0.1.0/src/harbor_glovebox/_image.py

@@ -0,0 +1,201 @@
+"""A Harbor task's image as the microVM's root filesystem.
+
+PROBLEM CLASS — a task names a prebuilt `docker_image` or ships a Dockerfile, and that image
+IS the environment the trial is scored in. A microVM boots ONE root filesystem, so glovebox's
+guest layers are built on top of the task's image and the result is booted. Every step here
+fails loud: a task whose image cannot be built must not fall back to glovebox's own guest
+image, which would score it against an environment missing its setup.
+
+INVARIANT: every image is named by its content id, never by the tag the task wrote. A tag is
+repointable, so a concurrent trial or a re-push could otherwise hand one trial another's bytes.
+"""
+
+import json
+import subprocess
+import tempfile
+import threading
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+from uuid import uuid4
+
+from glovebox_driver import cli
+
+# The names this module writes, so `docker image ls harbor-glovebox-*` shows what a run left.
+_BASE_REPO = "harbor-glovebox-base"
+_ROOTFS_REPO = "harbor-glovebox-rootfs"
+_STAGING_REPO = "harbor-glovebox-staging"
+
+# The guest reads its own startup file through this name, so a task's value would replace it.
+_GUEST_OWNED_ENV = frozenset({"BASH_ENV"})
+
+# Harbor writes these fixed root-level trees, and the guest's root is read-only. Each is baked
+# as a link into this scratch directory on the guest's writable /tmp disk.
+HARBOR_SCRATCH = "/tmp/gb-harbor"  # noqa: S108 — a guest path, made by root before any task command
+HARBOR_TREES = ("harbor", "logs", "solution", "tests")
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ImageConfig:
+    """What `docker exec` inherits from an image: its `WORKDIR`, `USER` and `ENV`."""
+
+    # "" when no base in the chain set one, which is docker's own answer for "the root".
+    working_dir: str
+    # "" when no base set one, which is docker's own answer for "root" too.
+    user: str
+    environment: tuple[tuple[str, str], ...]
+
+
+def pulled_image(image: str, *, refresh: bool = False) -> str:
+    """`image`, present on this host, as a tag bound to its content id; `refresh` pulls even when present.
+
+    The presence check, the pull and the binding run under one lock per name, so a concurrent
+    trial's pull cannot retag `image` between this trial's check and its binding."""
+    with _lock_for(_tag_locks, image):
+        if refresh or not _image_id(image):
+            _docker(["pull", image], announce=f"harbor-glovebox: pulling {image}.")
+        return _bound(image)
+
+
+def image_from_dockerfile(dockerfile: Path, *, no_cache: bool = False) -> str:
+    """The task's Dockerfile built with its own directory as context, as a tag bound to the result's content id.
+
+    The build lands under a one-use tag, so a concurrent build of the same task cannot retag
+    it before this one reads it back. `no_cache` rebuilds every layer and re-pulls the base,
+    which is what Harbor's `force_build` asks for."""
+    resolved = dockerfile.resolve()
+    staging = f"{_STAGING_REPO}:{uuid4().hex}"
+    fresh = ["--no-cache", "--pull"] if no_cache else []
+    try:
+        _docker(
+            [
+                "build",
+                *fresh,
+                "--tag",
+                staging,
+                "--file",
+                str(resolved),
+                str(resolved.parent),
+            ],
+            announce=f"harbor-glovebox: building {resolved}.",
+        )
+        return _bound(staging)
+    finally:
+        # Not `_docker`: this name decides nothing, and a failed removal must not mask the build.
+        subprocess.run(
+            ["docker", "image", "rm", staging],
+            capture_output=True,
+            timeout=cli.IMAGE_BUILD_TIMEOUT_S,
+            check=False,
+        )
+
+
+def with_harbor_trees(base: str) -> str:
+    """`base` with each of Harbor's root-level trees linked into `HARBOR_SCRATCH`.
+
+    COPY carries the links as links and needs no shell in the task's image. An image that
+    already ships one of these trees fails the build rather than lose it silently."""
+    with tempfile.TemporaryDirectory() as context:
+        root = Path(context) / "root"
+        root.mkdir()
+        for tree in HARBOR_TREES:
+            (root / tree).symlink_to(f"{HARBOR_SCRATCH}/{tree}")
+        dockerfile = Path(context) / "Dockerfile"
+        dockerfile.write_text(f"FROM {base}\nCOPY root/ /\n", encoding="utf-8")
+        return image_from_dockerfile(dockerfile)
+
+
+def image_config(image: str) -> ImageConfig:
+    """`image`'s own `WORKDIR`, `USER` and `ENV`, as docker resolved them through every base."""
+    config = json.loads(
+        _docker(["image", "inspect", "--format", "{{json .Config}}", image])
+    )
+    pairs = (str(entry).partition("=") for entry in config.get("Env") or ())
+    return ImageConfig(
+        working_dir=str(config.get("WorkingDir") or ""),
+        # Docker records "user:group"; only the user half names the account.
+        user=str(config.get("User") or "").split(":", maxsplit=1)[0],
+        environment=tuple(
+            (name, value)
+            for name, _, value in pairs
+            if name and name not in _GUEST_OWNED_ENV
+        ),
+    )
+
+
+_builds: dict[str, str] = {}
+_build_locks: dict[str, threading.Lock] = {}
+_tag_locks: dict[str, threading.Lock] = {}
+_builds_guard = threading.Lock()
+
+
+def _lock_for(locks: dict[str, threading.Lock], key: str) -> threading.Lock:
+    with _builds_guard:
+        return locks.setdefault(key, threading.Lock())
+
+
+def rootfs_from_image(base: str, working_dir: str) -> str:
+    """`base` with glovebox's guest layers on top, loaded into the backend's image store, as the tag a boot names.
+
+    Keyed on the base's content id and `working_dir`, which the build bakes aside for the disk
+    the cell mounts there. Concurrent trials of one image wait on one build rather than each
+    running their own."""
+    identity = _image_id(base)
+    if not identity:
+        raise RuntimeError(f"docker holds no image for {base}.")
+    key = f"{identity}\n{working_dir}"
+    with _lock_for(_build_locks, key):
+        if key not in _builds:
+            tag = _tag(_ROOTFS_REPO, key)
+            print(
+                f"harbor-glovebox: building {base} into the microVM's root filesystem. "
+                "This takes minutes; later trials of this image reuse it."
+            )
+            cli.build_rootfs(base, tag, working_dir)
+            _builds[key] = tag
+        return _builds[key]
+
+
+def _bound(image: str) -> str:
+    """A tag this module owns, bound to `image`'s content id, so no later retag of `image` moves it."""
+    identity = _image_id(image)
+    if not identity:
+        raise RuntimeError(f"docker holds no image for {image} after producing it.")
+    tag = _tag(_BASE_REPO, identity)
+    _docker(["tag", identity, tag])
+    return tag
+
+
+def _image_id(image: str) -> str:
+    """`image`'s content id on this host, or "" when this host holds no such image."""
+    held = subprocess.run(
+        ["docker", "image", "inspect", "--format", "{{.Id}}", image],
+        capture_output=True,
+        timeout=cli.IMAGE_BUILD_TIMEOUT_S,
+        check=False,
+    )
+    if held.returncode != 0:
+        return ""
+    return held.stdout.decode("utf-8", errors="replace").strip()
+
+
+def _tag(repo: str, key: str) -> str:
+    return f"{repo}:{sha256(key.encode('utf-8')).hexdigest()[:16]}"
+
+
+def _docker(args: list[str], *, announce: str | None = None) -> str:
+    """One `docker` call's stdout, raising on any failure."""
+    if announce is not None:
+        print(announce)
+    proc = subprocess.run(
+        ["docker", *args],
+        capture_output=True,
+        timeout=cli.IMAGE_BUILD_TIMEOUT_S,
+        check=False,
+    )
+    if proc.returncode != 0:
+        detail = proc.stderr.decode("utf-8", errors="replace").strip()
+        raise RuntimeError(
+            f"docker {' '.join(args)} failed (exit {proc.returncode}).\n{detail}"
+        )
+    return proc.stdout.decode("utf-8", errors="replace")

harbor_glovebox-0.1.0/src/harbor_glovebox/_policy.py

@@ -0,0 +1,83 @@
+"""How a Harbor trial's network policy and exec users map onto glovebox, with no Harbor import.
+
+Kept free of `harbor` so the rules are unit-tested without Harbor's closure, and so
+`environment.py` stays a thin translation of Harbor's calls onto them.
+"""
+
+from collections.abc import Sequence
+from ipaddress import ip_network
+
+from glovebox_driver.config import DEFAULT_GUEST_USER, Access
+
+# Harbor's `NetworkMode` values, as strings so this module needs no Harbor import.
+PUBLIC = "public"
+NO_NETWORK = "no-network"
+ALLOWLIST = "allowlist"
+
+_ROOT_NAMES: frozenset[str | int] = frozenset({"root", "0", 0})
+
+
+class UnsupportedPolicy(ValueError):
+    """A Harbor setting this environment cannot enforce exactly, refused before it takes effect."""
+
+
+def allowlist_pairs(mode: str, hosts: Sequence[str]) -> tuple[tuple[str, Access], ...]:
+    """Harbor's network policy as the host-to-access pairs glovebox's allowlist file takes.
+
+    INVARIANT: Harbor requires a provider to enforce a policy exactly or refuse it. glovebox
+    has no unfiltered mode, so `public` is refused rather than widened to a guess. An allowed
+    host gets `rw`, because Harbor's allowlist admits every request to that host.
+
+    A glovebox grant also reaches one label below its host, so `example.com` admits
+    `api.example.com`. A public suffix such as `github.io`, whose labels strangers
+    register, is held to its own host by glovebox's render instead
+    (`glovebox_hosts.grant_is_exact`). A bare top-level name like `com` is refused.
+    """
+    if mode == PUBLIC:
+        raise UnsupportedPolicy(
+            "glovebox has no unfiltered network mode, so it cannot run "
+            "network_mode='public'. Set network_mode='allowlist' and list every host the "
+            "task needs, including the agent's model endpoint (Harbor's "
+            "`extra_allowed_hosts`)."
+        )
+    if mode == NO_NETWORK:
+        return ()
+    if mode != ALLOWLIST:
+        raise UnsupportedPolicy(f"unknown Harbor network_mode {mode!r}.")
+    # Judged as glovebox reads them: surrounding whitespace is stripped before a host is
+    # matched, so a check on the raw string would let " *.example.com" through.
+    hosts = [host.strip() for host in hosts]
+    for host in hosts:
+        if host.startswith("*.") or _is_address(host):
+            raise UnsupportedPolicy(
+                f"allowlist entry {host!r} is not an exact hostname, and glovebox's "
+                "filter matches exact hostnames only."
+            )
+        if "." not in host.strip("."):
+            raise UnsupportedPolicy(
+                f"allowlist entry {host!r} is a bare top-level name, which glovebox "
+                "cannot grant. List the one host the task needs instead."
+            )
+    return tuple((host, "rw") for host in dict.fromkeys(hosts))
+
+
+def _is_address(host: str) -> bool:
+    """True for an IP address or a CIDR range, which Harbor accepts and glovebox cannot match."""
+    try:
+        ip_network(host, strict=False)
+    except ValueError:
+        return False
+    return True
+
+
+def exec_user(requested: str | int | None, default_user: str | int | None) -> str:
+    """The guest account one Harbor `exec` runs as.
+
+    An explicit `user` wins, then the task's own `[agent].user` or `[verifier].user`. With
+    neither named, the command runs as glovebox's de-privileged account, never as the image's
+    `USER`, which is usually root. Harbor names root itself for its own setup steps.
+    """
+    user = requested if requested is not None else default_user
+    if user is None:
+        return DEFAULT_GUEST_USER
+    return "root" if user in _ROOT_NAMES else str(user)

harbor_glovebox-0.1.0/src/harbor_glovebox/_trial.py

@@ -0,0 +1,329 @@
+"""One Harbor trial's microVM: build its root filesystem, boot it, run commands, move files, reap it.
+
+Everything `environment.py` does, with no Harbor import, so it runs under this repo's own
+tests and type checker. Harbor's dependency closure pins `openai<3`, which this repo's
+development environment cannot hold beside its own pin.
+"""
+
+import asyncio
+import io
+import posixpath
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import time
+from pathlib import Path, PurePosixPath
+
+from glovebox_driver import aio, cli
+from glovebox_driver.config import Access, GloveboxSandboxConfig
+from glovebox_driver.guest_account import ensure_working_dir, hand_contract_home_over
+from glovebox_driver.guest_exec import ExecOutcome
+from glovebox_driver.guest_prelude import EGRESS_FILTER_ENV_FILE
+from glovebox_driver.run import DisposableRun, EvidenceRequest
+
+from ._image import (
+    HARBOR_SCRATCH,
+    HARBOR_TREES,
+    image_config,
+    image_from_dockerfile,
+    pulled_image,
+    rootfs_from_image,
+    with_harbor_trees,
+)
+
+# A tar that writes into a guest directory as root-owned files, and one that reads out of it.
+# Paths bind to `$1`/`$2` and are never spliced into the script text. `--` keeps a member
+# named like `-C` a member. The read stops one byte past `$3`, so the host holds at most that.
+_UNPACK = 'mkdir -p "$1" && tar -x --no-same-owner -C "$1"'
+_PACK = 'set -o pipefail; tar -c -C "$1" -- "$2" | head -c "$3"'
+
+# The most one download may carry. The guest's tar arrives as one buffered reply, so a
+# directory the agent inflates must not be able to take the host's memory with it.
+MAX_DOWNLOAD_BYTES = 1 << 30
+
+# INVARIANT: every Harbor command, root's included, sources the in-VM filter's routing after
+# the caller's env, so no exec leaves the guest except through that filter. Root's exec sources
+# none of its own. With the file absent the command still runs, with no route out at all.
+_ROUTED = '[ -r "$1" ] && . "$1"; exec bash -c "$2"'
+
+
+class TransferFailed(RuntimeError):
+    """A file copy into or out of the guest did not complete."""
+
+
+def base_image(
+    environment_dir: Path, docker_image: str | None, *, force_build: bool = False
+) -> str:
+    """The Docker image the trial's root filesystem is layered on: the task's prebuilt one, else its Dockerfile built here.
+
+    A compose file is refused before either source is read: its sidecars would otherwise be
+    dropped silently, whichever image the primary service names."""
+    if (environment_dir / "docker-compose.yaml").exists():
+        raise NotImplementedError(
+            "harbor-glovebox runs single-container tasks only; this task ships a "
+            "docker-compose.yaml."
+        )
+    if docker_image:
+        return pulled_image(docker_image, refresh=force_build)
+    return image_from_dockerfile(environment_dir / "Dockerfile", no_cache=force_build)
+
+
+def evidence_request(evidence_dir: Path) -> EvidenceRequest:
+    """Where the decision log and the host-side filter log land, captured before teardown reaps the run."""
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+    return EvidenceRequest(
+        traffic=evidence_dir / "egress.jsonl",
+        host_filter=evidence_dir / "egress-host-filter.jsonl",
+    )
+
+
+def pack(members: list[tuple[Path, str]]) -> bytes:
+    """Each `(path, arcname)` as a tar entry, with no `.` entry, so a target directory keeps its own owner and mode."""
+    buffer = io.BytesIO()
+    with tarfile.open(fileobj=buffer, mode="w") as archive:
+        for path, arcname in members:
+            archive.add(path, arcname=arcname)
+    return buffer.getvalue()
+
+
+def unpack(data: bytes, into: Path) -> None:
+    """Extract a tar the guest produced under `into`, refusing any member that would land outside it."""
+    into.mkdir(parents=True, exist_ok=True)
+    # nosemgrep: tarfile-extractall-traversal — filter="data" is the refusal the rule asks for
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r") as archive:
+        archive.extractall(into, filter="data")
+
+
+def _land(data: bytes, target: Path, name: str, *, is_dir: bool) -> None:
+    """A guest tar at `target`: a directory's members under it, or the one member `name` as it."""
+    if is_dir:
+        unpack(data, target)
+        return
+    with tempfile.TemporaryDirectory() as scratch:
+        unpack(data, Path(scratch))
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(Path(scratch) / name, target)
+
+
+class GloveboxTrial:
+    """One booted microVM, driven through `glovebox_driver`, with Harbor's operations on top."""
+
+    def __init__(self, *, config: GloveboxSandboxConfig, evidence_dir: Path) -> None:
+        self._config = config
+        self._evidence_dir = evidence_dir
+        self._run: DisposableRun | None = None
+        self._handed_over = False
+        self._hand_over_lock = asyncio.Lock()
+
+    @property
+    def run(self) -> DisposableRun:
+        """The booted run, which exists only between `start` and `stop`."""
+        if self._run is None:
+            raise RuntimeError("the glovebox microVM is not running.")
+        return self._run
+
+    async def start(self) -> None:
+        """Stage an empty workspace, boot the microVM onto it, and make the trees Harbor writes.
+
+        Root makes them before any other command runs, so no later account owns their roots."""
+        staged = await aio.stage_run(
+            self._config, evidence=evidence_request(self._evidence_dir)
+        )
+        self._run = await aio.boot(staged)
+        try:
+            await self._make_trees()
+        except BaseException:
+            # The caller's cleanup begins only once this returns, so the booted VM is reaped here.
+            await self.stop(failed=True)
+            raise
+
+    async def _make_trees(self) -> None:
+        trees = [f"{HARBOR_SCRATCH}/{tree}" for tree in HARBOR_TREES]
+        made = await self._guest(["mkdir", "-p", "-m", "0755", *trees], "root")
+        if made.returncode != 0:
+            raise RuntimeError(
+                "could not make Harbor's directories in the guest: "
+                + made.stderr.decode("utf-8", "replace").strip()
+            )
+
+    async def _hand_over_once(self) -> None:
+        """Give the de-privileged account what the image's own `USER` owned, before its first command.
+
+        Deferred to that command, never run at boot: a task whose `[agent].user` names the
+        image's own account runs as that account, which already owns its files."""
+        async with self._hand_over_lock:
+            if self._handed_over:
+                return
+            await asyncio.to_thread(self._hand_task_dirs_over, self.run)
+            self._handed_over = True
+
+    def _hand_task_dirs_over(self, run: DisposableRun) -> None:
+        config = self._config
+        hand_contract_home_over(run.session, config.user, config.working_dir)
+        if config.working_dir:
+            ensure_working_dir(run.session, config.working_dir, config.user)
+
+    async def stop(self, *, failed: bool = False) -> None:
+        """Export the egress records, then reap the VM. A second call does nothing."""
+        run, self._run = self._run, None
+        if run is not None:
+            await aio.close(run, failed=failed)
+
+    async def exec(  # pylint: disable=too-many-arguments  # Harbor's exec signature
+        self,
+        command: str,
+        *,
+        user: str,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        timeout_sec: int | None = None,
+    ) -> ExecOutcome:
+        """Run `command` under bash in the guest as `user`, a name or a uid, as Harbor's Docker environment does.
+
+        `timeout_sec` bounds the account lookup and the command together."""
+        deadline = None if timeout_sec is None else time.monotonic() + timeout_sec
+        try:
+            account = await self._account(user, deadline)
+            if account == self._config.user:
+                await self._hand_over_once()
+            routed = ["bash", "-c", _ROUTED, "_", EGRESS_FILTER_ENV_FILE, command]
+            return await self._guest(
+                routed, account, cwd=cwd, env=env, timeout=_remaining(deadline)
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(
+                f"Command timed out after {timeout_sec} seconds"
+            ) from exc
+
+    async def _account(self, user: str, deadline: float | None) -> str:
+        """`user` as the account name `runuser` takes; a bare uid is looked up in the guest."""
+        if not user.isdigit():
+            return user
+        found = await self._guest(
+            ["getent", "passwd", user], "root", timeout=_remaining(deadline)
+        )
+        name = found.stdout.decode("utf-8", "replace").split(":", 1)[0]
+        if found.returncode != 0 or not name:
+            raise RuntimeError(f"uid {user} names no account in the guest.")
+        return name
+
+    async def upload(self, source: Path, target: str) -> None:
+        """Copy a host file or directory to `target` in the guest, as root."""
+        dest = PurePosixPath(target)
+        if source.is_dir():
+            into, members = dest, [(c, c.name) for c in sorted(source.iterdir())]
+        else:
+            into, members = dest.parent, [(source, dest.name)]
+        script = ["sh", "-c", _UNPACK, "_", str(into)]
+        # Packed off the event loop, so a large task directory stalls no other trial.
+        data = await asyncio.to_thread(pack, members)
+        outcome = await self._guest(script, "root", data=data)
+        if outcome.returncode != 0:
+            raise TransferFailed(
+                f"copying {source} to {target} failed in the guest: "
+                + outcome.stderr.decode("utf-8", "replace").strip()
+            )
+
+    async def download(self, source: str, target: Path, *, is_dir: bool) -> None:
+        """Copy a guest file or directory to `target` on the host, refusing one past `MAX_DOWNLOAD_BYTES`."""
+        src = PurePosixPath(source)
+        parent, member = (src, ".") if is_dir else (src.parent, src.name)
+        cap = str(MAX_DOWNLOAD_BYTES + 1)
+        script = ["bash", "-c", _PACK, "_", str(parent), member, cap]
+        outcome = await self._guest(script, "root")
+        if len(outcome.stdout) > MAX_DOWNLOAD_BYTES:
+            raise TransferFailed(
+                f"{source} packs to more than {MAX_DOWNLOAD_BYTES} bytes, the most one "
+                "download carries."
+            )
+        if outcome.returncode != 0:
+            raise TransferFailed(
+                f"reading {source} out of the guest failed: "
+                + outcome.stderr.decode("utf-8", "replace").strip()
+            )
+        await asyncio.to_thread(_land, outcome.stdout, target, src.name, is_dir=is_dir)
+
+    async def _guest(  # pylint: disable=too-many-arguments  # the run's own exec seams
+        self,
+        cmd: list[str],
+        user: str,
+        *,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        data: bytes | None = None,
+        timeout: float | None = None,
+    ) -> ExecOutcome:
+        """`cmd` run through the run's own exec, off the event loop."""
+        return await asyncio.to_thread(
+            self.run.exec,
+            cmd,
+            user=user,
+            cwd=cwd,
+            env=env,
+            input_bytes=data,
+            timeout=timeout,
+        )
+
+
+def _remaining(deadline: float | None) -> float | None:
+    """The seconds left before `deadline`, raising as Harbor does once none are."""
+    if deadline is None:
+        return None
+    left = deadline - time.monotonic()
+    if left <= 0:
+        raise RuntimeError("Command timed out before it started")
+    return left
+
+
+def _canonical_dir(path: str) -> str:
+    """One spelling of an absolute directory, so the hand-over's textual refusal of system paths holds.
+
+    `/opt/../etc` would otherwise read as living under `/opt`. POSIX keeps a leading `//`
+    through `normpath`, and Linux resolves it to `/`, so that run is collapsed first."""
+    if path.startswith("//"):
+        path = "/" + path.lstrip("/")
+    return posixpath.normpath(path)
+
+
+def task_config(  # pylint: disable=too-many-arguments  # one per task field a boot reads
+    *,
+    environment_dir: Path,
+    docker_image: str | None,
+    workdir: str | None,
+    allowlist: tuple[tuple[str, Access], ...],
+    cpus: int | None,
+    memory_mb: int | None,
+    force_build: bool = False,
+) -> GloveboxSandboxConfig:
+    """A task's boot config: its image under glovebox's guest layers, with the image's `WORKDIR` and `ENV`.
+
+    Refuses a host that cannot boot a microVM before the image costs minutes to build. The
+    image's own startup command never runs, as under Harbor's own compose files. Its `ENV`
+    reaches every Harbor command, as `docker exec` would carry it, under the caller's own."""
+    cli.preflight()
+    base = base_image(environment_dir, docker_image, force_build=force_build)
+    inherited = image_config(base)
+    booted = with_harbor_trees(base)
+    working_dir = _canonical_dir(workdir or inherited.working_dir or "")
+    fields: dict[str, object] = {
+        "allowlist": allowlist,
+        "cpus": cpus,
+        "environment": inherited.environment,
+    }
+    if memory_mb:
+        fields["memory"] = f"{memory_mb}m"
+    if working_dir != ".":
+        fields["working_dir"] = working_dir
+    fields["rootfs_image"] = rootfs_from_image(
+        booted, str(fields.get("working_dir", ""))
+    )
+    return GloveboxSandboxConfig.model_validate(fields)
+
+
+__all__ = [
+    "MAX_DOWNLOAD_BYTES",
+    "GloveboxTrial",
+    "TransferFailed",
+    "task_config",
+]

harbor_glovebox-0.1.0/src/harbor_glovebox/environment.py

@@ -0,0 +1,149 @@
+"""Harbor's `BaseEnvironment` on a glovebox microVM: `--env harbor_glovebox.environment:GloveboxEnvironment`.
+
+A translation layer only. The policy mapping lives in `_policy` and the VM lifecycle in
+`_trial`, both free of Harbor so this repo's own tests reach them. This module is the one
+file that imports Harbor, whose dependency closure this repo's environment cannot install.
+"""
+# pyright: reportMissingImports=false
+# pylint: disable=import-error  # Harbor pins openai<3, which this repo's dev environment cannot hold
+
+import asyncio
+from collections.abc import Sequence
+from pathlib import Path
+
+from harbor.environments.base import BaseEnvironment, EnvironmentPath, ExecResult
+from harbor.environments.capabilities import EnvironmentCapabilities
+from harbor.models.task.config import NetworkPolicy
+
+from . import _policy
+from ._trial import GloveboxTrial, task_config
+
+
+class GloveboxEnvironment(BaseEnvironment):
+    """One Harbor trial in one hypervisor-isolated, egress-filtered glovebox microVM."""
+
+    _trial: GloveboxTrial | None = None
+
+    @staticmethod
+    def type() -> str:
+        return "glovebox"
+
+    @property
+    def capabilities(self) -> EnvironmentCapabilities:
+        """What Harbor may ask of this environment; Harbor refuses a task needing more before start."""
+        return EnvironmentCapabilities(
+            disable_internet=True,
+            network_allowlist=True,
+            network_allowlist_hostnames=True,
+        )
+
+    def _validate_definition(self) -> None:
+        if self.task_env_config.docker_image:
+            return
+        if not (self.environment_dir / "Dockerfile").exists():
+            raise FileNotFoundError(
+                f"{self.environment_dir} has no Dockerfile and the task names no docker_image."
+            )
+
+    def validate_network_policy_support(
+        self, network_policy: NetworkPolicy | None = None
+    ) -> None:
+        super().validate_network_policy_support(network_policy)
+        policy = network_policy or self.network_policy
+        _policy.allowlist_pairs(policy.network_mode.value, policy.allowed_hosts)
+
+    async def start(self, force_build: bool) -> None:
+        policy = self.network_policy
+        config = await asyncio.to_thread(
+            task_config,
+            environment_dir=self.environment_dir,
+            docker_image=self.task_env_config.docker_image,
+            workdir=self.task_env_config.workdir,
+            allowlist=_policy.allowlist_pairs(
+                policy.network_mode.value, policy.allowed_hosts
+            ),
+            cpus=self.task_env_config.cpus,
+            memory_mb=self.task_env_config.memory_mb,
+            force_build=force_build,
+        )
+        self._trial = GloveboxTrial(
+            config=config, evidence_dir=self.trial_paths.artifacts_dir / "glovebox"
+        )
+        await self._trial.start()
+        try:
+            # Nothing bind-mounts Harbor's log directories here, so they are made in the guest.
+            await self.ensure_dirs(self._mount_targets(writable_only=True))
+            await self._upload_environment_dir_after_start()
+        except BaseException:
+            await self._trial.stop(failed=True)
+            raise
+
+    async def ensure_dirs(
+        self, dirs: Sequence[EnvironmentPath], *, chmod: bool = True
+    ) -> ExecResult | None:
+        """Harbor's directory setup, raised on failure rather than returned and ignored."""
+        return _checked(await super().ensure_dirs(dirs, chmod=chmod), dirs)
+
+    async def empty_dirs(
+        self, dirs: Sequence[EnvironmentPath], *, chmod: bool = True
+    ) -> ExecResult | None:
+        """Harbor's directory reset, raised on failure: a stale `/tests` would change the score."""
+        return _checked(await super().empty_dirs(dirs, chmod=chmod), dirs)
+
+    async def stop(self, delete: bool) -> None:  # noqa: ARG002  # pylint: disable=unused-argument  # a microVM is always deleted
+        if self._trial is not None:
+            await self._trial.stop()
+
+    async def exec(  # pylint: disable=too-many-arguments,too-many-positional-arguments  # Harbor's exec signature
+        self,
+        command: str,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        timeout_sec: int | None = None,
+        user: str | int | None = None,
+    ) -> ExecResult:
+        trial = self._require_trial()
+        run_user = _policy.exec_user(user, self.default_user)
+        outcome = await trial.exec(
+            command,
+            user=run_user,
+            cwd=cwd,
+            env=self._merge_env(env),
+            timeout_sec=timeout_sec,
+        )
+        return ExecResult(
+            stdout=outcome.stdout.decode("utf-8", "replace") or None,
+            stderr=outcome.stderr.decode("utf-8", "replace") or None,
+            return_code=outcome.returncode,
+        )
+
+    async def upload_file(self, source_path: Path | str, target_path: str) -> None:
+        await self._require_trial().upload(Path(source_path), target_path)
+
+    async def upload_dir(self, source_dir: Path | str, target_dir: str) -> None:
+        await self._require_trial().upload(Path(source_dir), target_dir)
+
+    async def download_file(self, source_path: str, target_path: Path | str) -> None:
+        await self._require_trial().download(
+            source_path, Path(target_path), is_dir=False
+        )
+
+    async def download_dir(self, source_dir: str, target_dir: Path | str) -> None:
+        await self._require_trial().download(source_dir, Path(target_dir), is_dir=True)
+
+    def _require_trial(self) -> GloveboxTrial:
+        if self._trial is None:
+            raise RuntimeError("the glovebox environment has not been started.")
+        return self._trial
+
+
+def _checked(
+    result: ExecResult | None, dirs: Sequence[EnvironmentPath]
+) -> ExecResult | None:
+    """`result`, raising when the guest command behind it failed."""
+    if result is not None and result.return_code != 0:
+        raise RuntimeError(
+            f"preparing {dirs} in the guest failed (exit {result.return_code}): "
+            f"{(result.stderr or '').strip()}"
+        )
+    return result