saferun-cli 0.0.2__py3-none-any.whl

saferun/hostos/__init__.py

@@ -0,0 +1,188 @@
+"""The only place SafeRun branches on the operating system (apart from the Windows copy engine, sandbox/copy_windows.py).
+
+POSIX (Linux, macOS) behaviour is the original behaviour of SafeRun and stays implemented where it always was (fcntl locks, O_NOFOLLOW /
+dir_fd copy, permission bits). This package adds what a native Windows host needs, plus path and endpoint rules that differ per platform.
+Nothing here weakens a check: where Windows cannot offer a POSIX guarantee, the function fails closed or says so (docs/platforms.md).
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+IS_WINDOWS = sys.platform == "win32"
+IS_MACOS = sys.platform == "darwin"
+
+if IS_WINDOWS:
+    from . import _win
+
+
+def user_data_base() -> Path:
+    """Directory that holds `saferun/…` (analyzer lock, OSV database). XDG_DATA_HOME wins on POSIX; Linux default is unchanged."""
+    if IS_WINDOWS:
+        return Path(os.environ.get("LOCALAPPDATA") or os.path.join(os.path.expanduser("~"), "AppData", "Local"))
+    env = os.environ.get("XDG_DATA_HOME")
+    if env:
+        return Path(env)
+    home = os.path.expanduser("~")
+    if IS_MACOS:
+        return Path(home) / "Library" / "Application Support"
+    return Path(home) / ".local" / "share"
+
+
+# Environment variables a child process needs on Windows (it cannot start, resolve DNS or load DLLs without them). Nothing secret.
+WINDOWS_BASE_ENV = ("SYSTEMROOT", "WINDIR", "COMSPEC", "PATHEXT", "SYSTEMDRIVE")
+
+
+def base_env_names() -> tuple[str, ...]:
+    return WINDOWS_BASE_ENV if IS_WINDOWS else ()
+
+
+def private_home_env(home: str) -> dict[str, str]:
+    """Variables that point a child's profile / temp locations at `home` (Windows names; POSIX uses HOME / XDG_* set by the callers)."""
+    if not IS_WINDOWS:
+        return {}
+    return {"USERPROFILE": home, "APPDATA": home, "LOCALAPPDATA": home, "TEMP": home, "TMP": home}
+
+
+def enable_ansi() -> None:
+    """Make colour / cursor escapes work in cmd.exe and PowerShell consoles (Windows 10+), and never crash on a non-UTF-8 code page."""
+    if not IS_WINDOWS:
+        return
+    for fd in (-11, -12):
+        _win.enable_ansi(fd)
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
+# ---- Docker endpoint and mount rules ------------------------------------------------------------------------------
+_NPIPE_RE = re.compile(r"^npipe:/{2,4}\./pipe/[A-Za-z0-9_.-]{1,128}$")   # host must be "." = this machine; no \\server\pipe\x
+
+
+def docker_endpoint_is_local(host: str) -> bool:
+    """POSIX: only a unix:// socket (unchanged). Windows: only a LOCAL named pipe; unix://, tcp://, ssh:// and remote pipes are refused."""
+    if IS_WINDOWS:
+        return bool(_NPIPE_RE.match(host))
+    return host.startswith("unix://")
+
+
+_DRIVE_PATH_RE = re.compile(r"^[A-Za-z]:\\")
+
+
+def mount_source_problem(path: str) -> str | None:
+    """Windows only: a bind-mount source must be a plain local drive path. UNC / device / extended paths could reach a remote machine."""
+    if not IS_WINDOWS:
+        return None
+    if not _DRIVE_PATH_RE.match(path) or "\\\\?\\" in path or "\\\\.\\" in path:
+        return "only a local drive path (C:\\...) can be mounted; network, device and extended-length paths are refused"
+    if _win.is_remote_drive(path):
+        return "the path is on a network drive; Docker would resolve it on another machine"
+    return None
+
+
+# ---- files owned and readable only by the current user (analyzer lock, workspace ownership) -------------------------
+def _trusted_sids() -> tuple[frozenset[str], str]:
+    from . import acl
+    _tok, user, owner = _win.current_token()
+    return frozenset({user, owner, acl.SYSTEM, acl.ADMINISTRATORS}), user
+
+
+def private_path_problem(path: Path, *, directory: bool) -> str | None:
+    """Windows counterpart of the POSIX "owned by me, mode 0700/0600, not a symlink" test; None if the path can be trusted.
+    The object must not be a reparse point, must be owned by the current user (or the account's default owner / Administrators), and its
+    DACL must grant nothing to any other principal than the user, SYSTEM and Administrators. Anything unreadable is NOT trusted."""
+    from . import acl
+    try:
+        h = _win.open_handle(str(path), _win.READ_CONTROL | _win.FILE_READ_ATTRIBUTES, _win.SHARE_READ | _win.SHARE_WRITE | _win.SHARE_DELETE,
+                             flags=_win.FLAG_BACKUP_SEMANTICS | _win.FLAG_OPEN_REPARSE_POINT)
+    except OSError as e:
+        return f"cannot examine {path}: {e}"
+    try:
+        info = _win.file_info(h)
+        if info["attrs"] & _win.ATTR_REPARSE_POINT:
+            return f"{path} is a reparse point (symlink or junction), not a real {'directory' if directory else 'file'}"
+        if bool(info["attrs"] & _win.ATTR_DIRECTORY) != directory:
+            return f"{path} is not a {'directory' if directory else 'regular file'}"
+        trusted, _user = _trusted_sids()
+        desc = acl.parse_descriptor(_win.security_descriptor(h))
+        if desc.owner not in trusted:
+            return f"{path} is owned by {desc.owner}, not by the current user"
+        # OWNER RIGHTS (S-1-3-4) is how Windows (and tools such as pytest's temp directories) pin the owner's own rights. It applies to the
+        # owner only, and the owner was verified above, so it grants nothing to a third party.
+        other = acl.only_trusted_principals(desc, trusted | {acl.OWNER_RIGHTS})
+        if other:
+            return f"{path} grants access to {other}; only the current user, SYSTEM and Administrators may have access (icacls {path} /inheritance:r /grant:r %USERNAME%:F)"
+    except (OSError, acl.AclUnverifiable) as e:
+        return f"cannot verify the permissions of {path}: {e}"
+    finally:
+        _win.close(h)
+    return None
+
+
+def restrict_to_owner(path: Path) -> None:
+    """Windows: make `path` accessible to the current user and SYSTEM only (protected DACL). The POSIX code uses chmod 0700 / 0600."""
+    _win.restrict_to_user(str(path), _win.current_token()[1])
+
+
+def ensure_private_dir(path: Path) -> bool:
+    """Create `path` owner-only (POSIX 0700, Windows protected DACL) if it is missing; missing ancestors are created normally. Returns True if it was
+    created. An EXISTING directory is never changed. Needed because SafeRun's per-user directory also holds the analyzer lock, whose trust rules
+    demand an owner-only directory: whichever SafeRun code creates it first must not leave it wider than that."""
+    if path.exists() or path.is_symlink():
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.mkdir(mode=0o700)
+    if IS_WINDOWS:
+        restrict_to_owner(path)
+    else:
+        os.chmod(path, 0o700)      # the umask may have narrowed it, never widened; make it exact
+    return True
+
+
+def owned_by_current_user(path: Path) -> bool:
+    """Windows counterpart of `st_uid == os.getuid()` (used before the reaper deletes a leftover workspace)."""
+    from . import acl
+    try:
+        h = _win.open_handle(str(path), _win.READ_CONTROL, _win.SHARE_READ | _win.SHARE_WRITE | _win.SHARE_DELETE,
+                             flags=_win.FLAG_BACKUP_SEMANTICS | _win.FLAG_OPEN_REPARSE_POINT)
+    except OSError:
+        return False
+    try:
+        _tok, user, owner = _win.current_token()   # `owner` is the account's default owner: Administrators for an elevated token
+        return acl.parse_descriptor(_win.security_descriptor(h)).owner in (user, owner)
+    except (OSError, acl.AclUnverifiable):
+        return False
+    finally:
+        _win.close(h)
+
+
+# ---- workspace liveness lock ---------------------------------------------------------------------------------------
+def create_workspace_lock(path: Path) -> int:
+    """Windows: file held with share mode 0 until the returned fd is closed (or the process dies)."""
+    return _win.create_exclusive_lock(str(path))
+
+
+def workspace_lock_state(path: str) -> str:
+    return _win.lock_state(path)
+
+
+def long_path(path) -> str:
+    """Windows: the extended-length form, so deletion works for long paths and names such as CON / trailing dots. Elsewhere: unchanged."""
+    return _win.ext(str(path)) if IS_WINDOWS else str(path)
+
+
+def rmtree_onexc(func, path, exc):
+    """shutil.rmtree error handler for Windows: clear the read-only flag and retry once. Any other failure is raised, never hidden."""
+    import stat
+    if isinstance(exc, PermissionError):
+        try:
+            os.chmod(path, stat.S_IWRITE)
+            func(path)
+            return
+        except OSError:
+            pass
+    raise exc

saferun/hostos/_win.py

@@ -0,0 +1,316 @@
+"""Thin ctypes layer over the Win32 / NT calls SafeRun needs. Imported only on Windows; nothing here decides policy (see acl.py).
+
+Every function declares argtypes/restype: without them 64-bit handles are truncated to 32 bits.
+"""
+from __future__ import annotations
+
+import ctypes
+import msvcrt
+import ntpath
+import os
+from ctypes import wintypes as wt
+
+from . import acl
+
+_k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+_adv = ctypes.WinDLL("advapi32", use_last_error=True)
+_nt = ctypes.WinDLL("ntdll", use_last_error=True)
+
+HANDLE = ctypes.c_void_p
+INVALID = ctypes.c_void_p(-1).value
+
+GENERIC_READ, GENERIC_WRITE = 0x80000000, 0x40000000
+FILE_LIST_DIRECTORY, FILE_READ_ATTRIBUTES, READ_CONTROL, DELETE = 0x1, 0x80, 0x20000, 0x10000
+SHARE_READ, SHARE_WRITE, SHARE_DELETE = 1, 2, 4
+CREATE_NEW, OPEN_EXISTING = 1, 3
+FLAG_BACKUP_SEMANTICS, FLAG_OPEN_REPARSE_POINT, ATTR_NORMAL = 0x02000000, 0x00200000, 0x80
+ATTR_DIRECTORY, ATTR_REPARSE_POINT = 0x10, 0x400
+TAG_SYMLINK = 0xA000000C
+ERROR_SHARING_VIOLATION, ERROR_FILE_NOT_FOUND, ERROR_HANDLE_EOF = 32, 2, 38
+DRIVE_REMOTE = 4
+
+
+class FILETIME(ctypes.Structure):
+    _fields_ = [("lo", wt.DWORD), ("hi", wt.DWORD)]
+
+
+class BY_HANDLE_FILE_INFORMATION(ctypes.Structure):
+    _fields_ = [("attrs", wt.DWORD), ("created", FILETIME), ("accessed", FILETIME), ("written", FILETIME),
+                ("volume", wt.DWORD), ("size_hi", wt.DWORD), ("size_lo", wt.DWORD), ("nlink", wt.DWORD),
+                ("index_hi", wt.DWORD), ("index_lo", wt.DWORD)]
+
+
+class FILE_BASIC_INFO(ctypes.Structure):
+    _fields_ = [("created", ctypes.c_int64), ("accessed", ctypes.c_int64), ("written", ctypes.c_int64),
+                ("changed", ctypes.c_int64), ("attrs", wt.DWORD)]
+
+
+class FILE_ID_INFO(ctypes.Structure):
+    _fields_ = [("volume", ctypes.c_uint64), ("file_id", ctypes.c_ubyte * 16)]
+
+
+class FILE_ATTRIBUTE_TAG_INFO(ctypes.Structure):
+    _fields_ = [("attrs", wt.DWORD), ("tag", wt.DWORD)]
+
+
+class WIN32_FIND_STREAM_DATA(ctypes.Structure):
+    _fields_ = [("size", ctypes.c_int64), ("name", ctypes.c_wchar * (260 + 36))]
+
+
+def _fn(dll, name, restype, *argtypes):
+    f = getattr(dll, name)
+    f.restype, f.argtypes = restype, list(argtypes)
+    return f
+
+
+CreateFileW = _fn(_k32, "CreateFileW", HANDLE, wt.LPCWSTR, wt.DWORD, wt.DWORD, ctypes.c_void_p, wt.DWORD, wt.DWORD, HANDLE)
+CloseHandle = _fn(_k32, "CloseHandle", wt.BOOL, HANDLE)
+GetFileInformationByHandle = _fn(_k32, "GetFileInformationByHandle", wt.BOOL, HANDLE, ctypes.POINTER(BY_HANDLE_FILE_INFORMATION))
+GetFileInformationByHandleEx = _fn(_k32, "GetFileInformationByHandleEx", wt.BOOL, HANDLE, ctypes.c_int, ctypes.c_void_p, wt.DWORD)
+GetFinalPathNameByHandleW = _fn(_k32, "GetFinalPathNameByHandleW", wt.DWORD, HANDLE, wt.LPWSTR, wt.DWORD, wt.DWORD)
+GetDriveTypeW = _fn(_k32, "GetDriveTypeW", wt.UINT, wt.LPCWSTR)
+FindFirstStreamW = _fn(_k32, "FindFirstStreamW", HANDLE, wt.LPCWSTR, ctypes.c_int, ctypes.c_void_p, wt.DWORD)
+FindNextStreamW = _fn(_k32, "FindNextStreamW", wt.BOOL, HANDLE, ctypes.c_void_p)
+FindClose = _fn(_k32, "FindClose", wt.BOOL, HANDLE)
+CreateJobObjectW = _fn(_k32, "CreateJobObjectW", HANDLE, ctypes.c_void_p, wt.LPCWSTR)
+SetInformationJobObject = _fn(_k32, "SetInformationJobObject", wt.BOOL, HANDLE, ctypes.c_int, ctypes.c_void_p, wt.DWORD)
+AssignProcessToJobObject = _fn(_k32, "AssignProcessToJobObject", wt.BOOL, HANDLE, HANDLE)
+TerminateJobObject = _fn(_k32, "TerminateJobObject", wt.BOOL, HANDLE, wt.UINT)
+GetStdHandle = _fn(_k32, "GetStdHandle", HANDLE, wt.DWORD)
+GetConsoleMode = _fn(_k32, "GetConsoleMode", wt.BOOL, HANDLE, ctypes.POINTER(wt.DWORD))
+SetConsoleMode = _fn(_k32, "SetConsoleMode", wt.BOOL, HANDLE, wt.DWORD)
+LocalFree = _fn(_k32, "LocalFree", HANDLE, HANDLE)
+GetCurrentProcess = _fn(_k32, "GetCurrentProcess", HANDLE)
+OpenProcessToken = _adv.OpenProcessToken
+OpenProcessToken.restype, OpenProcessToken.argtypes = wt.BOOL, [HANDLE, wt.DWORD, ctypes.POINTER(HANDLE)]
+GetTokenInformation = _fn(_adv, "GetTokenInformation", wt.BOOL, HANDLE, ctypes.c_int, ctypes.c_void_p, wt.DWORD, ctypes.POINTER(wt.DWORD))
+GetKernelObjectSecurity = _fn(_adv, "GetKernelObjectSecurity", wt.BOOL, HANDLE, wt.DWORD, ctypes.c_void_p, wt.DWORD, ctypes.POINTER(wt.DWORD))
+ConvertStringSecurityDescriptorToSecurityDescriptorW = _fn(
+    _adv, "ConvertStringSecurityDescriptorToSecurityDescriptorW", wt.BOOL, wt.LPCWSTR, wt.DWORD, ctypes.POINTER(ctypes.c_void_p), ctypes.c_void_p)
+SetFileSecurityW = _fn(_adv, "SetFileSecurityW", wt.BOOL, wt.LPCWSTR, wt.DWORD, ctypes.c_void_p)
+NtResumeProcess = _fn(_nt, "NtResumeProcess", ctypes.c_long, HANDLE)
+
+
+def ext(path: str) -> str:
+    """Extended-length form of an absolute path (no MAX_PATH limit, no Win32 name normalisation)."""
+    # os.path.abspath() asks Win32 to normalise the name, which turns a final component such as CON into the device path \\.\CON.
+    # An already absolute path is only cleaned up as a string; only a relative one needs the working directory.
+    path = ntpath.normpath(path) if ntpath.isabs(path) else os.path.abspath(path)
+    if path.startswith("\\\\?\\"):
+        return path
+    return "\\\\?\\UNC\\" + path[2:] if path.startswith("\\\\") else "\\\\?\\" + path
+
+
+def oserror(code: int | None = None) -> OSError:
+    code = ctypes.get_last_error() if code is None else code
+    return ctypes.WinError(code)
+
+
+def open_handle(path: str, access: int, share: int, disposition: int = OPEN_EXISTING, flags: int = 0) -> int:
+    h = CreateFileW(ext(path), access, share, None, disposition, flags, None)
+    if h is None or h == INVALID:
+        raise oserror()
+    return h
+
+
+def close(handle: int | None) -> None:
+    if handle:
+        CloseHandle(handle)
+
+
+def file_info(handle: int) -> dict:
+    """Identity and metadata of an OPEN handle (never of a path): attributes, 128-bit file id, size, links, times, reparse tag."""
+    bh = BY_HANDLE_FILE_INFORMATION()
+    if not GetFileInformationByHandle(handle, ctypes.byref(bh)):
+        raise oserror()
+    basic = FILE_BASIC_INFO()
+    if not GetFileInformationByHandleEx(handle, 0, ctypes.byref(basic), ctypes.sizeof(basic)):
+        raise oserror()
+    fid = FILE_ID_INFO()
+    if GetFileInformationByHandleEx(handle, 18, ctypes.byref(fid), ctypes.sizeof(fid)):
+        ident = (fid.volume, bytes(fid.file_id))
+    else:   # file systems without 128-bit ids: the 64-bit index
+        ident = (bh.volume, (bh.index_hi << 32) | bh.index_lo)
+    tag = 0
+    if bh.attrs & ATTR_REPARSE_POINT:
+        t = FILE_ATTRIBUTE_TAG_INFO()
+        if not GetFileInformationByHandleEx(handle, 9, ctypes.byref(t), ctypes.sizeof(t)):
+            raise oserror()
+        tag = t.tag
+    return {"attrs": bh.attrs, "ident": ident, "size": (bh.size_hi << 32) | bh.size_lo, "nlink": bh.nlink,
+            "written": basic.written, "changed": basic.changed, "tag": tag}
+
+
+def final_path(handle: int) -> str:
+    buf = ctypes.create_unicode_buffer(32768)
+    n = GetFinalPathNameByHandleW(handle, buf, len(buf), 0)
+    if n == 0 or n >= len(buf):
+        raise oserror()
+    p = buf.value
+    return p[4:] if p.startswith("\\\\?\\") and not p.startswith("\\\\?\\UNC\\") else p
+
+
+def is_remote_drive(path: str) -> bool:
+    p = os.path.abspath(path)
+    return p.startswith("\\\\") or GetDriveTypeW(os.path.splitdrive(p)[0] + "\\") == DRIVE_REMOTE
+
+
+def stream_names(path: str) -> list[str]:
+    """Names of all data streams of a file or directory, e.g. ['::$DATA', ':Zone.Identifier:$DATA']."""
+    data = WIN32_FIND_STREAM_DATA()
+    h = FindFirstStreamW(ext(path), 0, ctypes.byref(data), 0)
+    if h is None or h == INVALID:
+        err = ctypes.get_last_error()
+        if err == ERROR_HANDLE_EOF:
+            return []
+        raise oserror(err)
+    try:
+        names = [data.name]
+        while True:
+            if FindNextStreamW(h, ctypes.byref(data)):
+                names.append(data.name)
+                continue
+            err = ctypes.get_last_error()
+            if err != ERROR_HANDLE_EOF:   # enumeration ended on an error, not at the end: the list may be incomplete, so fail closed
+                raise oserror(err)
+            return names
+    finally:
+        FindClose(h)
+
+
+def security_descriptor(handle: int) -> bytes:
+    """Owner + DACL of an open handle (needs READ_CONTROL), self-relative."""
+    needed = wt.DWORD(0)
+    GetKernelObjectSecurity(handle, 0x5, None, 0, ctypes.byref(needed))
+    for _ in range(3):
+        buf = ctypes.create_string_buffer(max(needed.value, 64))
+        if GetKernelObjectSecurity(handle, 0x5, buf, len(buf), ctypes.byref(needed)):
+            return buf.raw[:needed.value]
+    raise oserror()
+
+
+def _sid_at(address: int) -> str:
+    count = ctypes.string_at(address + 1, 1)[0]
+    return acl.sid_to_str(ctypes.string_at(address, 8 + 4 * count))[0]
+
+
+def _token_info(token: int, cls: int) -> ctypes.Array:
+    n = wt.DWORD(0)
+    GetTokenInformation(token, cls, None, 0, ctypes.byref(n))
+    buf = ctypes.create_string_buffer(n.value)
+    if not GetTokenInformation(token, cls, buf, n.value, ctypes.byref(n)):
+        raise oserror()
+    return buf
+
+
+class _SidAndAttributes(ctypes.Structure):
+    _fields_ = [("sid", ctypes.c_void_p), ("attrs", wt.DWORD)]
+
+
+def current_token() -> tuple[acl.Token, str, str]:
+    """(token with enabled / deny-only groups, user SID, default owner SID) of this process."""
+    tok = HANDLE()
+    if not OpenProcessToken(GetCurrentProcess(), 0x8, ctypes.byref(tok)):   # TOKEN_QUERY
+        raise oserror()
+    try:
+        user = _sid_at(ctypes.cast(_token_info(tok, 1), ctypes.POINTER(ctypes.c_void_p))[0])
+        owner = _sid_at(ctypes.cast(_token_info(tok, 4), ctypes.POINTER(ctypes.c_void_p))[0])
+        buf = _token_info(tok, 2)
+        count = ctypes.cast(buf, ctypes.POINTER(wt.DWORD))[0]
+        first = ctypes.addressof(buf) + ctypes.sizeof(ctypes.c_void_p)    # groups start after the count, padded to pointer size
+        groups = (_SidAndAttributes * count).from_address(first)
+        enabled = {_sid_at(g.sid) for g in groups if g.attrs & 0x4}
+        deny_only = {_sid_at(g.sid) for g in groups if g.attrs & 0x10}
+    finally:
+        CloseHandle(tok)
+    return (acl.Token(frozenset(enabled | {user, acl.EVERYONE, acl.AUTHENTICATED_USERS}), frozenset(deny_only)), user, owner)
+
+
+def restrict_to_user(path: str, user_sid: str) -> None:
+    """Replace the DACL of `path` with a protected one granting full control to `user_sid` and SYSTEM only."""
+    sddl = f"D:P(A;OICI;FA;;;{user_sid})(A;OICI;FA;;;SY)"
+    psd = ctypes.c_void_p()
+    if not ConvertStringSecurityDescriptorToSecurityDescriptorW(sddl, 1, ctypes.byref(psd), None):
+        raise oserror()
+    try:
+        if not SetFileSecurityW(ext(path), 0x4, psd):   # DACL_SECURITY_INFORMATION
+            raise oserror()
+    finally:
+        LocalFree(psd)
+
+
+def create_exclusive_lock(path: str) -> int:
+    """Create `path` held with share mode 0: no one else can open it while this fd lives; the OS releases it if we die. -> C fd"""
+    h = open_handle(path, GENERIC_READ | GENERIC_WRITE, 0, CREATE_NEW, ATTR_NORMAL)
+    try:
+        return msvcrt.open_osfhandle(h, os.O_RDWR | os.O_NOINHERIT)
+    except BaseException:
+        CloseHandle(h)
+        raise
+
+
+def lock_state(path: str) -> str:
+    """'busy' (a live owner holds it), 'free' (no holder) or 'absent'."""
+    try:
+        h = open_handle(path, GENERIC_READ, 0)
+    except OSError as e:
+        code = getattr(e, "winerror", None)
+        if code == ERROR_SHARING_VIOLATION:
+            return "busy"
+        if code == ERROR_FILE_NOT_FOUND or isinstance(e, FileNotFoundError):
+            return "absent"
+        raise
+    CloseHandle(h)
+    return "free"
+
+
+def enable_ansi(stream_fd: int) -> bool:
+    """Turn on ANSI escape processing for the console behind std handle -11 (stdout) / -12 (stderr). False if not a console."""
+    h = GetStdHandle(wt.DWORD(stream_fd))
+    mode = wt.DWORD()
+    if not h or h == INVALID or not GetConsoleMode(h, ctypes.byref(mode)):
+        return False
+    return bool(SetConsoleMode(h, mode.value | 0x0004))   # ENABLE_VIRTUAL_TERMINAL_PROCESSING
+
+
+# ---- job objects -------------------------------------------------------------------------------------------------
+class _BasicLimit(ctypes.Structure):
+    _fields_ = [("per_process_time", ctypes.c_int64), ("per_job_time", ctypes.c_int64), ("flags", wt.DWORD),
+                ("min_ws", ctypes.c_size_t), ("max_ws", ctypes.c_size_t), ("active", wt.DWORD), ("affinity", ctypes.c_size_t),
+                ("priority", wt.DWORD), ("sched", wt.DWORD)]
+
+
+class _IoCounters(ctypes.Structure):
+    _fields_ = [(n, ctypes.c_uint64) for n in ("ro", "wo", "oo", "rb", "wb", "ob")]
+
+
+class _ExtendedLimit(ctypes.Structure):
+    _fields_ = [("basic", _BasicLimit), ("io", _IoCounters), ("proc_mem", ctypes.c_size_t), ("job_mem", ctypes.c_size_t),
+                ("peak_proc", ctypes.c_size_t), ("peak_job", ctypes.c_size_t)]
+
+
+def create_kill_on_close_job() -> int:
+    job = CreateJobObjectW(None, None)
+    if not job:
+        raise oserror()
+    info = _ExtendedLimit()
+    info.basic.flags = 0x2000   # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+    if not SetInformationJobObject(job, 9, ctypes.byref(info), ctypes.sizeof(info)):
+        err = oserror()
+        CloseHandle(job)
+        raise err
+    return job
+
+
+def assign_to_job(job: int, process_handle: int) -> None:
+    if not AssignProcessToJobObject(job, process_handle):
+        raise oserror()
+
+
+def resume_process(process_handle: int) -> None:
+    if NtResumeProcess(process_handle) < 0:
+        raise OSError("could not resume the suspended process")
+
+
+def terminate_job(job: int) -> None:
+    TerminateJobObject(job, 1)

saferun/hostos/acl.py

@@ -0,0 +1,172 @@
+"""Windows security descriptors and effective-access evaluation, in pure Python (no Windows API), so the logic is unit-testable everywhere.
+
+The Windows side (`_win.py`) only fetches the raw self-relative descriptor of an open handle and the caller's token; everything that
+decides something lives here and FAILS CLOSED: a descriptor or ACE this module does not fully understand raises `AclUnverifiable`,
+and callers treat that as "private / not trusted".
+
+Access evaluation follows the Windows access-check algorithm for a DACL: ACEs are evaluated in stored order (the stored DACL already has
+inherited ACEs in effective position); INHERIT_ONLY ACEs are ignored; an ACE applies when its SID is in the token; a deny ACE removes only
+rights not yet granted by an earlier ACE; a NULL DACL grants everyone everything and an empty DACL grants nothing.
+"""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+
+EVERYONE = "S-1-1-0"
+AUTHENTICATED_USERS = "S-1-5-11"
+SYSTEM = "S-1-5-18"
+ADMINISTRATORS = "S-1-5-32-544"
+USERS = "S-1-5-32-545"
+OWNER_RIGHTS = "S-1-3-4"   # an ACE for it applies to the object's owner only (whoever that is)
+
+FILE_READ_DATA = FILE_LIST_DIRECTORY = 0x0001
+FILE_TRAVERSE = 0x0020
+READ_FILE = FILE_READ_DATA
+READ_DIRECTORY = FILE_LIST_DIRECTORY | FILE_TRAVERSE   # the Windows counterpart of the POSIX "other r-x" test for directories
+_GENERIC = ((0x80000000, 0x120089), (0x40000000, 0x120116), (0x20000000, 0x1200A0), (0x10000000, 0x1F01FF))  # read, write, execute, all
+_ACCESS_ALLOWED, _ACCESS_DENIED = 0, 1
+_INHERIT_ONLY = 0x08
+SE_DACL_PRESENT, SE_DACL_PROTECTED = 0x0004, 0x1000
+
+
+class AclUnverifiable(ValueError):
+    """The security descriptor cannot be fully understood, so no conclusion may be drawn from it."""
+
+
+@dataclass(frozen=True)
+class Ace:
+    allow: bool
+    mask: int
+    sid: str
+    inherit_only: bool = False
+
+
+@dataclass(frozen=True)
+class Descriptor:
+    owner: str | None
+    dacl: tuple[Ace, ...] | None     # None: no DACL at all (everyone has full access)
+    protected: bool = False          # inheritance from the parent is blocked
+
+
+@dataclass(frozen=True)
+class Token:
+    """The SIDs of a (possibly hypothetical) security token. `deny_only` SIDs match deny ACEs only, as in a real filtered token."""
+    sids: frozenset[str]
+    deny_only: frozenset[str] = field(default_factory=frozenset)
+
+
+def sid_to_str(data: bytes, offset: int = 0) -> tuple[str, int]:
+    """(`S-1-...`, length in bytes) of the binary SID at `offset`."""
+    try:
+        revision, count = data[offset], data[offset + 1]
+        if revision != 1 or count > 15:
+            raise AclUnverifiable("unsupported SID revision or size")
+        authority = int.from_bytes(data[offset + 2: offset + 8], "big")
+        subs = struct.unpack_from(f"<{count}I", data, offset + 8)
+    except (IndexError, struct.error):
+        raise AclUnverifiable("truncated SID") from None
+    return "S-1-" + "-".join(str(x) for x in (authority, *subs)), 8 + 4 * count
+
+
+def _expand(mask: int) -> int:
+    for generic, specific in _GENERIC:
+        if mask & generic:
+            mask = (mask & ~generic) | specific
+    return mask
+
+
+def parse_descriptor(data: bytes) -> Descriptor:
+    """Parse a self-relative SECURITY_DESCRIPTOR. Raises AclUnverifiable for anything unexpected (conditional or object ACEs, bad offsets)."""
+    try:
+        revision, _sbz, control, off_owner, _off_group, _off_sacl, off_dacl = struct.unpack_from("<BBHIIII", data, 0)
+    except struct.error:
+        raise AclUnverifiable("security descriptor too short") from None
+    if revision != 1 or not control & 0x8000:   # SE_SELF_RELATIVE
+        raise AclUnverifiable("not a self-relative security descriptor")
+    owner = sid_to_str(data, off_owner)[0] if off_owner else None
+    if not control & SE_DACL_PRESENT or not off_dacl:
+        return Descriptor(owner, None, bool(control & SE_DACL_PROTECTED))
+    try:
+        _rev, _sbz1, acl_size, count, _sbz2 = struct.unpack_from("<BBHHH", data, off_dacl)
+    except struct.error:
+        raise AclUnverifiable("truncated ACL") from None
+    if off_dacl + acl_size > len(data):
+        raise AclUnverifiable("ACL larger than the descriptor")
+    aces, pos = [], off_dacl + 8
+    for _ in range(count):
+        try:
+            kind, flags, size = struct.unpack_from("<BBH", data, pos)
+            mask, = struct.unpack_from("<I", data, pos + 4)
+        except struct.error:
+            raise AclUnverifiable("truncated ACE") from None
+        if kind not in (_ACCESS_ALLOWED, _ACCESS_DENIED) or size < 12 or pos + size > off_dacl + acl_size:
+            raise AclUnverifiable(f"unsupported or malformed ACE (type {kind})")
+        sid, sid_len = sid_to_str(data, pos + 8)
+        if 8 + sid_len > size:
+            raise AclUnverifiable("SID longer than its ACE")
+        aces.append(Ace(kind == _ACCESS_ALLOWED, _expand(mask), sid, bool(flags & _INHERIT_ONLY)))
+        pos += size
+    return Descriptor(owner, tuple(aces), bool(control & SE_DACL_PROTECTED))
+
+
+def effective_access(dacl: tuple[Ace, ...] | None, token: Token) -> int:
+    """Rights `token` is granted by `dacl` (restricted to bits that appear in an ACE; callers test the bits they need)."""
+    if dacl is None:
+        return 0xFFFFFFFF
+    granted = denied = 0
+    for ace in dacl:
+        if ace.inherit_only:
+            continue
+        if ace.allow:
+            if ace.sid in token.sids:
+                granted |= ace.mask & ~denied
+        elif ace.sid in token.sids or ace.sid in token.deny_only:
+            denied |= ace.mask & ~granted
+    return granted
+
+
+def can(dacl, token: Token, wanted: int) -> bool:
+    return effective_access(dacl, token) & wanted == wanted
+
+
+def _principal_token(sid: str) -> Token:
+    """A hypothetical user holding `sid`, plus the groups every authenticated user is in."""
+    if sid == EVERYONE:
+        return Token(frozenset({EVERYONE}))
+    return Token(frozenset({sid, EVERYONE, AUTHENTICATED_USERS}))
+
+
+def readers(dacl, wanted: int) -> list[Token]:
+    """Tokens that can read according to `dacl`: a hypothetical user for each SID with an allow ACE for the wanted rights."""
+    if dacl is None:
+        return [_principal_token(EVERYONE)]
+    out = []
+    for ace in dacl:
+        if ace.allow and not ace.inherit_only and ace.mask & wanted:
+            tok = _principal_token(ace.sid)
+            if can(dacl, tok, wanted):
+                out.append(tok)
+    return out
+
+
+def at_least_as_readable(file_dacl, baseline_dacl, caller: Token, *, directory: bool) -> bool:
+    """True iff everyone who can read the project root (the caller, using the real token with its groups, and every principal the root's
+    DACL grants read to) can also read this entry. A file narrower than the tree around it is deliberately private: the Windows
+    counterpart of "not world-readable" on POSIX. Callers must treat AclUnverifiable (and any other failure) as private."""
+    wanted = READ_DIRECTORY if directory else READ_FILE
+    # The root itself is always evaluated with the directory rights, whatever the entry is.
+    for tok in (caller, *readers(baseline_dacl, READ_DIRECTORY)):
+        if can(baseline_dacl, tok, READ_DIRECTORY) and not can(file_dacl, tok, wanted):
+            return False
+    return True
+
+
+def only_trusted_principals(desc: Descriptor, trusted: frozenset[str]) -> str | None:
+    """None if no principal outside `trusted` is granted anything; else the first offending SID. A missing DACL grants everyone access."""
+    if desc.dacl is None:
+        return EVERYONE
+    for ace in desc.dacl:
+        if ace.allow and not ace.inherit_only and ace.mask and ace.sid not in trusted:
+            return ace.sid
+    return None