From 63dc36d6cecfa7be07448c948cac02b31518065f Mon Sep 17 00:00:00 2001 From: jesse-merhi <79823012+jesse-merhi@users.noreply.github.com> Date: Wed, 29 Apr 2026 23:00:01 +1000 Subject: [PATCH] docs(security): link proxy SSRF scope docs --- SECURITY.md | 25 ++----------------------- docs/security/network-proxy.md | 4 ++-- 2 files changed, 4 insertions(+), 25 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 3861d3c8f3b..dba9a1b2a30 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -76,7 +76,7 @@ These are frequently reported but are typically closed with no code change: - Claims that Microsoft Teams `fileConsent/invoke` `uploadInfo.uploadUrl` is attacker-controlled without demonstrating one of: auth boundary bypass, a real authenticated Teams/Bot Framework event carrying attacker-chosen URL, or compromise of the Microsoft/Bot trust path. - Scanner-only claims against stale/nonexistent paths, or claims without a working repro. - Reports that restate an already-fixed issue against later released versions without showing the vulnerable path still exists in the shipped tag or published artifact for that later version. -- SSRF reports against the operator-managed HTTP/WebSocket proxy-routing feature whose only claim is that ordinary process-local HTTP clients (`fetch`, `node:http`, `node:https`, WebSocket clients, axios/got/node-fetch-style clients) can reach an internal, metadata, private, or otherwise sensitive destination when proxy routing is disabled, missing, or the operator-managed proxy policy allows it. For this feature, OpenClaw provides fail-closed proxy routing when enabled; the external proxy's destination policy is operator infrastructure, not an OpenClaw-controlled security boundary. +- SSRF reports against the operator-managed HTTP/WebSocket proxy-routing feature whose only claim is that ordinary process-local HTTP clients (`fetch`, `node:http`, `node:https`, WebSocket clients, axios/got/node-fetch-style clients) can reach an internal, metadata, private, or otherwise sensitive destination when proxy routing is disabled, missing, or the operator-managed proxy policy allows it. For this feature, OpenClaw provides fail-closed proxy routing when enabled; the external proxy's destination policy is operator infrastructure, not an OpenClaw-controlled security boundary. See [Network proxy](https://docs.openclaw.ai/security/network-proxy). ### Duplicate Report Handling @@ -130,27 +130,6 @@ Plugins/extensions are part of OpenClaw's trusted computing base for a gateway. - Plugin behavior such as reading env/files or running host commands is expected inside this trust boundary. - Security reports must show a boundary bypass (for example unauthenticated plugin load, allowlist/policy bypass, or sandbox/path-safety bypass), not only malicious behavior from a trusted-installed plugin. -## HTTP/WS SSRF and Operator-Managed Proxy Routing - -OpenClaw's SSRF boundary for this feature is operator-managed proxy routing for normal JavaScript HTTP egress: - -- For process-local HTTP and WebSocket clients, operators can enable proxy routing with `proxy.enabled=true` plus a valid `http://` forward proxy URL from `proxy.proxyUrl` or `OPENCLAW_PROXY_URL`. -- The `proxy.enabled` setting is fail-closed by design: when proxy routing is enabled but no valid proxy URL is configured, protected commands fail startup instead of silently falling back to direct network access. -- While routing is active, OpenClaw clears destination bypass environment variables (`NO_PROXY`, `no_proxy`, and `GLOBAL_AGENT_NO_PROXY`) and preserves only a narrow literal-loopback Gateway control-plane path. - -For this specific feature, OpenClaw generally will not accept SSRF reports whose only claim is that `fetch`, `node:http`, `node:https`, WebSocket clients, axios/got/node-fetch-style clients, or similar process-local HTTP(S)/WebSocket egress can reach a destination that a correctly configured operator proxy is expected to block. Reports that depend on proxy routing being disabled, absent, permissive, or misconfigured are also not treated as OpenClaw vulnerabilities. - -The proxy itself is operator-managed infrastructure. OpenClaw does not ship, start, certify, inspect, or control the proxy's destination denylist, DNS resolution behavior, connect-time policy, authentication, or logging. If that external proxy allows a destination, that decision is outside OpenClaw's control. - -A report may still be in scope if it demonstrates that OpenClaw violates this feature's documented routing or fail-closed contract with `proxy.enabled=true` and a valid filtering proxy, such as: - -- a supported HTTP/WebSocket client unexpectedly bypassing the configured proxy -- invalid proxy configuration falling back to direct egress instead of failing startup -- destination bypass environment variables remaining active while proxy routing is active -- OpenClaw applying an unintended direct-egress exemption beyond the documented literal-loopback Gateway control-plane path - -This feature-specific policy does not classify non-HTTP/WebSocket egress, raw `net`/`tls`/`http2` sockets, native addons, child processes, or other OpenClaw features. Those reports are assessed under their own documented boundaries. - ## Out of Scope - Public Internet Exposure @@ -175,7 +154,7 @@ This feature-specific policy does not classify non-HTTP/WebSocket egress, raw `n - Exposed secrets that are third-party/user-controlled credentials (not OpenClaw-owned and not granting access to OpenClaw-operated infrastructure/services) without demonstrated OpenClaw impact - Reports whose only claim is host-side exec when sandbox runtime is disabled/unavailable (documented default behavior in the trusted-operator model), without a boundary bypass. - Reports whose only claim is that a platform-provided upload destination URL is untrusted (for example Microsoft Teams `fileConsent/invoke` `uploadInfo.uploadUrl`) without proving attacker control in an authenticated production flow. -- SSRF reports limited to the operator-managed HTTP/WebSocket proxy-routing feature where the demonstrated mitigation is to enable/configure `proxy.enabled` with a filtering `proxy.proxyUrl`/`OPENCLAW_PROXY_URL`, or where impact depends on a permissive/misconfigured operator proxy. This only covers normal process-local HTTP(S)/WebSocket egress (`fetch`, Node HTTP(S), and similar JavaScript clients); non-HTTP egress and other features are assessed separately. +- SSRF reports limited to the operator-managed HTTP/WebSocket proxy-routing feature where the demonstrated mitigation is to enable/configure `proxy.enabled` with a filtering `proxy.proxyUrl`/`OPENCLAW_PROXY_URL`, or where impact depends on a permissive/misconfigured operator proxy. This only covers normal process-local HTTP(S)/WebSocket egress (`fetch`, Node HTTP(S), and similar JavaScript clients); non-HTTP egress and other features are assessed separately. See [Network proxy](https://docs.openclaw.ai/security/network-proxy). ## Deployment Assumptions diff --git a/docs/security/network-proxy.md b/docs/security/network-proxy.md index 63370c7aeaf..db80ff753b4 100644 --- a/docs/security/network-proxy.md +++ b/docs/security/network-proxy.md @@ -23,7 +23,7 @@ A proxy gives operators one network control point for outbound HTTP and WebSocke - Auditability: log allowed and denied destinations at the egress boundary. - Operational control: enforce destination rules, network segmentation, rate limits, or outbound allowlists without rebuilding OpenClaw. -OpenClaw still keeps application-level SSRF guards such as `fetchWithSsrFGuard`. Proxy routing is an additional process-level guardrail for normal HTTP and WebSocket egress, not a replacement for guarded fetches or an OS-level network sandbox. +Proxy routing is a process-level guardrail for normal HTTP and WebSocket egress. It gives operators a fail-closed path for routing supported JavaScript HTTP clients through their own filtering proxy, but it is not an OS-level network sandbox and does not make OpenClaw certify the proxy's destination policy. ## How OpenClaw Routes Traffic @@ -147,7 +147,7 @@ proxy: ## Limits -- The proxy improves coverage for process-local JavaScript HTTP and WebSocket clients, but it does not replace application-level `fetchWithSsrFGuard`. +- The proxy improves coverage for process-local JavaScript HTTP and WebSocket clients, but it is not an OS-level network sandbox. - Raw `net`, `tls`, and `http2` sockets, native addons, and child processes may bypass Node-level proxy routing unless they inherit and respect proxy environment variables. - User local WebUIs and local model servers should be allowlisted in the operator proxy policy when needed; OpenClaw does not expose a general local-network bypass for them. - Gateway control-plane proxy bypass is intentionally limited to `localhost` and literal loopback IP URLs. Use `ws://127.0.0.1:18789`, `ws://[::1]:18789`, or `ws://localhost:18789` for local direct Gateway control-plane connections; other hostnames route like ordinary hostname-based traffic.