~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
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.mdnew file mode 100644index 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.pyindex 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_endpointfrom ..auth.password_utils import get_user_password, resolve_user_passwordfrom ..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.pynew file mode 100644index 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.calleddiff --git a/tests/llm/test_provider_adapter_contracts.py b/tests/llm/test_provider_adapter_contracts.pyindex 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.mdindex 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 |