Skip to content

Commit 20d1a8c

Browse files
committed
feat(utils): add composable UrlValidator for URL screening
Implements the UrlValidator sketch agreed on issue #1023: a core validator parses and resolves a URL, runs composable UrlValidationRule objects (RequireScheme, BlockPrivateNetworks with allow_hosts/allow_cidrs), and returns a ResolvedUrl that carries the addresses the host resolved to, so callers can pin connections to a validated address and guard against DNS rebinding. Domain wrappers: - PushNotificationUrlValidator: validate_push_notification_url now delegates to the composable stack; its boolean, fail-closed contract is unchanged (all existing SSRF tests pass unmodified). - AgentCardUrlValidator: new, validating agent card URLs (http/https, public addresses by default, private networks opt-in). Rules and the resolver are individually injectable so deployments can compose custom policies. Issue #1023 scopes this to the validator as the foundation for #975 and #786. Refs #1023 Signed-off-by: andy <linux2011@qq.com>
1 parent 494a8ec commit 20d1a8c

3 files changed

Lines changed: 563 additions & 53 deletions

File tree

Lines changed: 16 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,22 @@
1-
"""Shared policy for screening client-supplied push-notification URLs."""
1+
"""Backward-compatible entry point for push-notification URL screening.
2+
3+
The implementation now lives in :mod:`a2a.utils.url_validation` as a
4+
composition of :class:`a2a.utils.url_validation.UrlValidator` rules
5+
(issue #1023); this module keeps the historical boolean, fail-closed
6+
entry point.
7+
"""
28

3-
import asyncio
4-
import ipaddress
59
import logging
6-
import socket
7-
import urllib.parse
810

11+
from a2a.utils.url_validation import (
12+
InvalidUrlError,
13+
PushNotificationUrlValidator,
14+
)
915

10-
logger = logging.getLogger(__name__)
1116

17+
logger = logging.getLogger(__name__)
1218

13-
def _ip_is_blocked(ip_str: str) -> bool:
14-
"""Whether an address is not a public unicast destination."""
15-
try:
16-
addr = ipaddress.ip_address(ip_str.split('%', maxsplit=1)[0])
17-
except ValueError:
18-
return True
19-
return (
20-
addr.is_private
21-
or addr.is_loopback
22-
or addr.is_link_local
23-
or addr.is_multicast
24-
or addr.is_reserved
25-
or addr.is_unspecified
26-
)
19+
_validator = PushNotificationUrlValidator()
2720

2821

2922
async def validate_push_notification_url(url: str) -> bool:
@@ -47,37 +40,7 @@ async def validate_push_notification_url(url: str) -> bool:
4740
screening).
4841
"""
4942
try:
50-
parsed = urllib.parse.urlparse(url)
51-
explicit_port = parsed.port
52-
except ValueError:
53-
logger.warning('Push-notification URL is unparseable: %s', url)
54-
return False
55-
if parsed.scheme not in ('http', 'https'):
56-
logger.warning(
57-
'Push-notification URL scheme %r is not http/https: %s',
58-
parsed.scheme,
59-
url,
60-
)
61-
return False
62-
host = parsed.hostname
63-
if not host:
64-
logger.warning('Push-notification URL has no hostname: %s', url)
65-
return False
66-
port = explicit_port or (443 if parsed.scheme == 'https' else 80)
67-
try:
68-
loop = asyncio.get_running_loop()
69-
infos = await loop.getaddrinfo(host, port, type=socket.SOCK_STREAM)
70-
except OSError:
71-
logger.warning(
72-
'Push-notification host %r could not be resolved: %s', host, url
73-
)
43+
return await _validator.validate(url)
44+
except InvalidUrlError:
45+
logger.warning('Push-notification URL rejected: %s', url)
7446
return False
75-
for info in infos:
76-
if _ip_is_blocked(str(info[4][0])):
77-
logger.warning(
78-
'Push-notification host %r resolves to a non-public address: %s',
79-
host,
80-
url,
81-
)
82-
return False
83-
return True

‎src/a2a/utils/url_validation.py‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
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

Comments
 (0)