~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
"""Exercise stored provider URLs and response-bearing fetches without egress.
The settings API, encrypted settings store, provider factory, SDK, fetch tool,
ContentFetcher, and HTML downloader are real. Only DNS and the final HTTP
transports are replaced; socket connections fail the test, including attempts
whose exceptions application code catches.
"""
import ipaddress
import socket
from types import SimpleNamespace
import httpx
import pytest
import requests
from openai import DefaultHttpxClient
from local_deep_research.content_fetcher import ContentFetcher
from local_deep_research.database.session_context import get_user_db_session
from local_deep_research.llm.providers import openai_base
from local_deep_research.llm.providers.implementations.custom_openai_endpoint import (
CustomOpenAIEndpointProvider,
)
from local_deep_research.security import dns_pinning
from local_deep_research.security.egress.policy import (
EgressContext,
EgressScope,
)
from local_deep_research.settings import SettingsManager
ENDPOINT_SETTING = "llm.openai_endpoint.url"
FIXTURE_TEXT = "Local research service content is available."
# Always-blocked metadata literals: refused by every guard, the stored
# provider endpoint included.
METADATA_ADDRESSES = [
"169.254.169.254",
"192.0.0.192",
"168.63.129.16",
"fd00:ec2::23",
"fd20:ce::254",
"169.254.42.42",
"fe80::a9fe:a9fe",
]
# Other link-local addresses: refused by the content-fetch guards, but
# deliberately still accepted as a provider endpoint (rootless Podman maps
# host.containers.internal to 169.254.1.2).
LINK_LOCAL_ADDRESSES = [
"169.254.10.5",
"169.254.169.253",
"fe80::1",
]
@pytest.fixture(autouse=True)
def synthetic_network(monkeypatch):
answers = {
"localhost": ["127.0.0.1"],
"backend-fixture.invalid": ["10.0.0.5"],
}
connections = []
def resolve(host, port=None, *args, **kwargs):
addresses = answers.get(host, [host])
records = []
for address in addresses:
try:
ip = ipaddress.ip_address(address)
except ValueError as exc:
raise socket.gaierror("No synthetic DNS answer") from exc
family = socket.AF_INET6 if ip.version == 6 else socket.AF_INET
records.append(
(family, socket.SOCK_STREAM, 6, "", (str(ip), port or 80))
)
return records
def refuse_connect(sock, address):
connections.append(address)
raise AssertionError(
"A metadata regression test attempted a socket connection"
)
monkeypatch.setattr(socket, "getaddrinfo", resolve)
# The downloader pins DNS through the resolver captured at module import.
monkeypatch.setattr(dns_pinning, "_real_getaddrinfo", resolve)
monkeypatch.setattr(socket.socket, "connect", refuse_connect)
monkeypatch.setattr(socket.socket, "connect_ex", refuse_connect)
yield answers
assert connections == [], "All HTTP traffic must stay in fixture transports"
def _url(host):
authority = f"[{host}]" if ":" in host else host
return f"http://{authority}/v1"
@pytest.fixture
def sdk_transport(monkeypatch):
requests_seen = []
constructors = []
real_constructor = openai_base.ChatOpenAI
# OpenAI 2 uses httpx; the locked OpenAI 3 client uses httpx2.
if issubclass(DefaultHttpxClient, httpx.Client):
transport_module = httpx
else:
import httpx2
transport_module = httpx2
def respond(request):
requests_seen.append(request)
return transport_module.Response(
200,
json={
"id": "chatcmpl-metadata-guard-fixture",
"object": "chat.completion",
"created": 0,
"model": "fixture-model",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": FIXTURE_TEXT,
},
"finish_reason": "stop",
}
],
},
)
# Preserve the real provider-owned clients and their redirect policy;
# replace only the final network transport, not constructor arguments.
monkeypatch.setattr(
transport_module.HTTPTransport,
"handle_request",
lambda transport, request: respond(request),
)
models = []
def construct(**kwargs):
constructors.append(kwargs["base_url"])
model = real_constructor(**kwargs)
models.append(model)
return model
monkeypatch.setattr(openai_base, "ChatOpenAI", construct)
try:
yield SimpleNamespace(requests=requests_seen, constructors=constructors)
finally:
from local_deep_research.utilities.llm_utils import _close_base_llm
for model in models:
_close_base_llm(model)
def _save_and_read_snapshot(client, endpoint):
response = client.put(
f"/settings/api/{ENDPOINT_SETTING}", json={"value": endpoint}
)
assert response.status_code == 200, response.text
username = client.get("/auth/check").json()["username"]
with get_user_db_session(username) as session:
snapshot = SettingsManager(session).get_settings_snapshot()
assert snapshot[ENDPOINT_SETTING] == endpoint
snapshot["llm.openai_endpoint.api_key"] = "metadata-guard-fixture-key"
snapshot["llm.streaming"] = False
return snapshot
@pytest.mark.real_session_check
@pytest.mark.parametrize("address", METADATA_ADDRESSES)
def test_stored_endpoint_blocks_before_sdk_but_localhost_still_works(
authenticated_client, sdk_transport, address
):
snapshot = _save_and_read_snapshot(authenticated_client, _url(address))
with pytest.raises(ValueError, match="failed SSRF validation"):
CustomOpenAIEndpointProvider.create_llm(
"fixture-model", settings_snapshot=snapshot
)
assert sdk_transport.constructors == []
assert sdk_transport.requests == []
# Exercise the same saved-setting path with a usable self-hosted backend.
snapshot = _save_and_read_snapshot(authenticated_client, _url("localhost"))
llm = CustomOpenAIEndpointProvider.create_llm(
"fixture-model", settings_snapshot=snapshot
)
assert llm.invoke("Check the local service").content == FIXTURE_TEXT
assert sdk_transport.constructors == [_url("localhost")]
assert len(sdk_transport.requests) == 1
assert str(sdk_transport.requests[0].url) == (
"http://localhost/v1/chat/completions"
)
@pytest.mark.real_session_check
@pytest.mark.parametrize("address", ["169.254.1.2"] + LINK_LOCAL_ADDRESSES)
def test_stored_link_local_endpoint_still_constructs(
authenticated_client, sdk_transport, address
):
# Not a metadata literal, so the provider guard must not refuse it: a
# rootless Podman host backend lives at 169.254.1.2.
snapshot = _save_and_read_snapshot(authenticated_client, _url(address))
CustomOpenAIEndpointProvider.create_llm(
"fixture-model", settings_snapshot=snapshot
)
assert len(sdk_transport.constructors) == 1
assert address in sdk_transport.constructors[0]
assert sdk_transport.requests == []
@pytest.fixture
def html_transport(monkeypatch):
requests_seen = []
paragraphs = "".join(
f"<p>{FIXTURE_TEXT} This fixture describes a local document service "
"that researchers use to read articles on their private network. "
"The complete article should be returned through the fetch tool.</p>"
for _ in range(8)
)
html = (
"<html><head><title>Local research fixture</title></head>"
f"<body><article>{paragraphs}</article></body></html>"
)
def send(adapter, request, **kwargs):
requests_seen.append(request)
response = requests.Response()
response.status_code = 200
response.url = request.url
response.request = request
response.headers["Content-Type"] = "text/html; charset=utf-8"
response._content = html.encode()
response.headers["Content-Length"] = str(len(response._content))
return response
monkeypatch.setattr(requests.adapters.HTTPAdapter, "send", send)
return requests_seen
def _fetch(entry_point, url, local_hostnames=()):
context = EgressContext(
scope=EgressScope.PRIVATE_ONLY,
primary_engine="test",
require_local_llm=False,
require_local_embeddings=False,
local_hostnames=local_hostnames,
)
if entry_point == "content_fetcher":
with ContentFetcher(egress_context=context) as fetcher:
result = fetcher.fetch(url)
return result["status"] == "success", result.get(
"content", result.get("error")
)
from local_deep_research.advanced_search_system.tools.fetch import (
build_fetch_tool,
)
from local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy import (
SearchResultsCollector,
)
collector = SearchResultsCollector()
tool = build_fetch_tool(
"full",
collector,
egress_context=context,
settings_snapshot={"web.enable_javascript_rendering": False},
max_fetches=0,
)
output = tool.invoke({"url": url})
return collector.find_by_url(url) is not None, output
@pytest.mark.parametrize("entry_point", ["content_fetcher", "agent_tool"])
@pytest.mark.parametrize("address", METADATA_ADDRESSES + LINK_LOCAL_ADDRESSES)
def test_metadata_never_reaches_fetch_transport(
entry_point, address, html_transport
):
success, output = _fetch(entry_point, _url(address))
assert not success
assert "blocked" in output.lower()
assert FIXTURE_TEXT not in output
assert html_transport == []
@pytest.mark.parametrize("entry_point", ["content_fetcher", "agent_tool"])
@pytest.mark.parametrize(
"addresses",
[
["169.254.10.5"],
["fe80::1"],
["192.0.0.192"],
["10.0.0.5", "192.0.0.192"],
],
)
def test_allowlisted_metadata_dns_never_reaches_fetch_transport(
entry_point, addresses, synthetic_network, html_transport
):
host = "metadata-fixture.invalid"
synthetic_network[host] = addresses
success, output = _fetch(entry_point, _url(host), local_hostnames=(host,))
assert not success
assert "blocked" in output.lower()
assert FIXTURE_TEXT not in output
assert html_transport == []
@pytest.mark.parametrize("entry_point", ["content_fetcher", "agent_tool"])
@pytest.mark.parametrize(
"host",
[
"localhost",
"10.0.0.5",
"192.168.1.10",
"fd12::1",
"backend-fixture.invalid",
],
)
def test_private_content_reaches_fetch_output(
entry_point, host, html_transport
):
success, output = _fetch(entry_point, _url(host))
assert success, output
assert FIXTURE_TEXT in output
assert html_transport
assert all(request.url == _url(host) for request in html_transport)