saferun-cli 0.0.2__py3-none-any.whl

saferun/sandbox/copy_windows.py

@@ -0,0 +1,281 @@
+"""Windows copy engine: the same algorithm and guarantees-by-detection as copy.py, on Win32 handles (see hostos/winfs.py).
+
+Three passes over the tree (pre-scan, verified copy, final validation) compare a signature per entry (type, attributes, 128-bit file id,
+size, LastWrite and Change time, link count) and the name set of every directory; any replaced, added, removed or modified entry abandons
+the whole copy (WorkspaceChangedError). On top of that, Windows lets us hold directories and files open with a share mode that forbids
+rename / delete / write, which prevents what the POSIX engine can only detect (see winfs.py for exactly what is and is not prevented).
+
+Not copied, and reported as skipped: symlinks and every other reparse point (junctions, mount points, cloud placeholders) and entries
+with an alternate data stream other than Zone.Identifier. Withheld: files whose access list is narrower than the project root's
+(or cannot be read), and files with a credential signature. Hard links with names outside the tree are skipped.
+
+This module has no Windows-only imports: it runs against any `FsOps`, which is how its logic is tested on every platform.
+"""
+from __future__ import annotations
+
+import ntpath
+import os
+from collections import Counter
+
+from ..hostos.fsops import EntryReplaced, FsOps, Info
+from .config import (
+    SandboxError, SensitivePolicy, SkippedEntry, WithheldEntry, WorkspaceChangedError, WorkspaceLimits,
+)
+from .copy import CHUNK, CopyResult, _Budget
+from .secrets import LEARN_MAX, Redactor, SignatureScanner
+
+
+def _changed(path: str, what: str) -> WorkspaceChangedError:
+    return WorkspaceChangedError(
+        f"{path or '.'}: {what} while SafeRun was copying; the copy was abandoned (retry on a quiescent tree)")
+
+
+class _Sink:
+    """Writes the copy under `dest` (a directory we own and created)."""
+
+    def __init__(self, dest: str, ops: FsOps):
+        self.dest, self.ops = dest, ops
+
+    def _p(self, rel: str) -> str:
+        p = os.path.join(self.dest, *rel.split("/"))
+        # Extended-length form. Not os.path.abspath(): Win32 normalisation turns a final component such as CON into the device path \\.\CON.
+        # `dest` is absolute and `rel` comes from a directory listing, so cleaning up the string is all that is needed.
+        return "\\\\?\\" + ntpath.normpath(p) if os.name == "nt" else p
+
+    def mkdir(self, rel: str) -> None:
+        os.mkdir(self._p(rel))
+
+    def write(self, rel, node, want: Info, budget: _Budget, redactor: Redactor, withhold_on_match: bool):
+        dest, scanner, kind = self._p(rel), SignatureScanner(), None
+        head: bytearray | None = bytearray()
+        written = read = 0
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOINHERIT", 0)
+        try:
+            fd = os.open(dest, flags, 0o644)
+        except FileExistsError:
+            raise SandboxError(f"{rel}: another entry with the same name (differing only in case) was already copied") from None
+        try:
+            while chunk := self.ops.read(node, CHUNK):
+                read += len(chunk)
+                budget.add_bytes(len(chunk))
+                kind = kind or scanner.feed(chunk)
+                if kind and withhold_on_match:
+                    break
+                if head is not None:
+                    head += chunk
+                    head = head if len(head) <= LEARN_MAX else None
+                view = memoryview(chunk)
+                while view:
+                    n = os.write(fd, view)
+                    written += n
+                    view = view[n:]
+        finally:
+            os.close(fd)
+        if kind and withhold_on_match:
+            os.unlink(dest)
+            return kind, 0
+        after = self.ops.refresh(node)
+        if read != want.size or after.sig != want.sig:
+            raise _changed(rel, "file was modified while being read")
+        if head is not None:
+            redactor.learn(bytes(head))
+        return None, written
+
+
+class _Walker:
+    """One traversal. sink=None is the pre-scan (nothing is read or written)."""
+
+    def __init__(self, ops: FsOps, lim: WorkspaceLimits, policy: SensitivePolicy, sink: _Sink | None,
+                 seen_links: Counter | None = None, expected: dict | None = None, expected_listings: dict | None = None):
+        self.ops, self.budget, self.policy, self.sink = ops, _Budget(lim), policy, sink
+        self.skipped: list[SkippedEntry] = []
+        self.withheld: list[WithheldEntry] = []
+        self.redactor = Redactor()
+        self.copied_files = self.copied_dirs = self.copied_bytes = 0
+        self.links: Counter = Counter()
+        self.seen_links = seen_links or Counter()
+        self.records: dict[str, tuple] = {}
+        self.listings: dict[str, frozenset] = {}
+        self.expected, self.expected_listings = expected, expected_listings
+
+    def _private(self, path: str, info: Info) -> bool:
+        if self.policy.honor_private_modes and path not in self.policy.allow_paths and info.private:
+            self.withheld.append(WithheldEntry(path, "private-mode"))
+            return True
+        return False
+
+    def _verify(self, path: str, want: tuple) -> None:
+        if self.expected is None:
+            self.records[path] = want
+        elif self.expected.get(path) != want:
+            raise _changed(path, "entry was replaced, added or modified")
+
+    def _list(self, d, rel: str) -> list[str]:
+        exp = None
+        if self.expected_listings is not None:
+            exp = self.expected_listings.get(rel)
+            if exp is None:
+                raise _changed(rel, "directory was not part of the pre-scan")
+        names = self.ops.listdir(d)
+        for name in names:
+            self.budget.entry()
+            if exp is not None and name not in exp:
+                raise _changed(f"{rel}/{name}" if rel else name, "entry was added")
+        if exp is not None:
+            if len(names) != len(exp):
+                raise _changed(rel, "an entry was removed")
+        else:
+            self.listings[rel] = frozenset(names)
+        return sorted(names)
+
+    def walk(self, d, rel: str, depth: int) -> None:
+        for name in self._list(d, rel):
+            path = f"{rel}/{name}" if rel else name
+            try:
+                info = self.ops.probe(d, name, True)
+            except FileNotFoundError:
+                raise _changed(path, "entry was removed") from None
+            except OSError:
+                self.skipped.append(SkippedEntry(path, "unreadable"))
+                continue
+            self._verify(path, info.sig)
+            if info.kind == "symlink":
+                self.skipped.append(SkippedEntry(path, "symlink"))
+            elif info.kind == "reparse":
+                self.skipped.append(SkippedEntry(path, "reparse-point"))
+            elif info.kind == "dir":
+                self._dir(d, name, path, info, depth)
+            elif info.kind == "file":
+                self._file(d, name, path, info)
+            else:
+                self.skipped.append(SkippedEntry(path, "not-regular-file"))
+
+    def _streams_skip(self, d, name: str, path: str) -> bool:
+        try:
+            extra = self.ops.streams(d, name)
+        except OSError:
+            self.skipped.append(SkippedEntry(path, "unreadable"))
+            return True
+        if extra:
+            self.skipped.append(SkippedEntry(path, "alternate-data-stream"))
+            return True
+        return False
+
+    def _open(self, opener, d, name: str, path: str, want: Info):
+        try:
+            node = opener(d, name)
+        except EntryReplaced:
+            raise _changed(path, "entry was replaced or moved") from None
+        except (FileNotFoundError, NotADirectoryError):
+            raise _changed(path, "entry was replaced or removed") from None
+        except OSError:
+            self.skipped.append(SkippedEntry(path, "unreadable"))
+            return None
+        if node.info.sig != want.sig:
+            self.ops.close(node)
+            raise _changed(path, "entry was replaced or modified")
+        return node
+
+    def _dir(self, d, name, path, info: Info, depth):
+        self.budget.depth(depth + 1)
+        if self._private(path, info) or self._streams_skip(d, name, path):   # same in both passes: such a directory is never entered
+            return
+        node = self._open(self.ops.open_dir, d, name, path, info)
+        if node is None:
+            return
+        try:
+            if self.sink:
+                self.sink.mkdir(path)
+                self.copied_dirs += 1
+            self.walk(node, path, depth + 1)
+        finally:
+            self.ops.close(node)
+
+    def _file(self, d, name, path, info: Info):
+        if self.sink is None:   # pre-scan
+            if info.nlink > 1:
+                self.links[info.ident] += 1
+            if not (self.policy.honor_private_modes and path not in self.policy.allow_paths and info.private):
+                self.budget.add_bytes(info.size)
+            return
+        if self._private(path, info):   # never opened, never read
+            return
+        if self._streams_skip(d, name, path):
+            return
+        node = self._open(self.ops.open_file, d, name, path, info)
+        if node is None:
+            return
+        try:
+            if node.info.nlink > 1 and self.seen_links[node.info.ident] != node.info.nlink:
+                self.skipped.append(SkippedEntry(path, "hardlink-external"))
+                return
+            kind, kept = self.sink.write(path, node, info, self.budget, self.redactor,
+                                         withhold_on_match=path not in self.policy.allow_paths)
+            if kind:
+                self.withheld.append(WithheldEntry(path, kind))
+            else:
+                self.copied_files += 1
+                self.copied_bytes += kept
+        finally:
+            self.ops.close(node)
+
+
+def _validate_tree(ops: FsOps, d, rel: str, records: dict, listings: dict, budget: _Budget) -> None:
+    """Final pass: everything below `d` must still be exactly what the pre-scan recorded."""
+    expected = listings[rel]
+    names = ops.listdir(d)
+    for name in names:
+        budget.entry()
+        if name not in expected:
+            raise _changed(f"{rel}/{name}" if rel else name, "entry was added (final check)")
+    if len(names) != len(expected):
+        raise _changed(rel, "an entry was removed (final check)")
+    for name in sorted(names):
+        path = f"{rel}/{name}" if rel else name
+        try:
+            info = ops.probe(d, name, False)
+        except FileNotFoundError:
+            raise _changed(path, "entry was removed (final check)") from None
+        except OSError:
+            if path in records:
+                raise _changed(path, "entry became unreadable (final check)") from None
+            continue
+        if records.get(path) != info.sig:
+            raise _changed(path, "entry was replaced or modified (final check)")
+        if info.kind == "dir" and path in listings:
+            try:
+                node = ops.open_dir(d, name)
+            except OSError:
+                raise _changed(path, "directory was replaced or removed (final check)") from None
+            try:
+                if node.info.sig != records[path]:
+                    raise _changed(path, "directory was replaced or modified (final check)")
+                _validate_tree(ops, node, path, records, listings, budget)
+            finally:
+                ops.close(node)
+
+
+def copy_tree(src: str, dest: str, lim: WorkspaceLimits, policy: SensitivePolicy | None = None, ops: FsOps | None = None) -> CopyResult:
+    """Same contract as copy.copy_tree."""
+    policy = policy or SensitivePolicy()
+    if ops is None:
+        from ..hostos.winfs import WinOps
+        ops = WinOps()
+    try:
+        root = ops.open_root(src)
+    except EntryReplaced as e:
+        raise _changed("", str(e)) from None
+    try:
+        pre = _Walker(ops, lim, policy, None)
+        pre.records[""] = root.info.sig
+        pre.walk(root, "", 0)
+        w = _Walker(ops, lim, policy, _Sink(dest, ops), pre.links, pre.records, pre.listings)
+        if ops.refresh(root).sig != pre.records[""]:
+            raise _changed("", "the project root was modified")
+        w.walk(root, "", 0)
+        if ops.refresh(root).sig != pre.records[""]:
+            raise _changed("", "the project root was modified (final check)")
+        _validate_tree(ops, root, "", pre.records, pre.listings, _Budget(lim))
+        return CopyResult(w.skipped, w.withheld, w.budget.files, w.copied_files, w.copied_dirs, w.copied_bytes, w.redactor)
+    finally:
+        ops.close(root)

saferun/sandbox/cosign_tool.py

@@ -0,0 +1,134 @@
+"""A pinned, hash-verified copy of cosign that SafeRun fetches itself, so users do not have to install it.
+
+Trust model: the expected SHA-256 of every supported cosign binary is written in THIS file (taken from the upstream release's
+`cosign_checksums.txt`, v2.4.3, the version the release workflow uses). A download is written to a temporary file in the private
+tool directory, hashed, and only a file whose SHA-256 equals the pin is made executable and moved into place. The file is hashed
+again every time it is looked up, so a binary that was modified later is ignored (and re-fetched by `saferun init`). Nothing else is
+trusted: not the redirect target, not the file name, not the HTTP headers. HTTPS only, size-capped.
+What this does NOT give you: it trusts the hashes in this reviewed source file, and the GitHub release that they were copied from.
+The cosign binary then verifies the analyzer image's signature exactly as before (signature.py); the identity check is unchanged.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import platform
+import sys
+import tempfile
+import urllib.request
+from pathlib import Path
+
+from .. import hostos
+from .config import SandboxError
+
+COSIGN_VERSION = "2.4.3"
+BASE_URL = f"https://github.com/sigstore/cosign/releases/download/v{COSIGN_VERSION}"
+MAX_BYTES = 200 * 1024 * 1024
+# (system, machine) -> (release asset, sha256). Source: cosign_checksums.txt of release v2.4.3.
+ASSETS = {
+    ("linux", "x86_64"): ("cosign-linux-amd64", "caaad125acef1cb81d58dcdc454a1e429d09a750d1e9e2b3ed1aed8964454708"),
+    ("linux", "aarch64"): ("cosign-linux-arm64", "bd0f9763bca54de88699c3656ade2f39c9a1c7a2916ff35601caf23a79be0629"),
+    ("darwin", "x86_64"): ("cosign-darwin-amd64", "98a3bfd691f42c6a5b721880116f89210d8fdff61cc0224cd3ef2f8e55a466fb"),
+    ("darwin", "arm64"): ("cosign-darwin-arm64", "edfc761b27ced77f0f9ca288ff4fac7caa898e1e9db38f4dfdf72160cdf8e638"),
+    ("windows", "x86_64"): ("cosign-windows-amd64.exe", "a2ac24e197111c9430cb2a98f10a641164381afb83df036504868e4ea5720800"),
+}
+_MACHINE_ALIASES = {"amd64": "x86_64", "x64": "x86_64", "arm64": "aarch64"}
+
+
+class CosignFetchError(SandboxError):
+    """The pinned cosign could not be obtained or did not match its pinned hash. Nothing was installed."""
+
+
+def platform_key(system: str | None = None, machine: str | None = None) -> tuple[str, str]:
+    s = (system or platform.system()).lower()
+    m = (machine or platform.machine()).lower()
+    if s == "darwin":
+        m = {"amd64": "x86_64", "x64": "x86_64"}.get(m, m)           # Apple silicon reports arm64
+    else:
+        m = _MACHINE_ALIASES.get(m, m)
+    return s, m
+
+
+def asset_for(system: str | None = None, machine: str | None = None) -> tuple[str, str]:
+    key = platform_key(system, machine)
+    if key not in ASSETS:
+        raise CosignFetchError(f"no pinned cosign build for {key[0]}/{key[1]}; install cosign {COSIGN_VERSION}+ yourself "
+                               "(https://docs.sigstore.dev/cosign/system_config/installation/) and put it on PATH")
+    return ASSETS[key]
+
+
+def tool_dir() -> Path:
+    return hostos.user_data_base() / "saferun" / "bin"
+
+
+def managed_path(system: str | None = None) -> Path:
+    exe = ".exe" if (system or sys.platform).lower().startswith(("win", "windows")) else ""
+    return tool_dir() / f"cosign-{COSIGN_VERSION}{exe}"
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while chunk := f.read(1 << 20):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def managed_cosign() -> str | None:
+    """Absolute path of the managed cosign if it exists, is a regular file (no symlink) and still has its pinned hash; else None. Never raises."""
+    try:
+        want = asset_for()[1]
+        p = managed_path()
+        if p.is_symlink() or not p.is_file() or _sha256(p) != want:
+            return None
+        return str(p.resolve())
+    except (OSError, SandboxError):
+        return None
+
+
+def ensure_cosign(*, opener=None, progress=None) -> str:
+    """Return the managed cosign, downloading and verifying it first if needed. Raises CosignFetchError (nothing is left behind)."""
+    have = managed_cosign()
+    if have:
+        return have
+    name, want = asset_for()
+    url = f"{BASE_URL}/{name}"
+    if not url.startswith("https://"):
+        raise CosignFetchError("cosign must be downloaded over https")
+    opener = opener or urllib.request.urlopen
+    d = tool_dir()
+    if d.is_symlink():
+        raise CosignFetchError(f"refusing to use a symlink as the tool directory: {d}")
+    try:
+        hostos.ensure_private_dir(d.parent)      # <data>/saferun also holds the analyzer lock, which requires it to be owner-only
+        hostos.ensure_private_dir(d)
+        fd, tmp = tempfile.mkstemp(dir=d, prefix=".cosign-")
+    except OSError as e:
+        raise CosignFetchError(f"cannot prepare {d}: {e}") from None
+    try:
+        h, size = hashlib.sha256(), 0
+        with os.fdopen(fd, "wb") as out, opener(url, timeout=120) as resp:  # noqa: S310 - https enforced above
+            while chunk := resp.read(1 << 20):
+                size += len(chunk)
+                if size > MAX_BYTES:
+                    raise CosignFetchError(f"download exceeds {MAX_BYTES} bytes; refused")
+                h.update(chunk)
+                out.write(chunk)
+                if progress:
+                    progress("cosign", size, None)
+        if h.hexdigest() != want:
+            raise CosignFetchError("the downloaded cosign does not match its pinned SHA-256; it was discarded and NOT installed")
+        if not hostos.IS_WINDOWS:
+            os.chmod(tmp, 0o700)
+        os.replace(tmp, managed_path())
+    except CosignFetchError:
+        raise
+    except OSError as e:                      # URLError, timeouts and disk errors are all OSError subclasses
+        raise CosignFetchError(f"could not download cosign from {url}: {e}") from None
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+    got = managed_cosign()
+    if not got:
+        raise CosignFetchError("cosign was installed but could not be verified afterwards")
+    return got

saferun/sandbox/docker.py

@@ -0,0 +1,167 @@
+"""Thin, defensive wrappers over the docker CLI. Never uses a shell; args are lists.
+
+Everything Docker returns is treated as untrusted input: unexpected output becomes a
+SandboxError, never a raw exception and never a silent "success".
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+
+from .. import hostos
+from .config import CONTAINER_LABEL, ControlStatus, SandboxError
+from .controls import REQUIRED_DAEMON, daemon_controls
+from .images import digest_of, repo_digests
+
+DEFAULT_TIMEOUT = 30  # seconds per docker CLI call (module attribute so tests can shorten it)
+# Plain image reference only: must not start with "-" (would be parsed as a docker option).
+_IMAGE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/:@+-]{0,254}$")
+_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def docker_bin() -> str:
+    """Absolute path of the docker executable (PATH is trusted; see PROJECT.md)."""
+    path = shutil.which("docker")
+    if not path:
+        raise SandboxError("docker executable not found on PATH")
+    return os.path.abspath(path)
+
+
+def docker(*args: str, timeout: float | None = None) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            [docker_bin(), *args], capture_output=True, text=True, errors="replace",
+            timeout=DEFAULT_TIMEOUT if timeout is None else timeout, stdin=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        raise SandboxError(f"docker {args[0] if args else ''} failed: {e}") from e
+
+
+def validate_image(image: str) -> str:
+    if not isinstance(image, str) or not _IMAGE_RE.match(image):
+        raise SandboxError(f"invalid image reference: {image!r}")
+    return image
+
+
+def check_local_daemon() -> None:
+    """Refuse a remote daemon: the workspace is bind-mounted by host path, so a remote
+    DOCKER_HOST / context would resolve that path on another machine."""
+    host = os.environ.get("DOCKER_HOST")
+    if host is None:
+        r = docker("context", "inspect", "--format", "{{.Endpoints.docker.Host}}")
+        if r.returncode != 0:
+            raise SandboxError(f"cannot determine the docker endpoint: {r.stderr.strip()}")
+        host = r.stdout.strip()
+    if not hostos.docker_endpoint_is_local(host):
+        only = "local named pipes (npipe:////./pipe/...)" if hostos.IS_WINDOWS else "unix:// sockets"
+        raise SandboxError(f"refusing non-local docker endpoint {host!r} (only {only} are supported)")
+
+
+def daemon_info() -> dict:
+    r = docker("info", "--format", "{{json .}}")
+    if r.returncode != 0:
+        raise SandboxError(f"docker daemon unavailable: {r.stderr.strip()}")
+    try:
+        info = json.loads(r.stdout)
+    except ValueError as e:
+        raise SandboxError(f"unexpected `docker info` output: {e}") from e
+    if not isinstance(info, dict):
+        raise SandboxError("unexpected `docker info` output: not an object")
+    return info
+
+
+def resolve_image(image: str) -> str:
+    """Image ID (sha256:...) of a *local* image. SafeRun never pulls implicitly."""
+    r = docker("image", "inspect", "--format", "{{.Id}}", validate_image(image))
+    if r.returncode != 0:
+        raise SandboxError(f"image {image!r} not present locally (SafeRun never pulls implicitly)")
+    image_id = r.stdout.strip()
+    if not _IMAGE_ID_RE.match(image_id):
+        raise SandboxError(f"unexpected image id from docker: {image_id!r}")
+    pinned = digest_of(image)
+    if pinned is not None:
+        verify_pinned_digest(image, pinned)
+    return image_id
+
+
+def verify_pinned_digest(image: str, digest: str) -> None:
+    """Fail closed unless the local image behind `image` really carries the pinned `digest`.
+
+    Docker resolves `repo:tag@sha256:...` by digest, so a retagged image should not match at all; this second,
+    independent check on what Docker reports (RepoDigests) guards against a daemon that resolves differently.
+    """
+    r = docker("image", "inspect", "--format", "{{json .RepoDigests}}", validate_image(image))
+    if r.returncode != 0:
+        raise SandboxError(f"image {image!r} not present locally (SafeRun never pulls implicitly)")
+    try:
+        have = repo_digests(r.stdout.strip())
+    except ValueError as e:
+        raise SandboxError(f"cannot verify the digest of image {image!r}: {e}") from e
+    if digest not in have:
+        raise SandboxError(f"image digest mismatch for {image!r}: pinned {digest}, local image has {have or 'no digest'}")
+
+
+def preflight(image: str, allow_degraded: frozenset[str] = frozenset()) -> tuple[str, list[ControlStatus]]:
+    """Fail closed before anything is created. Returns (image_id, daemon control statuses).
+
+    A required daemon control that is missing raises, unless the caller explicitly lists it in
+    `allow_degraded`; allowed degradations stay visible in the returned statuses.
+    """
+    validate_image(image)
+    check_local_daemon()
+    info = daemon_info()
+    # The sandbox images are Linux images: a daemon in Windows-containers mode (or any other OS type) cannot run them as specified.
+    if info.get("OSType") != "linux":
+        raise SandboxError(f"the docker daemon runs {info.get('OSType')!r} containers; SafeRun needs Linux containers"
+                           + (" (Docker Desktop: right-click the tray icon and choose 'Switch to Linux containers')" if hostos.IS_WINDOWS else ""))
+    statuses = daemon_controls(info)
+    for s in statuses:
+        if s.name in REQUIRED_DAEMON and s.state != "verified" and s.name not in allow_degraded:
+            raise SandboxError(f"required control {s.name} is {s.state}: {s.detail}")
+    return resolve_image(image), statuses
+
+
+def check_available(image: str) -> None:
+    """Raise SandboxError unless Docker is usable for SafeRun with `image` (used by the test setup)."""
+    preflight(image)
+
+
+def container_exists(name: str) -> bool:
+    """True/False for a definite answer; SandboxError if Docker could not tell us."""
+    r = docker("inspect", "--type", "container", name)
+    if r.returncode == 0:
+        return True
+    if "no such" in r.stderr.lower():
+        return False
+    raise SandboxError(f"cannot determine whether container {name} exists: {r.stderr.strip()}")
+
+
+def inspect(name: str) -> dict:
+    """`docker inspect` of a container; {} if it does not exist; SandboxError on odd output."""
+    r = docker("inspect", "--type", "container", name)
+    if r.returncode != 0:
+        if "no such" in r.stderr.lower():
+            return {}
+        raise SandboxError(f"docker inspect {name} failed: {r.stderr.strip()}")
+    try:
+        data = json.loads(r.stdout)
+        info = data[0]
+    except (ValueError, IndexError, KeyError, TypeError) as e:
+        raise SandboxError(f"unexpected `docker inspect` output for {name}: {e}") from e
+    if not isinstance(info, dict):
+        raise SandboxError(f"unexpected `docker inspect` output for {name}: not an object")
+    return info
+
+
+def force_remove(name: str) -> bool:
+    """Kill and remove a container; True only if Docker confirms it is gone."""
+    docker("rm", "-f", "-v", name, timeout=60)
+    return not container_exists(name)
+
+
+def leftover_containers() -> list[str]:
+    r = docker("ps", "-a", "-q", "--filter", f"label={CONTAINER_LABEL}")
+    return r.stdout.split()