|
| 1 | +"""Composable, domain-agnostic URL validation. |
| 2 | +
|
| 3 | +Foundation for screening URLs that the SDK fetches or dials (agent card |
| 4 | +endpoints, push-notification webhooks) before invocation, so that |
| 5 | +user-controlled URLs cannot reach loopback, private, or otherwise |
| 6 | +non-public destinations (SSRF). |
| 7 | +
|
| 8 | +The design follows the sketch agreed on issue #1023: a core |
| 9 | +:class:`UrlValidator` parses and (optionally) resolves the URL, runs a |
| 10 | +sequence of composable :class:`UrlValidationRule` objects, and returns |
| 11 | +the resolved URL — including the addresses the host resolved to, so |
| 12 | +callers can pin the connection to a validated address. Domain-specific |
| 13 | +wrappers (e.g. |
| 14 | +:func:`a2a.utils.push_url_validator.validate_push_notification_url`) |
| 15 | +own which fields to validate and how failures surface. |
| 16 | +""" |
| 17 | + |
| 18 | +import asyncio |
| 19 | +import ipaddress |
| 20 | +import logging |
| 21 | +import socket |
| 22 | +import urllib.parse |
| 23 | + |
| 24 | +from abc import ABC, abstractmethod |
| 25 | +from collections.abc import Awaitable, Callable, Sequence |
| 26 | +from dataclasses import dataclass |
| 27 | + |
| 28 | + |
| 29 | +logger = logging.getLogger(__name__) |
| 30 | + |
| 31 | +_Address = ipaddress.IPv4Address | ipaddress.IPv6Address |
| 32 | + |
| 33 | +Resolver = Callable[[str, int], Awaitable[list[tuple]]] |
| 34 | + |
| 35 | + |
| 36 | +class InvalidUrlError(ValueError): |
| 37 | + """Raised by UrlValidator.validate when a URL is rejected.""" |
| 38 | + |
| 39 | + |
| 40 | +@dataclass(frozen=True) |
| 41 | +class ResolvedUrl: |
| 42 | + """A parsed URL together with the addresses its host resolved to.""" |
| 43 | + |
| 44 | + raw: str |
| 45 | + parsed: urllib.parse.SplitResult |
| 46 | + addresses: tuple[_Address, ...] |
| 47 | + |
| 48 | + @property |
| 49 | + def hostname(self) -> str: |
| 50 | + """The lowercased host from the parsed URL (may be empty).""" |
| 51 | + return self.parsed.hostname or '' |
| 52 | + |
| 53 | + |
| 54 | +def _is_non_public(address: _Address) -> bool: |
| 55 | + """Whether an address is not a public unicast destination.""" |
| 56 | + return ( |
| 57 | + address.is_private |
| 58 | + or address.is_loopback |
| 59 | + or address.is_link_local |
| 60 | + or address.is_multicast |
| 61 | + or address.is_reserved |
| 62 | + or address.is_unspecified |
| 63 | + ) |
| 64 | + |
| 65 | + |
| 66 | +class UrlValidationRule(ABC): |
| 67 | + """A single composable URL check. |
| 68 | +
|
| 69 | + Implementations raise :class:`InvalidUrlError` to reject the URL; |
| 70 | + returning normally means 'continue to the next rule'. |
| 71 | + """ |
| 72 | + |
| 73 | + @abstractmethod |
| 74 | + async def check(self, url: ResolvedUrl) -> None: |
| 75 | + """Check the resolved URL. Raise InvalidUrlError to reject.""" |
| 76 | + |
| 77 | + |
| 78 | +class RequireScheme(UrlValidationRule): |
| 79 | + """Rejects URLs whose scheme is not one of the allowed values.""" |
| 80 | + |
| 81 | + def __init__(self, schemes: Sequence[str]) -> None: |
| 82 | + self._schemes = tuple(scheme.lower() for scheme in schemes) |
| 83 | + |
| 84 | + async def check(self, url: ResolvedUrl) -> None: |
| 85 | + """Reject the URL when its scheme is not allowed.""" |
| 86 | + if url.parsed.scheme not in self._schemes: |
| 87 | + raise InvalidUrlError( |
| 88 | + f'Scheme {url.parsed.scheme!r} is not allowed; expected one ' |
| 89 | + f'of: {", ".join(self._schemes)}' |
| 90 | + ) |
| 91 | + |
| 92 | + |
| 93 | +class BlockPrivateNetworks(UrlValidationRule): |
| 94 | + """Rejects hosts resolving to non-public addresses. |
| 95 | +
|
| 96 | + Blocks loopback, private, link-local, multicast, reserved, and |
| 97 | + unspecified destinations (e.g. 169.254.169.254 cloud metadata, |
| 98 | + internal services). Deployments that legitimately use private |
| 99 | + networks can exempt specific hostnames via ``allow_hosts`` or whole |
| 100 | + ranges via ``allow_cidrs``. |
| 101 | + """ |
| 102 | + |
| 103 | + def __init__( |
| 104 | + self, |
| 105 | + *, |
| 106 | + allow_hosts: Sequence[str] = (), |
| 107 | + allow_cidrs: Sequence[str] = (), |
| 108 | + ) -> None: |
| 109 | + self._allow_hosts = frozenset(allow_hosts) |
| 110 | + self._allow_cidrs = tuple( |
| 111 | + ipaddress.ip_network(cidr, strict=False) for cidr in allow_cidrs |
| 112 | + ) |
| 113 | + |
| 114 | + def _is_allowed(self, url: ResolvedUrl, address: _Address) -> bool: |
| 115 | + if url.hostname in self._allow_hosts: |
| 116 | + return True |
| 117 | + return any(address in network for network in self._allow_cidrs) |
| 118 | + |
| 119 | + async def check(self, url: ResolvedUrl) -> None: |
| 120 | + """Reject the URL when any resolved address is non-public.""" |
| 121 | + for address in url.addresses: |
| 122 | + if self._is_allowed(url, address): |
| 123 | + continue |
| 124 | + if _is_non_public(address): |
| 125 | + raise InvalidUrlError( |
| 126 | + f'Host {url.hostname!r} resolves to a non-public ' |
| 127 | + f'address: {address}' |
| 128 | + ) |
| 129 | + |
| 130 | + |
| 131 | +async def _default_resolver(host: str, port: int) -> list[tuple]: |
| 132 | + loop = asyncio.get_running_loop() |
| 133 | + return await loop.getaddrinfo(host, port, type=socket.SOCK_STREAM) |
| 134 | + |
| 135 | + |
| 136 | +class UrlValidator: |
| 137 | + """Parses and optionally resolves a URL, then runs composable rules. |
| 138 | +
|
| 139 | + Rules run in order; the first rule that raises :class:`InvalidUrlError` |
| 140 | + rejects the URL. With ``resolve=True`` (default) the host is resolved |
| 141 | + via the running event loop's ``getaddrinfo`` before rules run, so |
| 142 | + IP-based rules (e.g. :class:`BlockPrivateNetworks`) see every address |
| 143 | + the host maps to — and resolution failures fail closed. |
| 144 | + """ |
| 145 | + |
| 146 | + def __init__( |
| 147 | + self, |
| 148 | + rules: Sequence[UrlValidationRule] = (), |
| 149 | + *, |
| 150 | + resolve: bool = True, |
| 151 | + resolver: Resolver | None = None, |
| 152 | + ) -> None: |
| 153 | + self._rules = tuple(rules) |
| 154 | + self._resolve = resolve |
| 155 | + self._resolver = resolver or _default_resolver |
| 156 | + |
| 157 | + async def validate(self, url: str) -> ResolvedUrl: |
| 158 | + """Validate ``url`` and return it with its resolved addresses.""" |
| 159 | + try: |
| 160 | + parsed = urllib.parse.urlsplit(url) |
| 161 | + port = parsed.port or (443 if parsed.scheme == 'https' else 80) |
| 162 | + except ValueError as e: |
| 163 | + raise InvalidUrlError(f'URL is unparseable: {url}') from e |
| 164 | + host = parsed.hostname |
| 165 | + if not host: |
| 166 | + raise InvalidUrlError(f'URL has no hostname: {url}') |
| 167 | + |
| 168 | + addresses: tuple[_Address, ...] = () |
| 169 | + if self._resolve: |
| 170 | + try: |
| 171 | + infos = await self._resolver(host, port) |
| 172 | + except OSError as e: |
| 173 | + raise InvalidUrlError( |
| 174 | + f'Host {host!r} could not be resolved: {url}' |
| 175 | + ) from e |
| 176 | + resolved: list[_Address] = [] |
| 177 | + for info in infos: |
| 178 | + raw_ip = str(info[4][0]).split('%', maxsplit=1)[0] |
| 179 | + try: |
| 180 | + resolved.append(ipaddress.ip_address(raw_ip)) |
| 181 | + except ValueError as e: |
| 182 | + raise InvalidUrlError( |
| 183 | + f'Host {host!r} resolved to an unparseable address' |
| 184 | + ) from e |
| 185 | + addresses = tuple(resolved) |
| 186 | + |
| 187 | + resolved_url = ResolvedUrl(raw=url, parsed=parsed, addresses=addresses) |
| 188 | + for rule in self._rules: |
| 189 | + await rule.check(resolved_url) |
| 190 | + return resolved_url |
| 191 | + |
| 192 | + |
| 193 | +class PushNotificationUrlValidator: |
| 194 | + """Domain wrapper validating push-notification webhook URLs. |
| 195 | +
|
| 196 | + Keeps the boolean, fail-closed contract of |
| 197 | + :func:`a2a.utils.push_url_validator.validate_push_notification_url`. |
| 198 | + """ |
| 199 | + |
| 200 | + def __init__(self) -> None: |
| 201 | + self._validator = UrlValidator( |
| 202 | + rules=(RequireScheme(('http', 'https')), BlockPrivateNetworks()) |
| 203 | + ) |
| 204 | + |
| 205 | + async def validate(self, url: str) -> bool: |
| 206 | + """Return True if the webhook URL is safe to fetch.""" |
| 207 | + try: |
| 208 | + await self._validator.validate(url) |
| 209 | + except InvalidUrlError as e: |
| 210 | + logger.warning('Push-notification URL rejected: %s (%s)', url, e) |
| 211 | + return False |
| 212 | + return True |
| 213 | + |
| 214 | + |
| 215 | +class AgentCardUrlValidator: |
| 216 | + """Domain wrapper validating URLs advertised on an agent card. |
| 217 | +
|
| 218 | + Covers the service endpoint and additional interfaces, screening |
| 219 | + them before the SDK dials them. By default only http/https on |
| 220 | + public addresses are allowed; deployments that legitimately target |
| 221 | + private networks can pass ``allow_private_networks=True``. |
| 222 | + """ |
| 223 | + |
| 224 | + def __init__( |
| 225 | + self, |
| 226 | + *, |
| 227 | + allowed_schemes: Sequence[str] = ('http', 'https'), |
| 228 | + allow_private_networks: bool = False, |
| 229 | + resolver: Resolver | None = None, |
| 230 | + ) -> None: |
| 231 | + rules: list[UrlValidationRule] = [RequireScheme(allowed_schemes)] |
| 232 | + if not allow_private_networks: |
| 233 | + rules.append(BlockPrivateNetworks()) |
| 234 | + self._validator = UrlValidator(rules, resolver=resolver) |
| 235 | + |
| 236 | + async def validate(self, url: str) -> ResolvedUrl: |
| 237 | + """Validate and return the resolved URL (addresses included).""" |
| 238 | + return await self._validator.validate(url) |
0 commit comments