security(adagents): pin DNS to prevent rebinding on SSRF gate

[bokelley]

Context

The SSRF gate added in #753 (_check_safe_host at src/adcp/adagents.py:178) validates publisher_domain and authoritative_location hostnames against IP literals and well-known internal hostnames at the string level. It does not pin DNS resolution.

A hostile DNS server can return a public IP on the first lookup (passes the gate) and a private IP — 127.0.0.1, 10.0.0.5, 169.254.169.254 — on the second lookup at connect time. This is DNS rebinding, the standard escape for string-level SSRF gates.

This was explicitly called out as deferred in the PR body of #753:

DNS pinning to harden against rebinding (security H1) — needs a custom httpx transport.

And in the docstring of _check_safe_host itself:

This is a string-level gate — it catches IP literals and well-known private hostnames, but does not pin DNS resolution. A hostile DNS server that returns a public IP on first lookup and a private IP on connect (DNS rebinding) is out of scope; see security follow-up.

What needs to change

The SDK should resolve each outbound hostname once, validate every returned address against the IP class gate (_check_safe_host already covers IPv4/IPv6 literals — extract its IP-block logic into a shared helper), and pin the connection to the validated IP.

The standard pattern in httpx:

import socket
import httpx

async def _safe_get(url: str, timeout: float, ...) -> httpx.Response:
    parsed = urlparse(url)
    hostname = parsed.hostname or ""
    # Single resolve via getaddrinfo
    infos = socket.getaddrinfo(hostname, parsed.port or 443, type=socket.SOCK_STREAM)
    addresses = {info[4][0] for info in infos}
    for addr in addresses:
        _check_safe_host(addr, "resolved address")  # raises on private/reserved
    # Pin via httpx transport that overrides the resolver
    transport = httpx.HTTPTransport(local_address=...)  # or a custom resolver
    ...

A cleaner production approach is a custom httpx.AsyncHTTPTransport subclass that overrides connection establishment to use the pre-resolved IP, with the Host: header preserved.

Surface affected

Every outbound HTTP call in src/adcp/adagents.py constructed from publisher-controlled input:

• _resolve_direct → _fetch_adagents_url → _stream_capped (publisher_domain + authoritative_location)
• _fetch_ads_txt_managerdomains (publisher_domain + manager_domain post-fix(adagents): disable follow_redirects on ads.txt MANAGERDOMAIN fetch #754)
• _try_managerdomain_fallback (manager_domain resolved from ads.txt)

The same transport should be threaded through all three.

Out of scope for this issue

• Connection-level timeouts / asyncio.wait_for total bound (separate follow-up — security M1 in the feat(adagents): publisher_domains compact form, revoked_publisher_domains, streaming fetch caps (closes #729) #753 review).
• JSON parse depth guard (security M3 in the feat(adagents): publisher_domains compact form, revoked_publisher_domains, streaming fetch caps (closes #729) #753 review).

Acceptance criteria

• Custom httpx.AsyncHTTPTransport (or equivalent) that resolves once, gates every returned address, and connects to the pre-resolved IP.
• Used by both the streaming adagents.json path and the ads.txt MANAGERDOMAIN path.
• Test: simulate a rebinding DNS that returns a public IP first then a private IP — the SDK rejects on the second lookup (or, with pinned resolution, never re-resolves).
• Test: per-hop resolution remains correct for legitimately public targets across pointer + authoritative hops.

Related

• PR feat(adagents): publisher_domains compact form, revoked_publisher_domains, streaming fetch caps (closes #729) #753 (closed the string-level gate)
• PR fix(adagents): disable follow_redirects on ads.txt MANAGERDOMAIN fetch #754 (extended follow_redirects=False to ads.txt)
• Security review of feat(adagents): publisher_domains compact form, revoked_publisher_domains, streaming fetch caps (closes #729) #753 — round-1 H1, round-2 verified deferred

[bokelley]

Status refresh: current main now has a DNS resolve-and-gate pre-check (_dns_validate_host) and tests for private/mixed resolved addresses, so the original string-only gap is reduced. This issue should remain open, though: the acceptance criterion is stronger DNS pinning/equivalent connection behavior. The current helper still documents a residual rebinding window because httpx can resolve again at connect time after the pre-check. Next action is a pinned transport or equivalent for the adagents and ads.txt fetch paths.