Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(tokenizers): disable trust_remote_code and allowlist HF tokenizer repos (#3723)
Tejas Chopra34da21e89ebb
diff --git a/benchmarks/comprehensive_eval.py b/benchmarks/comprehensive_eval.pyindex 3c8573760..ae47fbb4f 100644--- a/benchmarks/comprehensive_eval.py+++ b/benchmarks/comprehensive_eval.py@@ -41,7 +41,9 @@ def load_bfcl_samples(n: int = 20) -> list[dict]:"gorilla-llm/Berkeley-Function-Calling-Leaderboard","BFCL_v3_live_simple",split="train",- trust_remote_code=True,+ # BFCL is plain parquet; never execute a dataset repository's own+ # loading script, here or anywhere else in the tree.+ trust_remote_code=False,)samples = []diff --git a/headroom/tokenizers/huggingface.py b/headroom/tokenizers/huggingface.pyindex 8ace0a792..255866736 100644--- a/headroom/tokenizers/huggingface.py+++ b/headroom/tokenizers/huggingface.py@@ -122,6 +122,56 @@ MODEL_TO_TOKENIZER: dict[str, str] = {}+# Every repository Headroom is willing to hand to the HuggingFace loader.+#+# The loader resolves a name against the Hub and, historically, ran repository+# code while doing it (``trust_remote_code``). The model id reaching this module+# can come straight off a client request body — the proxy routes ``model`` to a+# tokenizer — so an unconstrained identifier is remote code execution in the+# proxy process by way of "publish a repo, then ask for it by name". The+# allowlist is derived from the mappings we actually ship, so adding a family to+# MODEL_TO_TOKENIZER allows it and nothing else drifts in.+ALLOWED_TOKENIZER_REPOS: frozenset[str] = frozenset(MODEL_TO_TOKENIZER.values())++# The tokenizer an unrecognised model resolves to. Llama 3 is the canonical open+# model vocabulary and is what the registry already routes bare ``llama*`` ids+# to. The repository is gated on the Hub, so a deployment without HF credentials+# simply fails the load and falls back to character estimation — which is what+# an unknown model got before this allowlist existed.+DEFAULT_TOKENIZER: str = MODEL_TO_TOKENIZER["llama-3"]++# Operator escape hatch for self-hosted or private tokenizer repositories:+# a comma-separated list of repo ids. This is deliberately environment-only —+# server-side configuration an operator sets, never anything a client can+# influence through a request body. Repositories added here are still loaded+# with ``trust_remote_code=False``.+_ALLOWLIST_ENV = "HEADROOM_HF_TOKENIZER_ALLOWLIST"+++@lru_cache(maxsize=8)+def _allowlist_index(extra: str) -> dict[str, str]:+ """Lowercased repo id -> canonical repo id, for the shipped list plus ``extra``.++ Keyed on the raw environment value so the (tiny) index is built once per+ distinct configuration rather than on every model resolution.+ """+ repos = set(ALLOWED_TOKENIZER_REPOS)+ repos.update(part.strip() for part in extra.split(",") if part.strip())+ return {repo.lower(): repo for repo in repos}+++def _resolve_allowed_repo(name: str) -> str | None:+ """Return the canonical allowlisted repo id for ``name``, or None.++ Matching is case-insensitive because Hub ids are commonly retyped with+ different capitalisation, but the value returned is always *our* spelling+ from the allowlist — the caller's string is never propagated to the loader.+ """+ if not name:+ return None+ return _allowlist_index(os.environ.get(_ALLOWLIST_ENV, "")).get(name.strip().lower())++# Bound the first (network) load of a HuggingFace tokenizer. Without a bound,# huggingface_hub download retries can block for many minutes (GH #1701: 610s# on a restricted Windows network). 0 disables network loads entirely.@@ -148,18 +198,42 @@ def _load_tokenizer(tokenizer_name: str):Failures are cached by ``lru_cache`` (returns ``None``), so a slow oroffline hub is probed at most once per process per tokenizer.+ Only repositories on the allowlist reach ``from_pretrained`` at all. This is+ the chokepoint, not a second opinion: ``get_tokenizer_name`` already resolves+ unrecognised models to DEFAULT_TOKENIZER, but this function is importable and+ callable with an arbitrary string, and a name that is not on the allowlist+ must never turn into a Hub lookup. Refusing here fails closed to estimation+ rather than substituting a different vocabulary behind the caller's back.+Args:tokenizer_name: HuggingFace model/tokenizer name.Returns:Loaded tokenizer, or None if unavailable."""+ repo = _resolve_allowed_repo(tokenizer_name)+ if repo is None:+ logger.warning(+ f"Refusing to load unallowlisted tokenizer {tokenizer_name!r}; using "+ f"estimation (add it to {_ALLOWLIST_ENV} if this repository is trusted)"+ )+ return None+ # Load the allowlist's own spelling, never the argument: matching is+ # case-insensitive, so the string that reaches the Hub must be the one we+ # vetted, not a variant the caller chose.+ tokenizer_name = repo+from transformers import AutoTokenizertry:+ # trust_remote_code=False, always. A tokenizer repository can ship its own+ # Python, and executing it is equivalent to running whatever the repo owner+ # publishes inside the proxy. Every tokenizer we map is a plain vocabulary+ # that loads fine without it; a repo that genuinely needs custom code is a+ # repo we are not willing to execute.return AutoTokenizer.from_pretrained(tokenizer_name,- trust_remote_code=True,+ trust_remote_code=False,local_files_only=True,)except Exception:@@ -181,7 +255,7 @@ def _load_tokenizer(tokenizer_name: str):result.append(AutoTokenizer.from_pretrained(tokenizer_name,- trust_remote_code=True,+ trust_remote_code=False, # see the cache-only attempt above))except BaseException as e: # noqa: BLE001 — report any failure to the waiter@@ -209,11 +283,15 @@ def _load_tokenizer(tokenizer_name: str):def get_tokenizer_name(model: str) -> str:"""Get HuggingFace tokenizer name for a model.+ Always returns an allowlisted repository. ``model`` is attacker-reachable —+ it is the ``model`` field of a proxied request body — so this resolver must+ never return a caller-controlled string for the loader to look up on the Hub.+Args:model: Model name.Returns:- HuggingFace tokenizer identifier.+ HuggingFace tokenizer identifier, from ALLOWED_TOKENIZER_REPOS."""model_lower = model.lower()@@ -231,8 +309,26 @@ def get_tokenizer_name(model: str) -> str:if model_lower.startswith(key):return MODEL_TO_TOKENIZER[key]- # Assume model name is the tokenizer name- return model+ # A caller may legitimately name a shipped repository outright+ # ("meta-llama/Llama-3.1-8B") instead of using the short alias, and that has+ # to keep counting exactly. Accepting it via the allowlist returns our own+ # canonical spelling, so the caller's string still never reaches the loader.+ allowed = _resolve_allowed_repo(model)+ if allowed is not None:+ return allowed++ # Fail closed. This branch used to be "assume the model name is the+ # tokenizer name", which handed an arbitrary client-supplied string to+ # AutoTokenizer.from_pretrained -> a Hub fetch of whatever repository the+ # caller named. An unrecognised model now resolves to the default vocabulary;+ # the count is an approximation, which is what an unknown model already got+ # when the made-up repo id failed to resolve.+ logger.debug(+ "No tokenizer mapping for model %r; using default tokenizer %s",+ model,+ DEFAULT_TOKENIZER,+ )+ return DEFAULT_TOKENIZERclass HuggingFaceTokenizer(BaseTokenizer):diff --git a/tests/test_huggingface_tokenizer_allowlist.py b/tests/test_huggingface_tokenizer_allowlist.pynew file mode 100644index 000000000..6950839fe--- /dev/null+++ b/tests/test_huggingface_tokenizer_allowlist.py@@ -0,0 +1,225 @@+"""The HF tokenizer loader must only ever fetch repositories we ship (A-1).++``AutoTokenizer.from_pretrained`` resolves a name against the HuggingFace Hub and,+with ``trust_remote_code``, executes Python that the repository owner published.+The identifier reaching this module can come straight off a proxied request body:+the proxy picks a tokenizer from the request's ``model`` field, and the resolver's+old fallthrough was "assume the model name is the tokenizer name". Publishing a+repo and then naming it in a request body was therefore code execution in the+proxy process.++The fix is two-layered and fails closed: ``get_tokenizer_name`` never returns a+caller-controlled string, and ``_load_tokenizer`` refuses anything off the+allowlist before it imports transformers at all.+"""++from __future__ import annotations++import sys+import types+from typing import Any++import pytest++from headroom.tokenizers import huggingface as hf_mod+from headroom.tokenizers.huggingface import (+ MODEL_TO_TOKENIZER,+ HuggingFaceTokenizer,+ _load_tokenizer,+ get_tokenizer_name,+)++# A repository id an attacker could plausibly stand up and then request by name.+CRAFTED = "attacker-controlled/headroom-rce-poc"++SHIPPED_REPOS = frozenset(MODEL_TO_TOKENIZER.values())++[email protected](autouse=True)+def _fresh_caches():+ """Both caches are process-wide; env-driven tests need them cleared."""+ index = getattr(hf_mod, "_allowlist_index", None)+ _load_tokenizer.cache_clear()+ if index is not None:+ index.cache_clear()+ yield+ _load_tokenizer.cache_clear()+ if index is not None:+ index.cache_clear()+++class _FakeTokenizer:+ """Minimal stand-in: enough surface for count_text/encode."""++ def encode(self, text: str, add_special_tokens: bool = False) -> list[int]:+ return list(range(len(text.split())))+++def _install_fake_transformers(monkeypatch: pytest.MonkeyPatch, from_pretrained) -> None:+ fake = types.ModuleType("transformers")+ fake.AutoTokenizer = type(+ "AutoTokenizer", (), {"from_pretrained": staticmethod(from_pretrained)}+ )+ monkeypatch.setitem(sys.modules, "transformers", fake)+++# ---------------------------------------------------------------------------+# A crafted model id must not reach the loader+# ---------------------------------------------------------------------------+++def test_crafted_model_never_reaches_the_loader(monkeypatch: pytest.MonkeyPatch) -> None:+ """The exploit path end to end: request body -> tokenizer -> Hub fetch."""+ names: list[str] = []++ def fake_from_pretrained(name: str, **kwargs: Any):+ names.append(name)+ return _FakeTokenizer()++ _install_fake_transformers(monkeypatch, fake_from_pretrained)++ counter = HuggingFaceTokenizer(CRAFTED)+ assert counter.count_text("hello world") > 0 # counting still works++ assert CRAFTED not in names, "attacker-named repository was handed to from_pretrained"+ assert set(names) <= SHIPPED_REPOS, f"unallowlisted repository fetched: {names}"+++def test_crafted_model_resolves_to_a_shipped_tokenizer() -> None:+ for model in (+ CRAFTED,+ "../../../etc/passwd",+ "evil/repo",+ "https://example.invalid/evil",+ "",+ "x" * 500,+ ):+ assert get_tokenizer_name(model) in SHIPPED_REPOS, f"{model!r} escaped the allowlist"+++def test_crafted_model_resolves_to_the_declared_default() -> None:+ assert get_tokenizer_name(CRAFTED) == hf_mod.DEFAULT_TOKENIZER+ assert hf_mod.DEFAULT_TOKENIZER in hf_mod.ALLOWED_TOKENIZER_REPOS+++def test_prefix_match_on_a_crafted_name_still_lands_on_a_shipped_repo() -> None:+ """A crafted id may *start* with a family alias; that path is safe too."""+ assert get_tokenizer_name("llama-3-evil/rce") == MODEL_TO_TOKENIZER["llama-3"]+++def test_loader_refuses_unallowlisted_repo_without_touching_the_hub(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The loader is the chokepoint, not just the resolver."""++ def fake_from_pretrained(name: str, **kwargs: Any):+ raise AssertionError(f"Hub lookup attempted for {name!r}")++ _install_fake_transformers(monkeypatch, fake_from_pretrained)+ monkeypatch.setenv("HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS", "5")++ assert _load_tokenizer(CRAFTED) is None+ assert _load_tokenizer("meta-llama/Meta-Llama-3-8B-but-not-really") is None+++def test_loader_fetches_the_allowlists_own_spelling(monkeypatch: pytest.MonkeyPatch) -> None:+ """Case-insensitive matching must not let the caller pick the fetched string."""+ names: list[str] = []++ def fake_from_pretrained(name: str, **kwargs: Any):+ names.append(name)+ return _FakeTokenizer()++ _install_fake_transformers(monkeypatch, fake_from_pretrained)++ assert _load_tokenizer(" META-LLAMA/llama-3.1-8b ") is not None+ assert names == ["meta-llama/Llama-3.1-8B"]+++# ---------------------------------------------------------------------------+# trust_remote_code is off on every path+# ---------------------------------------------------------------------------++# Built by concatenation so this file contributes no literal occurrence of the+# token to the tree-wide scan in test_no_trust_remote_code.py.+_REMOTE_CODE_KWARG = "trust_remote" + "_code"+++def test_remote_code_disabled_on_cache_and_network_paths(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ calls: list[dict[str, Any]] = []++ def fake_from_pretrained(name: str, **kwargs: Any):+ calls.append(kwargs)+ if kwargs.get("local_files_only"):+ raise OSError("not in cache")+ return _FakeTokenizer()++ _install_fake_transformers(monkeypatch, fake_from_pretrained)+ monkeypatch.setenv("HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS", "5")++ assert _load_tokenizer("Qwen/Qwen2.5-7B") is not None+ assert len(calls) == 2, "expected the cache-only attempt then the bounded network one"+ for kwargs in calls:+ assert kwargs.get(_REMOTE_CODE_KWARG) is False+++# ---------------------------------------------------------------------------+# Legitimate resolutions are unchanged+# ---------------------------------------------------------------------------+++def test_every_shipped_alias_still_resolves_to_its_mapping() -> None:+ for alias, repo in MODEL_TO_TOKENIZER.items():+ assert get_tokenizer_name(alias) == repo+++def test_full_repo_id_for_a_shipped_tokenizer_is_accepted_verbatim() -> None:+ """Callers pass the repo id instead of the alias; counts must not change.++ The allowlist is consulted *after* alias and prefix matching, so ids that a+ family prefix already claimed keep resolving exactly as they did before —+ ``mistralai/Mixtral-8x7B-v0.1`` still hits the "mistral" prefix, exactly as+ it did before. This fix changes no resolution that previously worked.+ """+ assert get_tokenizer_name("meta-llama/Llama-3.1-8B") == "meta-llama/Llama-3.1-8B"+ assert get_tokenizer_name("google/gemma-2-27b") == "google/gemma-2-27b"+ assert get_tokenizer_name("microsoft/Phi-3-mini-4k-instruct") == (+ "microsoft/Phi-3-mini-4k-instruct"+ )+ # Unchanged prefix-match precedence, shown explicitly so a future reorder+ # of the resolver has to acknowledge it.+ assert get_tokenizer_name("mistralai/Mixtral-8x7B-v0.1") == "mistralai/Mistral-7B-v0.1"+++def test_repo_id_matching_is_case_insensitive_but_returns_our_spelling() -> None:+ assert get_tokenizer_name("META-LLAMA/llama-3.1-8b") == "meta-llama/Llama-3.1-8B"+++# ---------------------------------------------------------------------------+# Operator escape hatch (server-side env only)+# ---------------------------------------------------------------------------+++def test_operator_env_allowlist_admits_a_private_repo(monkeypatch: pytest.MonkeyPatch) -> None:+ names: list[str] = []++ def fake_from_pretrained(name: str, **kwargs: Any):+ names.append(name)+ return _FakeTokenizer()++ _install_fake_transformers(monkeypatch, fake_from_pretrained)+ monkeypatch.setenv(hf_mod._ALLOWLIST_ENV, "acme/internal-tokenizer, acme/other")++ assert _load_tokenizer("acme/internal-tokenizer") is not None+ assert names == ["acme/internal-tokenizer"]++ # Still closed for everything the operator did not name.+ assert _load_tokenizer(CRAFTED) is None+ assert CRAFTED not in names+++def test_empty_operator_env_admits_nothing_extra(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv(hf_mod._ALLOWLIST_ENV, " , ,")+ assert get_tokenizer_name(CRAFTED) == hf_mod.DEFAULT_TOKENIZERdiff --git a/tests/test_huggingface_tokenizer_timeout.py b/tests/test_huggingface_tokenizer_timeout.pyindex 175d4e750..4a8a4fb97 100644--- a/tests/test_huggingface_tokenizer_timeout.py+++ b/tests/test_huggingface_tokenizer_timeout.py@@ -4,6 +4,11 @@ path it blocked the event loop for ~10 minutes and zombified the server. The fixtries the local HF cache first (local_files_only=True), bounds the network attemptwith HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS on a daemon thread, and fails open toestimation — caching the failure so the hub is probed at most once per process.++The repo ids below are real shipped ones because _load_tokenizer now refuses+anything off the tokenizer allowlist before it reaches the loading path at all+(see test_huggingface_tokenizer_allowlist.py); a placeholder name would short+out these tests by being rejected rather than exercising the timeout."""from __future__ import annotations@@ -50,7 +55,7 @@ def test_local_cache_tried_before_network(monkeypatch: pytest.MonkeyPatch) -> No_install_fake_transformers(monkeypatch, fake_from_pretrained)monkeypatch.setenv("HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS", "5")- assert _load_tokenizer("some/model") == "network-tokenizer"+ assert _load_tokenizer("Qwen/Qwen2.5-7B") == "network-tokenizer"assert calls[0].get("local_files_only") is True, "first attempt must be cache-only"assert not calls[1].get("local_files_only")@@ -64,7 +69,7 @@ def test_cache_hit_never_touches_network(monkeypatch: pytest.MonkeyPatch) -> Non_install_fake_transformers(monkeypatch, fake_from_pretrained)- assert _load_tokenizer("some/model") == "cached-tokenizer"+ assert _load_tokenizer("Qwen/Qwen2.5-7B") == "cached-tokenizer"assert len(calls) == 1assert calls[0].get("local_files_only") is True@@ -80,12 +85,12 @@ def test_slow_network_load_times_out_and_fails_open(monkeypatch: pytest.MonkeyPamonkeypatch.setenv("HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS", "0.2")start = time.monotonic()- assert _load_tokenizer("slow/model") is None+ assert _load_tokenizer("Qwen/Qwen2-7B") is Noneassert time.monotonic() - start < 5, "load must unblock at the timeout, not the download"# Failure is cached (lru_cache) — the second call must not re-probe the hub.start = time.monotonic()- assert _load_tokenizer("slow/model") is None+ assert _load_tokenizer("Qwen/Qwen2-7B") is Noneassert time.monotonic() - start < 0.05@@ -98,7 +103,7 @@ def test_timeout_zero_disables_network_loading(monkeypatch: pytest.MonkeyPatch)_install_fake_transformers(monkeypatch, fake_from_pretrained)monkeypatch.setenv("HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS", "0")- assert _load_tokenizer("offline/model") is None+ assert _load_tokenizer("google/gemma-7b") is Nonedef test_count_messages_fails_open_to_estimation(monkeypatch: pytest.MonkeyPatch) -> None:diff --git a/tests/test_no_trust_remote_code.py b/tests/test_no_trust_remote_code.pynew file mode 100644index 000000000..55ae7374f--- /dev/null+++ b/tests/test_no_trust_remote_code.py@@ -0,0 +1,77 @@+"""Nothing in this tree may enable HuggingFace remote code execution (A-1).++``trust_remote_code`` makes a model/dataset repository's own Python run inside+the process that loads it. Headroom loads tokenizers from identifiers that trace+back to proxied request bodies, so a single re-introduced ``=True`` anywhere is+remote code execution in the proxy. This is a tree-wide scan rather than a test+of one module: the tokenizer loader was not the only caller, and the next one+will not be either.+"""++from __future__ import annotations++import re+import subprocess+from pathlib import Path++import pytest++ROOT = Path(__file__).resolve().parents[1]++# Assembled at runtime so this file contributes no literal occurrence of the+# token to its own scan.+FLAG = "trust_remote" + "_code"++# Matches the kwarg form (``flag=True``), the mapping form (``"flag": True``)+# and the subscript form (``kwargs["flag"] = True``), capturing whatever it is+# set to. The optional quote and bracket matter: without them the mapping form+# slips through, and ``from_pretrained(**{"flag": True})`` is exactly how this+# would come back.+ASSIGNMENT = re.compile(re.escape(FLAG) + r"[\"']?\s*\]?\s*[=:]\s*([A-Za-z_][\w.]*)")+++def _tracked_files() -> list[Path]:+ """Every git-tracked file, so the scan cannot be dodged by adding a directory.++ git-tracked rather than a filesystem walk: the repository is commonly checked+ out alongside worktrees and virtualenvs that a naive rglob would sweep in.+ """+ try:+ out = subprocess.run(+ ["git", "ls-files", "-z"],+ cwd=ROOT,+ capture_output=True,+ check=True,+ ).stdout+ except (OSError, subprocess.CalledProcessError) as exc: # pragma: no cover+ pytest.skip(f"git ls-files unavailable: {exc}")+ return [ROOT / name for name in out.decode().split("\0") if name]+++def test_remote_code_is_never_enabled_anywhere_in_the_tree() -> None:+ offenders: list[str] = []++ for path in _tracked_files():+ try:+ text = path.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError):+ continue # binary or vanished (submodule, symlink) — nothing to read+ if FLAG not in text:+ continue+ for lineno, line in enumerate(text.splitlines(), start=1):+ for value in ASSIGNMENT.findall(line):+ if value != "False":+ offenders.append(f"{path.relative_to(ROOT)}:{lineno}: {line.strip()}")++ assert not offenders, (+ f"{FLAG} must be False everywhere — it executes repository-supplied "+ "Python in this process:\n" + "\n".join(offenders)+ )+++def test_the_tokenizer_loader_sets_the_flag_explicitly() -> None:+ """Explicit beats relying on the library default, which upstream can change."""+ source = (ROOT / "headroom" / "tokenizers" / "huggingface.py").read_text(encoding="utf-8")+ values = ASSIGNMENT.findall(source)+ assert values, f"tokenizer loader no longer passes {FLAG} explicitly"+ assert set(values) == {"False"}