Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(security): restrict the Windows runtime log via NTFS ACL, not just warn (#4135)
Radhakrishnan Pachyappan125a703a65c5
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 910f85fef..dbdb55636 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -747,6 +747,30 @@ jobs:tests/test_cli/test_wrap_opencode.py \tests/test_proxy_workspace_registration_middleware.py -q+ windows-file-permissions:+ # Verifies the Windows NTFS-ACL path in headroom._fileperms_windows for+ # real: those tests were previously skipped everywhere, so the module+ # was asserted correct but never run (#4058). The mode-bits (POSIX)+ # assertions in the same file stay skipped here deliberately.+ needs: changes+ if: needs.changes.outputs.code == 'true'+ runs-on: windows-latest+ timeout-minutes: 20+ steps:+ - uses: actions/checkout@v7+ - uses: actions/setup-python@v6+ with:+ python-version: ${{ env.PY_VERSION }}+ - name: Install headroom-ai[dev] (published wheel; local source shadows it)+ run: |+ python -m pip install --upgrade pip+ pip install torch --index-url https://download.pytorch.org/whl/cpu+ pip install "headroom-ai[dev]"+ - name: Run the owner-only file-permission tests+ shell: bash+ run: |+ pytest tests/test_cache_breakpoint_diagnostics.py tests/test_private_state_files.py -v+macos-native-wrapper:needs: changesif: needs.changes.outputs.native == 'true'diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdxindex 0044e113d..1a4d65b4b 100644--- a/docs/content/docs/proxy.mdx+++ b/docs/content/docs/proxy.mdx@@ -381,13 +381,16 @@ when they are enabled.only, and so is every rotated backup (`proxy-8000.log.1`, …). This is notconditional on which content switch is on. If the log path already exists as asymlink, Headroom refuses to log rather than write through it, and says so.-- **Windows:** **Headroom does not restrict the log file.** Read access on NTFS is- decided by the file's ACL; `chmod` there only toggles the read-only attribute,- and Python has no API for setting an ACL, so Headroom does not claim a- protection it cannot establish. The log inherits the ACL of the directory it- is written into, and the proxy logs a warning at startup saying so. Keep- `%USERPROFILE%\.headroom` (or your chosen `--log-file` path) off shared- volumes and out of directories with broadened permissions.+- **Windows:** Headroom restricts the log file too, through an NTFS ACL —+ Python has no ACL API, so this goes directly through `ctypes` rather than a+ third-party dependency. The DACL it sets grants access to exactly the+ current user, replacing (not merging with) whatever was inherited from the+ parent directory. This can fail for reasons unrelated to Headroom's own+ code — a non-NTFS volume, a missing privilege — so the proxy re-reads the+ file afterward to confirm, and only logs a warning at startup if that+ check fails. If you see that warning, keep `%USERPROFILE%\.headroom` (or+ your chosen `--log-file` path) off shared volumes and out of directories+ with broadened permissions.A log shipper or sidecar running as a different user or group cannot read theruntime log on Linux/macOS. Run the collector as the same user, or copy the filediff --git a/headroom/_fileperms_windows.py b/headroom/_fileperms_windows.pynew file mode 100644index 000000000..61d316be9--- /dev/null+++ b/headroom/_fileperms_windows.py@@ -0,0 +1,494 @@+"""Windows NTFS ACL implementation backing :mod:`headroom.fileperms`.++Python ships no ACL API, so this module talks to ``advapi32``/``kernel32``+through ``ctypes`` directly rather than adding a third-party dependency+(``pywin32``) for a handful of calls. Imported only on Windows; every public+function fails closed (returns ``False``) on any error rather than raising,+because the caller's contract (see :mod:`headroom.fileperms`) is "report+whether owner-only protection took effect" — a partially-applied ACL that+raised out of a logging setup path would be worse than one that silently+reports failure and lets the caller warn.++Both entry points restrict a HANDLE, not a path: :func:`restrict_handle` for+a file we hold open (its fd's handle is reopened via ``ReOpenFile`` for+``WRITE_DAC``, which the CRT's own open does not request, with no path+re-resolution and therefore no TOCTOU window), and :func:`restrict_path` for+one we did not (rotated backups) — opened with ``FILE_FLAG_OPEN_REPARSE_POINT``+so a symlink/junction at the path is restricted as the link itself rather+than followed, mirroring the POSIX ``O_NOFOLLOW`` used for the same purpose.++The DACL this sets has exactly one entry: full control for the calling+user's own SID, created fresh (not merged with the inherited DACL) and+applied with ``PROTECTED_DACL_SECURITY_INFORMATION`` so the parent+directory's inherited entries — which is what made the file readable in the+first place — are dropped rather than left alongside the new entry. That is+deliberately stricter than POSIX ``0600`` relative to an administrator:+POSIX root bypasses file permissions outright, while this ACL does not carve+out Administrators/SYSTEM, matching what "owner-only" says.+"""++from __future__ import annotations++import ctypes+import msvcrt+import os+from ctypes import wintypes++_advapi32 = ctypes.WinDLL("advapi32", use_last_error=True) # type: ignore[attr-defined]+_kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) # type: ignore[attr-defined]++_SE_FILE_OBJECT = 1+_DACL_SECURITY_INFORMATION = 0x00000004+_PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000+_NO_INHERITANCE = 0+_SET_ACCESS = 2+_ERROR_SUCCESS = 0+_FILE_ALL_ACCESS = 0x001F01FF+_TOKEN_QUERY = 0x0008+_TokenUser = 1+_WRITE_DAC = 0x00040000+_READ_CONTROL = 0x00020000+_OPEN_EXISTING = 3+_CREATE_NEW = 1+_GENERIC_WRITE = 0x40000000+_ERROR_FILE_NOT_FOUND = 2+_FILE_BEGIN = 0+_FILE_ATTRIBUTE_NORMAL = 0x80+_FILE_ATTRIBUTE_REPARSE_POINT = 0x400+_FILE_SHARE_READ = 1+_FILE_SHARE_WRITE = 2+_FILE_SHARE_DELETE = 4+_FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000+_INVALID_HANDLE_VALUE = wintypes.HANDLE(-1).value+++class _TRUSTEE_W(ctypes.Structure):+ pass+++_TRUSTEE_W._fields_ = [+ ("pMultipleTrustee", ctypes.POINTER(_TRUSTEE_W)),+ ("MultipleTrusteeOperation", ctypes.c_int),+ ("TrusteeForm", ctypes.c_int),+ ("TrusteeType", ctypes.c_int),+ ("ptstrName", ctypes.c_void_p),+]+++class _EXPLICIT_ACCESS_W(ctypes.Structure):+ _fields_ = [+ ("grfAccessPermissions", wintypes.DWORD),+ ("grfAccessMode", ctypes.c_int),+ ("grfInheritance", wintypes.DWORD),+ ("Trustee", _TRUSTEE_W),+ ]+++_advapi32.BuildTrusteeWithSidW.argtypes = [ctypes.POINTER(_TRUSTEE_W), ctypes.c_void_p]+_advapi32.BuildTrusteeWithSidW.restype = None++_advapi32.SetEntriesInAclW.argtypes = [+ wintypes.ULONG,+ ctypes.POINTER(_EXPLICIT_ACCESS_W),+ ctypes.c_void_p,+ ctypes.POINTER(ctypes.c_void_p),+]+_advapi32.SetEntriesInAclW.restype = wintypes.DWORD++_advapi32.SetSecurityInfo.argtypes = [+ wintypes.HANDLE,+ ctypes.c_int,+ wintypes.DWORD,+ ctypes.c_void_p,+ ctypes.c_void_p,+ ctypes.c_void_p,+ ctypes.c_void_p,+]+_advapi32.SetSecurityInfo.restype = wintypes.DWORD++_advapi32.GetSecurityInfo.argtypes = [+ wintypes.HANDLE,+ ctypes.c_int,+ wintypes.DWORD,+ ctypes.POINTER(ctypes.c_void_p),+ ctypes.POINTER(ctypes.c_void_p),+ ctypes.POINTER(ctypes.c_void_p),+ ctypes.POINTER(ctypes.c_void_p),+ ctypes.POINTER(ctypes.c_void_p),+]+_advapi32.GetSecurityInfo.restype = wintypes.DWORD++_advapi32.GetAclInformation.argtypes = [+ ctypes.c_void_p,+ ctypes.c_void_p,+ wintypes.DWORD,+ ctypes.c_int,+]+_advapi32.GetAclInformation.restype = wintypes.BOOL++_advapi32.GetAce.argtypes = [ctypes.c_void_p, wintypes.DWORD, ctypes.POINTER(ctypes.c_void_p)]+_advapi32.GetAce.restype = wintypes.BOOL++_advapi32.EqualSid.argtypes = [ctypes.c_void_p, ctypes.c_void_p]+_advapi32.EqualSid.restype = wintypes.BOOL++_advapi32.OpenProcessToken.argtypes = [+ wintypes.HANDLE,+ wintypes.DWORD,+ ctypes.POINTER(wintypes.HANDLE),+]+_advapi32.OpenProcessToken.restype = wintypes.BOOL++_advapi32.GetTokenInformation.argtypes = [+ wintypes.HANDLE,+ ctypes.c_int,+ ctypes.c_void_p,+ wintypes.DWORD,+ ctypes.POINTER(wintypes.DWORD),+]+_advapi32.GetTokenInformation.restype = wintypes.BOOL++_kernel32.GetCurrentProcess.restype = wintypes.HANDLE+_kernel32.CloseHandle.argtypes = [wintypes.HANDLE]+_kernel32.LocalFree.argtypes = [ctypes.c_void_p]+_kernel32.ReOpenFile.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD]+_kernel32.ReOpenFile.restype = wintypes.HANDLE+_kernel32.CreateFileW.argtypes = [+ wintypes.LPCWSTR,+ wintypes.DWORD,+ wintypes.DWORD,+ ctypes.c_void_p,+ wintypes.DWORD,+ wintypes.DWORD,+ wintypes.HANDLE,+]+_kernel32.CreateFileW.restype = wintypes.HANDLE+_kernel32.SetFilePointerEx.argtypes = [+ wintypes.HANDLE,+ ctypes.c_longlong,+ ctypes.POINTER(ctypes.c_longlong),+ wintypes.DWORD,+]+_kernel32.SetFilePointerEx.restype = wintypes.BOOL+_kernel32.SetEndOfFile.argtypes = [wintypes.HANDLE]+_kernel32.SetEndOfFile.restype = wintypes.BOOL+++class _ByHandleFileInformation(ctypes.Structure):+ _fields_ = [+ ("dwFileAttributes", wintypes.DWORD),+ ("ftCreationTime", wintypes.FILETIME),+ ("ftLastAccessTime", wintypes.FILETIME),+ ("ftLastWriteTime", wintypes.FILETIME),+ ("dwVolumeSerialNumber", wintypes.DWORD),+ ("nFileSizeHigh", wintypes.DWORD),+ ("nFileSizeLow", wintypes.DWORD),+ ("nNumberOfLinks", wintypes.DWORD),+ ("nFileIndexHigh", wintypes.DWORD),+ ("nFileIndexLow", wintypes.DWORD),+ ]+++_kernel32.GetFileInformationByHandle.argtypes = [+ wintypes.HANDLE,+ ctypes.POINTER(_ByHandleFileInformation),+]+_kernel32.GetFileInformationByHandle.restype = wintypes.BOOL+++class _AclSizeInformation(ctypes.Structure):+ _fields_ = [+ ("AceCount", wintypes.DWORD),+ ("AclBytesInUse", wintypes.DWORD),+ ("AclBytesFree", wintypes.DWORD),+ ]+++class _AceHeader(ctypes.Structure):+ _fields_ = [+ ("AceType", ctypes.c_ubyte),+ ("AceFlags", ctypes.c_ubyte),+ ("AceSize", wintypes.WORD),+ ]+++def _current_user_sid() -> tuple[ctypes.c_void_p, ctypes.Array[ctypes.c_char]]:+ """The calling process's user SID, plus the buffer it lives in.++ Caller must keep the buffer alive for as long as the SID pointer is used+ -- the SID is a view into it, not a copy.+ """+ token = wintypes.HANDLE()+ if not _advapi32.OpenProcessToken(+ _kernel32.GetCurrentProcess(), _TOKEN_QUERY, ctypes.byref(token)+ ):+ raise ctypes.WinError(ctypes.get_last_error()) # type: ignore[attr-defined]+ try:+ size = wintypes.DWORD(0)+ _advapi32.GetTokenInformation(token, _TokenUser, None, 0, ctypes.byref(size))+ buf = ctypes.create_string_buffer(size.value)+ if not _advapi32.GetTokenInformation(token, _TokenUser, buf, size, ctypes.byref(size)):+ raise ctypes.WinError(ctypes.get_last_error()) # type: ignore[attr-defined]+ # TOKEN_USER is { SID_AND_ATTRIBUTES { PSID Sid; DWORD Attributes; } };+ # the first pointer-sized field is the PSID.+ sid = ctypes.cast(buf, ctypes.POINTER(ctypes.c_void_p))[0]+ return ctypes.c_void_p(sid), buf+ finally:+ _kernel32.CloseHandle(token)+++def _apply_owner_only_dacl(handle: wintypes.HANDLE) -> bool:+ """Replace *handle*'s DACL with a single owner-only entry.++ *handle* must already carry ``WRITE_DAC``.+ """+ try:+ sid, _buf = _current_user_sid()+ except OSError:+ return False++ trustee = _TRUSTEE_W()+ _advapi32.BuildTrusteeWithSidW(ctypes.byref(trustee), sid)+ entry = _EXPLICIT_ACCESS_W()+ entry.grfAccessPermissions = _FILE_ALL_ACCESS+ entry.grfAccessMode = _SET_ACCESS+ entry.grfInheritance = _NO_INHERITANCE+ entry.Trustee = trustee++ new_dacl = ctypes.c_void_p()+ # Passing NULL for the existing-ACL argument builds a fresh ACL containing+ # only *entry*, rather than merging with whatever inherited entries the+ # file already had -- those inherited entries are exactly what made it+ # readable, so merging would defeat the point.+ if (+ _advapi32.SetEntriesInAclW(1, ctypes.byref(entry), None, ctypes.byref(new_dacl))+ != _ERROR_SUCCESS+ ):+ return False+ try:+ rc = _advapi32.SetSecurityInfo(+ handle,+ _SE_FILE_OBJECT,+ _DACL_SECURITY_INFORMATION | _PROTECTED_DACL_SECURITY_INFORMATION,+ None,+ None,+ new_dacl,+ None,+ )+ return bool(rc == _ERROR_SUCCESS)+ finally:+ _kernel32.LocalFree(new_dacl)+++def restrict_handle(fd: int) -> bool:+ """Make the open file behind CRT descriptor *fd* owner-only.++ The CRT's own ``CreateFileW`` call underneath ``os.open``/``open()`` does+ not request ``WRITE_DAC``, so this reopens the same file object (via+ ``ReOpenFile`` -- no path involved, so nothing for a symlink to redirect)+ with that right, applies the DACL, and closes the reopened handle. *fd*+ itself is left exactly as the caller had it.+ """+ try:+ original = wintypes.HANDLE(msvcrt.get_osfhandle(fd)) # type: ignore[attr-defined]+ except OSError:+ return False+ reopened = _kernel32.ReOpenFile(+ original,+ _WRITE_DAC | _READ_CONTROL,+ _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,+ 0,+ )+ if not reopened or reopened == _INVALID_HANDLE_VALUE:+ return False+ try:+ return _apply_owner_only_dacl(reopened)+ finally:+ _kernel32.CloseHandle(reopened)+++def restrict_path(path: str) -> bool:+ """Make the file at *path* owner-only without following a symlink there.++ For files this process did not open itself (rotated log backups).+ ``FILE_FLAG_OPEN_REPARSE_POINT`` opens a symlink/junction as the link+ itself rather than its target, the Windows equivalent of the POSIX+ ``O_NOFOLLOW`` the caller's own ``islink`` check already guards against+ on both platforms.+ """+ handle = _kernel32.CreateFileW(+ path,+ _WRITE_DAC | _READ_CONTROL,+ _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,+ None,+ _OPEN_EXISTING,+ _FILE_FLAG_OPEN_REPARSE_POINT,+ None,+ )+ if not handle or handle == _INVALID_HANDLE_VALUE:+ return False+ try:+ return _apply_owner_only_dacl(handle)+ finally:+ _kernel32.CloseHandle(handle)+++def open_no_follow(path: str, *, truncate: bool) -> int:+ """Create-or-open *path* for append/truncate, refusing a symlink or+ junction there, and apply the owner-only DACL -- all against the one+ HANDLE this opens, so there is no window between checking the path and+ writing through it.++ This is the primitive :func:`headroom.fileperms.open_owner_only` needs+ and plain ``os.open()`` cannot provide on Windows: the CRT open it wraps+ has no ``O_NOFOLLOW`` equivalent, so it silently follows a planted+ symlink/junction to whatever it points at, and anything opened that way+ -- including a later DACL change -- lands on the target, not the+ intended file. ``FILE_FLAG_OPEN_REPARSE_POINT`` makes this CreateFileW+ call open the reparse point itself rather than its target regardless of+ *disposition*, so the attribute check below sees the real thing even on+ the create-or-open path a planted link races against.++ Raises ``OSError`` on any failure, including when *path* is a symlink or+ junction -- matching the POSIX ``O_NOFOLLOW`` contract this mirrors, and+ the caller's existing "failing closed is deliberate" policy.++ Always opens with ``OPEN_EXISTING`` first, regardless of *truncate*.+ ``CREATE_ALWAYS``/``OPEN_ALWAYS`` against an existing reparse point does+ not error or open the link -- it deletes it and creates a fresh regular+ file in its place, *before* this function ever gets a handle to inspect,+ so the refusal below would silently never fire for exactly the request+ (truncate) that most needs it. Truncating, when asked for, happens via+ ``SetEndOfFile`` on the one handle this function opens, once that handle+ is confirmed not to be a reparse point -- never by asking ``CreateFileW``+ to recreate the path.+ """+ access = _GENERIC_WRITE | _WRITE_DAC+ share = _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE+ flags = _FILE_FLAG_OPEN_REPARSE_POINT | _FILE_ATTRIBUTE_NORMAL++ handle = _kernel32.CreateFileW(path, access, share, None, _OPEN_EXISTING, flags, None)+ if not handle or handle == _INVALID_HANDLE_VALUE:+ err = ctypes.get_last_error() # type: ignore[attr-defined]+ if err != _ERROR_FILE_NOT_FOUND:+ raise OSError(f"CreateFileW failed for {path!r}: error {err}")+ # Nothing there yet. CREATE_NEW fails outright instead of silently+ # opening whatever a symlink planted in the gap since the check+ # above left behind -- the same race OPEN_EXISTING already closed+ # for the file-exists case, closed here for the file-missing one.+ handle = _kernel32.CreateFileW(path, access, share, None, _CREATE_NEW, flags, None)+ if not handle or handle == _INVALID_HANDLE_VALUE:+ err = ctypes.get_last_error() # type: ignore[attr-defined]+ raise OSError(f"CreateFileW failed for {path!r}: error {err}")+ try:+ info = _ByHandleFileInformation()+ if not _kernel32.GetFileInformationByHandle(handle, ctypes.byref(info)):+ err = ctypes.get_last_error() # type: ignore[attr-defined]+ raise OSError(f"GetFileInformationByHandle failed for {path!r}: error {err}")+ if info.dwFileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:+ raise OSError(f"refusing to open {path!r}: it is a symlink or junction")+ if truncate:+ if not _kernel32.SetFilePointerEx(handle, 0, None, _FILE_BEGIN):+ err = ctypes.get_last_error() # type: ignore[attr-defined]+ raise OSError(f"SetFilePointerEx failed for {path!r}: error {err}")+ if not _kernel32.SetEndOfFile(handle):+ err = ctypes.get_last_error() # type: ignore[attr-defined]+ raise OSError(f"SetEndOfFile failed for {path!r}: error {err}")+ # Best-effort, like every other restrict_* call: a failure here does+ # not fail the open (see fileperms.verify_owner_only for why), but a+ # planted symlink always fails above regardless of this result.+ _apply_owner_only_dacl(handle)+ fd: int = msvcrt.open_osfhandle( # type: ignore[attr-defined]+ handle, os.O_APPEND if not truncate else os.O_TRUNC+ )+ return fd+ except BaseException:+ _kernel32.CloseHandle(handle)+ raise+++def verify_handle(fd: int) -> bool:+ """Like :func:`verify_path`, for a file this process already holds open."""+ try:+ handle = wintypes.HANDLE(msvcrt.get_osfhandle(fd)) # type: ignore[attr-defined]+ except OSError:+ return False+ return _verify_handle(handle)+++def verify_path(path: str) -> bool:+ """Re-read the DACL at *path* and confirm it grants access to exactly the+ calling user and no one else.++ Independent of :func:`restrict_path`/:func:`restrict_handle`'s own+ success return: that return says the API calls reported success, this+ re-reads what is actually on the object now. Used to decide whether to+ warn, so the warning reflects the file in front of it rather than a+ static assumption about the platform. Only needs ``READ_CONTROL``, not+ ``WRITE_DAC`` -- it never modifies the DACL.+ """+ handle = _kernel32.CreateFileW(+ path,+ _READ_CONTROL,+ _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,+ None,+ _OPEN_EXISTING,+ _FILE_FLAG_OPEN_REPARSE_POINT,+ None,+ )+ if not handle or handle == _INVALID_HANDLE_VALUE:+ return False+ try:+ return _verify_handle(handle)+ finally:+ _kernel32.CloseHandle(handle)+++def _verify_handle(handle: wintypes.HANDLE) -> bool:+ try:+ sid, _buf = _current_user_sid()+ except OSError:+ return False++ dacl = ctypes.c_void_p()+ sec_desc = ctypes.c_void_p()+ rc = _advapi32.GetSecurityInfo(+ handle,+ _SE_FILE_OBJECT,+ _DACL_SECURITY_INFORMATION,+ None,+ None,+ ctypes.byref(dacl),+ None,+ ctypes.byref(sec_desc),+ )+ if rc != _ERROR_SUCCESS:+ return False+ try:+ size_info = _AclSizeInformation()+ if not _advapi32.GetAclInformation(+ dacl,+ ctypes.byref(size_info),+ ctypes.sizeof(size_info),+ 2, # AclSizeInformation+ ):+ return False+ if size_info.AceCount != 1:+ return False+ ace_ptr = ctypes.c_void_p()+ if not _advapi32.GetAce(dacl, 0, ctypes.byref(ace_ptr)):+ return False+ # ACCESS_ALLOWED_ACE lays out as ACE_HEADER, then a DWORD access mask,+ # then the SID -- the SID starts right after those two fixed fields.+ ace_addr = ace_ptr.value+ if ace_addr is None:+ return False+ sid_offset = ctypes.sizeof(_AceHeader) + ctypes.sizeof(wintypes.DWORD)+ ace_sid = ctypes.c_void_p(ace_addr + sid_offset)+ return bool(_advapi32.EqualSid(ace_sid, sid))+ finally:+ # sec_desc, not dacl: GetSecurityInfo returns pointers into one+ # LocalAlloc'd block: freeing dacl (an offset into it, not its start)+ # is an invalid free. See cpython ctypes issue discussions on+ # GetSecurityInfo for the same gotcha.+ _kernel32.LocalFree(sec_desc)diff --git a/headroom/fileperms.py b/headroom/fileperms.pyindex f5e76daab..668eb40ef 100644--- a/headroom/fileperms.py+++ b/headroom/fileperms.py@@ -28,21 +28,41 @@ Scope of the guarantee — read this before citing it in a threat model:the wrong inode by a path that changed underneath us. ``O_NOFOLLOW`` means asymlink planted at the path fails the open outright rather than redirectingthe write.-* **Windows**: *not* enforced, and deliberately not claimed. Who may read an- NTFS file is decided by its ACL. ``os.chmod`` on Windows only toggles the- read-only attribute and leaves the ACL untouched, so ``chmod(0o600)`` returns- successfully while ``stat.S_IMODE`` still reports ``0666`` and the file stays- readable per the inherited ACL. Python ships no ACL API, so Headroom does not- pretend to set one: on Windows the log inherits the ACL of its parent- directory and :data:`OWNER_ONLY_SUPPORTED` is ``False``. Callers that create- sensitive files say so once in the log (see- ``headroom.proxy.helpers._setup_file_logging``), and operators should treat- the log directory itself as the access-control boundary — keep it under the- user profile, and do not put it on a share.--``O_NOFOLLOW`` does not exist on Windows either, so the symlink protection-there is the explicit :func:`is_symlink` check callers make before opening, not-a kernel-enforced one.+* **Windows**: mode bits do not control read access there — who may read an+ NTFS file is decided by its ACL, and ``os.chmod`` only toggles the+ read-only attribute and leaves the ACL untouched, so ``chmod(0o600)``+ returns successfully while ``stat.S_IMODE`` still reports ``0666``. That is+ why :data:`OWNER_ONLY_SUPPORTED` — "mode bits enforce this" — is ``False``+ on Windows and stays that way regardless of the rest of this paragraph.+ :func:`restrict_fd_to_owner` and :func:`restrict_path_to_owner` nonetheless+ restrict the log, its rotated backups, and the JSONL request log there too,+ through :mod:`headroom._fileperms_windows`: a DACL with exactly one entry+ (the calling user, full control), built fresh rather than merged with the+ inherited entries that made the file readable in the first place, and+ applied with ``PROTECTED_DACL_SECURITY_INFORMATION`` so those inherited+ entries are dropped rather than left alongside it. Unlike the POSIX path+ this can fail per-call (a non-NTFS volume, a missing privilege), so callers+ that need to know whether it actually took effect call+ :func:`verify_owner_only` rather than trusting the static flag — see+ ``headroom.proxy.helpers._warn_once_if_not_protected``, which warns only+ when verification fails rather than unconditionally on Windows. Not+ extended (yet) to the sqlite-backed memory/CCR stores+ (:func:`ensure_private_file`/:func:`connect_private_sqlite`) or+ :func:`private_dir` — those remain unenforced on Windows, same as before.++``O_NOFOLLOW`` does not exist on Windows, so the CRT ``os.open`` underneath+Python's own ``open()`` has no way to refuse a symlink/junction there — it+silently follows one to whatever it points at. :func:`open_owner_only` does+not route through that on Windows for this reason: it opens via+``headroom._fileperms_windows.open_no_follow``, which uses+``FILE_FLAG_OPEN_REPARSE_POINT`` to open the reparse point itself regardless+of create-or-open disposition, and refuses it outright if the resulting+handle's own attributes show it is one — closing the same gap ``O_NOFOLLOW``+closes on POSIX, checked on the handle rather than the path so there is+nothing for a race to redirect. :func:`restrict_path_to_owner` uses the same+flag for the same reason when narrowing a file it did not open itself+(rotated backups): because that path only ever touches the reparse point's+own DACL, never a target's, it is safe even without the attribute check."""from __future__ import annotations@@ -62,9 +82,14 @@ OWNER_ONLY_MODE = 0o600OWNER_ONLY_DIR_MODE = 0o700#: ``True`` only where the mode bits above actually decide who can read the-#: file. See the module docstring for why Windows is excluded.+#: file. See the module docstring for why Windows is excluded -- it has its+#: own, separately-verified mechanism instead, not reflected in this flag.OWNER_ONLY_SUPPORTED = os.name == "posix"+_win: Any = None+if os.name == "nt":+ from . import _fileperms_windows as _win+def _open_flags(*, truncate: bool = False) -> int:flags = os.O_CREAT | os.O_WRONLY | (os.O_TRUNC if truncate else os.O_APPEND)@@ -83,14 +108,17 @@ def restrict_fd_to_owner(fd: int) -> bool:Acts on the descriptor, not the path, so there is no window in which themode could land on a different file, and no way for a symlink to move it.- Returns ``False`` on platforms where the mode bits do not carry the- guarantee rather than reporting a protection that was not established.+ On Windows this goes through :mod:`headroom._fileperms_windows` instead+ of mode bits (see the module docstring); returns ``False`` if that fails+ too, rather than reporting a protection that was not established."""- if not OWNER_ONLY_SUPPORTED:- return False- if stat.S_IMODE(os.fstat(fd).st_mode) != OWNER_ONLY_MODE:- os.fchmod(fd, OWNER_ONLY_MODE)- return True+ if OWNER_ONLY_SUPPORTED:+ if stat.S_IMODE(os.fstat(fd).st_mode) != OWNER_ONLY_MODE:+ os.fchmod(fd, OWNER_ONLY_MODE)+ return True+ if _win is not None:+ return bool(_win.restrict_handle(fd))+ return Falsedef restrict_path_to_owner(path: str | os.PathLike[str]) -> bool:@@ -98,18 +126,43 @@ def restrict_path_to_owner(path: str | os.PathLike[str]) -> bool:For files Headroom did not open itself — rotated log backups, and backupsleft behind by an older unhardened run. A path that is a symlink is left- alone: the target is not ours to re-permission.+ alone on every platform: the target is not ours to re-permission. On+ Windows the ACL path (see the module docstring) adds+ ``FILE_FLAG_OPEN_REPARSE_POINT`` underneath that check as a second guard."""- if not OWNER_ONLY_SUPPORTED:- return Falsetry:if os.path.islink(path) or not os.path.exists(path):return False- if stat.S_IMODE(os.stat(path).st_mode) != OWNER_ONLY_MODE:- os.chmod(path, OWNER_ONLY_MODE)+ if OWNER_ONLY_SUPPORTED:+ if stat.S_IMODE(os.stat(path).st_mode) != OWNER_ONLY_MODE:+ os.chmod(path, OWNER_ONLY_MODE)+ return Trueexcept OSError:return False- return True+ if _win is not None:+ return bool(_win.restrict_path(os.fspath(path)))+ return False+++def verify_owner_only(path: str | os.PathLike[str]) -> bool:+ """Confirm *path* is restricted to its current owner right now.++ Unlike :data:`OWNER_ONLY_SUPPORTED` (a static per-platform flag) or the+ return value of :func:`restrict_fd_to_owner`/:func:`restrict_path_to_owner`+ (whether the API calls *reported* success), this re-reads the file's+ actual permissions. On Windows the ACL call can fail for reasons that+ have nothing to do with Headroom's code -- a non-NTFS volume, a missing+ privilege -- so a caller deciding whether to warn an operator should ask+ what happened to *this* file, not assume from the platform.+ """+ if OWNER_ONLY_SUPPORTED:+ try:+ return stat.S_IMODE(os.stat(path).st_mode) == OWNER_ONLY_MODE+ except OSError:+ return False+ if _win is not None:+ return bool(_win.verify_path(os.fspath(path)))+ return Falsedef open_owner_only(@@ -124,22 +177,43 @@ def open_owner_only(Raises ``OSError`` — which every caller already treats as "logging isunavailable, carry on" — if the path cannot be opened, including when it is- a symlink on a platform with ``O_NOFOLLOW``. Failing closed is deliberate:- a redirected sensitive log is worse than no log.+ a symlink or junction. Failing closed is deliberate: a redirected sensitive+ log is worse than no log.++ On POSIX, ``O_NOFOLLOW`` makes the ``os.open`` below refuse a symlink at+ the kernel level. Windows has no such flag -- plain ``os.open`` there+ silently follows a planted symlink/junction to whatever it points at, so+ a DACL applied afterward lands on the target, not the intended file; this+ goes through :func:`headroom._fileperms_windows.open_no_follow` instead,+ which opens the reparse point itself and verifies that before touching+ anything, closing the one path/open gap ``O_NOFOLLOW`` closes on POSIX."""if mode[:1] not in ("a", "w"):raise ValueError(f"open_owner_only: mode must start with 'a' or 'w', got {mode!r}")- fd = os.open(path, _open_flags(truncate=mode.startswith("w")), OWNER_ONLY_MODE)- try:- restrict_fd_to_owner(fd)- return open(fd, mode, encoding=encoding, errors=errors, newline=newline, closefd=True)- except BaseException:+ truncate = mode.startswith("w")+ if OWNER_ONLY_SUPPORTED:+ fd = os.open(path, _open_flags(truncate=truncate), OWNER_ONLY_MODE)try:- os.close(fd)- except OSError:- # open() can have taken and closed the descriptor on its way out.- pass- raise+ restrict_fd_to_owner(fd)+ return open(fd, mode, encoding=encoding, errors=errors, newline=newline, closefd=True)+ except BaseException:+ try:+ os.close(fd)+ except OSError:+ # open() can have taken and closed the descriptor on its way out.+ pass+ raise+ if _win is not None:+ fd = _win.open_no_follow(os.fspath(path), truncate=truncate)+ try:+ return open(fd, mode, encoding=encoding, errors=errors, newline=newline, closefd=True)+ except BaseException:+ try:+ os.close(fd)+ except OSError:+ pass+ raise+ return open(path, mode, encoding=encoding, errors=errors, newline=newline)def ensure_private_file(path: str | os.PathLike[str], *, what: str = "file") -> None:diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 7c66d85ee..f13eca886 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -1862,22 +1862,26 @@ class _OwnerOnlyRotatingFileHandler(RotatingFileHandler):_owner_only_warning_emitted = False-def _warn_once_if_owner_only_unsupported(log_path: Path) -> None:- """Say plainly, once per process, when the file cannot be made owner-only.-- A security control that quietly does nothing on a supported platform is- worse than no control, so Windows gets told rather than left to assume the- 0600 in the docs applies to it.+def _warn_once_if_not_protected(log_path: Path) -> None:+ """Say plainly, once per process, when the file is not actually owner-only.++ Checks the file itself (:func:`headroom.fileperms.verify_owner_only`)+ rather than assuming from the platform: on Windows the ACL restriction+ (:mod:`headroom._fileperms_windows`) usually succeeds, in which case this+ stays silent, but it can fail for reasons that have nothing to do with+ Headroom's own code — a non-NTFS volume, a missing privilege — and a+ control that quietly does nothing is worse than no control."""global _owner_only_warning_emitted- if _fileperms.OWNER_ONLY_SUPPORTED or _owner_only_warning_emitted:+ if _owner_only_warning_emitted or _fileperms.verify_owner_only(log_path):return_owner_only_warning_emitted = Truelogger.warning(- "Headroom cannot create %s owner-only on this platform: file modes do not "- "control read access here, and Headroom does not set an ACL. The runtime log "- "can contain request and response content (--log-messages, wire debug, "- "HEADROOM_LOG_PAYLOAD_PREVIEW) — protect the log directory itself.",+ "Headroom could not restrict %s to the current user — other accounts "+ "on this machine may be able to read it. The runtime log can contain "+ "request and response content (--log-messages, wire debug, "+ "HEADROOM_LOG_PAYLOAD_PREVIEW); move HEADROOM_WORKSPACE_DIR somewhere "+ "only you can access, or restrict the containing directory yourself.",log_path,)@@ -1971,7 +1975,6 @@ def _setup_file_logging(log_path,)return- _warn_once_if_owner_only_unsupported(log_path)# Attach to the headroom root logger so all sub-loggers are captured.# Keep root propagation enabled for container stdout/stderr while# this handler writes the separate port/worker-specific proxy log.@@ -2011,6 +2014,11 @@ def _setup_file_logging(headroom_logger.removeHandler(stale)stale.close()headroom_logger.addHandler(handler)+ # After, not before: the handler's _open() is what actually attempts+ # the protection (mode bits on POSIX, the ACL call on Windows), so+ # only now is there something real to verify rather than a platform+ # guess.+ _warn_once_if_not_protected(log_path)if level == logging.DEBUG:logger.warning("Headroom debug logging is on (HEADROOM_LOG_LEVEL). %s now records "@@ -2022,11 +2030,13 @@ def _setup_file_logging()except OSError as exc:# Non-fatal: can't write logs (read-only fs, permissions, etc.). Say so,- # or the missing proxy.log is the only clue. The OSError names the path.+ # or the missing proxy.log is the only clue. str(exc) embeds repr(filename),+ # which doubles backslashes on Windows -- exc.filename is the raw path.logger.warning(- "Headroom runtime log disabled: cannot write the log file: %s. "+ "Headroom runtime log disabled: cannot write the log file: %s: %s. ""Point HEADROOM_WORKSPACE_DIR at a writable directory to restore proxy.log.",- exc,+ exc.filename or log_dir,+ exc.strerror or exc,)diff --git a/tests/test_cache_breakpoint_diagnostics.py b/tests/test_cache_breakpoint_diagnostics.pyindex acb518b4e..281ad0978 100644--- a/tests/test_cache_breakpoint_diagnostics.py+++ b/tests/test_cache_breakpoint_diagnostics.py@@ -370,6 +370,51 @@ def test_pre_existing_backups_are_tightened_when_the_handler_opens(assert stat.S_IMODE(stale.stat().st_mode) == 0o600+_windows_only = pytest.mark.skipif(+ os.name != "nt",+ reason="exercises the Windows ACL path specifically",+)+++@_windows_only+def test_runtime_log_is_owner_only_via_acl_with_previews_off(tmp_path, monkeypatch) -> None:+ """Windows counterpart of test_runtime_log_is_owner_only_with_previews_off.++ Same scenario, checked with verify_owner_only (the DACL) instead of+ stat.S_IMODE (mode bits do not apply on Windows either way).+ """+ monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)+ with _proxy_log(tmp_path, monkeypatch, 18812) as log_path:+ assert log_path.exists()+ assert fileperms.verify_owner_only(log_path) is True+++@_windows_only+def test_rotated_backups_are_owner_only_via_acl(tmp_path, monkeypatch) -> None:+ """Windows counterpart of test_rotated_backups_are_owner_only.++ Rotation must not launder the restriction away there either: doRollover+ renames the base file (the DACL moves with the rename, same as a POSIX+ rename preserves mode bits) and opens a fresh one that must be+ independently restricted.+ """+ monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)+ with _proxy_log(tmp_path, monkeypatch, 18813) as log_path:+ handler = next(+ h for h in logging.getLogger("headroom").handlers if h.name == "headroom.proxy.file"+ )+ handler.maxBytes = 256+ for i in range(60):+ handler.emit(+ logging.LogRecord("headroom", logging.INFO, __file__, i, "x" * 64, None, None)+ )+ handler.flush()+ backups = sorted(log_path.parent.glob(f"{log_path.name}.*"))+ assert backups, "no rollover happened — the test did not exercise the path it claims to"+ for path in [log_path, *backups]:+ assert fileperms.verify_owner_only(path) is True, path++@pytest.mark.skipif(os.name != "posix",reason="creating a symlink needs elevation on Windows, and O_NOFOLLOW does not exist there",@@ -475,6 +520,82 @@ def test_open_owner_only_fails_closed_on_a_symlink(tmp_path) -> None:fileperms.open_owner_only(link).close()+def _try_symlink(link: Path, target: Path) -> None:+ """Create a real symlink, or skip with an explicit reason.++ Unprivileged symlink creation on Windows needs Developer Mode; a CI+ runner without it would otherwise either silently skip this test's+ actual point or crash on the OSError from symlink_to itself. Skipping+ explicitly, with the reason, is the point: a runner that cannot create+ symlinks must say so rather than have this look covered by the ACL+ assertions elsewhere in this file, which exercise a different thing.+ """+ try:+ link.symlink_to(target)+ except OSError as exc:+ pytest.skip(+ f"cannot create a symlink on this runner ({exc}); needs Developer Mode on Windows"+ )+++@_windows_only+def test_open_owner_only_redirect_blocker_regression(tmp_path) -> None:+ """Regression for a real Windows finding: open_owner_only followed a+ planted symlink to its target instead of refusing it.++ Plain os.open() on Windows has no O_NOFOLLOW equivalent, so it silently+ followed the link; a DACL applied afterward (restrict_fd_to_owner) then+ landed on the target, not the intended file, and content written+ through the "log" landed there too -- a real redirect, independently+ reproduced, not a theoretical one. open_owner_only now opens through+ headroom._fileperms_windows.open_no_follow instead, which refuses a+ reparse point outright. Covers both modes open_owner_only supports:+ append (what the proxy log actually uses) and truncate.+ """+ target = tmp_path / "ORIGINAL"+ target.write_text("ORIGINAL", encoding="utf-8")+ link = tmp_path / "log.txt"+ _try_symlink(link, target)++ with pytest.raises(OSError):+ fileperms.open_owner_only(link, "a").close()+ assert target.read_text(encoding="utf-8") == "ORIGINAL", "append mode wrote through the symlink"++ with pytest.raises(OSError):+ fileperms.open_owner_only(link, "w").close()+ assert target.read_text(encoding="utf-8") == "ORIGINAL", (+ "truncate mode wrote through the symlink"+ )+++@_windows_only+def test_runtime_log_refuses_a_symlinked_path_on_windows(tmp_path, monkeypatch) -> None:+ """Windows counterpart of test_runtime_log_refuses_a_symlinked_path."""+ from headroom.proxy.helpers import _PROXY_LOG_HANDLER_NAME, _setup_file_logging++ monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))+ log_path = _paths.proxy_log_path(18814)+ log_path.parent.mkdir(parents=True, exist_ok=True)+ elsewhere = tmp_path / "attacker-readable.log"+ elsewhere.write_text("", encoding="utf-8")+ _try_symlink(log_path, elsewhere)++ headroom_logger = logging.getLogger("headroom")+ before = list(headroom_logger.handlers)+ try:+ _setup_file_logging(18814)+ attached = [h for h in headroom_logger.handlers if h.name == _PROXY_LOG_HANDLER_NAME]+ assert not attached, "logging was wired up through the symlink"+ logging.getLogger("headroom").info("a record that must not be written")+ finally:+ for handler in list(headroom_logger.handlers):+ if handler not in before:+ headroom_logger.removeHandler(handler)+ handler.close()++ assert elsewhere.read_text(encoding="utf-8") == ""++@_posix_onlydef test_jsonl_request_log_is_owner_only(tmp_path, predictable_umask) -> None:"""``--log-file`` with ``--log-messages`` writes whole bodies to this file."""@@ -522,31 +643,45 @@ def test_owner_only_support_matches_what_the_platform_can_enforce() -> None:@pytest.mark.skipif(fileperms.OWNER_ONLY_SUPPORTED,- reason="asserts the *absence* of the mode guarantee; only meaningful off POSIX",+ reason="exercises the non-mode-bits path; only meaningful off POSIX",)-def test_no_owner_only_claim_is_made_off_posix(tmp_path) -> None:- """On Windows the handler still logs — it just does not claim 0600."""+def test_windows_acl_restricts_even_though_mode_bits_do_not(tmp_path) -> None:+ """On Windows the handler still logs, and is restricted by ACL, not mode.++ ``OWNER_ONLY_SUPPORTED`` (mode bits decide access) stays ``False`` here —+ that is still true, Windows mode bits never controlled read access. What+ changed is that :func:`restrict_path_to_owner` no longer gives up just+ because mode bits do not apply: it restricts the DACL instead, and+ :func:`verify_owner_only` confirms it by re-reading that DACL rather than+ trusting the call's own return value.+ """log_path = tmp_path / "proxy-18808.log"handler = _OwnerOnlyRotatingFileHandler(log_path, maxBytes=1024, backupCount=1, encoding="utf-8")handler.close()- assert log_path.exists(), "logging must keep working where hardening cannot"- assert fileperms.restrict_path_to_owner(log_path) is False+ assert log_path.exists(), "logging must keep working regardless of the ACL outcome"+ assert fileperms.restrict_path_to_owner(log_path) is True+ assert fileperms.verify_owner_only(log_path) is Truedef test_unsupported_platform_says_so_rather_than_silently_not_protecting(tmp_path, monkeypatch) -> None:- """Simulates the Windows path on any host, since CI cannot be both.-- A control that quietly does nothing on a supported platform is the thing- to avoid, so the operator is told once per process.+ """Covers the case where no protection mechanism works at all — mode bits+ don't apply (as on Windows) and, simulated here via ``verify_owner_only``,+ neither does the ACL call (a non-NTFS volume, a missing privilege). Runs+ on every platform: POSIX gets there because ``verify_owner_only`` is+ forced to report failure directly; Windows can get there for real.++ A control that quietly does nothing is the thing to avoid, so the+ operator is told once per process."""from headroom.proxy import helpers as _helpersmonkeypatch.setattr(fileperms, "OWNER_ONLY_SUPPORTED", False)+ monkeypatch.setattr(fileperms, "verify_owner_only", lambda path: False)monkeypatch.setattr(_helpers, "_owner_only_warning_emitted", False)monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))@@ -567,9 +702,9 @@ def test_unsupported_platform_says_so_rather_than_silently_not_protecting(handler.close()warnings = [r for r in records if r.levelno == logging.WARNING]- assert warnings, "the unsupported platform was not reported at all"+ assert warnings, "the unprotected file was not reported at all"message = warnings[0].getMessage()- assert "owner-only" in message+ assert "could not restrict" in messageassert "proxy-18809.log" in message# And only once per process, so it is a notice and not a per-worker flood.assert _helpers._owner_only_warning_emitted is True