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(paths): reject '.', '..', and NUL as plugin names (#2132)

thejesh23af7385a2980a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index abcc697c6..dd342a574 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Unreleased
### Fixed
+- **paths:** reject `.`, `..`, and NUL as plugin names so `plugin_config_dir` / `plugin_workspace_dir` cannot resolve outside the `plugins/` sandbox. Previously `plugin_config_dir("..")` returned the entire config root and `plugin_workspace_dir("..")` returned the workspace root (savings ledger, memory DB, license cache, logs).
- **backends/litellm:** drop tool names over 64 chars before calling Bedrock Converse (`send_message` and `stream_message`), instead of letting the whole request 401. The Bedrock Converse API hard-rejects any tool name past that length, and Claude Code includes every globally-added claude.ai MCP connector tool in every request, even ones the user hasn't enabled locally, so a single oversized connector name broke every call through this backend. Only the `bedrock` provider filters; other providers forward tool names unfiltered.
- **memory:** annotate `_EMBEDDER_CACHE` as `dict[tuple[str, str, str], Embedder]` to match the 3-element key (backend, model, ollama_base_url). The stale 2-tuple annotation made `mypy headroom` fail on `main`, which broke the `lint` CI job on every open PR.
- **install:** include `orjson` in the `[proxy]` extra so `uv tool install "headroom-ai[all]"` satisfies LiteLLM OpenRouter/provider backends that import it at runtime ([#2056](https://github.com/headroomlabs-ai/headroom/issues/2056)).
diff --git a/headroom/paths.py b/headroom/paths.py
index 49c7619a8..8845718c7 100644
--- a/headroom/paths.py
+++ b/headroom/paths.py
@@ -370,19 +370,38 @@ def models_config_path() -> Path:
# ---------------------------------------------------------------------------
+def _validate_plugin_name(plugin_name: str) -> None:
+ """Reject plugin names that would escape the ``plugins/`` sandbox.
+
+ Path separators (``/``, ``\\``) are rejected so a name cannot address a
+ subdirectory. ``.`` and ``..`` are rejected because ``plugins / ".."``
+ resolves to the plugins-parent (i.e. the whole config/workspace root),
+ handing a plugin read/write access to every other plugin's state and the
+ workspace's savings ledger, memory DB, license cache, and logs. NUL is
+ rejected because it terminates paths on POSIX APIs.
+ """
+
+ if (
+ not plugin_name
+ or plugin_name in {".", ".."}
+ or "/" in plugin_name
+ or "\\" in plugin_name
+ or "\x00" in plugin_name
+ ):
+ raise ValueError(f"invalid plugin name: {plugin_name!r}")
+
+
def plugin_config_dir(plugin_name: str) -> Path:
"""Return the config directory for a named plugin."""
- if not plugin_name or "/" in plugin_name or "\\" in plugin_name:
- raise ValueError(f"invalid plugin name: {plugin_name!r}")
+ _validate_plugin_name(plugin_name)
return config_dir() / _PLUGINS_DIR / plugin_name
def plugin_workspace_dir(plugin_name: str) -> Path:
"""Return the workspace directory for a named plugin."""
- if not plugin_name or "/" in plugin_name or "\\" in plugin_name:
- raise ValueError(f"invalid plugin name: {plugin_name!r}")
+ _validate_plugin_name(plugin_name)
return workspace_dir() / _PLUGINS_DIR / plugin_name
diff --git a/tests/test_paths.py b/tests/test_paths.py
index 6af26ef9c..532fb7568 100644
--- a/tests/test_paths.py
+++ b/tests/test_paths.py
@@ -471,7 +471,7 @@ def test_plugin_workspace_dir_namespaced(fake_home: Path) -> None:
assert b == fake_home / ".headroom" / "plugins" / "beta"
[email protected]("bad_name", ["", "foo/bar", "foo\\bar"])
[email protected]("bad_name", ["", "foo/bar", "foo\\bar", "..", ".", "\x00"])
def test_plugin_dirs_reject_bad_names(fake_home: Path, bad_name: str) -> None:
with pytest.raises(ValueError):
paths.plugin_config_dir(bad_name)
@@ -479,6 +479,22 @@ def test_plugin_dirs_reject_bad_names(fake_home: Path, bad_name: str) -> None:
paths.plugin_workspace_dir(bad_name)
+def test_plugin_dirs_reject_traversal_escapes_sandbox(fake_home: Path) -> None:
+ """A plugin name of ``..`` must not resolve outside ``plugins/``.
+
+ Without this guard, ``plugin_config_dir("..") == config_dir()`` — a plugin
+ can read/write the entire config root (models catalog, other plugins'
+ settings), and ``plugin_workspace_dir("..") == workspace_dir()`` exposes
+ the license cache, savings ledger, memory DB, and logs.
+ """
+
+ for name in ("..", "."):
+ with pytest.raises(ValueError):
+ paths.plugin_config_dir(name)
+ with pytest.raises(ValueError):
+ paths.plugin_workspace_dir(name)
+
+
def test_plugin_config_dir_follows_config_env(
fake_home: Path, clean_env: pytest.MonkeyPatch, tmp_path: Path
) -> None: