feat: add URL validation infrastructure for SSRF protection

[Linux2010]

Summary

Implements composable URL validation rules to protect against SSRF attacks when fetching Agent Cards and processing webhook URLs. Closes #1023.

Changes

New files

• src/a2a/utils/url_validator.py — Core implementation (251 lines)
• tests/utils/test_url_validator.py — 31 test cases, 96% module coverage

Modified files

• src/a2a/utils/__init__.py — Export new public symbols

Implementation Details

Public API

Symbol	Description
InvalidUrlError	Exception raised when a URL is rejected by validation
ResolvedUrl	Frozen dataclass: original URL + parsed result + resolved IP addresses
UrlValidationRule	Abstract base class for composable validation rules
RequireScheme	Rule restricting allowed URL schemes (e.g. HTTPS only)
BlockPrivateNetworks	Rule rejecting private/loopback addresses with allow_hosts and allow_cidrs exemptions
UrlValidator	Core validator: resolve → pin → validate through configurable rule chain

Design (per issue #1023)

• Composable rules — validation logic is split into independent UrlValidationRule implementations run in order; a rule raises InvalidUrlError to reject, returning means "continue"
• Pinned addresses — UrlValidator.validate resolves DNS and returns resolved addresses so callers can pin the connection to a specific IP, preventing DNS-rebinding attacks
• Configurable strictness — BlockPrivateNetworks accepts allow_hosts and allow_cidrs so deployments that legitimately use private networks can opt in
• Defense in depth — BlockPrivateNetworks also inspects the host portion of the URL as a literal IP address when resolve=False is used, so http://127.0.0.1/ is still rejected even without DNS resolution

Review Feedback Addressed (commit 175f198)

1. Async resolver support: _resolve_host now checks inspect.isawaitable(result) and awaits if the custom resolver returns a coroutine — supports both sync and async resolvers (e.g. aiodns)
2. Consistent error type: ValueError from ipaddress.ip_address() on invalid resolver output is now caught and re-raised as InvalidUrlError, ensuring all validation failures use the same exception type
3. IPv6 bracket normalization: _normalize_host() strips surrounding square brackets from IPv6 literals (e.g. [::1] → ::1), ensuring consistent matching in allow_hosts

Test Plan

• 31/31 unit tests pass
• ruff check passes
• ruff format passes
• ty check passes
• Overall coverage 93% (≥88% threshold)
• Module coverage 96%
• Full test suite: 1377 passed

Security Impact

• Before: No URL validation — SSRF via agent card URLs or webhook URLs possible
• After: Composable rules enforce scheme restrictions and block private network access with configurable exemptions

[gemini-code-assist]

Code Review

This pull request introduces a composable URL validation utility (UrlValidator) designed for SSRF protection, along with validation rules like RequireScheme and BlockPrivateNetworks, and comprehensive tests. The review feedback suggests several robust improvements: supporting asynchronous custom resolvers by checking and awaiting coroutines, catching raw ValueError exceptions during IP address parsing to consistently raise InvalidUrlError, and normalizing IPv6 hostnames by stripping square brackets to ensure reliable matching in allow_hosts.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Since UrlValidator is designed to be used in an asynchronous context (with validate being an async method), custom resolvers will often need to perform asynchronous I/O (e.g., using aiodns). Currently, the custom resolver is called synchronously. We should support both synchronous and asynchronous resolvers by checking if the returned result is a coroutine and awaiting it if so.

Suggested change

	if self._resolver is not None:
	resolved = self._resolver(host, port)
	if self._resolver is not None:
	resolved = self._resolver(host, port)
	if asyncio.iscoroutine(resolved):
	resolved = await resolved

[Linux2010]

Good catch! This has been addressed in commit 175f198 ("fix: address PR #1117 review feedback"). The _resolve_host method now checks inspect.isawaitable(result) and awaits the result if it is a coroutine, supporting both sync and async custom resolvers (e.g. aiodns). A test (test_async_resolver_is_awaited) was also added to verify this behavior.

[gemini-code-assist]

If a custom resolver returns an invalid IP address string, ipaddress.ip_address will raise a raw ValueError. To adhere to the class's contract that all validation/resolution failures raise InvalidUrlError, we should catch ValueError here and raise InvalidUrlError directly without instantiating it.

Suggested change

	addresses = tuple(
	dict.fromkeys(
	addr
	if isinstance(
	addr, (ipaddress.IPv4Address, ipaddress.IPv6Address)
	)
	else ipaddress.ip_address(addr)
	for addr in resolved
	)
	)
	try:
	addresses = tuple(
	dict.fromkeys(
	addr
	if isinstance(
	addr, (ipaddress.IPv4Address, ipaddress.IPv6Address)
	)
	else ipaddress.ip_address(addr)
	for addr in resolved
	)
	)
	except ValueError:
	raise InvalidUrlError

References

1. Raise exception classes directly, without instantiating them (e.g., raise MyError instead of raise MyError()).

[Linux2010]

Fixed in commit 175f198. The _resolve_host method now wraps ipaddress.ip_address() in a try/except that catches ValueError and re-raises as InvalidUrlError, ensuring all validation/resolution failures consistently raise InvalidUrlError. Test: test_resolver_returning_invalid_address_raises_invalid_url_error.

[gemini-code-assist]

If a user configures an IPv6 address in allow_hosts using the standard bracketed URL notation (e.g., "[::1]"), it won't match the parsed hostname because urllib.parse.urlsplit strips the square brackets from IPv6 literals. Normalizing the host by stripping surrounding square brackets ensures consistent matching for IPv6 addresses.

Suggested change

	def _normalize_host(host: str) -> str:
	return host.rstrip('.').lower()
	def _normalize_host(host: str) -> str:
	normalized = host.rstrip('.').lower()
	if normalized.startswith('[') and normalized.endswith(']'):
	return normalized[1:-1]
	return normalized

[Linux2010]

Fixed in commit 175f198. The _normalize_host() helper now strips surrounding square brackets from IPv6 literals (e.g. [::1] → ::1), ensuring consistent matching when users configure allow_hosts with bracketed notation. Test: test_block_private_networks_allow_ipv6_with_brackets.

[github-actions]

🧪 Code Coverage (vs main)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/utils/url_validator.py (new)	—	96.23%	—
Total	92.97%	93.01%	🟢 +0.04%

Generated by coverage-comment.yml