mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 16:45:34 +08:00
## 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>
711 lines
28 KiB
Python
711 lines
28 KiB
Python
"""Tests for cache_control breakpoint diagnostics and log-privacy switches.
|
|
|
|
Covers the three pieces added for the uncached-tail investigation:
|
|
- ``count_cache_breakpoints`` / ``log_cache_breakpoints`` (proxy helpers)
|
|
- the ``HEADROOM_LOG_PAYLOAD_PREVIEW`` kill switch (compression store)
|
|
- the injection guard that keeps proactive expansion out of breakpointed blocks
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import os
|
|
import stat
|
|
from contextlib import contextmanager
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
from headroom import fileperms
|
|
from headroom import paths as _paths
|
|
from headroom.cache.compression_store import _payload_for_retrieval_log
|
|
from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
|
|
from headroom.proxy.helpers import (
|
|
_OwnerOnlyRotatingFileHandler,
|
|
count_cache_breakpoints,
|
|
log_cache_breakpoints,
|
|
)
|
|
|
|
_CC = {"cache_control": {"type": "ephemeral"}}
|
|
|
|
|
|
def _claude_code_style_request() -> tuple[list[dict], list[dict], list[dict]]:
|
|
"""System/messages/tools shaped like a real Claude Code request."""
|
|
system = [
|
|
{"type": "text", "text": "You are Claude Code."},
|
|
{"type": "text", "text": "project instructions", **_CC},
|
|
]
|
|
tools = [
|
|
{"name": "Bash", "input_schema": {}},
|
|
{"name": "Read", "input_schema": {}, **_CC},
|
|
]
|
|
messages = [
|
|
{"role": "user", "content": [{"type": "text", "text": "hi", **_CC}]},
|
|
{"role": "assistant", "content": [{"type": "text", "text": "ack"}]},
|
|
{
|
|
"role": "user",
|
|
"content": [
|
|
{
|
|
"type": "tool_result",
|
|
"tool_use_id": "t1",
|
|
"content": [{"type": "text", "text": "big output"}],
|
|
**_CC,
|
|
}
|
|
],
|
|
},
|
|
]
|
|
return system, messages, tools
|
|
|
|
|
|
def test_count_cache_breakpoints_counts_all_sections() -> None:
|
|
system, messages, tools = _claude_code_style_request()
|
|
stats = count_cache_breakpoints(system, messages, tools)
|
|
assert stats["system"] == 1
|
|
assert stats["tools"] == 1
|
|
assert stats["messages"] == 2
|
|
assert stats["total"] == 4
|
|
assert stats["message_count"] == 3
|
|
assert stats["last_marker_tail"] == 0 # last message carries a marker
|
|
|
|
|
|
def test_count_cache_breakpoints_counts_nested_tool_result_markers() -> None:
|
|
messages = [
|
|
{
|
|
"role": "user",
|
|
"content": [
|
|
{
|
|
"type": "tool_result",
|
|
"tool_use_id": "t1",
|
|
"content": [{"type": "text", "text": "out", **_CC}],
|
|
}
|
|
],
|
|
}
|
|
]
|
|
stats = count_cache_breakpoints("plain system string", messages, None)
|
|
assert stats["system"] == 0
|
|
assert stats["tools"] == 0
|
|
assert stats["messages"] == 1
|
|
assert stats["last_marker_tail"] == 0
|
|
|
|
|
|
def test_count_cache_breakpoints_tail_tracks_last_marker() -> None:
|
|
messages = [
|
|
{"role": "user", "content": [{"type": "text", "text": "a", **_CC}]},
|
|
{"role": "assistant", "content": [{"type": "text", "text": "b"}]},
|
|
{"role": "user", "content": [{"type": "text", "text": "c"}]},
|
|
]
|
|
stats = count_cache_breakpoints(None, messages, None)
|
|
assert stats["last_marker_tail"] == 2
|
|
assert count_cache_breakpoints(None, [], None)["last_marker_tail"] == -1
|
|
|
|
|
|
def test_log_cache_breakpoints_warns_on_dropped_marker(caplog) -> None:
|
|
system, messages, tools = _claude_code_style_request()
|
|
inbound = count_cache_breakpoints(system, messages, tools)
|
|
# Transform "lost" the final breakpoint: strip it from the last message.
|
|
stripped = [dict(m) for m in messages]
|
|
stripped[2] = {
|
|
"role": "user",
|
|
"content": [{"type": "tool_result", "tool_use_id": "t1", "content": "compressed"}],
|
|
}
|
|
outbound = count_cache_breakpoints(system, stripped, tools)
|
|
with caplog.at_level(logging.INFO, logger="headroom.proxy"):
|
|
log_cache_breakpoints(request_id="r1", inbound=inbound, outbound=outbound)
|
|
[record] = caplog.records
|
|
assert record.levelno == logging.WARNING
|
|
assert "dropped=true" in record.getMessage()
|
|
assert "tail_grew=true" in record.getMessage()
|
|
|
|
|
|
def test_log_cache_breakpoints_info_when_preserved(caplog) -> None:
|
|
system, messages, tools = _claude_code_style_request()
|
|
stats = count_cache_breakpoints(system, messages, tools)
|
|
with caplog.at_level(logging.INFO, logger="headroom.proxy"):
|
|
log_cache_breakpoints(request_id="r1", inbound=stats, outbound=stats)
|
|
[record] = caplog.records
|
|
assert record.levelno == logging.INFO
|
|
assert "dropped=false" in record.getMessage()
|
|
|
|
|
|
def test_payload_preview_disabled_omits_content(monkeypatch) -> None:
|
|
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", "0")
|
|
payload = "secret file contents: api_key=sk-abcdefghijklmnop"
|
|
event = _payload_for_retrieval_log(payload)
|
|
assert event["payload_preview"] == ""
|
|
assert event["payload_preview_chars"] == 0
|
|
assert event["payload_chars"] == len(payload)
|
|
assert event["payload_truncated"] is True
|
|
|
|
|
|
def test_payload_preview_disabled_by_default(monkeypatch) -> None:
|
|
"""Unset means off: the log gets byte counts, never the content."""
|
|
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
|
|
event = _payload_for_retrieval_log("hello world")
|
|
assert event["payload_preview"] == ""
|
|
assert event["payload_preview_chars"] == 0
|
|
assert event["payload_chars"] == len("hello world")
|
|
|
|
|
|
@pytest.mark.parametrize("value", ["1", "true", "TRUE", "yes", "on"])
|
|
def test_payload_preview_opt_in_values(monkeypatch, value: str) -> None:
|
|
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", value)
|
|
assert _payload_for_retrieval_log("hello world")["payload_preview"] == "hello world"
|
|
|
|
|
|
@pytest.mark.parametrize("value", ["", "0", "off", "no", "maybe", " "])
|
|
def test_payload_preview_stays_off_for_anything_else(monkeypatch, value: str) -> None:
|
|
"""Only an explicit opt-in turns previews on — a typo must not."""
|
|
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", value)
|
|
assert _payload_for_retrieval_log("hello world")["payload_preview"] == ""
|
|
|
|
|
|
def test_append_context_skips_breakpointed_text_block() -> None:
|
|
messages = [
|
|
{
|
|
"role": "user",
|
|
"content": [
|
|
{"type": "text", "text": "breakpointed", **_CC},
|
|
{"type": "text", "text": "free"},
|
|
],
|
|
}
|
|
]
|
|
result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
|
|
messages, "CTX", frozen_message_count=0
|
|
)
|
|
blocks = result[0]["content"]
|
|
assert blocks[0]["text"] == "breakpointed" # untouched
|
|
assert blocks[1]["text"].endswith("CTX")
|
|
|
|
|
|
def test_append_context_no_eligible_block_returns_unchanged() -> None:
|
|
messages = [
|
|
{
|
|
"role": "user",
|
|
"content": [{"type": "text", "text": "breakpointed", **_CC}],
|
|
}
|
|
]
|
|
result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
|
|
messages, "CTX", frozen_message_count=0
|
|
)
|
|
assert result == messages
|
|
|
|
|
|
def test_count_cache_breakpoints_tolerates_malformed_shapes() -> None:
|
|
messages = [
|
|
"not-a-dict",
|
|
{"role": "user", "content": ["scalar-block", {"type": "text", "text": "x", **_CC}]},
|
|
{"role": "user", "content": "plain string"},
|
|
]
|
|
stats = count_cache_breakpoints("system-as-string", messages, "tools-as-string")
|
|
assert stats["system"] == 0
|
|
assert stats["tools"] == 0
|
|
assert stats["messages"] == 1
|
|
assert stats["message_count"] == 3
|
|
assert stats["last_marker_tail"] == 1
|
|
|
|
empty = count_cache_breakpoints(None, None, None)
|
|
assert empty["total"] == 0
|
|
assert empty["message_count"] == 0
|
|
|
|
|
|
# --- the runtime log file itself -------------------------------------------
|
|
#
|
|
# _payload_for_retrieval_log decides what goes into the record;
|
|
# _setup_file_logging decides who can read the file it lands in. Both halves
|
|
# of the default-off guarantee are checked against a real log on disk.
|
|
|
|
|
|
@contextmanager
|
|
def _proxy_log(tmp_path, monkeypatch, port: int):
|
|
"""Point the workspace at *tmp_path*, install the real proxy log handler."""
|
|
from headroom.proxy.helpers import _PROXY_LOG_HANDLER_NAME, _setup_file_logging
|
|
|
|
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
|
|
headroom_logger = logging.getLogger("headroom")
|
|
before = list(headroom_logger.handlers)
|
|
propagate = headroom_logger.propagate
|
|
try:
|
|
_setup_file_logging(port)
|
|
[handler] = [h for h in headroom_logger.handlers if h.name == _PROXY_LOG_HANDLER_NAME]
|
|
yield Path(handler.baseFilename)
|
|
finally:
|
|
for handler in list(headroom_logger.handlers):
|
|
if handler not in before:
|
|
headroom_logger.removeHandler(handler)
|
|
handler.close()
|
|
headroom_logger.propagate = propagate
|
|
|
|
|
|
def test_runtime_log_holds_no_payload_text_at_default_settings(tmp_path, monkeypatch) -> None:
|
|
"""A retrieval on default settings leaves byte counts in the log, not content."""
|
|
from headroom.cache.compression_store import CompressionStore
|
|
|
|
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
|
|
secret = "BEGIN-CUSTOMER-DATA ssn=123-45-6789 def sekrit(): pass END-CUSTOMER-DATA"
|
|
|
|
with _proxy_log(tmp_path, monkeypatch, 18801) as log_path:
|
|
store = CompressionStore(enable_feedback=False)
|
|
assert store.retrieve(store.store(original=secret, compressed="[compressed]")) is not None
|
|
logging.getLogger("headroom").handlers[-1].flush()
|
|
text = log_path.read_text(encoding="utf-8")
|
|
|
|
assert "event=headroom_retrieve" in text, "the retrieval was not logged at all"
|
|
assert secret not in text
|
|
assert "123-45-6789" not in text
|
|
assert f'"payload_chars":{len(secret)}' in text
|
|
assert '"payload_preview":""' in text
|
|
|
|
|
|
_posix_only = pytest.mark.skipif(
|
|
not fileperms.OWNER_ONLY_SUPPORTED,
|
|
reason=(
|
|
"asserts POSIX mode bits, which do not control read access on this platform; "
|
|
"the scope of the guarantee is asserted instead by "
|
|
"test_owner_only_support_matches_what_the_platform_can_enforce and "
|
|
"test_no_owner_only_claim_is_made_off_posix"
|
|
),
|
|
)
|
|
|
|
|
|
@pytest.fixture
|
|
def predictable_umask():
|
|
"""Pin the umask so "would have been world-readable" is not luck.
|
|
|
|
Without this the fail-before evidence for these tests depends on whatever
|
|
umask the runner happens to have; 0o022 is the stock developer value that
|
|
makes an unhardened log 0644.
|
|
"""
|
|
previous = os.umask(0o022)
|
|
try:
|
|
yield
|
|
finally:
|
|
os.umask(previous)
|
|
|
|
|
|
@_posix_only
|
|
def test_runtime_log_is_owner_only_with_previews_off(
|
|
tmp_path, monkeypatch, predictable_umask
|
|
) -> None:
|
|
"""The file's permissions are not keyed off the payload-preview switch.
|
|
|
|
Previews are one of several sources of request content in this file:
|
|
``--log-messages`` bodies, wire-debug dumps and query logging land here
|
|
too, each behind its own switch. Hardening only when previews are on left
|
|
every other combination creating a sensitive log at the umask.
|
|
"""
|
|
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
|
|
with _proxy_log(tmp_path, monkeypatch, 18804) as log_path:
|
|
assert log_path.exists()
|
|
assert stat.S_IMODE(log_path.stat().st_mode) == 0o600
|
|
|
|
|
|
@_posix_only
|
|
def test_runtime_log_is_owner_only_when_preview_enabled(tmp_path, monkeypatch) -> None:
|
|
"""Opting in to previews hardens the log the previews land in."""
|
|
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", "1")
|
|
with _proxy_log(tmp_path, monkeypatch, 18802) as log_path:
|
|
assert log_path.exists()
|
|
assert stat.S_IMODE(log_path.stat().st_mode) == 0o600
|
|
|
|
|
|
@_posix_only
|
|
def test_runtime_log_hardening_survives_a_pre_existing_world_readable_log(
|
|
tmp_path, monkeypatch, predictable_umask
|
|
) -> None:
|
|
"""O_CREAT's mode does not apply to an existing file; the fchmod must."""
|
|
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
|
|
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
|
|
stale = _paths.proxy_log_path(18803)
|
|
stale.parent.mkdir(parents=True, exist_ok=True)
|
|
stale.write_text("from an older, unhardened run\n", encoding="utf-8")
|
|
stale.chmod(0o644)
|
|
|
|
with _proxy_log(tmp_path, monkeypatch, 18803) as log_path:
|
|
assert stat.S_IMODE(log_path.stat().st_mode) == 0o600
|
|
|
|
|
|
@_posix_only
|
|
def test_rotated_backups_are_owner_only(tmp_path, monkeypatch, predictable_umask) -> None:
|
|
"""Rotation must not launder the mode away.
|
|
|
|
``doRollover`` renames the base file and opens a fresh one; a backup that
|
|
ends up 0644 exposes exactly the content the base file was protecting, and
|
|
keeps exposing it for ``backupCount`` rotations. Exercised through the real
|
|
handler the proxy installs (with ``maxBytes`` shrunk so a rollover is
|
|
reachable in a test), not a hand-built one, so the handler *selection* is
|
|
part of what is asserted.
|
|
"""
|
|
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
|
|
with _proxy_log(tmp_path, monkeypatch, 18805) 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 stat.S_IMODE(path.stat().st_mode) == 0o600, path
|
|
|
|
|
|
@_posix_only
|
|
def test_pre_existing_backups_are_tightened_when_the_handler_opens(
|
|
tmp_path, predictable_umask
|
|
) -> None:
|
|
"""Backups written by an older, unhardened build are still on disk."""
|
|
log_path = tmp_path / "proxy-18806.log"
|
|
stale = tmp_path / "proxy-18806.log.2"
|
|
stale.write_text("payload from before the fix\n", encoding="utf-8")
|
|
stale.chmod(0o644)
|
|
|
|
handler = _OwnerOnlyRotatingFileHandler(
|
|
log_path, maxBytes=1024, backupCount=5, encoding="utf-8"
|
|
)
|
|
handler.close()
|
|
|
|
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",
|
|
)
|
|
def test_runtime_log_refuses_a_symlinked_path(tmp_path, monkeypatch) -> None:
|
|
"""A planted symlink must not redirect the log — or the mode we set on it."""
|
|
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(18807)
|
|
log_path.parent.mkdir(parents=True, exist_ok=True)
|
|
elsewhere = tmp_path / "attacker-readable.log"
|
|
elsewhere.write_text("", encoding="utf-8")
|
|
elsewhere.chmod(0o666)
|
|
log_path.symlink_to(elsewhere)
|
|
|
|
headroom_logger = logging.getLogger("headroom")
|
|
before = list(headroom_logger.handlers)
|
|
try:
|
|
_setup_file_logging(18807)
|
|
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") == ""
|
|
assert stat.S_IMODE(elsewhere.stat().st_mode) == 0o666, "the symlink target was chmodded"
|
|
|
|
|
|
class _ListHandler(logging.Handler):
|
|
def __init__(self) -> None:
|
|
super().__init__(logging.DEBUG)
|
|
self.records: list[logging.LogRecord] = []
|
|
|
|
def emit(self, record: logging.LogRecord) -> None:
|
|
self.records.append(record)
|
|
|
|
|
|
def _runtime_log_warnings(port: int) -> list[str]:
|
|
"""Run ``_setup_file_logging`` and return the 'runtime log disabled' warnings.
|
|
|
|
The handler sits on ``headroom.proxy`` directly: caplog does not see
|
|
``headroom.*`` records once a proxy app has configured logging.
|
|
"""
|
|
from headroom.proxy.helpers import _setup_file_logging
|
|
|
|
proxy_logger = logging.getLogger("headroom.proxy")
|
|
headroom_logger = logging.getLogger("headroom")
|
|
before = list(headroom_logger.handlers)
|
|
capture = _ListHandler()
|
|
proxy_logger.addHandler(capture)
|
|
try:
|
|
_setup_file_logging(port)
|
|
finally:
|
|
proxy_logger.removeHandler(capture)
|
|
for handler in list(headroom_logger.handlers):
|
|
if handler not in before:
|
|
headroom_logger.removeHandler(handler)
|
|
handler.close()
|
|
return [
|
|
r.getMessage()
|
|
for r in capture.records
|
|
if r.levelno == logging.WARNING and "runtime log disabled" in r.getMessage()
|
|
]
|
|
|
|
|
|
def test_runtime_log_says_why_it_is_missing(tmp_path, monkeypatch) -> None:
|
|
"""An unwritable log directory used to disable proxy.log without a word."""
|
|
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
|
|
# A regular file where the logs directory belongs: mkdir raises OSError.
|
|
_paths.log_dir().write_text("", encoding="utf-8")
|
|
|
|
warnings = _runtime_log_warnings(18808)
|
|
|
|
assert len(warnings) == 1
|
|
assert str(_paths.log_dir()) in warnings[0]
|
|
assert "HEADROOM_WORKSPACE_DIR" in warnings[0]
|
|
|
|
|
|
def test_runtime_log_stays_quiet_when_writable(tmp_path, monkeypatch) -> None:
|
|
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
|
|
|
|
assert _runtime_log_warnings(18809) == []
|
|
assert _paths.proxy_log_path(18809).exists()
|
|
|
|
|
|
@pytest.mark.skipif(
|
|
os.name != "posix",
|
|
reason="creating a symlink needs elevation on Windows, and O_NOFOLLOW does not exist there",
|
|
)
|
|
def test_open_owner_only_fails_closed_on_a_symlink(tmp_path) -> None:
|
|
"""The kernel-enforced half of the same refusal, at the open() itself."""
|
|
target = tmp_path / "target"
|
|
target.write_text("", encoding="utf-8")
|
|
link = tmp_path / "link"
|
|
link.symlink_to(target)
|
|
|
|
with pytest.raises(OSError):
|
|
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."""
|
|
from headroom.proxy.models import RequestLog
|
|
from headroom.proxy.request_logger import RequestLogger
|
|
|
|
log_file = tmp_path / "requests.jsonl"
|
|
entry = RequestLog(
|
|
request_id="r1",
|
|
timestamp="2026-09-23T00:00:00Z",
|
|
provider="anthropic",
|
|
model="claude-opus-4-20250514",
|
|
input_tokens_original=10,
|
|
input_tokens_optimized=8,
|
|
output_tokens=2,
|
|
tokens_saved=2,
|
|
savings_percent=20.0,
|
|
optimization_latency_ms=1.0,
|
|
total_latency_ms=2.0,
|
|
tags={},
|
|
cache_hit=False,
|
|
transforms_applied=[],
|
|
request_messages=[{"role": "user", "content": "ssn=123-45-6789"}],
|
|
)
|
|
RequestLogger(log_file=str(log_file), log_full_messages=True).log(entry)
|
|
|
|
assert "123-45-6789" in log_file.read_text(encoding="utf-8")
|
|
assert stat.S_IMODE(log_file.stat().st_mode) == 0o600
|
|
|
|
|
|
# --- what the guarantee is, and is not, on Windows -------------------------
|
|
|
|
|
|
def test_owner_only_support_matches_what_the_platform_can_enforce() -> None:
|
|
"""The scope is a value in the code, not a claim in a comment.
|
|
|
|
POSIX mode bits decide read access; on Windows an NTFS ACL does, and
|
|
``os.chmod`` there only flips the read-only attribute — a
|
|
``chmod(0o600)`` succeeds while ``stat.S_IMODE`` still reports ``0666``.
|
|
Python ships no ACL API, so Headroom reports that it cannot make the
|
|
promise instead of making it and not keeping it.
|
|
"""
|
|
assert fileperms.OWNER_ONLY_SUPPORTED is (os.name == "posix")
|
|
|
|
|
|
@pytest.mark.skipif(
|
|
fileperms.OWNER_ONLY_SUPPORTED,
|
|
reason="exercises the non-mode-bits path; only meaningful off POSIX",
|
|
)
|
|
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 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:
|
|
"""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))
|
|
|
|
records: list[logging.LogRecord] = []
|
|
sink = logging.Handler()
|
|
sink.emit = records.append # type: ignore[method-assign]
|
|
emitter = logging.getLogger(_helpers.logger.name)
|
|
emitter.addHandler(sink)
|
|
headroom_logger = logging.getLogger("headroom")
|
|
before = list(headroom_logger.handlers)
|
|
try:
|
|
_helpers._setup_file_logging(18809)
|
|
finally:
|
|
emitter.removeHandler(sink)
|
|
for handler in list(headroom_logger.handlers):
|
|
if handler not in before:
|
|
headroom_logger.removeHandler(handler)
|
|
handler.close()
|
|
|
|
warnings = [r for r in records if r.levelno == logging.WARNING]
|
|
assert warnings, "the unprotected file was not reported at all"
|
|
message = warnings[0].getMessage()
|
|
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
|