Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(security): gate the chat custom LLM endpoint at the research-start boundary (#7992)

LearningCircuita97d76d1014e
diff --git a/changelog.d/7992.security.md b/changelog.d/7992.security.md
new file mode 100644
index 0000000000..01e7d2f98e
--- /dev/null
+++ b/changelog.d/7992.security.md
@@ -0,0 +1 @@
+Chat-triggered research now rejects a metadata or link-local `llm.openai_endpoint.url` with a clean 400 at the request boundary, before any message or research row is committed or a worker spawned — the same pre-flight `/api/start_research`, follow-up and news routes already apply. Legitimate endpoints (public, self-hosted localhost/LAN, unset) are unaffected.
diff --git a/src/local_deep_research/web/routers/chat.py b/src/local_deep_research/web/routers/chat.py
index 320797d40b..7316dc8c3d 100644
--- a/src/local_deep_research/web/routers/chat.py
+++ b/src/local_deep_research/web/routers/chat.py
@@ -54,6 +54,7 @@ from ...text_optimization.citation_formatter import (
strip_appended_sources_sentinel,
)
from ...utilities.formatting import short_id
+from ...utilities.url_utils import is_safe_custom_llm_endpoint
from ..auth.password_utils import get_user_password, resolve_user_password
from ..routes.globals import (
cleanup_research,
@@ -195,6 +196,19 @@ def _load_settings(username):
return ensure_snapshot_username(snapshot, username)
+def _custom_endpoint_from_snapshot(settings_snapshot):
+ """The openai_endpoint provider's base URL, or None for any other provider.
+
+ Single source of truth for the ``llm.openai_endpoint.url`` read both
+ chat research-start routes share, so the boundary gate and the spawn
+ kwargs can never disagree about which endpoint a run would use.
+ """
+ provider = settings_snapshot.get("llm.provider", {}).get("value", "")
+ if normalize_provider(provider) != "openai_endpoint":
+ return None
+ return settings_snapshot.get("llm.openai_endpoint.url", {}).get("value")
+
+
def _parse_int_param(
value: str | None,
default: int,
@@ -1062,6 +1076,29 @@ async def send_message(
status_code=400,
)
+ # SSRF pre-flight on the custom LLM endpoint: reject
+ # metadata / link-local targets at the request boundary,
+ # BEFORE the atomic write below commits the user message
+ # + IN_PROGRESS research row. Fail-fast defense-in-depth
+ # mirroring research.py / followup.py: the
+ # OpenAI-compatible provider's assert_base_url_safe
+ # re-validates the same URL before the client is built.
+ # Private IPs / localhost pass (local LLM backends),
+ # including scheme-less endpoints (the helper normalizes
+ # exactly as the provider does); None — any provider
+ # other than openai_endpoint, or no URL configured — is
+ # safe by definition.
+ if not is_safe_custom_llm_endpoint(
+ _custom_endpoint_from_snapshot(settings_snapshot)
+ ):
+ return JSONResponse(
+ {
+ "success": False,
+ "error": "Invalid custom endpoint URL",
+ },
+ status_code=400,
+ )
+
# End the cached read transaction before taking the stable
# per-user gate (gate -> DB is the process-wide lock order).
with get_user_db_session(username) as ordering_db:
@@ -1207,12 +1244,10 @@ async def send_message(
# llm.openai_endpoint.url is only the client's base URL for
# the openai_endpoint provider; passing it for any other
# provider mislabels that provider's endpoint downstream.
- custom_endpoint = (
- settings_snapshot.get("llm.openai_endpoint.url", {}).get(
- "value"
- )
- if normalize_provider(model_provider) == "openai_endpoint"
- else None
+ # (Boundary SSRF pre-flight happened above, before the
+ # atomic write.)
+ custom_endpoint = _custom_endpoint_from_snapshot(
+ settings_snapshot
)
# Defensive fallbacks kept in sync with default_settings.json.
user_strategy = settings_snapshot.get(
@@ -1751,6 +1786,25 @@ async def retry_attempt(
status_code=400,
)
+ # SSRF pre-flight on the custom LLM endpoint: reject metadata /
+ # link-local targets at the request boundary, BEFORE the atomic
+ # write below commits the replacement user message + IN_PROGRESS
+ # research row. Fail-fast defense-in-depth mirroring research.py
+ # / followup.py: the OpenAI-compatible provider's
+ # assert_base_url_safe re-validates the same URL before the
+ # client is built. Private IPs / localhost pass (local LLM
+ # backends), including scheme-less endpoints (the helper
+ # normalizes exactly as the provider does); None — any provider
+ # other than openai_endpoint, or no URL configured — is safe by
+ # definition.
+ if not is_safe_custom_llm_endpoint(
+ _custom_endpoint_from_snapshot(settings_snapshot)
+ ):
+ return JSONResponse(
+ {"success": False, "error": "Invalid custom endpoint URL"},
+ status_code=400,
+ )
+
# End all cached read transactions before taking the stable gate.
with get_user_db_session(username) as ordering_db:
ordering_db.rollback()
@@ -1885,14 +1939,9 @@ async def retry_attempt(
search_engine = settings_snapshot.get("search.tool", {}).get(
"value", ""
)
- # Only meaningful for the openai_endpoint provider (see above).
- custom_endpoint = (
- settings_snapshot.get("llm.openai_endpoint.url", {}).get(
- "value"
- )
- if normalize_provider(model_provider) == "openai_endpoint"
- else None
- )
+ # Only meaningful for the openai_endpoint provider (see above;
+ # boundary SSRF pre-flight happened before the atomic write).
+ custom_endpoint = _custom_endpoint_from_snapshot(settings_snapshot)
user_strategy = settings_snapshot.get(
"search.search_strategy", {}
).get("value", "langgraph-agent")
diff --git a/tests/chat/test_chat_custom_endpoint_gate.py b/tests/chat/test_chat_custom_endpoint_gate.py
new file mode 100644
index 0000000000..3fe73a3987
--- /dev/null
+++ b/tests/chat/test_chat_custom_endpoint_gate.py
@@ -0,0 +1,270 @@
+# allow: no-sut-import — black-box HTTP test; drives real chat routes
+"""Request-boundary SSRF pre-flight on the chat custom LLM endpoint.
+
+``send_message`` and ``retry_attempt`` read ``llm.openai_endpoint.url``
+from the caller's settings snapshot and hand it to
+``start_research_process``. Every sibling research-start boundary gates
+the identical read with ``is_safe_custom_llm_endpoint`` BEFORE any
+research row is committed or worker spawned (research.py, followup.py,
+news_flask_api.py); the chat routes must too. The provider's
+``assert_base_url_safe`` still re-validates at client construction —
+the boundary buys a clean 400 instead of a committed IN_PROGRESS row
+plus a spawned worker that dies at construction.
+"""
+
+import json
+from unittest.mock import patch
+
+import pytest
+
+# Endpoint shapes is_safe_custom_llm_endpoint refuses (defence-in-depth
+# class already shipped at the three sibling boundary sites). Inert
+# markers only — nothing is ever fetched: the spawn is mocked, and with
+# the gate in place the request never reaches it.
+POISONED_ENDPOINTS = [
+ # Cloud-instance metadata literal — blocked in every mode and scope.
+ "http://169.254.169.254/v1",
+ # Link-local (non-literal) — blocked via block_link_local=True.
+ "http://169.254.0.1:8000/v1",
+]
+
+# Legitimate endpoints an authenticated user could configure; they must
+# pass the boundary gate (spawn proceeds, mocked here). The self-hosted
+# shape is DNS-independent (localhost needs no resolver); the public
+# shape mirrors the sibling hardening suite's control.
+SAFE_ENDPOINTS = [
+ "http://127.0.0.1:11434/v1",
+ "https://api.openai.com/v1",
+]
+
+
+def _snapshot(url_value):
+ """A chat-route settings snapshot selecting the openai_endpoint provider."""
+ return {
+ "llm.provider": {"value": "openai_endpoint"},
+ "llm.model": {"value": "test-model"},
+ "llm.openai_endpoint.url": {"value": url_value},
+ }
+
+
+def _create_session(client):
+ create_response = client.post(
+ "/api/chat/sessions",
+ json={"initial_query": "Test query"},
+ content_type="application/json",
+ )
+ assert create_response.status_code == 200
+ return json.loads(create_response.data)["session_id"]
+
+
+def _send(client, session_id):
+ return client.post(
+ f"/api/chat/sessions/{session_id}/messages",
+ json={
+ "content": "What is quantum computing?",
+ "trigger_research": True,
+ },
+ content_type="application/json",
+ )
+
+
+class TestSendMessageCustomEndpointGate:
+ def test_poisoned_endpoint_returns_400_and_never_spawns(
+ self, authenticated_client
+ ):
+ """A metadata / link-local endpoint is refused at the request
+ boundary, before the atomic write commits the research row and
+ before start_research_process is ever called."""
+ from local_deep_research.web.routers import chat as chat_routes
+
+ session_id = _create_session(authenticated_client)
+ for url in POISONED_ENDPOINTS:
+ with (
+ patch.object(
+ chat_routes,
+ "_load_settings",
+ return_value=_snapshot(url),
+ ),
+ patch.object(chat_routes, "start_research_process") as spawn,
+ ):
+ response = _send(authenticated_client, session_id)
+
+ assert response.status_code == 400, (
+ f"endpoint {url!r} must be refused with 400, got "
+ f"{response.status_code}"
+ )
+ data = json.loads(response.data)
+ assert data["success"] is False
+ assert data["error"] == "Invalid custom endpoint URL"
+ assert not spawn.called, (
+ "no worker may be spawned for a poisoned endpoint"
+ )
+
+ @pytest.mark.parametrize("url", SAFE_ENDPOINTS)
+ def test_safe_endpoint_proceeds_to_spawn(self, authenticated_client, url):
+ """Pass-through guard: a legitimate endpoint still reaches
+ start_research_process (the boundary gate must not over-block)."""
+ from local_deep_research.web.routers import chat as chat_routes
+
+ session_id = _create_session(authenticated_client)
+ with (
+ patch.object(
+ chat_routes,
+ "_load_settings",
+ return_value=_snapshot(url),
+ ),
+ patch.object(chat_routes, "start_research_process") as spawn,
+ ):
+ response = _send(authenticated_client, session_id)
+
+ assert response.status_code == 200
+ assert json.loads(response.data)["research_id"] is not None
+ assert spawn.called
+
+ def test_unset_endpoint_for_openai_endpoint_provider_proceeds(
+ self, authenticated_client
+ ):
+ """Pass-through guard: provider openai_endpoint with no URL
+ configured (defaults apply downstream) is not blocked here."""
+ from local_deep_research.web.routers import chat as chat_routes
+
+ session_id = _create_session(authenticated_client)
+ with (
+ patch.object(
+ chat_routes,
+ "_load_settings",
+ return_value=_snapshot(None),
+ ),
+ patch.object(chat_routes, "start_research_process") as spawn,
+ ):
+ response = _send(authenticated_client, session_id)
+
+ assert response.status_code == 200
+ assert spawn.called
+
+ def test_other_provider_ignores_endpoint_setting(
+ self, authenticated_client
+ ):
+ """Pass-through guard: for any other provider the URL setting is
+ not the LLM endpoint (chat only forwards it for
+ openai_endpoint), so the gate must not interfere."""
+ from local_deep_research.web.routers import chat as chat_routes
+
+ session_id = _create_session(authenticated_client)
+ snapshot = {
+ "llm.provider": {"value": "ollama"},
+ "llm.model": {"value": "llama3"},
+ "llm.openai_endpoint.url": {
+ "value": POISONED_ENDPOINTS[0]
+ }, # irrelevant for ollama
+ }
+ with (
+ patch.object(chat_routes, "_load_settings", return_value=snapshot),
+ patch.object(chat_routes, "start_research_process") as spawn,
+ ):
+ response = _send(authenticated_client, session_id)
+
+ assert response.status_code == 200
+ assert spawn.called
+
+
+class TestRetryAttemptCustomEndpointGate:
+ def test_retry_with_poisoned_endpoint_returns_400_and_never_spawns(
+ self, authenticated_client
+ ):
+ """The retry boundary applies the same pre-flight: the original
+ attempt is only created here (its spawn is mocked); the retry is
+ then refused at the boundary instead of deleting the attempt and
+ spawning a doomed replacement."""
+ from local_deep_research.web.routers import chat as chat_routes
+
+ session_id = _create_session(authenticated_client)
+
+ # Create the original attempt with a SAFE endpoint so the first
+ # send succeeds (spawn mocked).
+ with (
+ patch.object(
+ chat_routes,
+ "_load_settings",
+ return_value=_snapshot(SAFE_ENDPOINTS[0]),
+ ),
+ patch.object(chat_routes, "start_research_process"),
+ ):
+ first = _send(authenticated_client, session_id)
+ assert first.status_code == 200
+ research_id = json.loads(first.data)["research_id"]
+ assert research_id is not None
+
+ # Retry under a poisoned endpoint snapshot: must 400 at the
+ # boundary, before any spawn of the replacement run. The slot
+ # cap is short-circuited (the first run's spawn is mocked, so
+ # its registration never clears) — admission is a different
+ # seam with its own 409 contract suite.
+ with (
+ patch.object(
+ chat_routes,
+ "_load_settings",
+ return_value=_snapshot(POISONED_ENDPOINTS[0]),
+ ),
+ patch.object(
+ chat_routes,
+ "_check_chat_research_slot_locked",
+ return_value=None,
+ ),
+ patch.object(chat_routes, "start_research_process") as spawn,
+ ):
+ response = authenticated_client.post(
+ f"/api/chat/sessions/{session_id}/attempts/{research_id}/retry",
+ content_type="application/json",
+ )
+
+ assert response.status_code == 400, (
+ f"retry with a poisoned endpoint must be refused with 400, "
+ f"got {response.status_code}"
+ )
+ data = json.loads(response.data)
+ assert data["success"] is False
+ assert data["error"] == "Invalid custom endpoint URL"
+ assert not spawn.called, (
+ "no replacement worker may be spawned for a poisoned endpoint"
+ )
+
+ def test_retry_with_safe_endpoint_proceeds_to_spawn(
+ self, authenticated_client
+ ):
+ """Pass-through guard: retry under a safe endpoint still spawns
+ the replacement run."""
+ from local_deep_research.web.routers import chat as chat_routes
+
+ session_id = _create_session(authenticated_client)
+ with (
+ patch.object(
+ chat_routes,
+ "_load_settings",
+ return_value=_snapshot(SAFE_ENDPOINTS[0]),
+ ),
+ patch.object(chat_routes, "start_research_process"),
+ ):
+ first = _send(authenticated_client, session_id)
+ research_id = json.loads(first.data)["research_id"]
+
+ with (
+ patch.object(
+ chat_routes,
+ "_load_settings",
+ return_value=_snapshot(SAFE_ENDPOINTS[0]),
+ ),
+ patch.object(
+ chat_routes,
+ "_check_chat_research_slot_locked",
+ return_value=None,
+ ),
+ patch.object(chat_routes, "start_research_process") as spawn,
+ ):
+ response = authenticated_client.post(
+ f"/api/chat/sessions/{session_id}/attempts/{research_id}/retry",
+ content_type="application/json",
+ )
+
+ assert response.status_code == 200
+ assert spawn.called
diff --git a/tests/llm/test_provider_adapter_contracts.py b/tests/llm/test_provider_adapter_contracts.py
index 35754e086b..c9ce71dff1 100644
--- a/tests/llm/test_provider_adapter_contracts.py
+++ b/tests/llm/test_provider_adapter_contracts.py
@@ -622,18 +622,6 @@ class TestCustomEndpointBoundaryGate:
gated.add(path.name)
assert {"research.py", "followup.py"} <= gated
- @pytest.mark.xfail(
- strict=True,
- reason=(
- "DEFECT: web/routers/chat.py reads llm.openai_endpoint.url from "
- "the settings snapshot and hands it to start_research_process at "
- "two sites (send_message, retry_attempt) without the "
- "is_safe_custom_llm_endpoint pre-flight that followup.py and "
- "research.py apply to the identical read. A poisoned endpoint "
- "commits DB rows and spawns a worker before the provider's "
- "assert_base_url_safe rejects it, instead of returning a 400."
- ),
- )
def test_every_research_start_boundary_gates_the_endpoint(self):
offenders = []
for path in sorted((SRC / "web" / "routers").glob("*.py")):
diff --git a/tests/security/INDEX.md b/tests/security/INDEX.md
index 12e44622e8..89bcea13e9 100644
--- a/tests/security/INDEX.md
+++ b/tests/security/INDEX.md
@@ -3,3 +3,4 @@
| Seam | Contract test | PR |
|---|---|---|
| `GET /benchmark/api/results` `grader_response` CWE-209 boundary (failure-prefixed raw exception detail genericized, including the historical 🔑-decorated prefix; normal/NULL pass through) | `tests/web/routers/test_benchmark_results_grader_response_boundary.py` | #7591 |
+| Chat research-start boundary `is_safe_custom_llm_endpoint` pre-flight (`send_message` + `retry_attempt` 400 before any row/worker; router-wide structural fence flipped from recorded xfail) | `tests/chat/test_chat_custom_endpoint_gate.py` + `tests/llm/test_provider_adapter_contracts.py::TestCustomEndpointBoundaryGate` | #7992 |