saferun-cli 0.0.2__py3-none-any.whl

saferun/sandbox/attestation.py

@@ -0,0 +1,110 @@
+"""Kernel-view attestation: run a tiny probe inside a sandbox built exactly like a scan sandbox
+and report what the *kernel* says is in force (not what we asked Docker for).
+
+Language-agnostic: the probe is POSIX sh reading /proc and /sys, so it works in any image that
+meets the profile requirements. Controls that cannot be read are reported "unverified" or
+"unavailable"; nothing is reported "verified" without evidence.
+"""
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass, field
+
+from . import docker as dk
+from .config import DEFAULT_IMAGE, SANDBOX_UID, ControlStatus, SandboxError, SandboxLimits
+from .controls import MIB
+from .runner import run_sandboxed
+
+PROBE = r"""
+echo "uid=$(id -u)"
+sed -n 's/^\(NoNewPrivs\|Seccomp\|CapEff\|CapBnd\|CapAmb\):[[:space:]]*/\1=/p' /proc/self/status
+echo "apparmor=$(cat /proc/self/attr/current 2>/dev/null || echo none)"
+for f in memory.max memory.swap.max pids.max cpu.max; do echo "$f=$(cat /sys/fs/cgroup/$f 2>/dev/null || echo none)"; done
+echo "ifaces=$(tail -n +3 /proc/net/dev | cut -d: -f1 | tr -d ' ' | tr '\n' ',')"
+for p in /workspace/.w /.w /tmp/.w; do if ( : > "$p" ) 2>/dev/null; then echo "write:$p=yes"; else echo "write:$p=no"; fi; done
+"""
+
+
+@dataclass
+class AttestationReport:
+    image: str
+    image_id: str
+    controls: list[ControlStatus] = field(default_factory=list)
+
+    def by_name(self) -> dict[str, ControlStatus]:
+        return {c.name: c for c in self.controls}
+
+    @property
+    def violated(self) -> list[ControlStatus]:
+        return [c for c in self.controls if c.state == "violated"]
+
+    @property
+    def ok(self) -> bool:
+        """No control observed to be violated (unverified/unavailable ones are listed, not hidden)."""
+        return not self.violated
+
+
+def _parse(out: str) -> dict[str, str]:
+    kv = {}
+    for line in out.splitlines():
+        k, sep, v = line.partition("=")
+        if sep:
+            kv[k.strip()] = v.strip()
+    return kv
+
+
+def evaluate(kv: dict[str, str], lim: SandboxLimits, daemon_has_apparmor: bool) -> list[ControlStatus]:
+    """Turn raw probe output into control statuses (pure; unit-tested)."""
+    def st(name, ok, detail, missing=False):
+        return ControlStatus(name, "unverified" if missing else ("verified" if ok else "violated"), detail)
+
+    def need(key):
+        return key not in kv or kv[key] == "none"
+
+    caps = (kv.get("CapEff"), kv.get("CapBnd"), kv.get("CapAmb"))
+    apparmor = kv.get("apparmor", "none")
+    out = [
+        st("kernel-non-root", kv.get("uid") == str(SANDBOX_UID), f"uid={kv.get('uid')}", missing="uid" not in kv),
+        st("kernel-no-new-privileges", kv.get("NoNewPrivs") == "1", f"NoNewPrivs={kv.get('NoNewPrivs')}",
+           missing="NoNewPrivs" not in kv),
+        st("kernel-seccomp-filter", kv.get("Seccomp") == "2", f"Seccomp={kv.get('Seccomp')} (2 = filter)",
+           missing="Seccomp" not in kv),
+        st("kernel-capabilities-empty", all(c == "0" * 16 for c in caps if c is not None) and None not in caps[:2],
+           f"CapEff={caps[0]} CapBnd={caps[1]} CapAmb={caps[2]}", missing=caps[0] is None or caps[1] is None),
+        st("kernel-network-loopback-only", kv.get("ifaces") == "lo,", f"interfaces={kv.get('ifaces')!r}",
+           missing="ifaces" not in kv),
+        st("kernel-memory-max", kv.get("memory.max") == str(lim.memory_mb * MIB), f"memory.max={kv.get('memory.max')}",
+           missing=need("memory.max")),
+        st("kernel-swap-disabled", kv.get("memory.swap.max") == "0", f"memory.swap.max={kv.get('memory.swap.max')}",
+           missing=need("memory.swap.max")),
+        st("kernel-pids-max", kv.get("pids.max") == str(lim.pids), f"pids.max={kv.get('pids.max')}",
+           missing=need("pids.max")),
+        st("kernel-cpu-quota", (kv.get("cpu.max") or "").split()[:1] == [str(int(lim.cpus * 100_000))],
+           f"cpu.max={kv.get('cpu.max')}", missing=need("cpu.max")),
+        st("fs-workspace-read-only", kv.get("write:/workspace/.w") == "no", f"write={kv.get('write:/workspace/.w')}",
+           missing="write:/workspace/.w" not in kv),
+        st("fs-root-read-only", kv.get("write:/.w") == "no", f"write={kv.get('write:/.w')}",
+           missing="write:/.w" not in kv),
+        st("fs-tmp-writable", kv.get("write:/tmp/.w") == "yes", f"write={kv.get('write:/tmp/.w')}",
+           missing="write:/tmp/.w" not in kv),
+    ]
+    if apparmor.startswith("docker-default") and "(enforce)" in apparmor:
+        out.append(ControlStatus("kernel-apparmor-profile", "verified", apparmor))
+    elif apparmor in ("none", "") or not daemon_has_apparmor:
+        out.append(ControlStatus("kernel-apparmor-profile", "unavailable",
+                                 "AppArmor not active for the container on this host (not required)"))
+    else:
+        out.append(ControlStatus("kernel-apparmor-profile", "violated", f"profile={apparmor!r}"))
+    return out
+
+
+def attest(image: str = DEFAULT_IMAGE, limits: SandboxLimits | None = None) -> AttestationReport:
+    """Probe the sandbox for `image`. Costs one short container run."""
+    lim = limits or SandboxLimits(timeout_s=20)
+    with tempfile.TemporaryDirectory(prefix="saferun-attest-") as empty:
+        r = run_sandboxed(empty, ["sh", "-c", PROBE], lim, image=image)
+    if r.exit_code != 0:
+        raise SandboxError(f"attestation probe failed (exit {r.exit_code}): {r.stderr.strip()[:300]}")
+    daemon_apparmor = any(c.name == "daemon-apparmor" and c.state == "verified" for c in r.controls)
+    probe_controls = evaluate(_parse(r.stdout), lim, daemon_apparmor)
+    return AttestationReport(image, r.image_id, [*r.controls, *probe_controls])

saferun/sandbox/config.py

@@ -0,0 +1,121 @@
+"""Sandbox policy and result types."""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+from .images import PYTHON_IMAGE
+
+DEFAULT_IMAGE = PYTHON_IMAGE.reference  # pinned by digest (Phase 5A)
+SANDBOX_UID = 65534  # "nobody"
+CONTAINER_LABEL = "saferun.sandbox=1"
+DEADLINE_LABEL = "saferun.deadline"  # epoch seconds after which a container is an orphan
+REAP_MARGIN_S = 60  # slack added to the deadline so live runs are never reaped
+
+
+class SandboxError(RuntimeError):
+    """Sandbox could not be set up or torn down safely."""
+
+
+class WorkspaceLimitError(SandboxError):
+    """The project exceeds the configured copy limits."""
+
+
+class WorkspaceChangedError(SandboxError):
+    """The source tree changed while SafeRun was copying it; the copy is abandoned (fail closed)."""
+
+
+@dataclass(frozen=True)
+class SandboxLimits:
+    timeout_s: float = 30.0          # host-side wall clock, from `docker start`
+    container_grace_s: float = 5.0   # container-side `timeout` fires at timeout_s + grace
+    memory_mb: int = 256
+    cpus: float = 1.0
+    pids: int = 64
+    tmpfs_mb: int = 64
+    max_output_bytes: int = 256 * 1024
+    nofile: int = 256
+    fsize_mb: int = 64
+    shm_mb: int = 16
+
+    def __post_init__(self):
+        for k, v in vars(self).items():
+            if not (isinstance(v, (int, float)) and math.isfinite(v) and v > 0):
+                raise ValueError(f"SandboxLimits.{k} must be a positive finite number, got {v!r}")
+
+
+@dataclass(frozen=True)
+class WorkspaceLimits:
+    max_bytes: int = 400 * 1024 * 1024
+    max_files: int = 20_000   # counts files, directories and skipped entries
+    max_depth: int = 32       # directory levels below the project root
+
+    def __post_init__(self):
+        for k, v in vars(self).items():
+            if not (isinstance(v, int) and v > 0):
+                raise ValueError(f"WorkspaceLimits.{k} must be a positive integer, got {v!r}")
+
+
+@dataclass(frozen=True)
+class SensitivePolicy:
+    """How credential-like files are treated when building the workspace.
+
+    By default a source file that is not world-readable (directory: no other r/x) is withheld, since the
+    sandbox user is "other" and would not have been able to read it. Files with a credential signature
+    (see secrets.py) are withheld whatever their name. `allow_paths` (relative, posix) opts specific
+    paths back in; `honor_private_modes=False` is for umask-077 trees where everything is private.
+    """
+    honor_private_modes: bool = True
+    allow_paths: frozenset[str] = frozenset()
+
+    def __post_init__(self):
+        object.__setattr__(self, "allow_paths", frozenset(self.allow_paths))
+
+
+@dataclass(frozen=True)
+class WithheldEntry:
+    path: str    # relative path (untrusted; sanitize before display)
+    reason: str  # private-mode | private-key | token:<vendor>  -- never the secret itself
+
+
+@dataclass(frozen=True)
+class ControlStatus:
+    """One security control and what is actually known about it.
+
+    state: verified    - confirmed from Docker's own configuration or from inside the sandbox
+           violated    - observed to differ from policy (a run is refused / flagged)
+           unavailable - the host or daemon cannot provide it
+           unverified  - not checked, or the evidence needed is not obtainable
+    """
+    name: str
+    state: str
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class SkippedEntry:
+    path: str    # relative to the project root; untrusted, sanitize before display
+    reason: str  # symlink | hardlink-external | not-regular-file | unreadable
+
+
+@dataclass
+class SandboxResult:
+    exit_code: int | None
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+    oom_killed: bool = False
+    output_truncated: bool = False
+    duration_s: float = 0.0
+    container_name: str = ""
+    hardening: dict = field(default_factory=dict)  # HostConfig as Docker applied it
+    controls: list[ControlStatus] = field(default_factory=list)  # evidence for this run, see ControlStatus
+    image_id: str = ""  # the exact image (sha256:...) the container was created from
+    skipped: list[SkippedEntry] = field(default_factory=list)
+    withheld: list[WithheldEntry] = field(default_factory=list)  # sensitive files NOT given to the sandbox
+    redactions: int = 0  # secrets masked in stdout/stderr
+    # Workspace accounting. entries_scanned == copied_files + copied_dirs + len(skipped) + len(withheld)
+    entries_scanned: int = 0  # every directory entry visited
+    copied_files: int = 0     # regular files actually written to the workspace
+    copied_dirs: int = 0
+    copied_bytes: int = 0     # bytes of those files (withheld content is not counted)

saferun/sandbox/controls.py

@@ -0,0 +1,104 @@
+"""Evidence about which security controls are really in force.
+
+Pure functions over data Docker reports, so every rule is unit-testable without a daemon.
+- daemon_controls():       what the *daemon* can enforce (seccomp, cgroup limits, AppArmor)
+- verify_applied_config(): what Docker *applied* to the created, not yet started, container
+A control is only ever reported "verified" when this evidence supports it.
+"""
+from __future__ import annotations
+
+from .config import CONTAINER_LABEL, SANDBOX_UID, ControlStatus, SandboxLimits
+
+MIB = 1024 * 1024
+# Controls without which a run is refused (unless the caller explicitly allows degradation).
+REQUIRED_DAEMON = ("daemon-seccomp", "daemon-memory-limit", "daemon-swap-limit",
+                   "daemon-pids-limit", "daemon-cpu-quota")
+
+
+def _flag(info: dict, key: str, name: str, what: str) -> ControlStatus:
+    v = info.get(key)
+    if v is True:
+        return ControlStatus(name, "verified", f"daemon reports {what} support")
+    if v is False:
+        return ControlStatus(name, "unavailable", f"daemon reports no {what} support")
+    return ControlStatus(name, "unverified", f"daemon did not report {key}")
+
+
+def daemon_controls(info: dict) -> list[ControlStatus]:
+    """Capabilities of the Docker daemon, from `docker info`."""
+    opts = [o for o in (info.get("SecurityOptions") or []) if isinstance(o, str)]
+    seccomp = next((o for o in opts if o.startswith("name=seccomp")), None)
+    apparmor = next((o for o in opts if o.startswith("name=apparmor")), None)
+    out = []
+    if seccomp is None:
+        out.append(ControlStatus("daemon-seccomp", "unavailable", "daemon reports no seccomp support"))
+    elif "profile=unconfined" in seccomp:
+        out.append(ControlStatus("daemon-seccomp", "violated", "daemon default seccomp profile is unconfined"))
+    else:
+        out.append(ControlStatus("daemon-seccomp", "verified", seccomp))
+    out.append(ControlStatus("daemon-apparmor", "verified", apparmor) if apparmor else
+               ControlStatus("daemon-apparmor", "unavailable", "AppArmor is not enabled on this host (not required)"))
+    out += [
+        _flag(info, "MemoryLimit", "daemon-memory-limit", "memory limit"),
+        _flag(info, "SwapLimit", "daemon-swap-limit", "swap limit"),
+        _flag(info, "PidsLimit", "daemon-pids-limit", "pids limit"),
+        _flag(info, "CpuCfsQuota", "daemon-cpu-quota", "CPU quota"),
+    ]
+    return out
+
+
+def verify_applied_config(info: dict, lim: SandboxLimits, image_id: str,
+                          extra_mount_targets: tuple[str, ...] = ()) -> list[ControlStatus]:
+    """Check the container Docker created (from `docker inspect`) against policy."""
+    hc = info.get("HostConfig") or {}
+    cfg = info.get("Config") or {}
+    ulimits = {u.get("Name"): (u.get("Soft"), u.get("Hard")) for u in (hc.get("Ulimits") or [])
+               if isinstance(u, dict)}
+    tmpfs = (hc.get("Tmpfs") or {}).get("/tmp", "")
+    mounts = hc.get("Mounts") or []
+    secopt = " ".join(hc.get("SecurityOpt") or [])
+    nofile, fsize = lim.nofile, lim.fsize_mb * MIB
+
+    checks = [
+        ("not-privileged", hc.get("Privileged") is False, f"Privileged={hc.get('Privileged')}"),
+        ("network-none", hc.get("NetworkMode") == "none", f"NetworkMode={hc.get('NetworkMode')}"),
+        ("rootfs-read-only", hc.get("ReadonlyRootfs") is True, f"ReadonlyRootfs={hc.get('ReadonlyRootfs')}"),
+        ("capabilities-dropped", hc.get("CapDrop") == ["ALL"] and not hc.get("CapAdd"),
+         f"CapDrop={hc.get('CapDrop')} CapAdd={hc.get('CapAdd')}"),
+        ("no-new-privileges", "no-new-privileges" in secopt, f"SecurityOpt={hc.get('SecurityOpt')}"),
+        ("no-unconfined-profile", "unconfined" not in secopt, f"SecurityOpt={hc.get('SecurityOpt')}"),
+        ("entrypoint-reset", cfg.get("Entrypoint") in (None, [], [""]), f"Entrypoint={cfg.get('Entrypoint')}"),
+        ("non-root-user", cfg.get("User") == f"{SANDBOX_UID}:{SANDBOX_UID}", f"User={cfg.get('User')}"),
+        ("memory-limit", hc.get("Memory") == lim.memory_mb * MIB, f"Memory={hc.get('Memory')}"),
+        ("swap-disabled", hc.get("MemorySwap") == hc.get("Memory") == lim.memory_mb * MIB,
+         f"Memory={hc.get('Memory')} MemorySwap={hc.get('MemorySwap')}"),
+        ("cpu-quota", hc.get("NanoCpus") == int(lim.cpus * 1_000_000_000), f"NanoCpus={hc.get('NanoCpus')}"),
+        ("pids-limit", hc.get("PidsLimit") == lim.pids, f"PidsLimit={hc.get('PidsLimit')}"),
+        ("fd-limit", ulimits.get("nofile") == (nofile, nofile), f"nofile={ulimits.get('nofile')}"),
+        ("file-size-limit", ulimits.get("fsize") == (fsize, fsize), f"fsize={ulimits.get('fsize')}"),
+        ("core-dumps-off", ulimits.get("core") == (0, 0), f"core={ulimits.get('core')}"),
+        ("tmp-tmpfs", all(f in tmpfs.split(",") for f in ("noexec", "nosuid", "nodev", f"size={lim.tmpfs_mb}m")),
+         f"/tmp={tmpfs!r}"),
+        ("shm-limit", hc.get("ShmSize") == lim.shm_mb * MIB, f"ShmSize={hc.get('ShmSize')}"),
+        ("workspace-mount-read-only",
+         len(mounts) == 1 + len(extra_mount_targets) and not hc.get("Binds")
+         and all(isinstance(m, dict) and m.get("Type") == "bind" and m.get("ReadOnly") is True for m in mounts)
+         and sorted(str(m.get("Target")) for m in mounts if isinstance(m, dict)) == sorted(("/workspace", *extra_mount_targets)),
+         f"Mounts={mounts} Binds={hc.get('Binds')} expected targets={['/workspace', *extra_mount_targets]}"),
+        ("no-image-volumes", not cfg.get("Volumes"), f"image declares VOLUME: {cfg.get('Volumes')}"),
+        ("no-devices", not hc.get("Devices"), f"Devices={hc.get('Devices')}"),
+        ("no-published-ports", not hc.get("PortBindings") and hc.get("PublishAllPorts") is False,
+         f"PortBindings={hc.get('PortBindings')}"),
+        ("private-namespaces", hc.get("PidMode") == "" and hc.get("IpcMode") in ("", "private")
+         and hc.get("UsernsMode") == "" and hc.get("UTSMode") == "",
+         f"Pid={hc.get('PidMode')!r} Ipc={hc.get('IpcMode')!r} Userns={hc.get('UsernsMode')!r} UTS={hc.get('UTSMode')!r}"),
+        ("init-process", hc.get("Init") is True, f"Init={hc.get('Init')}"),
+        ("logging-off", (hc.get("LogConfig") or {}).get("Type") == "none", f"LogConfig={hc.get('LogConfig')}"),
+        ("oom-kill-enabled", not hc.get("OomKillDisable"), f"OomKillDisable={hc.get('OomKillDisable')}"),
+        ("no-restart", (hc.get("RestartPolicy") or {}).get("Name") in ("", "no"),
+         f"RestartPolicy={hc.get('RestartPolicy')}"),
+        ("created-from-resolved-image", info.get("Image") == image_id, f"Image={info.get('Image')}"),
+        ("saferun-label", (cfg.get("Labels") or {}).get(CONTAINER_LABEL.split("=")[0]) == "1",
+         "label saferun.sandbox"),
+    ]
+    return [ControlStatus(n, "verified" if ok else "violated", d) for n, ok, d in checks]

saferun/sandbox/copy.py

@@ -0,0 +1,338 @@
+"""Race-safe, limit-enforcing, exposure-aware copy of an untrusted directory tree.
+
+Two passes over the tree, both relative to already-open directory fds with O_NOFOLLOW:
+
+1. Pre-scan (stat only for files): records a *signature* (type/mode, dev, ino, size, mtime_ns,
+   ctime_ns) for every visited entry and the name set of every directory it lists.
+2. Copy: every entry's lstat, and the object actually opened, must match its recorded
+   signature before anything is read; every directory listing must equal the recorded name set;
+   after reading, the file must be unchanged.
+3. Final validation: the whole tree is walked once more and every directory (identity,
+   metadata, listing) and every entry must still match the pre-scan records, so changes made
+   after an entry was copied, or after its directory was listed, are caught too.
+Any replaced, added, removed or modified entry found by any step aborts the whole copy with
+WorkspaceChangedError (nothing is kept); the caller can simply retry.
+
+This is *detection on a live filesystem, not an atomic snapshot*: a change made after the final
+validation cannot affect the already-copied files (each was verified when read), but without
+filesystem snapshot support SafeRun cannot make the tree stand still while it is read, and a
+modification that leaves every recorded field identical (e.g. within one coarse timestamp tick on
+kernels without fine-grained timestamps) is not detectable.
+
+ctime cannot be set from user space and changes on rename, chmod, link/unlink and content
+writes, so a restored mtime or a reused inode number does not hide a replacement.
+
+Exposure rules (see SensitivePolicy / secrets.py):
+- not world-readable in the source  -> withheld, never opened or read
+- credential signature in content   -> withheld (written copy deleted)
+- hard link whose inode has a name outside the scanned tree -> skipped
+"""
+from __future__ import annotations
+
+import errno
+import os
+import stat
+from collections import Counter
+from dataclasses import dataclass
+
+from .config import (
+    SensitivePolicy, SkippedEntry, WithheldEntry, WorkspaceChangedError, WorkspaceLimitError,
+    WorkspaceLimits,
+)
+from .secrets import LEARN_MAX, Redactor, SignatureScanner
+
+_RD = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)   # POSIX copy engine; Windows uses copy_windows.py (same value on Linux/macOS)
+CHUNK = 1024 * 1024
+_GONE = (errno.ELOOP, errno.ENOTDIR, errno.ENOENT)  # opening failed because the entry was replaced/removed
+_SIZE = 3  # index of st_size inside a signature
+
+
+def _sig(st: os.stat_result) -> tuple:
+    return (st.st_mode, st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns, st.st_ctime_ns)
+
+
+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)")
+
+
+@dataclass
+class CopyResult:
+    skipped: list[SkippedEntry]
+    withheld: list[WithheldEntry]
+    entries_scanned: int  # every directory entry visited; == copied_files + copied_dirs + len(skipped) + len(withheld)
+    copied_files: int     # regular files written and kept
+    copied_dirs: int
+    copied_bytes: int     # bytes of the kept files only (discarded/withheld content is not counted)
+    redactor: Redactor
+
+
+class _Budget:
+    def __init__(self, lim: WorkspaceLimits):
+        self.lim, self.files, self.bytes = lim, 0, 0
+
+    def entry(self) -> None:
+        self.files += 1
+        if self.files > self.lim.max_files:
+            raise WorkspaceLimitError(f"project has more than {self.lim.max_files} entries")
+
+    def add_bytes(self, n: int) -> None:
+        self.bytes += n
+        if self.bytes > self.lim.max_bytes:
+            raise WorkspaceLimitError(f"project is larger than {self.lim.max_bytes} bytes")
+
+    def depth(self, d: int) -> None:
+        if d > self.lim.max_depth:
+            raise WorkspaceLimitError(f"project is nested deeper than {self.lim.max_depth} directories")
+
+
+class _Sink:
+    """Writes the copy under `dest` (a directory we own and created; mode 0700 until the copy is done)."""
+
+    def __init__(self, dest: str):
+        self.dest = dest
+
+    def mkdir(self, rel: str) -> None:
+        p = os.path.join(self.dest, rel)
+        os.mkdir(p, 0o755)
+        os.chmod(p, 0o755)
+
+    def write(self, rel: str, src_fd: int, want: tuple, budget: _Budget, redactor: Redactor,
+              withhold_on_match: bool) -> tuple[str | None, int]:
+        """Copy one file. Returns (signature kind, bytes kept); kind is set iff the copy was removed."""
+        dest, scanner, kind = os.path.join(self.dest, rel), SignatureScanner(), None
+        head: bytearray | None = bytearray()
+        written = read = 0
+        fd = os.open(dest, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC, 0o644)
+        try:
+            os.fchmod(fd, 0o644)  # executable bits intentionally dropped
+            while chunk := os.read(src_fd, CHUNK):
+                read += len(chunk)
+                budget.add_bytes(len(chunk))  # real bytes: files may grow after the pre-scan
+                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
+        # Fully read: the file must be the very object and state the pre-scan recorded.
+        if read != want[_SIZE] or _sig(os.fstat(src_fd)) != want:
+            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: stat only for files, nothing is read or written.
+
+    Pre-scan fills `records` / `listings`; the copy pass is given them as `expected*` and verifies.
+    """
+
+    def __init__(self, lim: WorkspaceLimits, policy: SensitivePolicy, sink: _Sink | None,
+                 seen_links: Counter | None = None, expected: dict | None = None,
+                 expected_listings: dict | None = None):
+        self.budget, self.policy, self.sink = _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()          # pre-scan: names seen per multi-link inode
+        self.seen_links = seen_links or Counter()  # copy pass: result of the pre-scan
+        self.records: dict[str, tuple] = {}      # pre-scan: path -> signature
+        self.listings: dict[str, frozenset] = {}  # pre-scan: dir path -> names
+        self.expected, self.expected_listings = expected, expected_listings
+
+    def _private(self, path: str, mode: int, other_bits: int) -> bool:
+        if (self.policy.honor_private_modes and path not in self.policy.allow_paths
+                and not mode & other_bits):
+            self.withheld.append(WithheldEntry(path, "private-mode"))
+            return True
+        return False
+
+    def _verify(self, path: str, want: tuple) -> None:
+        """Pre-scan: record. Copy pass: the entry must be exactly what was recorded."""
+        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, dir_fd: int, rel: str) -> list[str]:
+        """List a directory, counting entries against the budget *as they are read*, so a huge
+        directory is rejected without being read in full. The copy pass must see the recorded names."""
+        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: list[str] = []
+        with os.scandir(dir_fd) as it:
+            for e in it:
+                self.budget.entry()
+                if exp is not None and e.name not in exp:
+                    raise _changed(f"{rel}/{e.name}" if rel else e.name, "entry was added")
+                names.append(e.name)
+        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, dir_fd: int, rel: str, depth: int) -> None:
+        for name in self._list(dir_fd, rel):
+            path = f"{rel}/{name}" if rel else name
+            try:
+                st = os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
+            except FileNotFoundError:
+                raise _changed(path, "entry was removed") from None
+            except OSError:
+                self.skipped.append(SkippedEntry(path, "unreadable"))
+                continue
+            want = _sig(st)
+            self._verify(path, want)
+            if stat.S_ISLNK(st.st_mode):
+                self.skipped.append(SkippedEntry(path, "symlink"))
+            elif stat.S_ISDIR(st.st_mode):
+                self._dir(dir_fd, name, path, st, want, depth)
+            elif stat.S_ISREG(st.st_mode):
+                self._file(dir_fd, name, path, st, want)
+            else:
+                self.skipped.append(SkippedEntry(path, "not-regular-file"))
+
+    def _open(self, name, dir_fd, extra, path, want):
+        """Open without following symlinks; the opened object must match `want`. -> (fd, fstat) | None"""
+        try:
+            fd = os.open(name, _RD | extra, dir_fd=dir_fd)
+        except OSError as e:
+            if e.errno in _GONE:
+                raise _changed(path, "entry was replaced or removed") from None
+            self.skipped.append(SkippedEntry(path, "unreadable"))
+            return None
+        fst = os.fstat(fd)
+        if _sig(fst) != want:
+            os.close(fd)
+            raise _changed(path, "entry was replaced or modified")
+        return fd, fst
+
+    def _dir(self, dir_fd, name, path, st, want, depth):
+        self.budget.depth(depth + 1)
+        if self._private(path, st.st_mode, 0o005):
+            return
+        opened = self._open(name, dir_fd, os.O_DIRECTORY, path, want)
+        if opened is None:
+            return
+        fd, _ = opened
+        try:
+            if self.sink:
+                self.sink.mkdir(path)
+                self.copied_dirs += 1
+            self.walk(fd, path, depth + 1)
+        finally:
+            os.close(fd)
+
+    def _file(self, dir_fd, name, path, st, want):
+        if self.sink is None:  # pre-scan
+            if st.st_nlink > 1:
+                self.links[(st.st_dev, st.st_ino)] += 1
+            if not self._private(path, st.st_mode, 0o004):
+                self.budget.add_bytes(st.st_size)
+            return
+        if self._private(path, st.st_mode, 0o004):  # never opened, never read
+            return
+        opened = self._open(name, dir_fd, os.O_NONBLOCK | os.O_NOCTTY, path, want)
+        if opened is None:
+            return
+        fd, fst = opened
+        try:
+            # Hard link: only safe if EVERY name of this inode was seen inside the tree.
+            if fst.st_nlink > 1 and self.seen_links[(fst.st_dev, fst.st_ino)] != fst.st_nlink:
+                self.skipped.append(SkippedEntry(path, "hardlink-external"))
+                return
+            kind, kept = self.sink.write(path, fd, want, 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:
+            os.close(fd)
+
+
+def _validate_tree(dir_fd: int, rel: str, records: dict, listings: dict, budget: _Budget) -> None:
+    """Final pass: `dir_fd` and everything below it must still be exactly what the pre-scan recorded.
+
+    Recurses only into directories the pre-scan descended into (those with a recorded listing);
+    other entries (symlinks, withheld or unreadable directories, special files) are checked by lstat.
+    """
+    expected = listings[rel]
+    names: list[str] = []
+    with os.scandir(dir_fd) as it:
+        for e in it:
+            budget.entry()
+            if e.name not in expected:
+                raise _changed(f"{rel}/{e.name}" if rel else e.name, "entry was added (final check)")
+            names.append(e.name)
+    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:
+            st = os.stat(name, dir_fd=dir_fd, follow_symlinks=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  # was already unreadable at pre-scan time
+        if records.get(path) != _sig(st):
+            raise _changed(path, "entry was replaced or modified (final check)")
+        if stat.S_ISDIR(st.st_mode) and path in listings:
+            try:
+                fd = os.open(name, _RD | os.O_DIRECTORY, dir_fd=dir_fd)
+            except OSError:
+                raise _changed(path, "directory was replaced or removed (final check)") from None
+            try:
+                if _sig(os.fstat(fd)) != records[path]:
+                    raise _changed(path, "directory was replaced or modified (final check)")
+                _validate_tree(fd, path, records, listings, budget)
+            finally:
+                os.close(fd)
+
+
+def copy_tree(src: str, dest: str, lim: WorkspaceLimits,
+              policy: SensitivePolicy | None = None) -> CopyResult:
+    """Pre-scan (stat only), verified copy, then a final validation pass.
+
+    Raises WorkspaceLimitError before anything is copied if the pre-scan already exceeds a
+    limit (limits are enforced again during the copy) and WorkspaceChangedError if the tree
+    is found modified between the passes, during a read, or by the final validation.
+    """
+    policy = policy or SensitivePolicy()
+    root_fd = os.open(src, _RD | os.O_DIRECTORY)
+    try:
+        pre = _Walker(lim, policy, None)
+        pre.records[""] = _sig(os.fstat(root_fd))
+        pre.walk(root_fd, "", 0)
+        w = _Walker(lim, policy, _Sink(dest), pre.links, pre.records, pre.listings)
+        if _sig(os.fstat(root_fd)) != pre.records[""]:
+            raise _changed("", "the project root was modified")
+        w.walk(root_fd, "", 0)
+        if _sig(os.fstat(root_fd)) != pre.records[""]:
+            raise _changed("", "the project root was modified (final check)")
+        _validate_tree(root_fd, "", 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:
+        os.close(root_fd)