~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
import ipaddress
import socket
from unittest.mock import patch
import pytest
import requests
from local_deep_research.security.notification_validator import (
NotificationURLValidator,
)
from local_deep_research.security.notification_destination import (
parse_notification_destination,
)
from local_deep_research.security.ssrf_validator import validate_url
_PUBLIC_ADDRINFO = [
(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("93.184.216.34", 0)),
]
_PUBLIC_RESOLVED_IPS = [ipaddress.IPv4Address("93.184.216.34")]
_AMBIGUOUS_NUMERIC_IPV4_ERROR = "Ambiguous numeric IPv4 host"
_ENCODED_NUMERIC_IPV4_ERROR = "Encoded numeric IPv4 host"
_PERCENT_ENCODED_NON_NUMERIC_HOST_URLS = (
"https://ex%61mple.com/",
"https://ex%61mple.com./",
"https://127.0.0.1%252e/",
)
_PERCENT_ESCAPE_OUTSIDE_HOST_URLS = (
"https://%32%31%33%30%37%30%36%34%33%[email protected]/",
"https://public.example/%32%31%33%30%37%30%36%34%33%33",
)
_PRESERVED_PERCENT_ENCODED_URLS = (
_PERCENT_ENCODED_NON_NUMERIC_HOST_URLS + _PERCENT_ESCAPE_OUTSIDE_HOST_URLS
)
_ENCODED_NUMERIC_IPV4_URLS = (
(
"http://%32%31%33%30%37%30%36%34%33%33/",
"http://2130706433/",
),
("http://0x7f%2e0%2e0%2e1/", "http://0x7f.0.0.1/"),
("http://127%2e0%2e0%2e1/", "http://127.0.0.1/"),
("http://8%2e8%2e8%2e8/", "http://8.8.8.8/"),
)
_ENCODED_TRAILING_DOT_NUMERIC_IPV4_URLS = (
("http://127.0.0.1%2e/", "http://127.0.0.1./"),
("http://127.0.0.1%2E/", "http://127.0.0.1./"),
("http://2130706433%2e/", "http://2130706433./"),
("http://2130706433%2E/", "http://2130706433./"),
("http://0x7f000001%2e/", "http://0x7f000001./"),
("http://0x7f000001%2E/", "http://0x7f000001./"),
)
def test_non_numeric_percent_encoded_hosts_preserve_current_outcomes():
# Given: public DNS answers for nonnumeric authorities and public hosts.
with (
patch(
"local_deep_research.security.ssrf_validator.socket.getaddrinfo",
return_value=_PUBLIC_ADDRINFO,
),
patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=_PUBLIC_RESOLVED_IPS,
),
):
# When: percent escapes occur outside a numeric network authority.
for url in _PRESERVED_PERCENT_ENCODED_URLS:
# Then: the notification validator retains its existing outcome
# (Apprise refuses a '%' host itself, so it never dials one).
assert NotificationURLValidator.validate_service_url(url) == (
True,
None,
)
# And: validate_url still accepts escapes outside the host.
for url in _PERCENT_ESCAPE_OUTSIDE_HOST_URLS:
assert validate_url(url) is True
@pytest.mark.parametrize("scheme", ("http", "https"))
def test_escaped_dns_name_resolves_the_hostname_requests_will_contact(scheme):
url = f"{scheme}://ex%61mple.com/"
assert parse_notification_destination(url).effective_host == "example.com"
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=_PUBLIC_RESOLVED_IPS,
) as resolver:
result = NotificationURLValidator.validate_service_url_with_hint(url)
assert requests.Request("GET", url).prepare().url == (
f"{scheme}://example.com/"
)
assert result == (True, None, False)
resolver.assert_called_once_with("example.com")
def test_escaped_plugin_host_fails_closed_on_parser_disagreement():
url = "json://ex%61mple.com/hook"
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
side_effect=AssertionError("ambiguous plugin host must not resolve"),
):
assert NotificationURLValidator.validate_service_url_with_hint(url) == (
False,
"Notification destination host is ambiguous",
False,
)
def test_double_encoded_host_is_not_decoded_twice():
url = "https://127.0.0.1%252e/"
assert (
parse_notification_destination(url).effective_host == "127.0.0.1%252e"
)
@pytest.mark.parametrize(
"url",
(
"discord://%32%31%33%30%37%30%36%34%33%33/webhook-token",
"discord://webhook-token%2e/",
),
)
def test_percent_encoded_opaque_plugin_authorities_preserve_current_outcome(
url,
):
# Given: an opaque token-style plugin authority with encoded digits.
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=_PUBLIC_RESOLVED_IPS,
) as resolver:
# When: notification validation receives the opaque token URL.
result = NotificationURLValidator.validate_service_url(url)
# Then: it remains valid without host resolution.
assert result == (True, None)
assert resolver.call_count == 0
def test_opaque_discord_authority_skips_host_resolution():
# Given: a resolver guard that fails if an opaque token is treated as a host.
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
side_effect=AssertionError("opaque Discord token must not resolve"),
):
# When: hint-aware validation receives a numeric-looking Discord token.
result = NotificationURLValidator.validate_service_url_with_hint(
"discord://169.254.169.254/path"
)
# Then: the token remains valid without suggesting an operator setting.
assert result == (True, None, False)
def test_host_bearing_signal_metadata_authority_rejects_without_resolution():
# Given: a resolver guard for a host-bearing Signal authority.
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
side_effect=AssertionError(
"metadata Signal host must reject before resolution"
),
):
# When: notification validation receives a Signal metadata address.
is_valid, _ = NotificationURLValidator.validate_service_url(
"signal://169.254.169.254:8080/path"
)
# Then: canonical metadata IP rejection remains deterministic and network-free.
assert is_valid is False
def test_invalid_percent_escape_keeps_existing_parser_rejection():
# Given: an authority that requests and urllib3 cannot parse.
with (
patch(
"local_deep_research.security.ssrf_validator.socket.getaddrinfo",
return_value=_PUBLIC_ADDRINFO,
) as general_resolver,
patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=_PUBLIC_RESOLVED_IPS,
) as notification_resolver,
):
# When: validators receive an invalid percent escape.
general_result = validate_url("http://%zz/")
service_result = NotificationURLValidator.validate_service_url(
"http://%zz/"
)
hint_result = NotificationURLValidator.validate_service_url_with_hint(
"http://%zz/"
)
# Then: existing parse rejection occurs before either resolver.
assert general_result is False
assert service_result == (False, "Invalid URL format (parser rejected)")
assert hint_result == (False, "Invalid URL format (parser rejected)", False)
assert general_resolver.call_count == 0
assert notification_resolver.call_count == 0
@pytest.mark.parametrize(
("url", "prepared_url"),
_ENCODED_NUMERIC_IPV4_URLS + _ENCODED_TRAILING_DOT_NUMERIC_IPV4_URLS,
)
def test_encoded_numeric_authority_matches_requests_and_rejects_before_dns(
url, prepared_url
):
# Given: public resolver answers that must not be used for encoded numeric hosts.
with (
patch(
"local_deep_research.security.ssrf_validator.socket.getaddrinfo",
return_value=_PUBLIC_ADDRINFO,
) as general_resolver,
patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=_PUBLIC_RESOLVED_IPS,
) as notification_resolver,
):
# When: requests prepares and validators receive an encoded numeric authority.
downstream_url = requests.Request("GET", url).prepare().url
general_result = validate_url(url)
service_result = NotificationURLValidator.validate_service_url(url)
# Then: downstream normalization and deterministic rejection agree.
assert downstream_url == prepared_url
assert general_result is False
assert service_result == (False, _ENCODED_NUMERIC_IPV4_ERROR)
assert general_resolver.call_count == 0
assert notification_resolver.call_count == 0
@pytest.mark.parametrize(
("url", "reason"),
(("http://2130706433/", _AMBIGUOUS_NUMERIC_IPV4_ERROR),)
+ tuple(
(url, _ENCODED_NUMERIC_IPV4_ERROR)
for url, _ in _ENCODED_NUMERIC_IPV4_URLS
+ _ENCODED_TRAILING_DOT_NUMERIC_IPV4_URLS
),
)
@pytest.mark.parametrize("allow_private_ips", (False, True))
def test_structural_numeric_rejections_never_offer_private_ip_hint(
url, reason, allow_private_ips
):
# Given: a structural numeric-host rejection under either private-IP policy.
with (
patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=_PUBLIC_RESOLVED_IPS,
) as resolver,
patch(
"local_deep_research.security.ssrf_validator.socket.getaddrinfo",
return_value=_PUBLIC_ADDRINFO,
) as general_resolver,
):
# When: hint-aware notification validation evaluates the URL.
result = NotificationURLValidator.validate_service_url_with_hint(
url, allow_private_ips=allow_private_ips
)
general_result = validate_url(url, allow_private_ips=allow_private_ips)
# Then: no operator setting is advertised and no DNS runs.
assert result == (False, reason, False)
assert general_result is False
assert resolver.call_count == 0
assert general_resolver.call_count == 0
@pytest.mark.parametrize(
"url",
(
"signal://0x7f%2e0%2e0%2e1/+15551234567/+15557654321",
"signal://0x7f000001%2e/+15551234567/+15557654321",
"signal://0x7f000001%2E/+15551234567/+15557654321",
),
)
def test_encoded_numeric_host_plugin_rejects_before_dns(url):
# Given: a host-bearing plugin URL with an encoded legacy IPv4 authority.
with patch.object(
NotificationURLValidator,
"_resolve_hostname_ips",
return_value=_PUBLIC_RESOLVED_IPS,
) as resolver:
# When: notification validation evaluates the plugin URL.
result = NotificationURLValidator.validate_service_url(url)
# Then: it is structurally rejected before host resolution.
assert result == (False, _ENCODED_NUMERIC_IPV4_ERROR)
assert resolver.call_count == 0
@pytest.mark.parametrize(
("url", "expected"),
(
("http://127%2e0%2e0%2e1/", True),
("http://user:p%40ss@127%2e0%2e0%2e1:8080/x", True),
("http://2130706433%2e?q=1", True),
("http://127.0.0.1/", False),
("http://[::1]/", False),
("https://ex%61mple.com/", False),
("https://%32%31%33%30%37%30%36%34%33%[email protected]/", False),
("https://public.example/%32%31%33%30%37%30%36%34%33%33", False),
("no-authority", False),
),
)
def test_raw_authority_detection_is_independent_of_urllib3_decoding(
url, expected
):
from local_deep_research.security.legacy_ipv4 import (
has_percent_encoded_numeric_ipv4_authority,
)
assert has_percent_encoded_numeric_ipv4_authority(url) is expected
_PERCENT_ENCODED_HOST_POLICIES = (
{},
{"allow_localhost": True},
{"allow_private_ips": True},
{"allow_localhost": True, "allow_private_ips": True},
)
@pytest.mark.parametrize("policy", _PERCENT_ENCODED_HOST_POLICIES)
@pytest.mark.parametrize(
"url",
_PERCENT_ENCODED_NON_NUMERIC_HOST_URLS
+ (
"http://ev%69l.attacker.com/v1",
"http://EV%49L.attacker.com:11434/v1",
"http://u:p@ev%69l.attacker.com./v1",
"http://ex%2fample.com/",
)
+ tuple(url for url, _ in _ENCODED_NUMERIC_IPV4_URLS)
+ tuple(url for url, _ in _ENCODED_TRAILING_DOT_NUMERIC_IPV4_URLS),
)
def test_validate_url_refuses_percent_encoded_host_under_every_policy(
url, policy
):
# Given: DNS answers that would pass every policy for the decoded name.
with patch(
"local_deep_research.security.ssrf_validator.socket.getaddrinfo",
return_value=_PUBLIC_ADDRINFO,
) as resolver:
# When: validate_url receives a percent-encoded host. urllib3 >= 2.8
# decodes it, while httpx (the LLM SDKs' client) resolves the
# escaped text, so the two would name different hosts.
result = validate_url(url, **policy)
# Then: it is refused before DNS, whatever the private-IP policy.
assert result is False
assert resolver.call_count == 0
def test_llm_base_url_with_percent_encoded_host_is_refused():
from local_deep_research.security.ssrf_validator import (
assert_base_url_safe,
)
# Given: a public DNS answer for the decoded name.
with patch(
"local_deep_research.security.ssrf_validator.socket.getaddrinfo",
return_value=_PUBLIC_ADDRINFO,
):
# When/Then: the LLM base_url guard refuses the encoded host.
with pytest.raises(ValueError):
assert_base_url_safe(
"http://ev%69l.attacker.com/v1", setting_key="llm.ollama.url"
)
# And: the plain spelling still passes.
assert (
assert_base_url_safe(
"http://evil.attacker.com/v1", setting_key="llm.ollama.url"
)
== "http://evil.attacker.com/v1"
)
@pytest.mark.parametrize(
("url", "expected"),
(
("http://ev%69l.example/", True),
("http://user:p%40ss@ex%61mple.com:8080/x", True),
("http://127%2e0%2e0%2e1/", True),
("http://a%zz.example/", True),
("http://example.com/", False),
("http://u%40x:p%3a@example.com/", False),
("http://example.com/%69?q=%69#%69", False),
("http://[fe80::1%25eth0]/", False),
("no-authority", False),
),
)
def test_raw_authority_percent_escape_detection(url, expected):
from local_deep_research.security.legacy_ipv4 import (
has_percent_escape_in_authority_host,
)
assert has_percent_escape_in_authority_host(url) is expected