feat(cluster): hostname-aware SSRF guard for cluster base_url

[SoundMindsAI]

Summary

Closes the SSRF hostname-bypass in the cluster base_url validator (the most critical finding from the codebase security review, #504). The prior guard only inspected literal IPs, so in the hardened posture (RELYLOOP_ALLOW_PRIVATE_CLUSTERS=False) any DNS hostname — metadata.google.internal, an internal name, or anything resolving to a private/loopback/link-local IP — sailed through unchecked and got probed.

• Pure classifier (backend/app/domain/cluster/url_policy.py): is_blocked_address (private/loopback/link-local/reserved/multicast/unspecified + CGNAT 100.64.0.0/10, IPv4-mapped-IPv6 unwrap) + is_metadata_hostname + denylist. No I/O.
• Async orchestrator (backend/app/services/cluster_url_policy.py): assert_base_url_allowed — flag-gated; metadata short-circuit → literal-IP classify → else getaddrinfo + classify every resolved address. gaierror falls through (an unresolvable host is not an SSRF target). Runs before any adapter build / probe in register_cluster + test_cluster_connection.
• Error contract: new 400 CLUSTER_URL_BLOCKED (non-retryable) on POST /clusters + POST /clusters/test-connection.
• Refactor (FR-4): collapsed the two byte-for-byte-duplicated base_url validators into one shared structural helper (scheme + host only); the SSRF policy moved to the service layer (DNS is I/O — must not block the sync Pydantic validator, per Gemini's earlier note on the idea).
• Default unchanged: RELYLOOP_ALLOW_PRIVATE_CLUSTERS defaults True, so the policy is a strict no-op for local Docker hostnames — ships dormant, activates only in the hardened posture.

Phase 2 (connect-time IP pinning for DNS rebinding) deferred → phase2_idea.md.

Test coverage

• Unit (38, runnable without a stack): test_cluster_url_policy.py (domain — 28: every blocked range incl. IPv4-mapped, metadata denylist) + (services — 10: flag no-op, metadata, literal, resolved-private/public, mixed-resolution fail-safe, gaierror fall-through, enforcement-fires-before-DB-and-probe on both entry points).
• Contract (CI-gated): test_error_codes.py — CLUSTER_URL_BLOCKED envelope on both endpoints; test_clusters_api_contract.py scheme test unchanged (still green).
• Integration (CI-gated): test_cluster_url_ssrf.py — real-DNS proof (flag-False + http://elasticsearch:9200 resolves to a private Docker IP → blocked) + flag-True no-op end-to-end.

Test plan

• uv run pytest backend/tests/unit/ — 2541 passed, 1 skipped
• ruff check + ruff format --check backend/ — clean (609 files)
• mypy backend/app — clean (177 files)
• Integration + contract layers (need Postgres + ES — run in CI)

No migration, no UI. Cross-model review: Opus self-review (GPT-5.5 unreachable in the remote sandbox); Gemini Code Assist is the live cross-family gate on this PR.

Closes #504

https://claude.ai/code/session_01WmcRoU8EEzy7dZKB1Jkq34

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request implements a hostname-aware SSRF guard for cluster base_urls, active when private clusters are disallowed. It introduces a pure domain classifier for blocked IP ranges and metadata hostnames, and an async service orchestrator that performs non-blocking DNS resolution. It also consolidates duplicate Pydantic validators into a single structural check. Feedback suggests adding a timeout to the DNS resolution to prevent API hangs and validating the port structure early in the schema validation to catch malformed ports.

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]

To prevent potential denial of service or API hangs when resolving slow or unresponsive DNS hostnames, it is highly recommended to enforce a timeout on the DNS resolution. Wrapping loop.getaddrinfo in asyncio.wait_for with a reasonable timeout (e.g., 5.0 seconds) ensures the API remains responsive.

Suggested change

	try:
	infos = await loop.getaddrinfo(host, None, type=socket.SOCK_STREAM)
	except socket.gaierror:
	return # unresolvable -> not an SSRF target; probe will report unreachable
	try:
	infos = await asyncio.wait_for(
	loop.getaddrinfo(host, None, type=socket.SOCK_STREAM),
	timeout=5.0,
	)
	except (socket.gaierror, asyncio.TimeoutError):
	return # unresolvable or timeout -> not an SSRF target; probe will report unreachable

[gemini-code-assist]

Accessing parsed.port during structural validation ensures that any malformed port (e.g., http://elasticsearch:9200abc) is caught early and rejected with a 422 VALIDATION_ERROR rather than propagating to the service layer and causing unexpected failures later.

Suggested change

	parsed = urlparse(v)
	if parsed.scheme not in ("http", "https"):
	raise ValueError("base_url must use http or https scheme")
	if not parsed.hostname:
	raise ValueError("base_url must include a host")
	return v
	parsed = urlparse(v)
	if parsed.scheme not in ("http", "https"):
	raise ValueError("base_url must use http or https scheme")
	if not parsed.hostname:
	raise ValueError("base_url must include a host")
	try:
	_ = parsed.port
	except ValueError as exc:
	raise ValueError("base_url has an invalid port") from exc
	return v

[SoundMindsAI]

Review adjudication (Gemini Code Assist)

Commit landing fixes: 8c2ca37

Gemini Code Assist (2 findings)

#	Sev	Location	Verdict	Notes
1	Medium	backend/app/services/cluster_url_policy.py:92	Accepted	Wrapped getaddrinfo in asyncio.wait_for(timeout=5.0); a slow/blackholed resolver now trips the timeout and falls through (treated as "not an SSRF hit") instead of hanging the request. Directly hardens the "resolver hang" failure mode the spec had flagged as Phase-1-acceptable. New unit test test_dns_timeout_falls_through.
2	Medium	backend/app/api/v1/schemas.py:79	Accepted	Structural validator now accesses parsed.port, so a malformed port (http://host:9200abc) surfaces as 422 VALIDATION_ERROR early instead of propagating. New contract test test_create_cluster_request_rejects_malformed_port.

Outcomes

• Applied fixes (2): DNS-resolution timeout; malformed-port 422.
• Rejected (0): —
• Deferred (0): —

Local gate after fixes: 52 targeted tests pass · ruff format --check + mypy backend/app (177 files) clean. CI re-running on 8c2ca37.

Cross-model review: Opus self-review (GPT-5.5 unreachable in the remote sandbox); Gemini is the live cross-family gate.

---

Generated by Claude Code