fix(security): WebClient DNS rebinding TOCTOU in SSRF check

[kovtcharov-amd]

Problem

WebClient._validate_host_ip() in src/gaia/web/client.py resolves the hostname via socket.getaddrinfo(), validates the IP is public, then hands the URL to requests, which resolves the hostname again on connect. A carefully timed DNS rebind (low-TTL record) can pass validation with a public IP and connect to an RFC1918 address (e.g. 127.0.0.1, 169.254.169.254).

Risk Assessment

Low for GAIA's threat model (local-first desktop agent). Exploitation requires:

1. Attacker controls a DNS record the user visits
2. Attacker times the TTL rotation between validation and connect
3. The target internal service must be reachable from the user's machine

Fix Options

1. Pin resolved IP: Resolve once, inject the IP into the connection via a custom urllib3 HTTPAdapter or Host header rewrite
2. Re-validate post-connect: Check the peer address from the established socket against the blocklist
3. Document the limitation: Add a comment noting the window (already done in PR review comments)

Option 1 is the most robust but requires lower-level socket control than requests exposes cleanly.

Files

• src/gaia/web/client.py — _validate_host_ip() (~line 132) and _request() (~line 196)

Identified during code review of #495, acknowledged as acceptable tradeoff by 3 independent reviewers.

[github-actions]

Confirmed the issue. The relevant code lives in PR #495 (branch feature/chat-agent-file-navigation, not yet on main):

• src/gaia/web/client.py:132 — _validate_host_ip() calls socket.getaddrinfo(hostname, None) and rejects private/loopback/link-local/reserved/multicast IPs.
• src/gaia/web/client.py:183 — _request() then passes the original url (hostname intact) into self._session.request(...), so requests re-resolves on connect. That's the TOCTOU window.

🟡 Real but low-severity for GAIA's threat model. The agent only follows URLs the user (or a tool) hands it, and 169.254.169.254 is the most interesting target on a desktop (no IMDS) — but it does protect users on cloud VMs / dev boxes, so it's worth fixing.

Recommended approach

Option 1 (pin resolved IP) is the right one. Options 2 (post-connect peer-address check) and 3 (document only) both leave a window where a request body, auth header, or cookie has already been sent to the rebind target before we notice. Pin-on-validate is the only fix that prevents the connection in the first place.

Sketch — works inside requests's public surface without forking urllib3:

# In _validate_host_ip, return the resolved IP instead of None
def _resolve_and_validate(self, hostname: str) -> str:
    results = socket.getaddrinfo(hostname, None)
    # ... existing checks ...
    return results[0][4][0]  # first validated address

# In _request, swap hostname for IP and preserve Host header for SNI/vhosts
ip = self._resolve_and_validate(hostname)
pinned_url = url.replace(f"//{hostname}", f"//{ip}", 1)
kwargs.setdefault("headers", {})["Host"] = hostname
# For HTTPS, also pass `verify=` with SNI hostname intact via a custom adapter

The HTTPS SNI/cert-validation piece is the gotcha — naively swapping to an IP breaks TLS hostname verification. The clean way is a small HTTPAdapter subclass that resolves once in send() and reuses the validated IP for the actual socket.connect(), while keeping SNI = hostname. There's an established pattern for this (see e.g. requests-toolbelt's host-header SSL adapter or the pinning recipe — adapt to your blocklist).

Each redirect hop is also a TOCTOU

While you're in there: _request() follows redirects manually (good — it re-runs validate_url on each hop, I assume). Make sure the same pin-on-validate logic is applied per hop, not just on the initial URL — otherwise hop 2's Location: can rebind even if hop 1 didn't.

Test coverage

Worth adding to tests/unit/test_web_client_edge_cases.py:

• Mock socket.getaddrinfo to return a public IP first, then 127.0.0.1 on second call → connection should still go to the first (pinned) address.
• HTTPS request with pinned IP should still verify the cert against the original hostname (no verify=False regressions).

Process

Since PR #495 is still open and the file is brand-new, addressing this in PR #495 is cleaner than a follow-up — there's no "before/after" history to preserve. If the reviewers already accepted the tradeoff and want this as follow-up, that's fine too; this issue is a sufficient tracker.

[theonlychant]

I'd like to work on this. Planning to implement Option 1 (pin resolved IP via a custom urllib3 HTTPAdapter) to eliminate the TOCTOU window - - resolve once in _validate_host_ip(), return the IP, then mount a _PinnedIPAdapter in _request() that forces the connection to that IP while preserving the original Host header. Building on top of the WebClient from #495. Let me know if you'd prefer a different approach.