fix(mcp): confine headroom_read to the workspace (GHSA-8g49-pg6g-xgrf) (#4525)

## Description

Fixes the arbitrary file read in the opt-in `headroom_read` MCP tool
tracked in draft advisory GHSA-8g49-pg6g-xgrf and reported externally in
#3310.

`headroom_read` resolved the supplied path with
`Path(file_path).expanduser().resolve()` and no boundary, so an agent
with the tool enabled (`HEADROOM_MCP_READ=on`) could read any file the
process could, including `~/.ssh` and `.env` files. This change confines
reads to the workspace root and refuses everything outside it with one
uniform error.

Supersedes #3310, whose approach added `~/.headroom` (credentials and
state) to the allowed roots; this one does not.

## Type of Change

- [x] Bug fix (security)

## Changes Made

- `headroom/ccr/mcp_server.py`: resolve the requested path and require
it to be inside a read root (the working directory, or
`HEADROOM_MCP_READ_ROOTS`). Anything outside, including `..`, symlinks
that escape, unresolvable paths and missing files outside the roots,
gets the same "outside the workspace" error so the tool is not an
existence oracle. Inside the roots a missing path answers "File not
found" and a directory "Not a file", as before.
- No default read root at `/` or `$HOME`: when the server is launched
from either (GUI hosts do) nothing is readable until roots are
configured.
- Open-time re-check (review finding): the check and the open were
separate steps, so a directory swapped for a symlink in between was
followed. `_open_within` now walks the resolved relative path from a
descriptor on the root one component at a time with `O_NOFOLLOW` and
reads from the descriptor it opened; a component that became a symlink
is refused (ELOOP) and reported as outside the workspace. Without openat
semantics (Windows) it opens directly and confirms the path still
resolves to what was checked.
- `tests/test_ccr_mcp_server.py`: inside-workspace reads, absolute,
`..`, symlink, symlinked directory, sibling-prefix, missing and
symlink-loop paths, root and home launch directories (patching
`Path.home()`, which is what Windows needs), configured roots, and the
directory-swap race.
- `tests/test_ccr_redis_backend.py`: the Redis-outage read test allows
its `tmp_path` via `HEADROOM_MCP_READ_ROOTS`, keeping its outage and
recovery assertions.

## Testing

- [x] `pytest tests/test_ccr_mcp_server.py
tests/test_ccr_redis_backend.py -k "not redis_fails and not
proxy_starts"`: 52 passed (the deselected tests need a live proxy and
fail identically on `main` locally)
- [x] `ruff check` and `ruff format --check` on the changed files: clean
- [x] `mypy headroom/ccr/mcp_server.py`: no issues

## Real Behavior Proof

- Environment: macOS 27.2 arm64, repo venv (CPython 3.14), branch on top
of `main` at 3c6f82b0
- Exact command / steps: `pytest -q tests/test_ccr_mcp_server.py
tests/test_ccr_redis_backend.py -k "not redis_fails and not
proxy_starts"`; `ruff check headroom/ccr/mcp_server.py
tests/test_ccr_mcp_server.py`; `mypy headroom/ccr/mcp_server.py
--ignore-missing-imports`
- Observed result: 52 passed in 2.34s; All checks passed; Success: no
issues found in 1 source file. The swap test injects the
directory-to-symlink swap between the boundary check and the open and
gets `File is outside the workspace`, with nothing cached; with
`O_DIRECTORY` in the walk macOS reported the swap as `File not found`,
which is why intermediates are opened with `O_NOFOLLOW` alone and
checked with `S_ISDIR`.
- Not tested: a live MCP client session against the running server; the
Windows fallback path beyond unit tests on macOS

## Runtime Rollout Safety

- Rollout-managed feature(s): none; `headroom_read` stays behind
`HEADROOM_MCP_READ=on`
- Stable/default behavior changed: reads outside the workspace root are
refused where they were previously served
- Kill switch / disable path: `HEADROOM_MCP_READ=off` (the default)
- Rollback path: revert the PR

Closes #3310

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
Tejas Chopra
2026-11-03 09:02:52 +05:30
committed by GitHub
co-authored by Claude Opus 5.5 JerrettDavis
parent ddeb13dca7
commit 8ab2e91468
3 changed files with 350 additions and 25 deletions
+139 -22
View File
@@ -25,9 +25,11 @@ from __future__ import annotations
import argparse
import asyncio
import contextlib
import errno
import json
import logging
import os
import stat
import time
from dataclasses import dataclass, field
from pathlib import Path
@@ -83,7 +85,8 @@ READ_TOOL_NAME = "headroom_read"
logger = logging.getLogger("headroom.ccr.mcp")
# Feature flag: enable headroom_read tool (file read caching via CCR)
# Set HEADROOM_MCP_READ=on to enable
# Set HEADROOM_MCP_READ=on to enable. Reads are confined to the server's working
# directory, or to the os.pathsep-separated directories in HEADROOM_MCP_READ_ROOTS.
_READ_ENABLED = os.environ.get("HEADROOM_MCP_READ", "off").lower().strip() in (
"on",
"true",
@@ -376,6 +379,73 @@ class SessionStats:
}
def _read_roots() -> list[Path]:
"""Directories ``headroom_read`` may read under, resolved like the paths checked against them.
Without HEADROOM_MCP_READ_ROOTS the root is the working directory, unless
that is the filesystem root or the home directory (GUI hosts such as
Claude Desktop launch MCP servers from ``/``): then nothing is readable
until roots are configured.
"""
configured = os.environ.get("HEADROOM_MCP_READ_ROOTS", "")
entries = [entry.strip() for entry in configured.split(os.pathsep) if entry.strip()]
if entries:
return [Path(entry).expanduser().resolve() for entry in entries]
cwd = Path.cwd().resolve()
if cwd == Path(cwd.anchor) or cwd == Path.home().resolve():
return []
return [cwd]
_O_CLOEXEC = getattr(os, "O_CLOEXEC", 0)
_O_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
def _open_nofollow(path: Path) -> int:
"""Open the resolved ``path`` for reading without following any symlink.
The boundary check and the open are separate steps. ``path`` had no
symlinks when it was resolved, but any component -- the file, a directory
on the way, the permitted root itself or one of its parents -- can have
been replaced by a symlink since, and a plain ``open()`` would follow it
wherever it points. So walk the whole path from its anchor one component
at a time with O_NOFOLLOW: a component that has become a symlink is
refused (ELOOP) rather than followed. Opens are non-blocking so a FIFO
put in the way cannot stall the event loop; the caller's S_ISREG check
rejects it, and a regular file reads the same either way.
Without openat semantics (Windows) open directly and confirm the path
still resolves to what was checked; best effort there.
"""
if os.open not in os.supports_dir_fd or not hasattr(os, "O_NOFOLLOW"):
fd = os.open(path, os.O_RDONLY | getattr(os, "O_BINARY", 0) | _O_CLOEXEC)
if path.resolve() != path:
os.close(fd)
raise OSError(errno.ELOOP, "path changed between check and open", str(path))
return fd
import fcntl
flags = os.O_RDONLY | os.O_NOFOLLOW | _O_NONBLOCK | _O_CLOEXEC
parts = path.parts
fd = os.open(parts[0], os.O_RDONLY | os.O_DIRECTORY | _O_CLOEXEC)
try:
for part in parts[1:-1]:
next_fd = os.open(part, flags, dir_fd=fd)
os.close(fd)
fd = next_fd
# S_ISDIR here rather than O_DIRECTORY on the open: with both
# flags macOS reports a symlink as ENOTDIR, which would make a
# swapped component look like a missing file instead of a refusal.
if not stat.S_ISDIR(os.fstat(fd).st_mode):
raise NotADirectoryError(errno.ENOTDIR, "Not a directory", str(path))
file_fd = os.open(parts[-1] if len(parts) > 1 else ".", flags, dir_fd=fd)
finally:
os.close(fd)
if _O_NONBLOCK:
fcntl.fcntl(file_fd, fcntl.F_SETFL, fcntl.fcntl(file_fd, fcntl.F_GETFL) & ~_O_NONBLOCK)
return file_fd
class HeadroomMCPServer:
"""MCP Server exposing Headroom's context engineering toolkit.
@@ -750,7 +820,10 @@ class HeadroomMCPServer:
"properties": {
"file_path": {
"type": "string",
"description": "Absolute path to the file to read.",
"description": (
"Path to the file to read, inside the workspace "
"(the server's working directory or HEADROOM_MCP_READ_ROOTS)."
),
},
"fresh": {
"type": "boolean",
@@ -1027,38 +1100,82 @@ class HeadroomMCPServer:
)
]
path = Path(file_path).expanduser().resolve()
if not path.exists():
# Check the resolved path, so `..` and symlinks cannot leave the roots,
# and check it before exists() so the tool is not an existence oracle.
# A path that cannot be resolved (symlink loop, NUL byte) gets the same
# answer, so its error text cannot reveal anything outside either.
def outside() -> list[TextContent]:
return [
TextContent(
type="text",
text=json.dumps(
{
"error": (
f"File is outside the workspace: {file_path}. "
"Ask the user to add its directory to HEADROOM_MCP_READ_ROOTS."
)
}
),
)
]
try:
path: Path | None = Path(file_path).expanduser().resolve()
except (OSError, RuntimeError, ValueError):
path = None
root = (
None
if path is None
else next((r for r in _read_roots() if path.is_relative_to(r)), None)
)
if path is None or root is None:
return outside()
# Open without following symlinks, so a component swapped for one
# after the check above is refused rather than followed (see
# _open_nofollow). Inside the roots, a missing path and a directory
# keep their specific answers.
fd = -1
try:
fd = _open_nofollow(path)
if not stat.S_ISREG(os.fstat(fd).st_mode):
return [
TextContent(
type="text",
text=json.dumps({"error": f"Not a file: {file_path}"}),
)
]
handle = os.fdopen(fd, "rb")
fd = -1
with handle:
raw = handle.read()
except (FileNotFoundError, NotADirectoryError):
return [
TextContent(
type="text",
text=json.dumps({"error": f"File not found: {file_path}"}),
)
]
if not path.is_file():
return [
TextContent(
type="text",
text=json.dumps({"error": f"Not a file: {file_path}"}),
)
]
# Read file from disk. PR-A8 / P1-8: avoid lossy decode kwargs
# in headroom/ccr/ — use the centralized safe-log decoder so
# the project-wide grep stays clean (this path is for tool
# output display, not SSE/wire path, so a replacement char on
# invalid bytes is acceptable).
try:
from headroom.proxy.helpers import safe_decode_for_logging
content = safe_decode_for_logging(path.read_bytes())
except Exception as e:
except OSError as e:
if e.errno == errno.ELOOP:
return outside()
return [
TextContent(
type="text",
text=json.dumps({"error": f"Cannot read file: {e}"}),
)
]
finally:
if fd != -1:
os.close(fd)
# PR-A8 / P1-8: avoid lossy decode kwargs in headroom/ccr/ — use the
# centralized safe-log decoder so the project-wide grep stays clean
# (this path is for tool output display, not SSE/wire path, so a
# replacement char on invalid bytes is acceptable).
from headroom.proxy.helpers import safe_decode_for_logging
content = safe_decode_for_logging(raw)
content_hash = hashlib.sha256(content.encode()).hexdigest()[:24]
line_count = content.count("\n") + (1 if content and not content.endswith("\n") else 0)
+205 -2
View File
@@ -5,6 +5,8 @@ import contextlib
import http.server
import json
import logging
import os
import shutil
import threading
import pytest
@@ -110,11 +112,12 @@ def _compact_json(tmp_path):
return path
def test_read_tool_prices_files_in_tokens_not_words(fresh_store, tmp_path) -> None:
def test_read_tool_prices_files_in_tokens_not_words(fresh_store, tmp_path, monkeypatch) -> None:
"""``headroom_read`` caches a token estimate and stores it as the entry's
``original_tokens``. It used to be ``len(content.split())`` — a word count
in a token field, which is 1 for a single-line JSON document that is
thousands of tokens long."""
monkeypatch.chdir(tmp_path)
path = _compact_json(tmp_path)
content = path.read_text(encoding="utf-8")
server = mcp_server.HeadroomMCPServer(check_proxy=False)
@@ -126,9 +129,10 @@ def test_read_tool_prices_files_in_tokens_not_words(fresh_store, tmp_path) -> No
assert estimated > len(content.split())
def test_read_tool_cache_note_reports_tokens(fresh_store, tmp_path) -> None:
def test_read_tool_cache_note_reports_tokens(fresh_store, tmp_path, monkeypatch) -> None:
"""The 'already in your context' note is read by the agent to decide whether
to re-read the file, so its ``~N tokens`` figure has to be a token count."""
monkeypatch.chdir(tmp_path)
path = _compact_json(tmp_path)
content = path.read_text(encoding="utf-8")
server = mcp_server.HeadroomMCPServer(check_proxy=False)
@@ -141,6 +145,205 @@ def test_read_tool_cache_note_reports_tokens(fresh_store, tmp_path) -> None:
assert f"~{EstimatingTokenCounter().count_text(content)} tokens" in payload["note"]
# --- headroom_read workspace boundary (GHSA-8g49-pg6g-xgrf) -----------------
# headroom_read is offered to the agent "INSTEAD of the built-in Read tool", so
# it must not read where the harness's own Read rules would not: it reads only
# under the server's working directory or HEADROOM_MCP_READ_ROOTS.
@pytest.fixture
def workspace_and_secret(tmp_path, monkeypatch):
workspace = tmp_path / "workspace"
private = tmp_path / "private"
workspace.mkdir()
private.mkdir()
secret = private / "secret.txt"
secret.write_text("TOP_SECRET\n", encoding="utf-8")
(workspace / "notes.txt").write_text("hello\n", encoding="utf-8")
monkeypatch.chdir(workspace)
monkeypatch.delenv("HEADROOM_MCP_READ_ROOTS", raising=False)
return workspace, secret
def _read_text(server, file_path: str) -> str:
return asyncio.run(server._handle_read({"file_path": file_path, "fresh": True}))[0].kwargs[
"text"
]
@pytest.mark.parametrize(
"how", ["absolute", "dotdot", "symlink", "symlinked_dir", "sibling_prefix", "missing", "loop"]
)
def test_read_tool_refuses_files_outside_the_workspace(
fresh_store, workspace_and_secret, how
) -> None:
workspace, secret = workspace_and_secret
if how == "absolute":
file_path = str(secret)
elif how == "dotdot":
file_path = "../private/secret.txt"
elif how == "symlink":
(workspace / "link.txt").symlink_to(secret)
file_path = str(workspace / "link.txt")
elif how == "symlinked_dir":
(workspace / "d").symlink_to(secret.parent)
file_path = "d/secret.txt"
elif how == "sibling_prefix":
# Same leading characters as the workspace, but a different directory.
sibling = workspace.parent / (workspace.name + "-evil")
sibling.mkdir()
(sibling / "secret.txt").write_text("TOP_SECRET\n", encoding="utf-8")
file_path = str(sibling / "secret.txt")
elif how == "missing":
# Same answer as for a file that exists: no existence oracle.
file_path = str(secret.parent / "does-not-exist.txt")
else:
loop = secret.parent / "loop"
loop.symlink_to(loop)
file_path = str(loop)
server = mcp_server.HeadroomMCPServer(check_proxy=False)
text = _read_text(server, file_path)
assert "TOP_SECRET" not in text
assert "outside the workspace" in json.loads(text)["error"]
assert server._file_cache == {}
@pytest.mark.parametrize("start_in", ["filesystem_root", "home"])
def test_read_tool_reads_nothing_from_root_or_home_without_roots(
fresh_store, workspace_and_secret, monkeypatch, start_in
) -> None:
# GUI hosts launch MCP servers from `/`; a working-directory root there
# (or in $HOME) would cover ~/.ssh and everything else.
_, secret = workspace_and_secret
# Path.home(), not $HOME: Windows reads USERPROFILE, so only the former
# makes this directory the process home on every platform.
monkeypatch.setattr(mcp_server.Path, "home", lambda: secret.parent)
monkeypatch.chdir(secret.parent if start_in == "home" else secret.anchor)
server = mcp_server.HeadroomMCPServer(check_proxy=False)
text = _read_text(server, str(secret))
assert "TOP_SECRET" not in text
assert "HEADROOM_MCP_READ_ROOTS" in json.loads(text)["error"]
def _swap_before_open(monkeypatch, swap) -> None:
"""Run ``swap`` between the boundary check and the open, as a racing writer would."""
real_open = mcp_server._open_nofollow
def swap_then_open(path):
swap()
return real_open(path)
monkeypatch.setattr(mcp_server, "_open_nofollow", swap_then_open)
def _read_text_promptly(server, file_path: str, fifo) -> str:
# A FIFO put in the way must not block the open. If the read is stuck,
# open the FIFO for writing to release it, then fail: the test ends in
# bounded time either way and leaves no worker thread behind.
result: list[str] = []
worker = threading.Thread(target=lambda: result.append(_read_text(server, file_path)))
worker.start()
worker.join(timeout=5)
if worker.is_alive():
with contextlib.suppress(OSError):
os.close(os.open(fifo, os.O_WRONLY | os.O_NONBLOCK))
worker.join(timeout=5)
pytest.fail(f"headroom_read blocked on the FIFO at {fifo}")
return result[0]
@pytest.mark.parametrize("replaced", ["directory", "root"])
def test_read_tool_refuses_a_symlink_swapped_in_after_the_check(
fresh_store, workspace_and_secret, monkeypatch, replaced
) -> None:
# The boundary check and the open are separate steps. If a directory on
# the way, or the permitted root itself, is replaced by a symlink in
# between, the open must refuse it rather than follow it out.
workspace, secret = workspace_and_secret
(workspace / "data").mkdir()
(workspace / "data" / "report.txt").write_text("PUBLIC\n", encoding="utf-8")
(secret.parent / "report.txt").write_text("OUTSIDE_SECRET\n", encoding="utf-8")
if replaced == "directory":
file_path = "data/report.txt"
def swap():
shutil.rmtree(workspace / "data")
(workspace / "data").symlink_to(secret.parent)
else:
# Configure the workspace as a root instead of working in it: Windows
# cannot rename the process's working directory.
monkeypatch.setenv("HEADROOM_MCP_READ_ROOTS", str(workspace))
monkeypatch.chdir(workspace.parent)
(workspace / "report.txt").write_text("PUBLIC\n", encoding="utf-8")
file_path = str(workspace / "report.txt")
def swap():
workspace.rename(workspace.parent / "moved-away")
workspace.symlink_to(secret.parent, target_is_directory=True)
_swap_before_open(monkeypatch, swap)
server = mcp_server.HeadroomMCPServer(check_proxy=False)
text = _read_text(server, file_path)
assert "OUTSIDE_SECRET" not in text
assert "outside the workspace" in json.loads(text)["error"]
assert server._file_cache == {}
@pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="named pipes are POSIX")
@pytest.mark.parametrize("where", ["target", "directory"])
def test_read_tool_does_not_block_on_a_fifo(
fresh_store, workspace_and_secret, monkeypatch, where
) -> None:
# Opening a FIFO for reading blocks until a writer appears; the read tool
# runs on the MCP event loop, so it must refuse one without waiting.
workspace, _ = workspace_and_secret
if where == "target":
fifo = workspace / "pipe"
os.mkfifo(fifo)
file_path = "pipe"
else:
(workspace / "data").mkdir()
(workspace / "data" / "report.txt").write_text("PUBLIC\n", encoding="utf-8")
file_path = "data/report.txt"
fifo = workspace / "data"
def swap():
shutil.rmtree(fifo)
os.mkfifo(fifo)
_swap_before_open(monkeypatch, swap)
server = mcp_server.HeadroomMCPServer(check_proxy=False)
text = _read_text_promptly(server, file_path, fifo)
assert "PUBLIC" not in text
assert json.loads(text)["error"].startswith(("Not a file", "File not found"))
assert server._file_cache == {}
def test_read_tool_reads_inside_the_workspace(fresh_store, workspace_and_secret) -> None:
server = mcp_server.HeadroomMCPServer(check_proxy=False)
assert "hello" in _read_text(server, "notes.txt")
def test_read_tool_reads_under_configured_roots(
fresh_store, workspace_and_secret, monkeypatch
) -> None:
_, secret = workspace_and_secret
monkeypatch.setenv("HEADROOM_MCP_READ_ROOTS", str(secret.parent))
server = mcp_server.HeadroomMCPServer(check_proxy=False)
assert "TOP_SECRET" in _read_text(server, str(secret))
assert "outside the workspace" in _read_text(server, "notes.txt")
def test_mcp_compress_surfaces_unreachable_proxy(fresh_store) -> None:
server = mcp_server.HeadroomMCPServer(
proxy_url="http://127.0.0.1:9",
+6 -1
View File
@@ -318,13 +318,18 @@ def test_rust_log_compression_keeps_the_log_while_redis_fails(flaky_store, outag
assert store.retrieve(resumed.cache_key).original_content == log
def test_mcp_read_returns_the_file_and_caches_no_hash_while_redis_is_down(flaky_store, tmp_path):
def test_mcp_read_returns_the_file_and_caches_no_hash_while_redis_is_down(
flaky_store, tmp_path, monkeypatch
):
import asyncio
from tests._mcp_stub import import_module_with_mcp_stub
mcp_server = import_module_with_mcp_stub("headroom.ccr.mcp_server")
store, client = flaky_store
monkeypatch.setenv(
"HEADROOM_MCP_READ_ROOTS", str(tmp_path)
) # reads are confined to the workspace
path = tmp_path / "a.py"
source = "x = 1\n" * 50
path.write_bytes(source.encode()) # exact bytes: write_text would emit CRLF on Windows