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.

14.2 KB
Raw Blame
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