mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(security): restrict the Windows runtime log via NTFS ACL, not just warn (#4135)
## Description Windows never got the owner-only guarantee POSIX mode bits give the proxy log, its rotated backups, and the JSONL request log — `os.chmod` there only toggles the read-only attribute and leaves the real access control (the ACL) untouched. The prior fix (#3728) correctly scoped that gap and warned about it, but the warning text read as cryptic to at least one user (reported here and on Discord), and closing the gap was explicitly left as a follow-up pending a Windows CI runner to verify against. This implements that follow-up. Closes #4058 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] Documentation update ## Changes Made - `headroom/_fileperms_windows.py` (new): the NTFS ACL implementation via `ctypes` (no `pywin32` dependency) — a DACL with exactly one entry, the calling user with full control, built fresh rather than merged with the inherited entries that made the file readable in the first place, applied with `PROTECTED_DACL_SECURITY_INFORMATION` so those inherited entries are dropped. - `headroom/fileperms.py`: `restrict_fd_to_owner`/`restrict_path_to_owner` go through the new module on Windows instead of giving up immediately; added `verify_owner_only(path)`, which re-reads the actual DACL rather than trusting a static platform flag — the ACL call can fail for reasons unrelated to this code (a non-NTFS volume, a missing privilege). - `headroom/proxy/helpers.py`: the startup warning now fires only when `verify_owner_only` reports failure (not unconditionally on Windows), and the wording says plainly that other accounts may be able to read the file instead of the more technical original phrasing. - `tests/test_cache_breakpoint_diagnostics.py`: new Windows-specific tests exercising the ACL path directly (mirroring the existing POSIX mode-bit tests), plus updates to the two tests whose assumption ("Windows protection is impossible") this PR deliberately changes. - `docs/content/docs/proxy.mdx`: updated the "Who can read the logs" section to describe the ACL instead of "Headroom does not restrict the log file." - `.github/workflows/ci.yml`: added a `windows-file-permissions` job (same lightweight pattern as the existing `windows-tool-result-interceptors` job) so this is exercised on a real Windows runner going forward, addressing the maintainer's own "I'd want a Windows runner in CI first" from #3728's review thread. Deliberately **not** extended to the sqlite-backed memory/CCR stores (`ensure_private_file`/`connect_private_sqlite`) or `private_dir` — those remain unenforced on Windows, same as before this change, to keep this PR scoped to what #4058 is actually about. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality ### Test Output ```text $ pytest tests/test_cache_breakpoint_diagnostics.py tests/test_private_state_files.py tests/test_proxy_handler_helpers.py -q 99 passed, 49 skipped in 13.50s $ ruff check headroom/fileperms.py headroom/_fileperms_windows.py headroom/proxy/helpers.py tests/test_cache_breakpoint_diagnostics.py All checks passed! $ ruff format --check <same files> 4 files already formatted $ mypy headroom/fileperms.py headroom/_fileperms_windows.py --ignore-missing-imports --platform linux Found 1 error in 1 file (checked 2 source files) # that 1 error is in headroom/providers/model_metadata.py, pre-existing and # unrelated -- confirmed via `git stash` against main before these changes. $ actionlint .github/workflows/ci.yml # clean, no output ``` ## Real Behavior Proof - Environment: actual Windows 11 machine (not simulated/mocked) — this is the one part of #3728 the original author explicitly could not do ("I cannot execute or test on this machine") - Exact command / steps: created a file, called the new `restrict_handle`/`restrict_path`, then independently verified the result with `icacls <path>` (a separate tool, not my own code checking its own work) - Observed result: ``` C:\Users\...\Temp\acl_proto_test.txt LAPTOP-...\<user>:(F) Successfully processed 1 files; Failed processing 0 files ``` Exactly one ACE, granting the current user full control — no `Everyone`, no `Users`, no leftover inherited entries. Also ran the full `test_cache_breakpoint_diagnostics.py` suite on this same machine, including the new Windows-specific tests (`test_runtime_log_is_owner_only_via_acl_with_previews_off`, `test_rotated_backups_are_owner_only_via_acl`) which were previously impossible to exercise without a Windows box. - Not tested: a non-NTFS volume or a locked-down-privilege environment (the failure paths `verify_owner_only` is meant to catch) — those fall back to the warning, covered by the existing simulated test, but I don't have a non-NTFS Windows volume handy to exercise for real. ## Runtime Rollout Safety - Rollout-managed feature(s): N/A - Minimum rollout channel: N/A - Stable/default behavior changed: Only on Windows — the runtime log is now actually restricted instead of warned-about; POSIX behavior is unchanged. - Kill switch / disable path: None needed — this only adds protection where there was none; a failure falls back to the pre-existing warning-only behavior automatically via `verify_owner_only`. - Unsafe override required: No - Qualification impact: None - Rollback path: Revert; Windows returns to warn-only, same as before this PR. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes Scope boundary, stated explicitly rather than left implicit: this does not touch `ensure_private_file`/`connect_private_sqlite`/`private_dir`, which stay unenforced on Windows as before. Extending ACL protection there would be a reasonable follow-up but is a separate, larger piece of surface (sqlite main file + `-wal`/`-shm`/`-journal` sidecars) than what #4058 asked about. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4135" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
co-authored by
JerrettDavis
parent
2a70d12819
commit
125a703a65
@@ -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'
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
+114
-40
@@ -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.
|
||||
* **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 either, so the symlink protection
|
||||
there is the explicit :func:`is_symlink` check callers make before opening, not
|
||||
a kernel-enforced one.
|
||||
``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:
|
||||
|
||||
+24
-14
@@ -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.
|
||||
def _warn_once_if_not_protected(log_path: Path) -> None:
|
||||
"""Say plainly, once per process, when the file is not actually 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.
|
||||
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,
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -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.
|
||||
"""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 on a supported platform is the thing
|
||||
to avoid, so the operator is told once per process.
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user