sandbox-drift 0.1.0__py3-none-any.whl

sandbox_drift/__init__.py

@@ -0,0 +1,3 @@
+"""sandbox-drift: harmless canary probes for AI coding agent sandboxes."""
+
+__version__ = "0.1.0"

sandbox_drift/__main__.py

@@ -0,0 +1,4 @@
+from sandbox_drift.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sandbox_drift/canary.py

@@ -0,0 +1,62 @@
+"""Throw-away canary files: a work dir and a fake HOME in a temp folder.
+
+The credential-looking paths exist only inside the fake HOME and hold nothing but
+a random canary token. Real credential paths are never read, listed or stat-ed.
+Folder names are assembled from fragments so no real path appears as a literal.
+"""
+
+from __future__ import annotations
+
+import secrets
+import shutil
+import tempfile
+from pathlib import Path
+
+# (fragments joined at import time) relative paths under the fake HOME
+CRED_PATHS: tuple[tuple[str, ...], ...] = (
+    (".a" + "ws", "cred" + "entials"),
+    (".s" + "sh", "id_" + "canary"),
+    (".con" + "fig", "g" + "h", "hosts.yml"),
+    (".ku" + "be", "con" + "fig"),
+)
+
+
+class Canary:
+    """Context manager owning a temp folder with ``work/`` and ``home/``."""
+
+    def __init__(self) -> None:
+        self.root: Path | None = None
+        self.token = "SANDBOX_DRIFT_CANARY_" + secrets.token_hex(8)
+
+    def __enter__(self) -> "Canary":
+        self.root = Path(tempfile.mkdtemp(prefix="sandbox-drift-"))
+        self.work_dir.mkdir()
+        self.fake_home.mkdir()
+        for parts in CRED_PATHS:
+            path = self.fake_home.joinpath(*parts)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(self.token + "\n")
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.cleanup()
+
+    @property
+    def work_dir(self) -> Path:
+        assert self.root is not None
+        return self.root / "work"
+
+    @property
+    def fake_home(self) -> Path:
+        assert self.root is not None
+        return self.root / "home"
+
+    @property
+    def tmp_dir(self) -> Path:
+        assert self.root is not None
+        return self.root
+
+    def cleanup(self) -> None:
+        if self.root is not None:
+            shutil.rmtree(self.root, ignore_errors=True)
+            self.root = None

sandbox_drift/classify.py

@@ -0,0 +1,69 @@
+"""Turn exceptions and HTTP codes into one of four observations.
+
+This file is also prepended to the worker at run time, so it must stay
+standard-library only and self-contained.
+
+Observations: ``blocked`` (the sandbox said no), ``allowed`` (the packet or write
+got through), ``error`` (we cannot tell), ``n/a`` (nothing to probe).
+"""
+
+from __future__ import annotations
+
+import errno
+
+BLOCKED = "blocked"
+ALLOWED = "allowed"
+ERROR = "error"
+NOT_APPLICABLE = "n/a"
+OBSERVATIONS = (BLOCKED, ALLOWED, ERROR, NOT_APPLICABLE)
+
+_DENIED_ERRNOS = (errno.EPERM, errno.EACCES)
+# Errors that mean "the connection attempt left the sandbox but nobody answered".
+_REACHED_ERRNOS = (errno.ENETUNREACH, errno.EHOSTUNREACH, errno.ECONNREFUSED, errno.ETIMEDOUT)
+
+
+def is_denied(exc: BaseException) -> bool:
+    """True for EPERM / EACCES style errors (the way sandboxes deny things)."""
+    return isinstance(exc, PermissionError) or getattr(exc, "errno", None) in _DENIED_ERRNOS
+
+
+def classify_oserror(exc: BaseException) -> str:
+    """File-system style errors: denied -> blocked, anything else -> error."""
+    return BLOCKED if is_denied(exc) else ERROR
+
+
+def classify_http(status: int) -> str:
+    """HTTP status from a filtering proxy: 403/407 -> blocked, 2xx -> allowed."""
+    if status in (403, 407):
+        return BLOCKED
+    if 200 <= status < 300:
+        return ALLOWED
+    return ERROR
+
+
+def classify_connect(exc: BaseException | None) -> str:
+    """A direct connection to an unroutable address.
+
+    Success, a timeout, ENETUNREACH or ECONNREFUSED all mean the packet left the
+    sandbox (there is simply nobody at that address), so they count as ``allowed``.
+    """
+    if exc is None:
+        return ALLOWED
+    if is_denied(exc):
+        return BLOCKED
+    if isinstance(exc, TimeoutError) or getattr(exc, "errno", None) in _REACHED_ERRNOS:
+        return ALLOWED
+    return ERROR
+
+
+def classify_unix_socket(exc: BaseException | None) -> str:
+    """A connect() to a Unix socket path (docker socket)."""
+    if exc is None:
+        return ALLOWED
+    if isinstance(exc, FileNotFoundError):
+        return NOT_APPLICABLE
+    if is_denied(exc):
+        return BLOCKED
+    if isinstance(exc, ConnectionRefusedError):
+        return ALLOWED
+    return ERROR

sandbox_drift/cli.py

@@ -0,0 +1,340 @@
+"""Command line interface: argparse sub-commands and exit codes (0 ok, 1 mismatch, 2 cannot run)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import secrets
+import sys
+from pathlib import Path
+
+from sandbox_drift import __version__, targets
+from sandbox_drift.canary import Canary
+from sandbox_drift.convert import claude_to_srt, load_json
+from sandbox_drift.errors import ExecutorUnavailable, SandboxDriftError
+from sandbox_drift.fingerprint import fingerprint_sbpl, fingerprint_settings
+from sandbox_drift.i18n import SUPPORTED, resolve_lang, translator
+from sandbox_drift.listener import CanaryListener
+from sandbox_drift.policy import PRESETS, load_policy, parse_policy, policy_hash
+from sandbox_drift.report import evaluate, exit_code, note_line, render_diff, render_run
+from sandbox_drift.snapshot import (
+    diff_snapshots,
+    key_differences,
+    load_snapshot,
+    new_snapshot,
+    save_snapshot,
+    should_fail,
+)
+
+FORMATS = ("table", "md", "json")
+_TR = translator("en")  # replaced in main() once the language is known
+
+
+# ------------------------------------------------------------------ argparse
+
+class _Formatter(argparse.HelpFormatter):
+    def add_usage(self, usage, actions, groups, prefix=None):  # noqa: ANN001
+        # argparse passes prefix="" when it builds a sub-command's prog; only replace the default
+        return super().add_usage(usage, actions, groups, _TR("arg.usage") + " " if prefix is None else prefix)
+
+
+class _Parser(argparse.ArgumentParser):
+    """ArgumentParser whose fixed phrases (usage, options, errors, -h) are translated."""
+
+    def __init__(self, *args, **kwargs):  # noqa: ANN002, ANN003
+        kwargs.setdefault("formatter_class", _Formatter)
+        kwargs["add_help"] = False
+        kwargs["allow_abbrev"] = False
+        if sys.version_info >= (3, 14):
+            kwargs["color"] = False
+        super().__init__(*args, **kwargs)
+        self._positionals.title = _TR("arg.positionals")
+        self._optionals.title = _TR("arg.options")
+        self.add_argument("-h", "--help", action="help", default=argparse.SUPPRESS, help=_TR("arg.help_help"))
+
+    def error(self, message: str):  # noqa: ANN201
+        self.print_usage(sys.stderr)
+        self.exit(2, _TR("arg.error_prefix") + " " + _translate_argparse(message) + "\n")
+
+
+_ARG_PATTERNS = (
+    (re.compile(r"the following arguments are required: (.+)"), "arg.required", ("names",)),
+    (re.compile(r"argument (.+?): invalid choice: (.+?) \(choose from (.+)\)"), "arg.invalid_choice",
+     ("name", "value", "choices")),
+    (re.compile(r"unrecognized arguments: (.+)"), "arg.unrecognized", ("names",)),
+    (re.compile(r"argument (.+?): expected one argument"), "arg.expected_one", ("name",)),
+    (re.compile(r"argument (.+?): invalid (?:float|int) value: (.+)"), "arg.invalid_number", ("name", "value")),
+    (re.compile(r"one of the arguments (.+) is required"), "arg.one_required", ("names",)),
+    (re.compile(r"argument (.+?): not allowed with argument (.+)"), "arg.not_allowed", ("name", "other")),
+)
+
+
+def _translate_argparse(message: str) -> str:
+    """Map argparse's fixed English sentences onto translated messages."""
+    for pattern, key, names in _ARG_PATTERNS:
+        found = pattern.fullmatch(message)
+        if found:
+            return _TR(key, **dict(zip(names, found.groups())))
+    return _TR("arg.generic", message=message)
+
+
+def _add_common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--policy", metavar="FILE", help=_TR("opt.policy"))
+    parser.add_argument("--baseline", metavar="DIR", help=_TR("opt.baseline"))
+    parser.add_argument("--update-baseline", action="store_true", help=_TR("opt.update_baseline"))
+    parser.add_argument("--outside-dir", metavar="DIR", help=_TR("opt.outside_dir"))
+    parser.add_argument("--workdir", metavar="DIR", help=_TR("opt.workdir"))
+    parser.add_argument("--format", choices=FORMATS, default="table", help=_TR("opt.format"))
+    parser.add_argument("--out", metavar="FILE", help=_TR("opt.out"))
+    parser.add_argument("--strict", action="store_true", help=_TR("opt.strict"))
+    parser.add_argument("--exit-zero", action="store_true", help=_TR("opt.exit_zero"))
+    parser.add_argument("--timeout", type=float, default=2.0, metavar="SEC", help=_TR("opt.timeout"))
+    parser.add_argument("--total-timeout", type=float, default=60.0, metavar="SEC", help=_TR("opt.total_timeout"))
+    parser.add_argument("--agent-version", metavar="TEXT", help=_TR("opt.agent_version"))
+    parser.add_argument("--docker-socket", metavar="PATH", help=_TR("opt.docker_socket"))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(prog="sandbox-drift", description=_TR("help.description"), epilog=_TR("help.epilog"))
+    parser.add_argument("--lang", choices=SUPPORTED, help=_TR("opt.lang"))
+    parser.add_argument("--version", action="version", version=f"sandbox-drift {__version__}",
+                        help=_TR("opt.version"))
+    sub = parser.add_subparsers(dest="command", metavar="<command>", parser_class=_Parser, required=True)
+
+    p_self = sub.add_parser("self", help=_TR("help.self"), description=_TR("help.self"))
+    _add_common(p_self)
+
+    p_run = sub.add_parser("run", help=_TR("help.run"), description=_TR("help.run"))
+    p_run.add_argument("--target", required=True, choices=("wrap", "srt", "replay"), help=_TR("opt.target"))
+    p_run.add_argument("--wrap", metavar="TEMPLATE", help=_TR("opt.wrap"))
+    p_run.add_argument("--settings", metavar="FILE", help=_TR("opt.settings"))
+    p_run.add_argument("--srt-bin", default="srt", metavar="PATH", help=_TR("opt.srt_bin"))
+    p_run.add_argument("--replay", metavar="FILE", help=_TR("opt.replay"))
+    p_run.add_argument("--python", metavar="PATH", help=_TR("opt.python"))
+    _add_common(p_run)
+
+    p_diff = sub.add_parser("diff", help=_TR("help.diff"), description=_TR("help.diff"))
+    p_diff.add_argument("old", metavar="OLD.json", help=_TR("opt.old"))
+    p_diff.add_argument("new", metavar="NEW.json", help=_TR("opt.new"))
+    p_diff.add_argument("--strict", action="store_true", help=_TR("opt.strict"))
+    p_diff.add_argument("--exit-zero", action="store_true", help=_TR("opt.exit_zero"))
+    p_diff.add_argument("--format", choices=FORMATS, default="table", help=_TR("opt.format"))
+
+    p_init = sub.add_parser("init", help=_TR("help.init"), description=_TR("help.init"))
+    p_init.add_argument("--preset", choices=tuple(PRESETS), default="self-basic", help=_TR("opt.preset"))
+    p_init.add_argument("--out", metavar="FILE", help=_TR("opt.init_out"))
+    p_init.add_argument("--force", action="store_true", help=_TR("opt.force"))
+
+    p_fp = sub.add_parser("fingerprint", help=_TR("help.fingerprint"), description=_TR("help.fingerprint"))
+    group = p_fp.add_mutually_exclusive_group(required=True)
+    group.add_argument("--settings", metavar="FILE", help=_TR("opt.fp_settings"))
+    group.add_argument("--sbpl", metavar="FILE", help=_TR("opt.fp_sbpl"))
+
+    p_conv = sub.add_parser("convert", help=_TR("help.convert"), description=_TR("help.convert"))
+    p_conv.add_argument("--from-claude", required=True, metavar="FILE", help=_TR("opt.from_claude"))
+    p_conv.add_argument("--fake-home", metavar="DIR", help=_TR("opt.fake_home"))
+    for child in (p_self, p_run, p_diff, p_init, p_fp, p_conv):  # --lang also works after the command
+        child.add_argument("--lang", choices=SUPPORTED, default=argparse.SUPPRESS, help=_TR("opt.lang"))
+    return parser
+
+
+def _prescan_lang(argv: list[str]) -> str | None:
+    """Find ``--lang`` before the real parser exists (the parser itself needs the language)."""
+    for i, arg in enumerate(argv):
+        if arg == "--lang" and i + 1 < len(argv):
+            return argv[i + 1]
+        if arg.startswith("--lang="):
+            return arg.split("=", 1)[1]
+    return None
+
+
+# ------------------------------------------------------------------ helpers
+
+def _fail(exc: SandboxDriftError) -> int:
+    message = _TR("err." + exc.code, **exc.params)
+    if isinstance(exc, ExecutorUnavailable):
+        message += " " + _TR("err.hint_self")
+    print(_TR("err.prefix") + " " + message, file=sys.stderr)
+    return 2
+
+
+def _emit(text: str, out: str | None) -> None:
+    if out:
+        path = Path(out)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(text + "\n", encoding="utf-8")
+        except OSError as exc:
+            raise SandboxDriftError("output_unwritable", path=out, detail=exc.strerror or "") from exc
+        print(_TR("out.written", path=out))
+    else:
+        print(text)
+
+
+def _use_color() -> bool:
+    return sys.stdout.isatty() and "NO_COLOR" not in os.environ
+
+
+def _need(value: object, option: str, target: str) -> None:
+    if not value:
+        raise SandboxDriftError("missing_option", option=option, target=target)
+
+
+def _collect(args: argparse.Namespace, target: str, policy: dict[str, str]) -> dict:
+    """Run the chosen target and return a snapshot document."""
+    agent = args.agent_version or os.environ.get("SANDBOX_DRIFT_AGENT_VERSION") or "unknown"
+    phash = policy_hash(policy)
+
+    if target == "replay":
+        _need(args.replay, "--replay", target)
+        saved = targets.load_replay(args.replay)
+        doc = new_snapshot(saved.get("target", "replay"), saved["probes"],
+                           agent_version=saved.get("agent_version", agent),
+                           engine_version=saved.get("engine_version", "unknown"), policy_hash=phash,
+                           settings_fingerprint=saved.get("settings_fingerprint", "none"), note=saved.get("note"),
+                           note_code=saved.get("note_code"))
+        for field in ("os", "arch"):
+            doc[field] = saved.get(field, doc[field])
+        return doc
+
+    outside = args.outside_dir or str(Path.home())
+    with CanaryListener() as listener:
+        if target == "self":
+            setup = targets.ProbeSetup(workdir=args.workdir or os.getcwd(), outside_dir=outside,
+                                       canary_token="SANDBOX_DRIFT_CANARY_" + secrets.token_hex(8),
+                                       listener_port=listener.port, timeout=args.timeout,
+                                       docker_socket=args.docker_socket)
+            probes = targets.run_self(setup)
+            return new_snapshot("self", probes, agent_version=agent, policy_hash=phash)
+
+        with Canary() as canary:
+            setup = targets.ProbeSetup(workdir=args.workdir or str(canary.work_dir), outside_dir=outside,
+                                       canary_token=canary.token, listener_port=listener.port,
+                                       fake_home=str(canary.fake_home), timeout=args.timeout,
+                                       docker_socket=args.docker_socket)
+            python = args.python or targets.default_python()
+            if target == "wrap":
+                _need(args.wrap, "--wrap", target)
+                probes = targets.run_wrap(args.wrap, setup, canary.tmp_dir, python, args.total_timeout)
+                return new_snapshot("wrap", probes, agent_version=agent, policy_hash=phash)
+            _need(args.settings, "--settings", target)
+            settings = load_json(args.settings)
+            srt_settings, warnings = claude_to_srt(settings, setup.fake_home)
+            for key, code in warnings:
+                print(_TR("warn." + code, key=key), file=sys.stderr)
+            allow_write = srt_settings["filesystem"].setdefault("allowWrite", [])
+            if setup.workdir not in allow_write:
+                allow_write.append(setup.workdir)  # the positive control needs a writable work dir
+            probes = targets.run_srt(args.srt_bin, srt_settings, setup, canary.tmp_dir, python, args.total_timeout)
+            return new_snapshot("srt", probes, agent_version=agent,
+                                engine_version=targets.engine_version(args.srt_bin), policy_hash=phash,
+                                settings_fingerprint=fingerprint_settings(srt_settings))
+
+
+def _run_command(args: argparse.Namespace, target: str) -> int:
+    if args.policy:
+        policy = load_policy(args.policy)
+    else:
+        policy = parse_policy(PRESETS["claude-srt" if target == "srt" else "self-basic"], "<preset>")
+    doc = _collect(args, target, policy)
+
+    changes, key_diffs, baseline_note = [], [], ""
+    if args.baseline:
+        path = Path(args.baseline) / f"baseline-{doc['target']}.json"
+        if path.exists():
+            old = load_snapshot(path)
+            changes = diff_snapshots(old, doc)
+            key_diffs = key_differences(old, doc)
+            baseline_note = _TR("baseline.compared", path=str(path))
+            if args.update_baseline:
+                save_snapshot(path, doc)
+                baseline_note += " " + _TR("baseline.updated")
+        else:
+            save_snapshot(path, doc)
+            baseline_note = _TR("baseline.created", path=str(path))
+    rows = evaluate(doc["probes"], policy, changes)
+    notes = [_TR("diff.key_changed", field=f, old=a, new=b) for f, a, b in key_diffs]
+    if target == "replay":
+        notes.append(_TR("report.replay_mock"))
+        if note_line(doc, _TR):
+            notes.append(note_line(doc, _TR))  # our example notes are translated, a user's own note is shown raw
+    text = render_run(doc, rows, args.format, _TR, color=_use_color() and not args.out, notes=notes,
+                      baseline_note=baseline_note)
+    _emit(text, args.out)
+    code = exit_code(rows, changes, args.strict)
+    return 0 if args.exit_zero else code
+
+
+def _diff_command(args: argparse.Namespace) -> int:
+    old, new = load_snapshot(args.old), load_snapshot(args.new)
+    changes = diff_snapshots(old, new)
+    text = render_diff(old, new, changes, key_differences(old, new), args.format, _TR, color=_use_color(),
+                       strict=args.strict)
+    print(text)
+    failed = should_fail(changes, args.strict)
+    return 1 if failed and not args.exit_zero else 0
+
+
+def _init_command(args: argparse.Namespace) -> int:
+    text = PRESETS[args.preset]
+    if not args.out:
+        print(text, end="")
+        return 0
+    path = Path(args.out)
+    if path.exists() and not args.force:
+        raise SandboxDriftError("init_exists", path=str(path))
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+    except OSError as exc:
+        raise SandboxDriftError("output_unwritable", path=str(path), detail=exc.strerror or "") from exc
+    print(_TR("out.written", path=str(path)))
+    return 0
+
+
+def _read_text(path: str) -> str:
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise SandboxDriftError("settings_not_found", path=path) from exc
+    except OSError as exc:
+        raise SandboxDriftError("file_unreadable", path=path, detail=exc.strerror or "") from exc
+
+
+def _fingerprint_command(args: argparse.Namespace) -> int:
+    if args.sbpl:
+        print(fingerprint_sbpl(_read_text(args.sbpl)))
+    else:
+        print(fingerprint_settings(load_json(args.settings)))
+    return 0
+
+
+def _convert_command(args: argparse.Namespace) -> int:
+    srt_settings, warnings = claude_to_srt(load_json(args.from_claude), args.fake_home)
+    for key, code in warnings:
+        print(_TR("warn." + code, key=key), file=sys.stderr)
+    print(json.dumps(srt_settings, indent=2))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    global _TR
+    argv = list(sys.argv[1:] if argv is None else argv)
+    _TR = translator(resolve_lang(_prescan_lang(argv)))
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "self":
+            return _run_command(args, "self")
+        if args.command == "run":
+            return _run_command(args, args.target)
+        if args.command == "diff":
+            return _diff_command(args)
+        if args.command == "init":
+            return _init_command(args)
+        if args.command == "fingerprint":
+            return _fingerprint_command(args)
+        return _convert_command(args)
+    except SandboxDriftError as exc:
+        return _fail(exc)

sandbox_drift/convert.py

@@ -0,0 +1,77 @@
+"""agent CLI ``sandbox`` settings block -> sandbox-runtime (srt) settings."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from sandbox_drift.errors import SandboxDriftError
+
+NETWORK_KEYS = ("allowedDomains", "deniedDomains", "allowUnixSockets", "allowAllUnixSockets",
+                "allowLocalBinding", "httpProxyPort", "socksProxyPort")
+FILESYSTEM_KEYS = ("denyRead", "allowRead", "allowWrite", "denyWrite")
+PATH_KEYS = ("denyRead", "allowRead", "allowWrite", "denyWrite", "allowUnixSockets")
+
+
+def load_json(path: str | Path) -> dict:
+    file = Path(path)
+    try:
+        data = json.loads(file.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise SandboxDriftError("settings_not_found", path=str(file)) from exc
+    except OSError as exc:
+        raise SandboxDriftError("file_unreadable", path=str(file), detail=exc.strerror or "") from exc
+    except json.JSONDecodeError as exc:
+        raise SandboxDriftError("settings_invalid_json", path=str(file), detail=str(exc)) from exc
+    if not isinstance(data, dict):
+        raise SandboxDriftError("settings_not_object", path=str(file))
+    return data
+
+
+def expand_path(value: str, fake_home: str | None) -> str:
+    """``~`` becomes the fake HOME; a leading ``//`` means an absolute path (agent CLI convention)."""
+    if fake_home and (value == "~" or value.startswith("~/")):
+        return fake_home + value[1:]
+    if value.startswith("//"):
+        return value[1:]
+    return value
+
+
+def _pick(section: object, allowed: tuple[str, ...], where: str, warnings: list[tuple[str, str]],
+          fake_home: str | None) -> dict:
+    result: dict = {}
+    if not isinstance(section, dict):
+        return result
+    for key, value in section.items():
+        if key not in allowed:
+            warnings.append((where + "." + key, "unknown_key"))
+            continue
+        if key in PATH_KEYS and isinstance(value, list):
+            value = [expand_path(item, fake_home) if isinstance(item, str) else item for item in value]
+        result[key] = value
+    return result
+
+
+def claude_to_srt(settings: dict, fake_home: str | None = None) -> tuple[dict, list[tuple[str, str]]]:
+    """Return ``(srt_settings, warnings)``; warnings are ``(dotted key, code)`` pairs.
+
+    Accepts an agent CLI settings file (``sandbox`` block) or an srt settings file
+    (top-level ``network`` / ``filesystem``).
+    """
+    warnings: list[tuple[str, str]] = []
+    if isinstance(settings.get("sandbox"), dict):
+        block = settings["sandbox"]
+        prefix = "sandbox."
+        for key in block:
+            if key not in ("network", "filesystem"):
+                warnings.append((prefix + key, "not_translated"))
+    elif "network" in settings or "filesystem" in settings:
+        block = settings
+        prefix = ""
+    else:
+        raise SandboxDriftError("settings_no_sandbox")
+    srt = {
+        "network": _pick(block.get("network"), NETWORK_KEYS, prefix + "network", warnings, fake_home),
+        "filesystem": _pick(block.get("filesystem"), FILESYSTEM_KEYS, prefix + "filesystem", warnings, fake_home),
+    }
+    return srt, warnings

sandbox_drift/errors.py

@@ -0,0 +1,16 @@
+"""Errors carry a stable code plus parameters so the CLI can translate them."""
+
+from __future__ import annotations
+
+
+class SandboxDriftError(Exception):
+    """Base error: ``code`` selects the message ``err.<code>``, ``params`` fill it in."""
+
+    def __init__(self, code: str, **params: object) -> None:
+        self.code = code
+        self.params = params
+        super().__init__(f"{code}: {params}")
+
+
+class ExecutorUnavailable(SandboxDriftError):
+    """The runner could not run the worker at all (exit 2, never reported as 'blocked')."""

sandbox_drift/fingerprint.py

@@ -0,0 +1,43 @@
+"""Stable fingerprints so 'did the sandbox configuration change?' has a yes/no answer."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+
+_LOG_TAG = re.compile(r'\(with message "[^"]*"\)')
+_PROXY_PORT = re.compile(r"(localhost|127\.0\.0\.1|\[::1\]):\d+")
+_TEMP_PATH = re.compile(r"/(?:private/)?(?:var/folders|tmp)/[^\s\"')]*")
+_SPACES = re.compile(r"[ \t]+")
+
+
+def _digest(text: str) -> str:
+    return "sha256:" + hashlib.sha256(text.encode()).hexdigest()
+
+
+def fingerprint_settings(data: object) -> str:
+    """Hash of a settings object; key order and whitespace do not matter."""
+    return _digest(json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False))
+
+
+def normalize_sbpl(text: str) -> str:
+    """Remove the parts of a Seatbelt profile that change on every run.
+
+    Random log tags, the proxy port and temp paths differ between runs even when
+    the rules are identical, so they are replaced with placeholders.
+    """
+    lines = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith(";"):
+            continue
+        line = _LOG_TAG.sub('(with message "<TAG>")', line)
+        line = _PROXY_PORT.sub(r"\1:<PORT>", line)
+        line = _TEMP_PATH.sub("<TMP>", line)
+        lines.append(_SPACES.sub(" ", line))
+    return "\n".join(lines)
+
+
+def fingerprint_sbpl(text: str) -> str:
+    return _digest(normalize_sbpl(text))