saferun-cli 0.0.2__py3-none-any.whl

saferun/hostos/fsops.py

@@ -0,0 +1,41 @@
+"""The file-system operations the Windows copy engine (sandbox/copy_windows.py) is written against.
+
+`copy_windows` contains the whole algorithm (three passes, signatures, listings, limits, exposure rules); an `FsOps` implementation only
+opens, lists, reads and describes things. The real one (`hostos.winfs.WinOps`) uses Win32 handles; the tests also run the algorithm
+against a POSIX implementation so its logic is exercised on every platform.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class EntryReplaced(OSError):
+    """An opened object is not the one that was named (moved, replaced, or reached through a different path)."""
+
+
+@dataclass(frozen=True)
+class Info:
+    kind: str          # file | dir | symlink | reparse | other
+    sig: tuple         # identity + state; the two passes and the final check must see the same value
+    ident: tuple       # identity shared by all hard links of a file
+    size: int
+    nlink: int
+    private: bool = False   # only meaningful when the probe asked for it: narrower than the project root, or unverifiable
+
+
+class Node(Protocol):
+    info: Info
+    path: str
+
+
+class FsOps(Protocol):
+    def open_root(self, path: str) -> Any: ...                              # directory node; reparse point or remote path -> OSError
+    def listdir(self, d: Any) -> list[str]: ...
+    def probe(self, d: Any, name: str, with_acl: bool) -> Info: ...               # describe WITHOUT following; FileNotFoundError if gone
+    def open_dir(self, d: Any, name: str) -> Any: ...                        # locks it against rename / delete while open
+    def open_file(self, d: Any, name: str) -> Any: ...                       # read-only; denies others write / delete while open
+    def refresh(self, node: Any) -> Info: ...                                # state of the OPEN object (fstat)
+    def read(self, node: Any, n: int) -> bytes: ...
+    def streams(self, d: Any, name: str) -> list[str]: ...                   # data stream names other than the default one
+    def close(self, node: Any) -> None: ...

saferun/hostos/process.py

@@ -0,0 +1,82 @@
+"""Starting, interrupting and killing a whole process tree.
+
+POSIX: a new session / process group, signalled as a group (exactly what SafeRun always did).
+Windows: the child starts SUSPENDED, is put into a kill-on-close job object and only then resumed, so it cannot spawn a process that
+escapes the job; killing the job ends the whole tree, and it also dies if SafeRun itself dies. Interrupt is CTRL_BREAK to the process group.
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+
+IS_WINDOWS = sys.platform == "win32"
+
+if IS_WINDOWS:
+    from . import _win
+
+    _CREATE_SUSPENDED = 0x00000004
+
+
+def popen_kwargs() -> dict:
+    if IS_WINDOWS:
+        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | _CREATE_SUSPENDED, "close_fds": True}
+    return {"start_new_session": True, "close_fds": True}
+
+
+def after_spawn(proc: subprocess.Popen) -> None:
+    """Windows: confine `proc` to a job and let it run. Raises OSError (after killing it) if that is impossible. POSIX: nothing to do."""
+    if not IS_WINDOWS:
+        return
+    job = None
+    try:
+        job = _win.create_kill_on_close_job()
+        _win.assign_to_job(job, int(proc._handle))
+        proc._saferun_job = job
+        _win.resume_process(int(proc._handle))
+    except BaseException:
+        try:
+            proc.kill()
+        except OSError:
+            pass
+        if job:
+            _win.close(job)
+        raise
+
+
+def kill_tree(proc: subprocess.Popen) -> None:
+    if IS_WINDOWS:
+        job = getattr(proc, "_saferun_job", None)
+        if job:
+            _win.terminate_job(job)
+    else:
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            pass
+    try:
+        proc.kill()
+    except OSError:
+        pass
+
+
+def interrupt_tree(proc: subprocess.Popen) -> None:
+    if IS_WINDOWS:
+        try:
+            proc.send_signal(signal.CTRL_BREAK_EVENT)
+        except (OSError, ValueError):
+            pass
+    else:
+        try:
+            os.killpg(proc.pid, signal.SIGINT)
+        except (ProcessLookupError, PermissionError):
+            pass
+
+
+def release(proc: subprocess.Popen) -> None:
+    """Windows: close the job handle, which also ends anything the finished process left behind. POSIX: nothing."""
+    job = getattr(proc, "_saferun_job", None)
+    if IS_WINDOWS and job:
+        proc._saferun_job = None
+        _win.close(job)

saferun/hostos/winfs.py

@@ -0,0 +1,164 @@
+"""`FsOps` for Windows (NTFS / ReFS) on Win32 handles. Imported only on Windows.
+
+Why this is race-resistant (the Windows counterpart of openat + O_NOFOLLOW):
+* every entry is opened with FILE_FLAG_OPEN_REPARSE_POINT, so a symlink / junction / mount point is opened as itself and never followed;
+* every directory stays open, with a share mode that forbids rename and delete, until its subtree has been walked, so NTFS refuses to
+  move or replace it or any ancestor on the way down;
+* files are read with a share mode that forbids writers and deleters;
+* the final path of each opened handle must equal parent path + name;
+* identity is read from the open handle (128-bit file id + volume), never from a path.
+Adding or removing entries inside a directory is still possible, so the listing / signature comparison of the three passes stays.
+"""
+from __future__ import annotations
+
+import msvcrt
+import os
+from dataclasses import dataclass, field
+
+from . import _win, acl
+from .fsops import EntryReplaced, Info
+
+_SIG_ATTRS = 0x1 | 0x2 | 0x4 | 0x10 | 0x400    # READONLY HIDDEN SYSTEM DIRECTORY REPARSE_POINT; ARCHIVE / indexing flags change by themselves
+_ALL_SHARE = _win.SHARE_READ | _win.SHARE_WRITE | _win.SHARE_DELETE
+_BENIGN_STREAMS = frozenset({"::$DATA", ":Zone.Identifier:$DATA"})   # default data; "downloaded from the internet" mark (never copied)
+
+
+@dataclass
+class WinNode:
+    path: str
+    info: Info
+    handle: int | None = None     # directories
+    fd: int | None = None         # files (owns the handle)
+    final: str = ""
+    extra: dict = field(default_factory=dict)
+
+
+def _norm(p: str) -> str:
+    return os.path.normcase(p).rstrip("\\")
+
+
+def _mk_info(h: int, acl_state: tuple | None, with_acl: bool) -> Info:
+    fi = _win.file_info(h)
+    attrs = fi["attrs"]
+    if attrs & _win.ATTR_REPARSE_POINT:
+        kind = "symlink" if fi["tag"] == _win.TAG_SYMLINK else "reparse"
+    else:
+        kind = "dir" if attrs & _win.ATTR_DIRECTORY else "file"
+    size = fi["size"] if kind == "file" else 0
+    sig = (kind, attrs & _SIG_ATTRS, fi["ident"], size, fi["written"], fi["changed"], fi["nlink"])
+    private = False
+    if with_acl and kind in ("file", "dir"):
+        private = not _readable_like_root(h, kind == "dir", acl_state)
+    return Info(kind, sig, fi["ident"], size, fi["nlink"], private)
+
+
+def _readable_like_root(h: int, directory: bool, state) -> bool:
+    caller, baseline = state
+    try:
+        desc = acl.parse_descriptor(_win.security_descriptor(h))
+        return acl.at_least_as_readable(desc.dacl, baseline, caller, directory=directory)
+    except (OSError, acl.AclUnverifiable):
+        return False   # cannot verify -> treated as private (withheld), never as shareable
+
+
+class WinOps:
+    def __init__(self):
+        self._caller = _win.current_token()[0]
+        self._state: tuple | None = None   # (caller token, root DACL) once the root is open
+
+    def open_root(self, path: str) -> WinNode:
+        real = os.path.realpath(path)
+        if _win.is_remote_drive(real):
+            raise OSError(f"{real} is on a network drive; SafeRun copies local projects only")
+        h = _win.open_handle(real, _win.FILE_LIST_DIRECTORY | _win.FILE_READ_ATTRIBUTES | _win.READ_CONTROL, _win.SHARE_READ,
+                             flags=_win.FLAG_BACKUP_SEMANTICS | _win.FLAG_OPEN_REPARSE_POINT)
+        try:
+            final = _win.final_path(h)
+            if _norm(final) != _norm(real):
+                raise EntryReplaced(f"the project root resolves to {final}, not {real}")
+            info = _mk_info(h, None, False)
+            if info.kind != "dir":
+                raise NotADirectoryError(f"not a plain directory (reparse point?): {real}")
+            try:
+                self._state = (self._caller, acl.parse_descriptor(_win.security_descriptor(h)).dacl)
+            except (OSError, acl.AclUnverifiable) as e:
+                raise OSError(f"cannot read the access-control list of the project root, so private files cannot be told apart: {e}") from None
+            return WinNode(final, info, handle=h, final=final)
+        except BaseException:
+            _win.close(h)
+            raise
+
+    def listdir(self, d: WinNode) -> list[str]:
+        with os.scandir(_win.ext(d.path)) as it:
+            return [e.name for e in it]
+
+    def _child(self, d: WinNode, name: str) -> str:
+        return d.path.rstrip("\\") + "\\" + name
+
+    def probe(self, d: WinNode, name: str, with_acl: bool) -> Info:
+        path = self._child(d, name)
+        private_forced = False
+        try:
+            h = _win.open_handle(path, _win.FILE_READ_ATTRIBUTES | _win.READ_CONTROL, _ALL_SHARE,
+                                 flags=_win.FLAG_BACKUP_SEMANTICS | _win.FLAG_OPEN_REPARSE_POINT)
+        except PermissionError:   # cannot even read its ACL: describe it, but it counts as private
+            h = _win.open_handle(path, _win.FILE_READ_ATTRIBUTES, _ALL_SHARE,
+                                 flags=_win.FLAG_BACKUP_SEMANTICS | _win.FLAG_OPEN_REPARSE_POINT)
+            private_forced = True
+        try:
+            info = _mk_info(h, self._state, with_acl and not private_forced)
+            if private_forced and with_acl:
+                info = Info(info.kind, info.sig, info.ident, info.size, info.nlink, True)
+            return info
+        finally:
+            _win.close(h)
+
+    def _check_path(self, d: WinNode, name: str, h: int) -> str:
+        """Final path of the open handle `h`. Raises without closing `h`: the caller owns it and closes it on any failure."""
+        final = _win.final_path(h)
+        if _norm(final) != _norm(d.final.rstrip("\\") + "\\" + name):
+            raise EntryReplaced(f"{name} is not located where its directory says")
+        return final
+
+    def open_dir(self, d: WinNode, name: str) -> WinNode:
+        h = _win.open_handle(self._child(d, name), _win.FILE_LIST_DIRECTORY | _win.FILE_READ_ATTRIBUTES | _win.READ_CONTROL, _win.SHARE_READ,
+                             flags=_win.FLAG_BACKUP_SEMANTICS | _win.FLAG_OPEN_REPARSE_POINT)
+        try:
+            final = self._check_path(d, name, h)
+            return WinNode(self._child(d, name), _mk_info(h, None, False), handle=h, final=final)
+        except BaseException:
+            _win.close(h)
+            raise
+
+    def open_file(self, d: WinNode, name: str) -> WinNode:
+        h = _win.open_handle(self._child(d, name), _win.GENERIC_READ | _win.FILE_READ_ATTRIBUTES, _win.SHARE_READ,
+                             flags=_win.FLAG_OPEN_REPARSE_POINT)
+        try:
+            final = self._check_path(d, name, h)
+            fd = msvcrt.open_osfhandle(h, os.O_RDONLY | os.O_BINARY | os.O_NOINHERIT)
+        except BaseException:
+            _win.close(h)
+            raise
+        try:   # from here the descriptor owns the handle
+            return WinNode(self._child(d, name), _mk_info(h, None, False), fd=fd, final=final)
+        except BaseException:
+            os.close(fd)
+            raise
+
+    def refresh(self, node: WinNode) -> Info:
+        h = node.handle if node.handle is not None else msvcrt.get_osfhandle(node.fd)
+        return _mk_info(h, None, False)
+
+    def read(self, node: WinNode, n: int) -> bytes:
+        return os.read(node.fd, n)
+
+    def streams(self, d: WinNode, name: str) -> list[str]:
+        return [s for s in _win.stream_names(self._child(d, name)) if s not in _BENIGN_STREAMS]
+
+    def close(self, node: WinNode) -> None:
+        if node.fd is not None:
+            os.close(node.fd)
+            node.fd = None
+        elif node.handle is not None:
+            _win.close(node.handle)
+            node.handle = None

saferun/runcmd.py

@@ -0,0 +1,139 @@
+"""`saferun run SCRIPT [ARGS...]`: scan a Python script, and only if the scan allows it, run it INSIDE the existing hardened sandbox.
+
+The script never runs on the host. The scan is the normal `validate_project` (syntax, Semgrep, dependencies); the run is the normal
+`run_sandboxed` (pinned python image, no network, read-only root and project, non-root, no capabilities, resource limits, output cap and
+secret redaction). By default only the script itself is staged and scanned (a copy in a private temporary directory); `--project-dir`
+stages a whole directory that contains it. A passing scan is NOT a proof of safety: it only means the checks found nothing they know about.
+
+Refusal (script not run): FAIL -> exit 1; WARNING -> exit 2. --allow-warnings only accepts a WARNING that comes from a COMPLETE scan whose
+findings are all below high severity; an incomplete, errored, timed-out, skipped or unavailable check, or any high/critical finding, is never overridden.
+Other exit codes: 0 the script ran and exited 0; 3 it ran and exited non-zero / timed out / was killed; 64 usage; 70 could not be scanned or sandboxed.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import stat
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .engine import ValidationOptions, Verdict, validate_project
+from .engine.model import CheckStatus, Severity
+from .sandbox import SandboxError, SandboxLimits, run_sandboxed
+from .sandbox.profiles import PYTHON
+
+EXIT_PASS, EXIT_FAIL, EXIT_WARNING, EXIT_SCRIPT_FAILED, EXIT_USAGE, EXIT_FATAL = 0, 1, 2, 3, 64, 70
+MAX_SCRIPT_BYTES = 5 * 1024 * 1024
+
+
+_COMPLETED = frozenset({CheckStatus.PASSED, CheckStatus.FINDINGS, CheckStatus.NOT_APPLICABLE})
+_SERIOUS = frozenset({Severity.CRITICAL, Severity.HIGH})
+
+
+def warning_blockers(report) -> list[str]:
+    """Reasons a WARNING can NOT be overridden by --allow-warnings (empty list: it may be). Fail closed."""
+    out = []
+    if not report.complete:
+        out.append("the scan is incomplete")
+    out += [f"check {c.name} did not complete ({c.status.value})" for c in report.checks if c.status not in _COMPLETED]
+    out += [f"{f.severity.value} finding {f.rule_id}" for f in report.findings if f.severity in _SERIOUS]
+    return out
+
+
+# The script's output is untrusted text: terminal escape sequences in it could clear the screen, rewrite earlier lines or fake SafeRun's own
+# messages. Everything except newline and tab that is a control, escape, C1 or bidi-override character is replaced before it reaches the terminal.
+_UNSAFE_OUTPUT = re.compile("[\x00-\x08\x0b-\x1f\x7f-\x9f\u200e\u200f\u202a-\u202e\u2066-\u2069]")
+
+
+def safe_output(text: str) -> str:
+    return _UNSAFE_OUTPUT.sub("?", text.replace("\r\n", "\n"))
+
+
+class RunUsageError(ValueError):
+    pass
+
+
+@dataclass
+class Staged:
+    root: Path          # directory handed to scan and sandbox
+    rel_script: str     # script path relative to root, posix
+
+
+def stage(script: Path, project_dir: Path | None, tmp_root: Path) -> Staged:
+    """Describe what will be scanned and run. Raises RunUsageError."""
+    try:
+        st = os.lstat(script)
+    except OSError:
+        raise RunUsageError(f"script does not exist: {script}") from None
+    if stat.S_ISLNK(st.st_mode) or not stat.S_ISREG(st.st_mode):
+        raise RunUsageError(f"not a regular file (symlinks are refused): {script}")
+    if script.suffix != ".py":
+        raise RunUsageError("only Python scripts (.py) can be run")
+    if st.st_size > MAX_SCRIPT_BYTES:
+        raise RunUsageError(f"script is larger than {MAX_SCRIPT_BYTES} bytes")
+    if project_dir is not None:
+        root = project_dir.resolve()
+        if not root.is_dir():
+            raise RunUsageError(f"not a directory: {project_dir}")
+        try:
+            rel = script.resolve().relative_to(root)
+        except ValueError:
+            raise RunUsageError("the script must be inside --project-dir") from None
+        return Staged(root, rel.as_posix())
+    root = tmp_root / "project"
+    root.mkdir(mode=0o755)
+    os.chmod(root, 0o755)                        # the sandbox user is "other": it must be able to read what it is given
+    dest = root / script.name
+    shutil.copyfile(script, dest)
+    os.chmod(dest, 0o644)
+    return Staged(root, script.name)
+
+
+def run_script(script: str, script_args: list[str], *, project_dir: str | None = None, timeout_s: float = 30.0,
+               allow_warnings: bool = False, out, err, render=None, scan=validate_project, sandbox=run_sandboxed) -> int:
+    """Returns the process exit code. `scan` and `sandbox` are injectable for tests."""
+    with tempfile.TemporaryDirectory(prefix="saferun-run-") as tmp:
+        try:
+            staged = stage(Path(script), Path(project_dir) if project_dir else None, Path(tmp))
+        except RunUsageError as e:
+            err.write(f"saferun: {e}\n")
+            return EXIT_USAGE
+        try:
+            report = scan(staged.root, ValidationOptions())
+        except SandboxError as e:
+            err.write(f"saferun: cannot scan, so the script was NOT run (no verdict): {e}\n")
+            return EXIT_FATAL
+        except Exception as e:  # noqa: BLE001 - never run anything after an unexpected scan failure
+            err.write(f"saferun: internal error while scanning, so the script was NOT run: {type(e).__name__}: {e}\n")
+            return EXIT_FATAL
+        if render:
+            out.write(render(report))
+        if report.verdict is Verdict.FAIL:
+            err.write("saferun: the scan found high-severity problems: the script was NOT run.\n")
+            return EXIT_FAIL
+        if report.verdict is not Verdict.PASS:
+            blockers = warning_blockers(report) if allow_warnings else ["--allow-warnings was not given"]
+            if blockers:
+                err.write("saferun: the scan verdict is WARNING: the script was NOT run (" + "; ".join(blockers[:5]) + "). Fix the findings or the "
+                          "missing setup (`saferun doctor`); --allow-warnings never overrides an incomplete check or a high/critical finding.\n")
+                return EXIT_WARNING
+        err.write("saferun: scan verdict " + report.verdict.value.upper() + ". A scan is not proof of safety; running inside the sandbox "
+                  "(no network, read-only filesystem, non-root, resource limits).\n")
+        try:
+            res = sandbox(staged.root, [PYTHON.interpreter, "-I", f"/workspace/{staged.rel_script}", *script_args],
+                          limits=SandboxLimits(timeout_s=timeout_s), image=PYTHON.image)
+        except SandboxError as e:
+            err.write(f"saferun: the sandbox could not run the script: {e}\n")
+            return EXIT_FATAL
+    out.write(safe_output(res.stdout))
+    if res.stderr:
+        err.write(safe_output(res.stderr))
+    if res.timed_out:
+        err.write(f"saferun: the script was stopped after {timeout_s:g} s.\n")
+    if res.oom_killed:
+        err.write("saferun: the script was killed for exceeding the memory limit.\n")
+    if res.output_truncated:
+        err.write("saferun: output was truncated at the sandbox limit.\n")
+    return EXIT_PASS if res.exit_code == 0 and not res.timed_out and not res.oom_killed else EXIT_SCRIPT_FAILED

saferun/sandbox/__init__.py

@@ -0,0 +1,11 @@
+from .config import (
+    DEFAULT_IMAGE, ControlStatus, SandboxError, SandboxLimits, SandboxResult, SensitivePolicy,
+    SkippedEntry, WithheldEntry, WorkspaceChangedError, WorkspaceLimitError, WorkspaceLimits,
+)
+from .reaper import ReapReport, reap_orphans
+from .runner import run_sandboxed
+
+__all__ = [
+    "ControlStatus", "DEFAULT_IMAGE", "ReapReport", "SandboxError", "SandboxLimits", "SandboxResult",
+    "SensitivePolicy", "SkippedEntry", "WithheldEntry", "WorkspaceChangedError", "WorkspaceLimitError", "WorkspaceLimits", "reap_orphans", "run_sandboxed",
+]

saferun/sandbox/analyzer.py

@@ -0,0 +1,192 @@
+"""The analyzer image (Phase 5B): where Semgrep and OSV-Scanner run, instead of on the host.
+
+The image is built locally by docker/analyzer/build.sh, which records its image ID in a lock file. Before every use
+`verify_analyzer_image` checks that
+  * the lock file exists and the local image `saferun-analyzer:local` has exactly that ID (a retagged or rebuilt image is refused),
+  * the labels baked in at build time equal the pins in images.py (tool versions) and the SHA-256 of the rules file in this checkout.
+The lock file is only trusted if it and its directory are owned by the current user and owner-only (0600 / 0700), and it is opened
+without following symlinks. It returns the image ID, and callers run the sandbox *by that ID*, so the image cannot change between check and use.
+Limits: the lock is a local file, not a registry digest or a signature. Whoever can write it AND re-tag or replace the image (the same user,
+root, or any member of the `docker` group, which is root-equivalent) can substitute an image; the labels checked below are set by whoever
+builds the image and prove nothing on their own.
+There is no fallback: any problem raises, and the engine reports the check as unavailable/error, never as clean.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+import tempfile
+from pathlib import Path
+
+from .. import hostos
+from . import docker as dk
+from .config import SandboxError
+from .images import OSV_SCANNER_VERSION, SEMGREP_VERSION
+
+ANALYZER_REPO_TAG = "saferun-analyzer:local"
+SEMGREP_EXE = "/usr/local/bin/semgrep"
+OSV_EXE = "/usr/local/bin/osv-scanner"
+RULES_PATH = "/opt/saferun/rules/python.yml"
+_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+class AnalyzerUnavailable(SandboxError):
+    """The analyzer image is not built or not usable (no host fallback exists)."""
+
+
+class AnalyzerIntegrityError(SandboxError):
+    """The image present locally is not the one that was built and locked (digest, tool or rules mismatch)."""
+
+
+def lock_path() -> Path:
+    env = os.environ.get("SAFERUN_ANALYZER_LOCK")
+    if env:
+        return Path(env)
+    return hostos.user_data_base() / "saferun" / "analyzer-image-id"
+
+
+def rules_sha256() -> str:
+    from ..engine.semgrep import RULES_FILE   # local import: the engine imports this module
+    return hashlib.sha256(RULES_FILE.read_bytes()).hexdigest()
+
+
+def _lock_problem(p: Path) -> str | None:
+    """Why the lock file's directory or the file itself cannot be trusted, or None. Both must belong to the current user and be
+    owner-only (directory 0700, file 0600), and neither may be a symlink (only the immediate parent directory is examined)."""
+    if hostos.IS_WINDOWS:   # owner + ACL instead of uid + mode bits (hostos.private_path_problem); reparse points are refused there
+        return hostos.private_path_problem(p.parent, directory=True)
+    me = os.geteuid()
+    try:
+        dst = os.lstat(p.parent)
+    except OSError as e:
+        return f"cannot examine the lock directory {p.parent}: {e}"
+    if not stat.S_ISDIR(dst.st_mode):
+        return f"the lock directory {p.parent} is not a real directory (a symlink?)"
+    if dst.st_uid != me:
+        return f"the lock directory {p.parent} is owned by uid {dst.st_uid}, not by the current user ({me})"
+    if dst.st_mode & 0o077:
+        return f"the lock directory {p.parent} is accessible to others (mode {stat.S_IMODE(dst.st_mode):04o}); run: chmod 700 {p.parent}"
+    return None
+
+
+def _read_lock() -> str:
+    p = lock_path()
+    if hostos.IS_WINDOWS:
+        return _read_lock_windows(p)
+    try:
+        fd = os.open(p, os.O_RDONLY | os.O_NOFOLLOW | os.O_CLOEXEC)
+    except FileNotFoundError:
+        raise AnalyzerUnavailable(f"the analyzer image has not been installed (no lock file at {p}); run `saferun init --only analyzer`") from None
+    except OSError as e:
+        raise AnalyzerIntegrityError(f"cannot open the analyzer lock file {p} (a symlink?): {e}") from None
+    try:
+        st = os.fstat(fd)
+        problem = None
+        if not stat.S_ISREG(st.st_mode):
+            problem = "is not a regular file"
+        elif st.st_uid != os.geteuid():
+            problem = f"is owned by uid {st.st_uid}, not by the current user"
+        elif st.st_mode & 0o077:
+            problem = f"is accessible to others (mode {stat.S_IMODE(st.st_mode):04o}); run: chmod 600 {p}"
+        if problem is None:
+            dir_problem = _lock_problem(p)
+            if dir_problem:
+                raise AnalyzerIntegrityError(f"analyzer lock not trusted: {dir_problem}")
+        else:
+            raise AnalyzerIntegrityError(f"analyzer lock file {p} {problem}; it is not trusted")
+        text = os.read(fd, 4096).decode("ascii", "replace").strip()
+    finally:
+        os.close(fd)
+    if not _ID_RE.match(text):
+        raise AnalyzerIntegrityError(f"analyzer lock file {p} is malformed")
+    return text
+
+
+def _read_lock_windows(p: Path) -> str:
+    if not p.exists():
+        raise AnalyzerUnavailable(f"the analyzer image has not been installed (no lock file at {p}); run `saferun init --only analyzer`")
+    problem = hostos.private_path_problem(p, directory=False) or hostos.private_path_problem(p.parent, directory=True)
+    if problem:
+        raise AnalyzerIntegrityError(f"analyzer lock not trusted: {problem}")
+    try:
+        text = p.read_bytes()[:4096].decode("ascii", "replace").strip()
+    except OSError as e:
+        raise AnalyzerIntegrityError(f"cannot read the analyzer lock file {p}: {e}") from None
+    if not _ID_RE.match(text):
+        raise AnalyzerIntegrityError(f"analyzer lock file {p} is malformed")
+    return text
+
+
+def write_lock(image_id: str) -> Path:
+    """Record `image_id` as the trusted analyzer image (used by docker/analyzer/build.sh). Creates the lock directory (0700) if it
+    does not exist; an EXISTING directory is never chmod'ed, it must already be owner-only. The file is written 0600, atomically."""
+    if not isinstance(image_id, str) or not _ID_RE.match(image_id):
+        raise SandboxError(f"not an image ID: {image_id!r}")
+    p = lock_path()
+    if p.parent.is_symlink():
+        raise SandboxError(f"refusing to write the lock through a symlinked directory: {p.parent}")
+    if not p.parent.exists():
+        p.parent.parent.mkdir(parents=True, exist_ok=True)
+        p.parent.mkdir(mode=0o700)
+        if hostos.IS_WINDOWS:
+            hostos.restrict_to_owner(p.parent)
+        else:
+            os.chmod(p.parent, 0o700)
+    problem = _lock_problem(p)
+    if problem:
+        raise SandboxError(f"not writing the analyzer lock: {problem}")
+    fd, tmp = tempfile.mkstemp(dir=p.parent, prefix=".lock-")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(image_id + "\n")
+        if hostos.IS_WINDOWS:
+            hostos.restrict_to_owner(Path(tmp))
+        else:
+            os.chmod(tmp, 0o600)
+        os.replace(tmp, p)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+    return p
+
+
+def inspect_analyzer_tag() -> tuple[str, dict]:
+    """(image ID, labels) of the local `saferun-analyzer:local` image. Raises AnalyzerUnavailable / AnalyzerIntegrityError."""
+    r = dk.docker("image", "inspect", "--format", "{{json .}}", ANALYZER_REPO_TAG)
+    if r.returncode != 0:
+        if "no such image" in r.stderr.lower():
+            raise AnalyzerUnavailable(f"image {ANALYZER_REPO_TAG} is not present locally; run `saferun init --only analyzer`")
+        raise AnalyzerUnavailable(f"cannot inspect {ANALYZER_REPO_TAG}: {r.stderr.strip()[:200]}")
+    try:
+        info = json.loads(r.stdout)
+        image_id = info["Id"]
+        labels = (info.get("Config") or {}).get("Labels") or {}
+        if not isinstance(image_id, str) or not isinstance(labels, dict):
+            raise TypeError("unexpected shape")
+    except (ValueError, KeyError, TypeError, AttributeError) as e:
+        raise AnalyzerIntegrityError(f"unexpected `docker image inspect` output for {ANALYZER_REPO_TAG}: {e}") from None
+    return image_id, labels
+
+
+def check_labels(labels: dict) -> None:
+    """The labels baked in at build time must equal this checkout's pins (tool versions) and rules hash."""
+    expected = {"saferun.analyzer": "1", "saferun.semgrep.version": SEMGREP_VERSION,
+                "saferun.osv-scanner.version": OSV_SCANNER_VERSION, "saferun.rules.sha256": rules_sha256()}
+    wrong = [k for k, v in expected.items() if labels.get(k) != v]
+    if wrong:
+        raise AnalyzerIntegrityError(f"analyzer image labels do not match the pinned tools/rules: {', '.join(wrong)}; rebuild it")
+
+
+def verify_analyzer_image() -> str:
+    """Return the verified image ID or raise AnalyzerUnavailable / AnalyzerIntegrityError."""
+    locked = _read_lock()
+    image_id, labels = inspect_analyzer_tag()
+    if image_id != locked:
+        raise AnalyzerIntegrityError(
+            f"analyzer image ID mismatch: {ANALYZER_REPO_TAG} is {image_id}, the build lock says {locked}; rebuild or investigate")
+    check_labels(labels)
+    return image_id