| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462 |
- """Directories an elevated Windows process creates must stay usable by the same user unelevated.
- Since CPython 3.13, ``os.mkdir(path, 0o700)`` on Windows applies a protected DACL of exactly
- SYSTEM, Administrators and OWNER RIGHTS. An elevated process's default owner is
- ``BUILTIN\\Administrators``, so OWNER RIGHTS resolves to Administrators too, and the user's own
- non-elevated token (where Administrators is deny-only) gets ``WinError 5`` on the directory and on
- everything created inside it (#139845, #139485, the ``gateway-locks`` reports in #134889 W2). A plain
- ``mkdir`` inherits its parent's ACL instead, which under ``%LOCALAPPDATA%`` names the user, so the
- ``mode=0o700`` sites are the ones that strand the user.
- :func:`make_user_dir` is the one place Hermes state/lock/log directories are created. Off Windows,
- or in a non-elevated process, it is exactly ``Path.mkdir``. In an elevated Windows process it adds
- an explicit, inheriting full-control ACE for the token's user SID to the directory, so the directory
- and every child created later stay usable by that user after elevation ends. An elevated call on an
- existing directory re-grants the same ACE, which repairs a directory an earlier elevated run left
- behind; the pywin32 write does not propagate, so when it had to write, the entries already inside
- (an old token lock) are granted too, once, never through a link. A non-elevated process cannot change such a DACL; callers that hit one report it once with
- :func:`unusable_dir_remedy`.
- An elevated grant never goes through a junction, symlink or other reparse point (nor a hard-linked
- file): same-user medium-integrity code can swap any entry under the home for a junction to e.g.
- ``C:\\Program Files\\X``, and a grant that followed it would hand the user full control of the
- target across the UAC boundary. The path is lstat-checked first, and the pywin32 grant opens it with
- ``FILE_FLAG_OPEN_REPARSE_POINT`` and re-checks the handle, so a swap after the check is not followed
- either; the icacls fallback passes ``/L``. :func:`grant_tree_user_access` is the recursive form
- (the post-update repair), pruning every reparse point instead of descending into it.
- """
- from __future__ import annotations
- import functools
- import logging
- import os
- import stat
- import subprocess
- import sys
- from collections.abc import Iterator
- from pathlib import Path
- log = logging.getLogger(__name__)
- _TOKEN_QUERY = 0x0008
- _TOKEN_USER = 1
- _TOKEN_ELEVATION = 20
- FILE_ATTRIBUTE_DIRECTORY = 0x10
- FILE_ATTRIBUTE_REPARSE_POINT = 0x400
- _READ_CONTROL = 0x00020000
- _WRITE_DAC = 0x00040000
- _FILE_SHARE_ALL = 0x7 # read | write | delete: never block another Hermes process
- _OPEN_EXISTING = 3
- _FILE_FLAG_BACKUP_SEMANTICS = 0x02000000 # needed to open a directory handle
- _FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000 # open the link itself, never its target
- class ReparsePointRefused(OSError):
- """The grant target is (or became) a junction, symlink, other reparse point or hard link."""
- def is_reparse_point(path: str | Path) -> bool:
- """True when *path* itself is a symlink, junction or other reparse point (never followed), or
- cannot be lstat-ed at all; the safe answer for "may an elevated grant act on this path"."""
- try:
- st = os.lstat(path)
- except OSError:
- return True
- if stat.S_ISLNK(st.st_mode) or getattr(st, "st_file_attributes", 0) & FILE_ATTRIBUTE_REPARSE_POINT:
- return True
- isjunction = getattr(os.path, "isjunction", None) # 3.12+; st_file_attributes covers 3.11
- return bool(isjunction and isjunction(path))
- _PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
- def process_elevation(pid: int | None = None) -> bool | None:
- """``TokenElevation`` of *pid*'s token (default: this process). The ONE elevation probe: the
- grants below, the refused-owner naming in ``gateway.runtime_bootstrap_windows`` and the
- Windows service installer all read it. None when the process or its token cannot be opened
- (across an elevation boundary that refusal is itself an answer the caller interprets)."""
- import ctypes
- from ctypes import wintypes
- advapi = ctypes.WinDLL("advapi32", use_last_error=True)
- kernel = ctypes.WinDLL("kernel32", use_last_error=True)
- kernel.GetCurrentProcess.restype = wintypes.HANDLE
- kernel.OpenProcess.restype = wintypes.HANDLE
- kernel.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
- advapi.OpenProcessToken.argtypes = [wintypes.HANDLE, wintypes.DWORD, ctypes.POINTER(wintypes.HANDLE)]
- advapi.GetTokenInformation.argtypes = [wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD,
- ctypes.POINTER(wintypes.DWORD)]
- kernel.CloseHandle.argtypes = [wintypes.HANDLE]
- own = pid is None
- process = kernel.GetCurrentProcess() if own else kernel.OpenProcess(_PROCESS_QUERY_LIMITED_INFORMATION,
- False, pid)
- if not process:
- return None
- token = wintypes.HANDLE()
- try:
- if not advapi.OpenProcessToken(process, _TOKEN_QUERY, ctypes.byref(token)):
- return None
- elevated, size = wintypes.DWORD(), wintypes.DWORD()
- if not advapi.GetTokenInformation(token, _TOKEN_ELEVATION, ctypes.byref(elevated),
- ctypes.sizeof(elevated), ctypes.byref(size)):
- return None
- return bool(elevated.value)
- finally:
- if token:
- kernel.CloseHandle(token)
- if not own: # the pseudo-handle of GetCurrentProcess is never closed
- kernel.CloseHandle(process)
- @functools.lru_cache(maxsize=1)
- def process_is_elevated() -> bool:
- """True for an elevated (UAC full-token) Windows process; False elsewhere or on any error."""
- if sys.platform != "win32":
- return False
- return bool(process_elevation())
- def _strip_win32_prefix(path: str) -> str:
- if path.startswith("\\\\?\\UNC\\"):
- return "\\\\" + path[8:]
- return path.removeprefix("\\\\?\\")
- def _grant_with_pywin32(path: Path, is_dir: bool, expected: str | None = None) -> bool:
- """Write the ACE on the handle; True when it was written (False: already present). The write
- does NOT propagate (``SetKernelObjectSecurity``), so a written dir's existing children are owed."""
- import ntsecuritycon
- import win32api
- import win32file
- import win32security
- token = win32security.OpenProcessToken(win32api.GetCurrentProcess(), win32security.TOKEN_QUERY)
- user_sid = win32security.GetTokenInformation(token, win32security.TokenUser)[0]
- # Act on the handle, never the name: GetFileSecurity/SetFileSecurity resolve a junction or symlink
- # to its target, so a swap after the lstat check would still redirect the grant.
- handle = win32file.CreateFile(str(path), _READ_CONTROL | _WRITE_DAC, _FILE_SHARE_ALL, None, _OPEN_EXISTING,
- _FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OPEN_REPARSE_POINT, None)
- try:
- if expected is not None:
- # A parent swapped for a junction after the lstat checks resolves the name elsewhere.
- final = _strip_win32_prefix(win32file.GetFinalPathNameByHandle(handle, 0))
- if os.path.normcase(final.rstrip("\\")) != os.path.normcase(expected.rstrip("\\")):
- raise ReparsePointRefused(f"{path} resolves to {final}, not {expected}")
- info = win32file.GetFileInformationByHandle(handle)
- attributes, links = info[0], info[7]
- if attributes & FILE_ATTRIBUTE_REPARSE_POINT:
- raise ReparsePointRefused(f"{path} is a junction, symlink or other reparse point")
- if not attributes & FILE_ATTRIBUTE_DIRECTORY and links > 1:
- raise ReparsePointRefused(f"{path} is a hard link ({links} names); its other names may be outside")
- is_dir = bool(attributes & FILE_ATTRIBUTE_DIRECTORY)
- descriptor = win32security.GetKernelObjectSecurity(handle, win32security.DACL_SECURITY_INFORMATION)
- dacl = descriptor.GetSecurityDescriptorDacl()
- inherit = (win32security.OBJECT_INHERIT_ACE | win32security.CONTAINER_INHERIT_ACE) if is_dir else 0
- if dacl is not None:
- for index in range(dacl.GetAceCount()):
- (ace_type, flags, *_), mask, sid = dacl.GetAce(index)[:3]
- if (ace_type == win32security.ACCESS_ALLOWED_ACE_TYPE and sid == user_sid
- and mask & ntsecuritycon.FILE_ALL_ACCESS == ntsecuritycon.FILE_ALL_ACCESS
- and flags & inherit == inherit and not flags & win32security.INHERIT_ONLY_ACE):
- return False # already granted: never grow the DACL on repeat calls
- else:
- dacl = win32security.ACL()
- dacl.AddAccessAllowedAceEx(win32security.ACL_REVISION_DS, inherit, ntsecuritycon.FILE_ALL_ACCESS, user_sid)
- descriptor.SetSecurityDescriptorDacl(True, dacl, False)
- # The handle form of SetFileSecurity: same semantics (no propagation walk), no name resolution.
- win32security.SetKernelObjectSecurity(handle, win32security.DACL_SECURITY_INFORMATION, descriptor)
- return True
- finally:
- handle.Close()
- @functools.lru_cache(maxsize=1)
- def _whoami_sid() -> str:
- whoami = subprocess.run(["whoami", "/user", "/fo", "csv", "/nh"], capture_output=True, text=True,
- check=True, encoding="utf-8", errors="replace", timeout=30)
- sid = whoami.stdout.strip().rsplit(",", 1)[-1].strip().strip('"')
- if not sid.upper().startswith("S-1-"):
- raise OSError(f"could not resolve the current user SID from whoami: {whoami.stdout!r}")
- return sid
- def _grant_with_icacls(path: Path, is_dir: bool, expected: str | None = None,
- subtree_has_link: bool | None = None) -> None:
- """*subtree_has_link*: the caller's own walk already answered it (None: walk here)."""
- if expected is None:
- # icacls opens by name, so nothing pins the object between the checks and the write. Inside
- # the home the components were lstat-checked against a known root; with no expected root
- # (off-home, or a path whose home provenance was lost) there is nothing to check: refuse.
- raise ReparsePointRefused(f"{path} has no trusted root to check (icacls fallback, no pywin32)")
- if is_dir and subtree_has_link:
- raise ReparsePointRefused(f"{path} holds a junction, symlink or hard link (icacls fallback)")
- if is_dir and subtree_has_link is None:
- # icacls applies an inheritable ACE through SetNamedSecurityInfo, which also propagates it
- # down the existing subtree; refuse when that subtree holds a link it could descend into.
- # Walk the WHOLE subtree before judging: the generator appends a link it meets after its
- # last yield, so checking inside the loop admitted a tree whose only link came last. A
- # hard-linked file is refused too: the inherited ACE lands on its other names outside.
- nested: list[Path] = []
- linked = [entry for entry, entry_is_dir in iter_tree_without_reparse_points(path, nested)
- if not entry_is_dir and _hard_linked_file(entry)]
- if nested or linked:
- raise ReparsePointRefused(f"{(nested + linked)[0]} under {path} is a junction, symlink or hard "
- "link (icacls fallback)")
- ace = f"*{_whoami_sid()}:(OI)(CI)F" if is_dir else f"*{_whoami_sid()}:F"
- # /L: act on a symbolic link or junction itself, not its target (the lstat check already refused
- # one; this covers a swap between that check and icacls opening the path). Without pywin32 there
- # is no handle to pin, so *expected* cannot be re-checked here.
- subprocess.run(["icacls", str(path), "/grant", ace, "/Q", "/L"], capture_output=True,
- check=True, timeout=60)
- def _hard_linked_file(path: Path) -> bool:
- try:
- st = os.lstat(path)
- except OSError:
- return True
- return not stat.S_ISDIR(st.st_mode) and st.st_nlink > 1
- def _grant(path: Path, is_dir: bool = True, expected: str | None = None,
- subtree_has_link: bool | None = None) -> bool:
- """Grant the token's user full control on *path* itself; raise :class:`ReparsePointRefused`
- for a reparse point or hard-linked file (or, with *expected*, a handle that resolves anywhere
- else) and anything else on failure.
- Returns True when the existing children are still owed: the pywin32 write does not propagate,
- while the icacls fallback (``SetNamedSecurityInfo``) does, and refuses a dir holding a link."""
- if is_reparse_point(path) or _hard_linked_file(path):
- raise ReparsePointRefused(f"{path} is a junction, symlink, other reparse point or hard link")
- try:
- return _grant_with_pywin32(path, is_dir, expected) and is_dir
- except ImportError:
- _grant_with_icacls(path, is_dir, expected, subtree_has_link)
- return False
- def _components_below_home(path: Path) -> list[Path]:
- """*path* and each ancestor of it strictly below the Hermes home (lexically), outermost first;
- empty when *path* is not under the home. The home itself (and above) is the user's own choice
- and may legitimately be a link; an entry INSIDE it is what same-user code can swap."""
- try:
- from hermes_constants import get_hermes_home
- home = Path(os.path.abspath(get_hermes_home()))
- rel = Path(os.path.abspath(path)).relative_to(home)
- except (ImportError, ValueError, OSError):
- return []
- return [home.joinpath(*rel.parts[:i]) for i in range(1, len(rel.parts) + 1)]
- def _expected_final(path: Path) -> str | None:
- """Where *path* must resolve when nothing below the home is a link: the home's real path plus
- the relative parts. None off-home (only the leaf's own open-reparse check applies there)."""
- components = _components_below_home(path)
- if not components:
- return None
- home = components[0].parent
- return os.path.join(os.path.realpath(home), *Path(os.path.abspath(path)).relative_to(home).parts)
- def _warn_refused(path: Path, exc: BaseException) -> None:
- log.warning("Not granting the current user access to %s while elevated (%s): an elevated grant "
- "never follows a junction or link out of the Hermes home. If this is your own link, "
- "point HERMES_HOME (or the link) at the real directory.", path, exc)
- def _elevated(elevated: bool | None) -> bool:
- """The host fact every grant decision takes: *elevated* as passed, else probed (an elevated
- Windows process; :func:`process_is_elevated` is False on every other host)."""
- return process_is_elevated() if elevated is None else elevated
- def grant_user_access(path: str | Path, *, elevated: bool | None = None, repair_children: bool = False) -> bool:
- """Give the token's user an inheriting full-control ACE on *path* when this process is elevated.
- True when a grant was attempted and did not fail; False off Windows, when not elevated, when
- *path* is a junction/symlink/reparse point (refused, one warning), or when the grant failed
- (logged; the directory itself still exists). *elevated* defaults to the probed host fact.
- With *repair_children* (an existing dir an earlier elevated run may have filled), a write that
- does not propagate is followed by the same grant on everything already below *path*, never
- through a link; children are best-effort and never change the result."""
- if not _elevated(elevated):
- return False
- target = Path(path)
- try:
- for component in _components_below_home(target):
- if is_reparse_point(component):
- raise ReparsePointRefused(f"{component} is a junction, symlink or other reparse point")
- expected = _expected_final(target)
- children_owed = _grant(target, expected=expected)
- except ReparsePointRefused as exc:
- _warn_refused(target, exc)
- return False
- except Exception as exc: # health: allow BLE001 -- pywintypes.error is not an OSError; never fail the mkdir
- log.warning("Could not grant the current user access to %s created while elevated (%s); a "
- "non-elevated Hermes may not be able to use it. To repair, from an elevated prompt run: "
- 'icacls "%s" /reset /t', target, exc, target)
- return False
- if repair_children and children_owed:
- real = expected or os.path.realpath(target)
- skipped: list[Path] = []
- entries = [(p, d) for p, d in iter_tree_without_reparse_points(target, skipped) if p != target]
- _, _, failed = _grant_entries(target, real, entries, skipped)
- if failed:
- log.debug("Granting the existing entries under %s failed for %d, e.g. %s: %s",
- target, len(failed), *failed[0])
- return True
- def iter_tree_without_reparse_points(root: str | Path, skipped: list[Path]) -> Iterator[tuple[Path, bool]]:
- """Yield ``(path, is_dir)`` for *root* and everything under it, never entering or yielding a
- junction, symlink or other reparse point (each one is appended to *skipped* instead).
- ``os.walk`` is not enough: it follows directory junctions (``os.path.islink`` is False for one).
- Unreadable directories are skipped silently, like ``icacls /C``."""
- root = Path(root)
- if is_reparse_point(root):
- skipped.append(root)
- return
- stack = [root]
- while stack:
- directory = stack.pop()
- yield directory, True
- try:
- with os.scandir(directory) as entries:
- children = [Path(entry.path) for entry in entries]
- except OSError:
- continue
- for child in sorted(children):
- if is_reparse_point(child):
- skipped.append(child)
- elif child.is_dir():
- stack.append(child)
- else:
- yield child, False
- def grant_tree_user_access(root: str | Path, *, pin_root: bool = False,
- elevated: bool | None = None) -> tuple[int, list[Path], list[tuple[Path, str]]]:
- """Recursive :func:`grant_user_access` (the elevated post-update repair): grant the token's user
- full control on *root* and every directory and file under it, inheriting on directories.
- With *pin_root*, *root* is the operator's own choice (``HERMES_HOME``) and may itself be a link:
- it is resolved once and the walk runs below the real directory. A link BELOW it is still never
- entered or granted through.
- Returns ``(granted, skipped, failed)``: *skipped* are the reparse points (and hard-linked files)
- that were neither granted nor entered, *failed* the ``(path, reason)`` grants that raised. A
- no-op ``(0, [], [])`` off Windows or when not elevated (*elevated* defaults to the probe)."""
- if not _elevated(elevated):
- return 0, [], []
- root = Path(os.path.realpath(root) if pin_root else os.path.abspath(root))
- skipped: list[Path] = []
- entries = list(iter_tree_without_reparse_points(root, skipped))
- granted, skipped, failed = _grant_entries(root, os.path.realpath(root), entries, skipped)
- if skipped:
- log.warning("Elevated ACL repair skipped %d junction/symlink/hard-link entr%s under %s (never "
- "granted through): %s", len(skipped), "y" if len(skipped) == 1 else "ies", root,
- ", ".join(str(p) for p in skipped[:5]) + (" ..." if len(skipped) > 5 else ""))
- return granted, skipped, failed
- def _grant_entries(root: Path, real_root: str, entries: list[tuple[Path, bool]],
- skipped: list[Path]) -> tuple[int, list[Path], list[tuple[Path, str]]]:
- """Grant each walked entry on its own (the pywin32 write does not propagate). The ONE walk
- that produced *entries* and *skipped* also decides which dirs hold a link, so the icacls
- fallback never re-walks a subtree per directory (it refuses exactly those dirs, as before)."""
- linked = {root, *skipped} # a skipped link, or the root itself when it was skipped
- linked.update(p for p, is_dir in entries if not is_dir and _hard_linked_file(p))
- holds_link: set[Path] = set()
- for bad in linked - {root}:
- holds_link.update(parent for parent in bad.parents if parent == root or root in parent.parents)
- if root in skipped:
- holds_link.add(root)
- granted, failed = 0, []
- for path, is_dir in entries:
- try:
- _grant(path, is_dir, os.path.join(real_root, *path.relative_to(root).parts),
- subtree_has_link=is_dir and path in holds_link)
- except ReparsePointRefused:
- skipped.append(path)
- except Exception as exc: # health: allow BLE001 -- pywintypes.error is not an OSError; keep going like /C
- failed.append((path, str(exc) or type(exc).__name__))
- else:
- granted += 1
- return granted, skipped, failed
- # Dir OBJECTS this elevated process already granted, as ``(path, volume serial, file id)`` from
- # ``os.lstat`` (st_dev / st_ino are exactly those on Windows): the grant reads and may rewrite a
- # DACL, and the callers (log handlers, lock acquires) re-enter on hot paths. Keyed by identity, not
- # name: media release deletes a digest dir and the next capture recreates it at the same path.
- _granted: set[tuple[Path, int, int]] = set()
- def _identity(path: Path) -> tuple[Path, int, int] | None:
- try:
- st = os.lstat(path)
- except OSError:
- return None
- return path, st.st_dev, st.st_ino
- def make_user_dir(path: str | Path, mode: int = 0o777, *, parents: bool = False, exist_ok: bool = False,
- elevated: bool | None = None) -> Path:
- """``Path.mkdir`` (same arguments and defaults) that keeps an elevated Windows creation usable
- by the same user unelevated.
- Off Windows or unelevated this is ``Path.mkdir`` and nothing else. Elevated, every directory
- this call created (missing parents included) is granted the user's inheriting full-control ACE,
- and an existing leaf (the repair case) once per directory object per process, except that a
- component that is a junction/symlink/reparse point stops the grants with one warning. An
- existing leaf without ``exist_ok`` is still granted before the ``FileExistsError``. *elevated*
- is the host fact (default: probed); production passes nothing."""
- target = Path(path)
- if not _elevated(elevated):
- target.mkdir(mode=mode, parents=parents, exist_ok=exist_ok)
- return target
- created = []
- probe = target
- while not probe.exists() and probe.parent != probe:
- created.append(probe)
- probe = probe.parent
- try:
- target.mkdir(mode=mode, parents=parents, exist_ok=exist_ok)
- except FileExistsError:
- # ``Path.mkdir`` contract: an existing leaf still raises without exist_ok. The directory an
- # earlier elevated run left is repaired first, so the caller's error is never the reason a
- # non-elevated Hermes stays locked out of it.
- if target.is_dir() and not is_reparse_point(target):
- _grant_dirs(target, [target])
- raise
- _grant_dirs(target, list(reversed(created or [target])), fresh=set(created))
- return target
- def _grant_dirs(target: Path, to_grant: list[Path], fresh: set[Path] = frozenset()) -> None:
- """Grant *to_grant*; a dir in *fresh* (this call created it) is always granted, an existing
- one once per verified object identity."""
- # A junction/symlink planted at (or swapped in for) the leaf, a created component, or any
- # existing ancestor inside the home: grant nothing, one warning (nothing past it is in the home).
- for component in dict.fromkeys([*_components_below_home(target), *to_grant]):
- if is_reparse_point(component):
- _warn_refused(component, ReparsePointRefused("junction, symlink or other reparse point"))
- return
- for directory in to_grant:
- key = _identity(directory)
- if key is None or (directory not in fresh and key in _granted):
- continue
- if grant_user_access(directory, elevated=True, repair_children=directory not in fresh):
- _granted.add(key)
- def unusable_dir_remedy(path: str | Path, *, windows: bool | None = None) -> str:
- """The one-line repair for a directory this process may not use (owner from an elevated run).
- *windows* is the host fact (default: this host)."""
- if (os.name == "nt") if windows is None else windows:
- return f'from an elevated prompt run: icacls "{path}" /reset /t'
- return f'run: sudo chown -R "$(id -un)" "{path}"'
|