Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(tokenizers): disable trust_remote_code and allowlist HF tokenizer repos (#3723)

Tejas Chopra34da21e89ebb
diff --git a/benchmarks/comprehensive_eval.py b/benchmarks/comprehensive_eval.py
index 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.py
index 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 or
offline 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 AutoTokenizer
try:
+ # 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_TOKENIZER
class HuggingFaceTokenizer(BaseTokenizer):
diff --git a/tests/test_huggingface_tokenizer_allowlist.py b/tests/test_huggingface_tokenizer_allowlist.py
new file mode 100644
index 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_TOKENIZER
diff --git a/tests/test_huggingface_tokenizer_timeout.py b/tests/test_huggingface_tokenizer_timeout.py
index 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 fix
tries the local HF cache first (local_files_only=True), bounds the network attempt
with HEADROOM_HF_TOKENIZER_LOAD_TIMEOUT_SECS on a daemon thread, and fails open to
estimation — 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) == 1
assert calls[0].get("local_files_only") is True
@@ -80,12 +85,12 @@ def test_slow_network_load_times_out_and_fails_open(monkeypatch: pytest.MonkeyPa
monkeypatch.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 None
assert 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 None
assert 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 None
def 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.py
new file mode 100644
index 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"}