inspect-ranges 0.2.0__py3-none-any.whl

inspect_ranges/__init__.py

@@ -0,0 +1,105 @@
+# __version__ resolves first: deep imports (the oracle's compiler/runtime
+# chain) read it during package initialization
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "unknown"
+
+from ._challenges import (
+    PROBE_MAC_PREFIX,
+    AnswerGoal,
+    AvailabilityGoal,
+    Challenge,
+    Challenges,
+    ControlGoal,
+    DegradeGoal,
+    DetectionGoal,
+    EvadeGoal,
+    ExecuteGoal,
+    ExfiltrateGoal,
+    FlagGoal,
+    Goal,
+    GoalBase,
+    GoalResult,
+    GoalType,
+    HijackGoal,
+    JudgeGoal,
+    Observations,
+    ObserverKind,
+    OracleSetupError,
+    PatchGoal,
+    Primitive,
+    RangeOracle,
+    Scoring,
+    SeverityFilter,
+    TamperGoal,
+    challenge_dataset,
+    challenge_scorer,
+    challenge_setup,
+    guest_segment_ip,
+    load_challenges,
+    load_collectors,
+    range_oracle,
+    register_exploit,
+    register_goal_type,
+    source_bound_find,
+    validate_challenges,
+    verify_goal,
+)
+from ._terminal import terminal
+from .schema import (
+    load_range,
+    range_json_schema,
+    revalidate_range,
+    validate_range,
+)
+from .types import semantic_issues
+
+__all__ = [
+    "PROBE_MAC_PREFIX",
+    "AnswerGoal",
+    "AvailabilityGoal",
+    "Challenge",
+    "Challenges",
+    "ControlGoal",
+    "DegradeGoal",
+    "DetectionGoal",
+    "EvadeGoal",
+    "ExecuteGoal",
+    "ExfiltrateGoal",
+    "FlagGoal",
+    "Goal",
+    "GoalBase",
+    "GoalResult",
+    "GoalType",
+    "HijackGoal",
+    "JudgeGoal",
+    "Observations",
+    "ObserverKind",
+    "OracleSetupError",
+    "PatchGoal",
+    "Primitive",
+    "RangeOracle",
+    "Scoring",
+    "SeverityFilter",
+    "TamperGoal",
+    "__version__",
+    "challenge_dataset",
+    "challenge_scorer",
+    "challenge_setup",
+    "guest_segment_ip",
+    "load_challenges",
+    "load_collectors",
+    "load_range",
+    "range_json_schema",
+    "range_oracle",
+    "register_exploit",
+    "register_goal_type",
+    "revalidate_range",
+    "semantic_issues",
+    "source_bound_find",
+    "terminal",
+    "validate_challenges",
+    "validate_range",
+    "verify_goal",
+]

inspect_ranges/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m inspect_ranges` — runs the CLI without needing the console script on `PATH`."""
+
+from ._cli.main import main
+
+if __name__ == "__main__":
+    main()

inspect_ranges/_attackbox/__init__.py

@@ -0,0 +1,48 @@
+"""The attack-box provider seam (`attack-box-v1.md`): an external supplier for one range's dedicated attack box.
+
+The range supplies an L2 attachment point on the foothold's segment (taps built inside the range netns, fds handed over) and routes the attacker's exec to the surface the provider returns; the provider supplies the box behind both and owns its lifecycle. Registration mirrors `INSPECT_RANGES_HOST`: the `INSPECT_RANGES_ATTACK_BOX` value is the registration, persisted as the project's attack-box origin so teardown re-resolves from disk. Selection is deployment knowledge, never `range.yaml`. Scope is dedicated attack boxes only: an assumed-breach foothold is a content guest this project builds and captures, excluded by construction.
+"""
+
+from .backend import (
+    ENV_VAR,
+    AttachedInterface,
+    AttackBoxBackend,
+    AttackBoxCapabilities,
+    AttackBoxContext,
+    AttackBoxFactory,
+    AttackBoxHandle,
+    AttackBoxProvider,
+    AttackBoxReclaimFn,
+    FootholdAttachment,
+    ParsedAttackBox,
+    attack_box_origin,
+    parse_attack_box,
+    resolve_attack_box,
+)
+from .record import (
+    AttackBoxRecord,
+    attack_box_record_path,
+    read_attack_box_record,
+    write_attack_box_record,
+)
+
+__all__ = [
+    "ENV_VAR",
+    "AttachedInterface",
+    "AttackBoxBackend",
+    "AttackBoxCapabilities",
+    "AttackBoxContext",
+    "AttackBoxFactory",
+    "AttackBoxHandle",
+    "AttackBoxProvider",
+    "AttackBoxReclaimFn",
+    "AttackBoxRecord",
+    "FootholdAttachment",
+    "ParsedAttackBox",
+    "attack_box_origin",
+    "attack_box_record_path",
+    "parse_attack_box",
+    "read_attack_box_record",
+    "resolve_attack_box",
+    "write_attack_box_record",
+]

inspect_ranges/_attackbox/attach.py

@@ -0,0 +1,293 @@
+"""The tap-fd attachment: build the external attack box's NICs inside the range netns and hand the fds out.
+
+The invariant this module exists to preserve (`architecture.md`: the host netns carries zero range state while a range runs): the external VMM gets its NIC as an OPEN TAP FD created inside the range container's network namespace, never as a device name it cannot resolve and never as a veth or bridge leg reaching into the host netns. A short verbatim helper (`ATTACH_HELPER_SOURCE`, the capture-supervisor pattern) runs inside the range container as root over the same `docker compose exec` transport as the boot script: it opens `/dev/net/tun`, `TUNSETIFF`s one non-persistent tap per attacker interface (so the fd IS the tap's lifetime), applies the libvirt tap-MAC rule, enslaves each tap to its segment bridge, then connects to a host-side unix listener in the shared vsock directory and ships the fds over `SCM_RIGHTS`. The host receives them in the realizing process and hands them to the provider in-process; the fd plumbing never crosses the public seam.
+
+The taps are created with `IFF_VNET_HDR`, matching what QEMU and Cloud Hypervisor request when they create taps themselves, so virtio offload negotiation works for an external VMM consuming the fd; a provider that cannot use the header may still read/write raw frames after `TUNSETVNETHDRSZ`. Teardown needs nothing from this module: a non-persistent tap dies when its last fd closes, and unconditionally when the range container's netns is destroyed; `down` tears the provider first, so the external VMM never outlives its NIC.
+"""
+
+import array
+import os
+import socket
+import subprocess
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from ipaddress import IPv4Address
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .._channel.vsock import peer_uid
+from .backend import AttachedInterface, FootholdAttachment
+
+if TYPE_CHECKING:
+    from .._runtime.up import BootGuest
+
+ATTACH_TIMEOUT_S = 60.0
+"""How long the host waits for the in-container helper to build the taps and connect back."""
+
+ATTACH_HELPER_SOURCE = '''\
+"""Attack-box attach helper: runs as root inside the range container (its netns IS the range netns).
+
+Config arrives as JSON in argv[1] (every value shape-validated host-side by `BootPlan` before interpolation). For each interface: open /dev/net/tun, TUNSETIFF a non-persistent IFF_TAP|IFF_NO_PI|IFF_VNET_HDR device, set the fe:-prefixed tap MAC BEFORE enslaving (the bridge adopts its lowest port MAC; a random tap MAC would leak onto the segment), enslave to the segment bridge, bring it up. Then connect to the handoff socket and send one JSON line plus every tap fd via SCM_RIGHTS; wait for the one-byte ack so the fds are known-received before this process (and its fd copies) exits. Any failure tracebacks to stderr and exits nonzero: the host fails the attach stage with it.
+"""
+
+import array
+import fcntl
+import json
+import socket
+import struct
+import subprocess
+import sys
+
+TUNSETIFF = 0x400454CA
+IFF_TAP = 0x0002
+IFF_NO_PI = 0x1000
+IFF_VNET_HDR = 0x4000
+
+
+def main() -> None:
+    config = json.loads(sys.argv[1])
+    fds = []
+    taps = []
+    for spec in config["interfaces"]:
+        fd = open("/dev/net/tun", "rb+", buffering=0)
+        name = spec["tap"]
+        ifr = struct.pack("16sH", name.encode(), IFF_TAP | IFF_NO_PI | IFF_VNET_HDR)
+        fcntl.ioctl(fd, TUNSETIFF, ifr)
+        subprocess.run(["ip", "link", "set", name, "address", spec["tap_mac"]], check=True)
+        subprocess.run(["ip", "link", "set", name, "master", spec["bridge"]], check=True)
+        subprocess.run(["ip", "link", "set", name, "up"], check=True)
+        fds.append(fd)
+        taps.append(name)
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+        client.connect(config["socket"])
+        payload = json.dumps({"taps": taps}).encode()
+        rights = array.array("i", [fd.fileno() for fd in fds])
+        client.sendmsg([payload], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, rights.tobytes())])
+        ack = client.recv(1)
+    if ack != b"1":
+        raise SystemExit("handoff not acknowledged; taps die with this process")
+
+
+main()
+'''
+
+
+class AttachError(Exception):
+    """The attachment did not complete; the message carries the helper's stderr or the handoff failure."""
+
+
+def tap_name(cid: int, index: int) -> str:
+    """The external attack box's per-NIC tap device name: CID-derived like the Cloud Hypervisor scheme (`ch{cid}n{index}`), distinct prefix so a review of a live netns tells the two apart, within IFNAMSIZ."""
+    return f"ab{cid}n{index}"
+
+
+def tap_mac(mac: str) -> str:
+    """The tap-device MAC for a guest MAC: first octet `fe`, the libvirt rule the boot script also applies (`up.py`), so the bridge never adopts a MAC that would leak onto the segment."""
+    return f"fe{mac[2:]}"
+
+
+def helper_config(guest: "BootGuest", container_socket: str) -> dict[str, Any]:
+    """The attach helper's argv[1] config for one attacker entry: tap name, tap MAC, and bridge per interface, plus the in-container handoff socket path. Pure; every value is already shape-validated by `BootPlan`."""
+    return {
+        "socket": container_socket,
+        "interfaces": [
+            {
+                "tap": tap_name(guest.cid, index),
+                "tap_mac": tap_mac(nic.mac),
+                "bridge": nic.bridge,
+            }
+            for index, nic in enumerate(guest.interfaces)
+        ],
+    }
+
+
+@dataclass(frozen=True)
+class AttachInvocation:
+    """Everything the attacher needs to run the helper and receive the fds; built by `up`, injectable for tests."""
+
+    argv: list[str]
+    """The `docker compose exec ... python3 - <config-json>` command."""
+    env: dict[str, str]
+    source: str
+    """The helper program, fed on stdin (`ATTACH_HELPER_SOURCE`)."""
+    host_socket: Path
+    """Where the host listens for the handoff (the shared vsock dir, so the container sees the same socket)."""
+    expected_fds: int
+    timeout: float = ATTACH_TIMEOUT_S
+
+
+Attacher = Callable[[AttachInvocation], list[int]]
+"""Runs the helper and returns one open tap fd per attacker interface, in interface order. Injectable so `up`'s attach stage is tested without a container; the default is `run_attacher`."""
+
+
+def receive_fds(listener: socket.socket, expected: int, timeout: float) -> list[int]:
+    """Accept the helper's connection and receive `expected` fds via `SCM_RIGHTS`, acking so the sender may exit.
+
+    The handoff socket sits in the shared vsock directory, which the range container mounts, so every in-container uid (the unprivileged VMMs foremost) can connect to it during the window: the accept loop therefore requires the peer to be the compose-exec root helper (`SO_PEERCRED`, the same check discipline as every exec dial: host uid 0 under rootful docker, the invoking user's uid under rootless, and never a VMM's per-guest uid) and keeps accepting until a credentialed peer or the deadline, so a hostile connector can neither hand over fds nor starve the real helper of its slot. Every blocking step is deadline-bounded (B21: the failure path is as bounded as the boot path), truncated ancillary data (`MSG_CTRUNC`) refuses, and received fds are marked non-inheritable (a provider passing them to its VMM does so explicitly, e.g. `pass_fds`).
+
+    Raises:
+        AttachError: No credentialed helper connected within `timeout`, the handoff was truncated, or it carried the wrong fd count (any received fds are closed before raising; half an attachment is worse than none).
+    """
+    deadline = time.monotonic() + timeout
+    anomaly: str | None = None
+
+    def remaining() -> float:
+        left = deadline - time.monotonic()
+        if left <= 0:
+            raise AttachError(
+                f"helper never completed the handoff within {timeout:.0f}s"
+                + (f" (last anomaly: {anomaly})" if anomaly else "")
+            )
+        return left
+
+    while True:
+        listener.settimeout(remaining())
+        try:
+            connection, _ = listener.accept()
+        except TimeoutError as error:
+            raise AttachError(
+                f"helper never connected to the handoff socket within {timeout:.0f}s"
+                + (f" (last anomaly: {anomaly})" if anomaly else "")
+            ) from error
+        with connection:
+            if peer_uid(connection) not in (0, os.getuid()):
+                continue  # not the root helper; keep the slot open for it
+            # a credentialed stray (another same-uid process probing sockets)
+            # must not abort the attach either: bound its recv so it cannot
+            # eat the window, note the anomaly, and keep awaiting the helper
+            connection.settimeout(min(remaining(), 10.0))
+            try:
+                space = socket.CMSG_SPACE(expected * array.array("i").itemsize)
+                payload, ancillary, flags, _ = connection.recvmsg(4096, space)
+            except TimeoutError:
+                anomaly = "a credentialed peer connected but sent nothing"
+                continue
+            fds: list[int] = []
+            for level, kind, data in ancillary:
+                if level == socket.SOL_SOCKET and kind == socket.SCM_RIGHTS:
+                    received = array.array("i")
+                    received.frombytes(
+                        data[: len(data) - (len(data) % received.itemsize)]
+                    )
+                    fds.extend(received.tolist())
+            if flags & socket.MSG_CTRUNC or len(fds) != expected:
+                for fd in fds:
+                    os.close(fd)
+                anomaly = (
+                    f"a credentialed peer sent {len(fds)} fds for {expected} "
+                    f"interfaces"
+                    f"{' (ancillary truncated)' if flags & socket.MSG_CTRUNC else ''}:"
+                    f" {payload!r}"
+                )
+                continue
+            for fd in fds:
+                os.set_inheritable(fd, False)
+            connection.sendall(b"1")
+        return fds
+
+
+def run_attacher(invocation: AttachInvocation) -> list[int]:
+    """The default `Attacher`: bind the handoff listener, run the helper in the range container, receive the fds, and require the helper's clean exit.
+
+    The listener binds BEFORE the helper starts (the helper connects, so there is no race), world-connectable because the container's root is not this uid; the private 0700 per-user root of the vsock dir bounds who can reach the path at all, and the socket is removed as soon as the handoff completes.
+
+    Raises:
+        AttachError: The helper failed, timed out, or the handoff was short; the message carries the helper's stderr tail.
+    """
+    invocation.host_socket.unlink(missing_ok=True)
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as listener:
+        listener.bind(str(invocation.host_socket))
+        os.chmod(invocation.host_socket, 0o666)
+        listener.listen(4)
+        process = subprocess.Popen(
+            invocation.argv,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            env=invocation.env,
+        )
+        delivered = False
+        try:
+            assert process.stdin is not None  # Popen with stdin=PIPE guarantees it
+            # the helper reads its program to EOF before executing, so stdin
+            # closes NOW; detach it from the Popen so communicate() below does
+            # not flush the already-closed pipe
+            process.stdin.write(invocation.source.encode())
+            process.stdin.close()
+            process.stdin = None
+            try:
+                fds = receive_fds(listener, invocation.expected_fds, invocation.timeout)
+            except AttachError as error:
+                process.kill()
+                _, stderr = process.communicate(timeout=10.0)
+                raise AttachError(
+                    f"{error} (helper stderr: {stderr.decode('utf-8', 'replace').strip()[-800:]})"
+                ) from error
+            try:
+                _, stderr = process.communicate(timeout=invocation.timeout)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                _, stderr = process.communicate(timeout=10.0)
+            if process.returncode != 0:
+                for fd in fds:
+                    os.close(fd)
+                raise AttachError(
+                    "helper exited "
+                    f"{process.returncode}: {stderr.decode('utf-8', 'replace').strip()[-800:]}"
+                )
+            delivered = True
+        finally:
+            invocation.host_socket.unlink(missing_ok=True)
+            if not delivered and process.poll() is None:
+                # an unexpected escape (connection reset, interrupt) must not
+                # orphan the root helper un-reaped
+                process.kill()
+                try:
+                    process.communicate(timeout=10.0)
+                except subprocess.TimeoutExpired:
+                    pass
+    return fds
+
+
+def attachment_from_boot(
+    guest: "BootGuest",
+    *,
+    project: str,
+    fds: list[int],
+    seed_dir: Path | None,
+) -> FootholdAttachment:
+    """Fold one attacker `boot.json` entry plus its received tap fds into the provider's `FootholdAttachment`. Pure.
+
+    Raises:
+        ValueError: The entry lacks the attacker address facts (a bundle rendered before they existed) or sizing; the caller folds this into its re-render refusal.
+    """
+    if guest.cpus is None or guest.memory_mb is None:
+        raise ValueError(f"attacker entry {guest.name!r} carries no sizing")
+    interfaces: list[AttachedInterface] = []
+    for nic, fd in zip(guest.interfaces, fds, strict=True):
+        if nic.network is None or nic.ip is None or nic.prefixlen is None:
+            raise ValueError(
+                f"attacker entry {guest.name!r} carries no address facts "
+                "(bundle rendered before attack-box support); re-render the bundle"
+            )
+        interfaces.append(
+            AttachedInterface(
+                segment=nic.network,
+                bridge=nic.bridge,
+                tap_fd=fd,
+                mac=nic.mac,
+                ip=IPv4Address(nic.ip),
+                prefixlen=nic.prefixlen,
+                gateway=IPv4Address(nic.gateway) if nic.gateway is not None else None,
+            )
+        )
+    return FootholdAttachment(
+        project=project,
+        guest_name=guest.name,
+        cid=guest.cid,
+        cpus=guest.cpus,
+        memory_mb=guest.memory_mb,
+        interfaces=tuple(interfaces),
+        seed_dir=seed_dir,
+    )

inspect_ranges/_attackbox/backend.py

@@ -0,0 +1,218 @@
+"""Backend selection for `INSPECT_RANGES_ATTACK_BOX`: the grammar, the bundle, and the resolver.
+
+The variable's value IS the registration, exactly as `INSPECT_RANGES_HOST` works (`_host/backend.py`): a dotted import path naming an `AttackBoxFactory`, as `<module>.<factory>[:<config>]`, imported and called at resolution. There are no built-in forms; the variable's absence is the built-in behavior (the realizer renders and boots the attack box itself). The value splits on the FIRST colon, so a config may itself contain colons.
+
+The value is persisted verbatim as the project's attack-box `origin` (`record.py`), and teardown-by-origin re-resolves it through `resolve_attack_box` in whatever process reclaims: `down` foremost, which may run fresh and never saw the driver's environment. Factories and provider constructors must therefore be cheap and must not dial anything: resolution happens in doctor, in `down`, and before `up` touches any docker resource; remote work belongs in the provider's `boot`.
+
+The seam itself is deliberately minimal (every method added is API someone freezes against): an attachment goes in, an exec surface and a teardown obligation come out. The provider's exec surface is held to the daemon wire protocol over a unix socket (the Cloud Hypervisor hybrid-vsock shape, `HybridEndpoint`), which is what makes the published conformance battery, not code review, the gate a provider must pass.
+"""
+
+import asyncio
+import importlib
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from ipaddress import IPv4Address
+from pathlib import Path
+from typing import Any, Protocol
+
+from .._channel.vsock import HybridEndpoint
+from .record import AttackBoxRecord
+
+ENV_VAR = "INSPECT_RANGES_ATTACK_BOX"
+
+DoctorProbe = Callable[[], str | None]
+"""An optional reachability probe for `inspect-ranges doctor`: `None` when healthy, else the failure detail (the `_host/backend.py` shape, aliased here so the realizer can import this module without the host-seam dependency chain)."""
+
+_GRAMMAR = "(expected a backend factory as '<module>.<factory>[:<config>]')"
+
+
+@dataclass(frozen=True)
+class AttachedInterface:
+    """One L2 attachment point on a foothold segment, built inside the range container's netns.
+
+    The tap is created and enslaved to the segment bridge inside the range netns before the provider sees it; the provider receives only the open fd. The host netns never carries a device for it, and the attachment dies with the fd (the tap is non-persistent) or with the range container's netns, whichever comes first.
+    """
+
+    segment: str
+    """The attached network's name in the plan."""
+    bridge: str
+    """The segment bridge device name inside the range netns (a fact; the tap is already enslaved)."""
+    tap_fd: int
+    """The open tap fd. The provider owns it from handoff: pass it to the VMM and close it on teardown."""
+    mac: str
+    """The allocated guest MAC the external box MUST present on this segment (addressing and ACLs treat it as this guest)."""
+    ip: IPv4Address
+    """The allocated interface address the external box MUST take."""
+    prefixlen: int
+    """The segment prefix length."""
+    gateway: IPv4Address | None
+    """The segment gateway address, when the segment has one."""
+
+
+@dataclass(frozen=True)
+class FootholdAttachment:
+    """What the compiled plan hands an external attack-box provider: attachment in, nothing else.
+
+    Everything here is a plan fact; the provider supplies its own box (image, VMM, hardening) and attaches it behind the taps. `seed_dir` points at the rendered cloud-init seed for the attack box when the bundle carries one; a provider MAY consume it for in-guest network configuration and is never required to.
+    """
+
+    project: str
+    guest_name: str
+    cid: int
+    """The guest's plan-reserved control-channel CID: a pure addressing token for exec routing, never a uid or tap-name promise."""
+    cpus: int
+    memory_mb: int
+    interfaces: tuple[AttachedInterface, ...]
+    seed_dir: Path | None = None
+
+
+@dataclass(frozen=True)
+class AttackBoxHandle:
+    """What a provider's `boot` returns: the exec surface plus a reclaim token, nothing else."""
+
+    exec_endpoint: HybridEndpoint
+    """A unix socket serving the Cloud Hypervisor hybrid-vsock shape: the `CONNECT <port>` / `OK <port>` preamble, then the daemon wire protocol, one request per connection; the peer uid is enforced at every dial."""
+    reclaim_token: str = ""
+    """Opaque provider state persisted in the attack-box record, handed back verbatim at `teardown`."""
+
+
+class AttackBoxProvider(Protocol):
+    """An external supplier of one range's dedicated attack box.
+
+    `boot` receives the attachment and returns the running box's handle; it owns the box's lifecycle from that moment. `teardown` must be idempotent (a crash between the record write and `boot` reclaims a box that never existed) and must tolerate a token from a `boot` that half-completed.
+    """
+
+    async def boot(self, attachment: FootholdAttachment) -> AttackBoxHandle: ...
+
+    async def teardown(self, project: str, reclaim_token: str) -> None: ...
+
+
+@dataclass(frozen=True)
+class AttackBoxCapabilities:
+    """What the backend declares it can do; a declared gap is recorded as evidence, never silently absent."""
+
+    console_stream: bool = False
+    """Whether the provider delivers the attack box's console stream. `False` records a declared gap on `console/<guest>`; `True` is not yet supported (no ingest path) and is refused."""
+
+
+AttackBoxReclaimFn = Callable[[AttackBoxRecord, Path], None]
+"""The teardown-by-origin connector: `(record, state_dir)`; raises on failure, after which `down` refuses to touch the range's own resources (a dead netns strands a live foreign VMM)."""
+
+
+@dataclass(frozen=True)
+class AttackBoxBackend:
+    """One resolved backend bundle: the provider plus the hooks the provider protocol alone cannot carry.
+
+    `reclaim` overrides the teardown-by-origin connector; left `None`, teardown runs `provider.teardown` with the recorded token. `doctor_probe` lets `inspect-ranges doctor` check reachability. `capabilities` is the declared-drop surface the evidence record and the conformance battery hold the provider to.
+    """
+
+    provider: AttackBoxProvider
+    reclaim: AttackBoxReclaimFn | None = None
+    doctor_probe: DoctorProbe | None = None
+    capabilities: AttackBoxCapabilities = AttackBoxCapabilities()
+
+    def reclaimer(self) -> AttackBoxReclaimFn:
+        """The teardown-by-origin connector `down` runs: the explicit `reclaim`, or the provider's own `teardown` with the recorded token."""
+        if self.reclaim is not None:
+            return self.reclaim
+        provider = self.provider
+
+        def provider_reclaim(record: AttackBoxRecord, state_dir: Path) -> None:
+            asyncio.run(provider.teardown(record.project, record.reclaim_token))
+
+        return provider_reclaim
+
+
+@dataclass(frozen=True)
+class AttackBoxContext:
+    """What an `AttackBoxFactory` is called with."""
+
+    origin: str
+    """The full `INSPECT_RANGES_ATTACK_BOX` value, verbatim: what `up` stamps into the attack-box record, so a fresh process re-resolves teardown from disk alone."""
+    config: str | None
+    """The text after the value's first colon, `None` when absent: the backend's own opaque config."""
+    state_dir: Path
+    """The shared project state dir (the attack-box record lives under it)."""
+
+
+AttackBoxFactory = Callable[[AttackBoxContext], AttackBoxBackend]
+"""What the dotted path in `INSPECT_RANGES_ATTACK_BOX` names. Must be cheap: no dialing, no probing; remote work belongs in the provider's `boot`."""
+
+
+@dataclass(frozen=True)
+class ParsedAttackBox:
+    """One `INSPECT_RANGES_ATTACK_BOX` value, split but not yet resolved."""
+
+    value: str
+    """The full value, verbatim: what `up` stamps as the record's origin."""
+    head: str
+    """The part before the first colon: the factory's dotted import path."""
+    config: str | None
+    """The part after the first colon (`None` when absent): opaque backend config."""
+
+
+def parse_attack_box(value: str) -> ParsedAttackBox:
+    """Split an `INSPECT_RANGES_ATTACK_BOX` value against the grammar, without importing anything.
+
+    Raises:
+        ValueError: The value is not a dotted factory path; the message carries the full grammar.
+    """
+    head, sep, tail = value.partition(":")
+    config = tail if sep else None
+    if "." in head and all(part.isidentifier() for part in head.split(".")):
+        return ParsedAttackBox(value, head, config)
+    raise ValueError(f"unknown {ENV_VAR} backend {value!r} {_GRAMMAR}")
+
+
+def resolve_attack_box(value: str, state_dir: Path) -> AttackBoxBackend:
+    """THE resolver: an `INSPECT_RANGES_ATTACK_BOX` value (or a persisted record origin) to its backend bundle.
+
+    Raises:
+        ValueError: The value fits no grammar form, the dotted path does not import or does not name a callable, or the factory returned something other than an `AttackBoxBackend`. A factory's own exception propagates as-is.
+    """
+    parsed = parse_attack_box(value)
+    module_name, _, attr = parsed.head.rpartition(".")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as error:
+        raise ValueError(
+            f"{ENV_VAR}={parsed.value!r}: backend module {module_name!r} does "
+            f"not import ({error}); install the package providing it, or fix "
+            f"the variable {_GRAMMAR}"
+        ) from error
+    factory: Any = getattr(module, attr, None)
+    if factory is None:
+        raise ValueError(
+            f"{ENV_VAR}={parsed.value!r}: module {module_name!r} has no "
+            f"attribute {attr!r} {_GRAMMAR}"
+        )
+    if not callable(factory):
+        raise ValueError(
+            f"{ENV_VAR}={parsed.value!r}: {parsed.head!r} is not callable "
+            "(expected an AttackBoxFactory)"
+        )
+    backend = factory(
+        AttackBoxContext(origin=parsed.value, config=parsed.config, state_dir=state_dir)
+    )
+    if not isinstance(backend, AttackBoxBackend):
+        raise ValueError(
+            f"{ENV_VAR}={parsed.value!r}: {parsed.head!r} returned "
+            f"{type(backend).__name__}, not an AttackBoxBackend"
+        )
+    return backend
+
+
+def attack_box_origin() -> str | None:
+    """The configured attack-box origin, validated against the grammar; `None` when unset or empty.
+
+    Validation here is parse-only (no import), so a malformed value refuses loudly wherever the origin is first consulted, before any resource exists.
+
+    Raises:
+        ValueError: The variable is set but fits no grammar form.
+    """
+    value = os.environ.get(ENV_VAR)
+    if not value:
+        return None
+    parse_attack_box(value)
+    return value