Skip to content

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.

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.yml
index 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: changes
if: needs.changes.outputs.native == 'true'
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdx
index 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 not
conditional on which content switch is on. If the log path already exists as a
symlink, 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 the
runtime log on Linux/macOS. Run the collector as the same user, or copy the file
diff --git a/headroom/_fileperms_windows.py b/headroom/_fileperms_windows.py
new file mode 100644
index 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.py
index 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 a
symlink planted at the path fails the open outright rather than redirecting
the 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 = 0o600
OWNER_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 the
mode 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 False
def 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 backups
left 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 False
try:
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 True
except 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 False
def open_owner_only(
@@ -124,22 +177,43 @@ def open_owner_only(
Raises ``OSError`` — which every caller already treats as "logging is
unavailable, 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.py
index 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 = True
logger.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.py
index 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_only
def 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 True
def 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 _helpers
monkeypatch.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 message
assert "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