Problem

Users on networks where DNS resolves external domains to private IP ranges are completely blocked from using Hermes's web tools, browser, vision URL fetching, and gateway media downloads. This affects:

• OpenWrt routers that use 198.18.0.0/15 (IANA benchmarking range) for DNS resolution
• Corporate proxies / split-tunnel VPNs that resolve all domains locally
• Tailscale/WireGuard setups using 100.64.0.0/10 (CGNAT range)

Example from a user's environment — nousresearch.com resolves to a private IP:

$ nslookup nousresearch.com
Name:    nousresearch.com
Address: 198.18.23.183

Python's ipaddress.is_private returns True for 198.18.23.183 (it's in the IANA benchmarking range 198.18.0.0/15), so Hermes's SSRF guard blocks the request with:

Blocked: URL targets a private or internal network address

This affects all 23 call sites that use is_safe_url() — web_extract, web_crawl, browser_navigate, vision_analyze URL downloads, and media downloads across all 13 gateway platform adapters (Telegram, Discord, Slack, Matrix, Feishu, etc.).

Previously, only the browser tool had an escape hatch (browser.allow_private_urls in config.yaml), but the other 21 call sites had no bypass mechanism at all.

Competitor Analysis

Audited OpenCode, Cline, and Claude Code (closed source). None of them have any SSRF protection:

We're already well ahead. This PR makes the protection configurable without weakening the security-critical parts.

Solution

A single global toggle in tools/url_safety.py that all 23 call sites inherit automatically — no changes needed at individual call sites.

Configuration (three ways, in priority order):

1. Env var: HERMES_ALLOW_PRIVATE_URLS=true
2. Config: security.allow_private_urls: true in ~/.hermes/config.yaml
3. Legacy: browser.allow_private_urls: true (existing key, now promotes globally)

Security guarantees preserved — hardened after competitive review

When the toggle is enabled, cloud metadata endpoints and the entire link-local range are ALWAYS blocked:

Key design: hostname checks (metadata.google.internal, metadata.goog) run before DNS resolution, so on networks where these hostnames resolve to local proxy IPs, they're still blocked by the string match.

Files changed

• tools/url_safety.py — Core change: _global_allow_private_urls() with cached config read, expanded _ALWAYS_BLOCKED_IPS (5 cloud metadata IPs), new _ALWAYS_BLOCKED_NETWORKS (entire 169.254.0.0/16), is_safe_url() checks toggle after blocking metadata
• hermes_cli/config.py — security.allow_private_urls: false added to DEFAULT_CONFIG
• tests/tools/test_url_safety.py — 37 new tests across 3 test classes

Tests

• 79 url_safety tests pass (42 existing + 37 new)
• 98 browser SSRF + website policy + vision tests pass (no regressions)
• E2E verified with real imports: toggle works via env var, config.yaml, and browser legacy fallback; all 6 cloud metadata IPs/ranges stay blocked with toggle on; public IPs unaffected

New test coverage:

• TestGlobalAllowPrivateUrls (11 tests) — toggle defaults, env var parsing, config.yaml security + browser fallback, precedence, caching
• TestAllowPrivateUrlsIntegration (16 tests) — full is_safe_url() integration: private/benchmark/CGNAT/localhost IPs allowed with toggle, and all metadata endpoints always blocked: AWS (169.254.169.254), ECS (169.254.170.2), Azure wire server (169.254.169.253), Alibaba (100.100.100.200), AWS IPv6 (fd00:ec2::254), full link-local range (169.254.x.x), metadata hostnames, DNS failures, empty URLs

How to use

Users hitting this issue add one line to ~/.hermes/config.yaml:

security:
  allow_private_urls: true

Or set the env var HERMES_ALLOW_PRIVATE_URLS=true for a quick workaround.