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.

9.8 KB
Raw Blame
"""Set-membership tripwire for the always-blocked metadata IPs.

``ALWAYS_BLOCKED_METADATA_IPS`` is the SSRF chain's absolute floor:
every entry is a cloud instance-metadata endpoint, and the review
contract says any **removal** is Critical while additions are fine.
Behavioral coverage also needs a set-membership pin: a consolidation
refactor that drops a less frequently exercised provider endpoint must
fail even when another metadata test still passes.

The IPv6 member deserves its own pin: ``fd00:ec2::254`` is a ULA,
not an IPv4-mapped or NAT64-wrapped form of the IPv4 entries, so no
derived check covers it — it must stay listed explicitly or it is
reachable under ``allow_private_ips=True`` (which permits fc00::/7).
The same holds for GCP's ``fd20:ce::254``. Azure's ``168.63.129.16`` is
public address space, so no private-range check covers it either.
"""

from __future__ import annotations

import ipaddress
import itertools

import pytest

from local_deep_research.security.ssrf_validator import (
    ALWAYS_BLOCKED_METADATA_IPS,
    is_ip_blocked,
)

#: Every endpoint documented for the set (additions to the production
#: set are fine; these may never leave it).
DOCUMENTED_METADATA_IPS = frozenset(
    {
        "169.254.169.254",  # AWS IMDSv1/v2, Azure, OCI, DigitalOcean
        "169.254.170.2",  # AWS ECS task metadata v3
        "169.254.170.23",  # AWS EKS Pod Identity credentials
        "169.254.0.23",  # Tencent Cloud
        "100.100.100.200",  # AlibabaCloud
        "192.0.0.192",  # Oracle Compute Classic IMDS
        "168.63.129.16",  # Azure WireServer
        "fd00:ec2::254",  # AWS IMDS over IPv6
        "fd00:ec2::23",  # AWS EKS Pod Identity credentials over IPv6
        "fd20:ce::254",  # GCP metadata server over IPv6
        "169.254.42.42",  # Scaleway instance metadata
        "fd00:42::42",  # Scaleway instance metadata over IPv6
        "fd00:a9fe:a9fe::1",  # Akamai / Linode metadata over IPv6
        "fd00:c1::a9fe:a9fe",  # Oracle Cloud (OCI) IMDS over IPv6
        "fe80::a9fe:a9fe",  # OpenStack Nova / Hetzner metadata over IPv6
    }
)


class TestMetadataIpSetTripwire:
    def test_every_documented_metadata_ip_stays_in_the_set(self):
        missing = DOCUMENTED_METADATA_IPS - ALWAYS_BLOCKED_METADATA_IPS
        assert missing == frozenset(), (
            f"metadata endpoints removed from the always-blocked set: "
            f"{sorted(missing)} — any removal is Critical"
        )

    def test_the_ipv6_imds_entry_is_explicit(self):
        """fd00:ec2::254 is a ULA, not derivable from the IPv4 entries
        or the NAT64 check; dropping the explicit listing reopens it
        under allow_private_ips."""
        assert "fd00:ec2::254" in ALWAYS_BLOCKED_METADATA_IPS

    @pytest.mark.parametrize(
        "ip", sorted(DOCUMENTED_METADATA_IPS), ids=lambda v: v.replace(":", "-")
    )
    def test_each_member_stays_blocked_under_the_permissive_posture(self, ip):
        """The absolute floor: blocked even when localhost AND private
        ranges are allowed — the posture that exists precisely so
        users can point the app at Ollama/LM Studio/vLLM."""
        assert is_ip_blocked(
            ip, allow_localhost=True, allow_private_ips=True
        ), f"{ip} is not blocked under the permissive posture"

    def test_the_set_only_contains_metadata_endpoints_shape(self):
        """Sanity for additions: every member parses as an IP literal,
        so the set cannot silently drift into hostname entries the
        IP-comparison path would never match."""
        import ipaddress

        for member in ALWAYS_BLOCKED_METADATA_IPS:
            ipaddress.ip_address(member)


#: Every combination of the is_ip_blocked policy flags. allow_nat64 is
#: passed explicitly so the result never depends on the process env.
_FLAG_COMBOS = [
    dict(
        allow_localhost=lh,
        allow_private_ips=priv,
        allow_nat64=nat64,
        block_link_local=ll,
    )
    for lh, priv, nat64, ll in itertools.product([False, True], repeat=4)
]
_FLAG_IDS = [
    "lh{allow_localhost:d}-priv{allow_private_ips:d}-nat64{allow_nat64:d}"
    "-ll{block_link_local:d}".format(**c)
    for c in _FLAG_COMBOS
]


def _nat64_96(v4: str) -> str:
    """RFC 6052 /96 well-known-prefix form (64:ff9b::/96) of ``v4``."""
    return str(
        ipaddress.IPv6Address(
            bytes.fromhex("0064ff9b0000000000000000")
            + ipaddress.IPv4Address(v4).packed
        )
    )


def _nat64_48(v4: str) -> str:
    """RFC 6052 §2.2 /48 local-use form (64:ff9b:1::/48) of ``v4``: the
    IPv4 sits at bytes 6, 7, 9, 10 around the reserved octet 8."""
    packed = ipaddress.IPv4Address(v4).packed
    raw = bytearray(16)
    raw[0:6] = bytes.fromhex("0064ff9b0001")
    raw[6:8] = packed[0:2]
    raw[9:11] = packed[2:4]
    return str(ipaddress.IPv6Address(bytes(raw)))


class TestAzureWireServerAndGcpIpv6Metadata:
    """168.63.129.16 (Azure WireServer) and fd20:ce::254 (GCP metadata
    over IPv6) are blocked under every flag combination."""

    @pytest.mark.parametrize("flags", _FLAG_COMBOS, ids=_FLAG_IDS)
    @pytest.mark.parametrize(
        "ip", ["168.63.129.16", "fd20:ce::254"], ids=["azure", "gcp-v6"]
    )
    def test_blocked_under_every_flag_combination(self, ip, flags):
        assert is_ip_blocked(ip, **flags) is True

    @pytest.mark.parametrize(
        "ip",
        [
            "FD20:CE::254",
            "fd20:00ce:0000:0000:0000:0000:0000:0254",
            "fd20:ce::254%eth0",
        ],
    )
    def test_gcp_v6_textual_variants_blocked_under_allow_private(self, ip):
        assert (
            is_ip_blocked(
                ip,
                allow_localhost=True,
                allow_private_ips=True,
                allow_nat64=True,
            )
            is True
        )

    @pytest.mark.parametrize("flags", _FLAG_COMBOS, ids=_FLAG_IDS)
    @pytest.mark.parametrize(
        "wrapped",
        [
            "::ffff:168.63.129.16",
            _nat64_96("168.63.129.16"),
            _nat64_48("168.63.129.16"),
        ],
        ids=["v4-mapped", "nat64-96", "nat64-48"],
    )
    def test_wrapped_azure_wireserver_blocked(self, wrapped, flags):
        """IPv4-mapped and NAT64-wrapped forms resolve to the same
        destination, including under the allow_nat64 opt-in."""
        assert is_ip_blocked(wrapped, **flags) is True

    @pytest.mark.parametrize("ip", ["168.63.129.15", "168.63.129.17"])
    def test_neighbouring_public_addresses_stay_allowed(self, ip):
        """Positive control: only the exact literal is blocked."""
        assert is_ip_blocked(ip) is False
        assert is_ip_blocked(ip, allow_private_ips=True) is False

    def test_neighbouring_ula_stays_allowed_under_allow_private(self):
        """Positive control: fd20:ce::253 is ordinary ULA space, allowed
        under the private-IP opt-in like any other fc00::/7 address."""
        assert is_ip_blocked("fd20:ce::253", allow_private_ips=True) is False

    def test_neighbouring_wrapped_address_stays_allowed(self):
        """Positive control for the wrapped forms: the neighbour's mapped
        and NAT64 forms are not blocked when their direct form is not."""
        assert (
            is_ip_blocked("::ffff:168.63.129.17", allow_private_ips=True)
            is False
        )
        assert (
            is_ip_blocked(_nat64_96("168.63.129.17"), allow_nat64=True) is False
        )


#: Provider metadata endpoints that the permissive LLM-provider posture
#: would otherwise admit: Scaleway's IPv4 address is ordinary link-local
#: (accepted for provider URLs because rootless Podman maps
#: host.containers.internal into 169.254.0.0/16), the IPv6 ULAs fall in
#: fc00::/7 and fe80::a9fe:a9fe is IPv6 link-local.
_LINK_LOCAL_AND_ULA_METADATA = [
    "169.254.42.42",
    "fd00:42::42",
    "fd00:a9fe:a9fe::1",
    "fd00:c1::a9fe:a9fe",
    "fe80::a9fe:a9fe",
]


class TestLinkLocalAndUlaProviderMetadata:
    """Each entry is blocked under every flag combination, including the
    allow_private_ips=True / block_link_local=False posture of the LLM
    provider guard, where only the explicit listing blocks it."""

    @pytest.mark.parametrize("flags", _FLAG_COMBOS, ids=_FLAG_IDS)
    @pytest.mark.parametrize(
        "ip", _LINK_LOCAL_AND_ULA_METADATA, ids=lambda v: v.replace(":", "-")
    )
    def test_blocked_under_every_flag_combination(self, ip, flags):
        assert is_ip_blocked(ip, **flags) is True

    @pytest.mark.parametrize(
        "ip",
        [
            "fe80::a9fe:a9fe%eth0",
            "fe80::a9fe:a9fe%2",
            "FE80:0000:0000:0000:0000:0000:A9FE:A9FE",
            "FD00:42::42",
            "fd00:0042:0000:0000:0000:0000:0000:0042%eth0",
            "fd00:a9fe:a9fe:0:0:0:0:1",
            "FD00:C1::A9FE:A9FE",
        ],
    )
    def test_textual_and_scoped_variants_blocked_under_allow_private(self, ip):
        assert (
            is_ip_blocked(
                ip,
                allow_localhost=True,
                allow_private_ips=True,
                allow_nat64=True,
            )
            is True
        )

    @pytest.mark.parametrize("flags", _FLAG_COMBOS, ids=_FLAG_IDS)
    @pytest.mark.parametrize(
        "wrapped",
        [
            "::ffff:169.254.42.42",
            _nat64_96("169.254.42.42"),
            _nat64_48("169.254.42.42"),
        ],
        ids=["v4-mapped", "nat64-96", "nat64-48"],
    )
    def test_wrapped_scaleway_blocked(self, wrapped, flags):
        assert is_ip_blocked(wrapped, **flags) is True

    @pytest.mark.parametrize(
        "ip", ["169.254.42.41", "169.254.1.2", "fd00:42::43", "fe80::1"]
    )
    def test_neighbouring_link_local_and_ula_stay_allowed(self, ip):
        """Positive control: only the exact literals are blocked. The
        neighbours stay allowed under the provider posture, so a host-side
        backend at 169.254.1.2 (rootless Podman) keeps working."""
        assert (
            is_ip_blocked(ip, allow_localhost=True, allow_private_ips=True)
            is False
        )