Summary

• Problem: web_fetch is completely broken in fake-IP proxy environments (Surge Enhanced Mode, Clash fake-ip, Quantumult X, etc.) because the SSRF guard blocks RFC 2544 benchmark range (198.18.0.0/15) addresses used for DNS interception. There is no config path to opt out. Internal network fetching (e.g. local docs servers) is also impossible.
• Why it matters: Every user running Surge, Clash, Shadowrocket, or similar tools in fake-IP/TUN mode cannot use web_fetch at all. Users wanting to access internal documentation servers are also blocked.
• What changed: Added tools.web.fetch.ssrfPolicy.allowCidrs — an array of CIDR strings that should be allowed through SSRF protection. This is a generic approach: instead of adding specific booleans for each IP range (like allowRfc2544BenchmarkRange), users specify exactly which CIDRs they trust.
• What did NOT change: Default behavior remains fully restrictive (no CIDRs allowed). The existing dangerouslyAllowPrivateNetwork nuclear option is untouched. Browser SSRF policy is unaffected.

Config example:

{
  "tools": {
    "web": {
      "fetch": {
        "ssrfPolicy": {
          "allowCidrs": ["198.18.0.0/15"]
        }
      }
    }
  }
}

More examples:

// Allow fake-IP proxy range
{ "allowCidrs": ["198.18.0.0/15"] }

// Allow internal docs server
{ "allowCidrs": ["10.0.0.0/8"] }

// Multiple ranges
{ "allowCidrs": ["198.18.0.0/15", "172.16.0.0/12"] }

Change Type (select all)

• Bug fix
• Feature

Scope (select all touched areas)

• Skills / tool execution
• API / contracts

Linked Issue/PR

• Closes [Feature]: web_fetch: pass ssrfPolicy from config to fetchWithSsrFGuard (fix fake-IP/proxy environments) #28271
• Closes Feature request: configurable SSRF allowedHostnames in config #26945
• Related fix: pass ssrfPolicy from config to web_fetch SSRF guard #28349 (specific allowRfc2544BenchmarkRange approach — this PR is a more generic alternative)
• Related feat(agent): add allowPrivateNetwork config for web_fetch #25229 (specific allowPrivateNetwork approach — complementary, this adds fine-grained control)

User-visible / Behavior Changes

• New config: tools.web.fetch.ssrfPolicy.allowCidrs (string array, optional, default empty)
• When set, IP addresses matching any listed CIDR bypass SSRF blocking for web_fetch
• Invalid CIDR strings are warned and skipped (no crash)
• Schema labels and help text added for UI discoverability

Security Impact (required)

• New permissions/capabilities? Yes — opt-in capability to bypass SSRF protection for specific CIDR ranges
• Secrets/tokens handling changed? No
• New/changed network calls? No (same fetch surface; destination allowlist is relaxed only when opted in)
• Command/tool execution surface changed? No
• Data access scope changed? Yes — when allowCidrs is set, tool can reach specified IP ranges
• Risk + mitigation: Users could allowlist dangerous ranges. Mitigation: (1) default is empty (fully restrictive), (2) explicit opt-in required, (3) each CIDR must be individually listed — no wildcards, (4) consistent with existing patterns (browser.ssrfPolicy.allowPrivateNetwork, dangerouslyAllowPrivateNetwork)

Repro + Verification

Environment

• OS: macOS 15.x (Apple Silicon)
• Runtime: Node.js v22.22.0
• Proxy: Surge Enhanced Mode (fake-IP to 198.18.0.0/15)
• Config: { "tools": { "web": { "fetch": { "ssrfPolicy": { "allowCidrs": ["198.18.0.0/15"] } } } } }

Steps

1. Run OpenClaw behind Surge Enhanced Mode (or any fake-IP proxy)
2. Use web_fetch to access any public URL (e.g. https://example.com)
3. DNS resolves to 198.18.x.x (fake-IP range) → SSRF guard blocks it

Expected

With allowCidrs: ["198.18.0.0/15"], web_fetch should succeed.

Actual (before fix)

Blocked: resolves to private/internal/special-use IP address for every URL.

Actual (after fix)

web_fetch succeeds for all public URLs, including cursor.com, baidu.com, etc.

Evidence

• npx vitest run src/infra/net/fetch-guard.ssrf.test.ts — 8/8 passed (including updated RFC2544 opt-in test)
• npx vitest run src/shared/net/ip.test.ts — 4/4 passed
• npm run build — clean, no type errors
• npx oxfmt --check — clean
• Live testing: web_fetch https://cursor.com/pricing succeeds with allowCidrs: ["198.18.0.0/15"] behind Surge

Human Verification (required)

• Verified scenarios: (1) web_fetch blocked without config, (2) web_fetch works with allowCidrs for fake-IP proxy, (3) invalid CIDRs logged as warning and skipped, (4) empty allowCidrs = default restrictive behavior
• Edge cases checked: IPv6 CIDRs gracefully skipped for IPv4 addresses, malformed CIDR strings, empty array
• What you did not verify: IPv6-only proxy environments, performance under very large CIDR lists (>100)

Compatibility / Migration

• Backward compatible? Yes — new config is optional, defaults maintain current restrictive behavior
• Config/env changes? New optional tools.web.fetch.ssrfPolicy.allowCidrs
• Migration needed? No

Failure Recovery (if this breaks)

• Remove ssrfPolicy.allowCidrs from config → behavior reverts to default restrictive SSRF policy
• No data migration, no schema versioning needed

Risks and Mitigations

• Risk: Users allowlist overly broad ranges (e.g. 0.0.0.0/0)
  • Mitigation: This is an explicit opt-in; dangerouslyAllowPrivateNetwork already provides full bypass. allowCidrs is strictly more restrictive since each range must be individually listed.
• Risk: CIDR parsing overhead per request
  • Mitigation: Typical lists are 1-3 entries; ipaddr.parseCIDR is trivial. Could be cached if needed in future.