Sandbox Network Isolation#

Dify's sandbox environments route all outbound HTTP/S traffic through Squid-based SSRF proxies. As of Dify 1.15.0, the workflow sandbox proxy enforces a deny-by-default policy that blocks all private/RFC-1918 IP ranges and only allows .marketplace.dify.ai out of the box. Workflows or HTTP-request nodes that call internal services will return TCP_DENIED/403 after upgrading from earlier versions. 1

The agent sandbox (local_sandbox) uses a separate, more restrictive proxy (agent_ssrf_proxy) that only permits access to specific internal endpoints and external internet traffic.

Network Topology#

Workflow Sandbox (sandbox)#

Docker Compose defines a dedicated internal bridge network named ssrf_proxy_network with internal: true. This means containers on that network cannot reach the Docker host's external network directly; all egress must traverse the proxy.

┌─ default network (external access) ─────────────┐
│ nginx ←──→ api / worker / plugin_daemon │
└──────────────────────────────────────────────────┘
                    │ ssrf_proxy_network (internal)
                    ↓
              ssrf_proxy (Squid :3128)
                    │
              sandbox (port 8194)

Services that join both networks (api, worker, worker_beat, plugin_daemon) can reach the Squid proxy for outbound calls while still communicating with the rest of the stack on the default network 2 3. The sandbox service joins only ssrf_proxy_network and is intentionally cut off from the default network 4.

The sandbox container is pre-configured to send all traffic through the proxy via HTTP_PROXY and HTTPS_PROXY environment variables 5:

HTTP_PROXY: http://ssrf_proxy:3128
HTTPS_PROXY: http://ssrf_proxy:3128

Service-name DNS resolution (e.g., ssrf_proxy) works because Docker's embedded DNS resolver is available to every container in a shared network — including the internal: true ssrf_proxy_network.

Agent Sandbox (local_sandbox)#

The local_sandbox service has no direct route to api. It is connected to two internal networks:

• agent_sandbox_network — shared with agent_backend so agent_backend can reach local_sandbox on port 5004 (shellctl). Note this is a known limitation: arbitrary code in the sandbox can make outbound requests to agent_backend through this network.
• local_sandbox_proxy_network — shared only with agent_ssrf_proxy to force all other egress through the proxy.

┌─ default network ────────────────────────────────┐
│ api ←──→ agent_backend │
│ │
│ agent_ssrf_proxy ──┐ │
└────────────────────┐│─────────────────────────────┘
                     ││ agent_sandbox_network
                     │└──→ agent_backend (port 5004 shellctl)
                     │ │
                     │ ↓
                     │ local_sandbox
                     │ ↑
                     └─────────┘
                 local_sandbox_proxy_network

The local_sandbox container is pre-configured to send all traffic through the agent proxy:

HTTP_PROXY: http://agent_ssrf_proxy:3128
HTTPS_PROXY: http://agent_ssrf_proxy:3128
NO_PROXY: localhost,127.0.0.1

All egress traffic (except to localhost/127.0.0.1 or direct requests to agent_backend via agent_sandbox_network) is routed through agent_ssrf_proxy, which enforces highly restrictive path-based ACLs to only allow:

• agent_backend /agent-stub/* endpoints
• api /files/* endpoints (signed upload/download URLs)
• External internet destinations

This prevents SSRF attacks where malicious code in the sandbox attempts to access internal services.

Squid Deny-by-Default Policy#

Workflow Sandbox Proxy (ssrf_proxy)#

The proxy configuration in docker/ssrf_proxy/squid.conf.template enforces the following access control order:

1. Include override file first — /etc/squid/dify_allow_private.conf is evaluated before any deny rules 6, so environment-variable-based exceptions always win.
2. Allow static allowlist — acl allowed_domains dstdomain .marketplace.dify.ai is the only hardcoded outbound domain 7.
3. Block private IPs — the to_private_networks ACL covers 14 ranges 8:
   0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.168.0.0/16, 224.0.0.0/4, 240.0.0.0/4, plus IPv6 equivalents (::1/128, fc00::/7, fe80::/10, etc.)
4. Deny everything else — http_access deny all as the final rule 9.

Agent Sandbox Proxy (agent_ssrf_proxy)#

The agent proxy configuration in docker/ssrf_proxy/squid-agent.conf.template enforces a more restrictive policy:

1. Deny unsafe ports and methods — blocks non-safe ports and CONNECT to non-SSL ports.
2. Allow agent_backend /agent-stub/* — http_access allow dst_agent_backend path_agent_stub permits requests to agent_backend matching the /agent-stub/ path prefix.
3. Allow api /files/* — http_access allow dst_dify_api path_files permits requests to api matching the /files/ path prefix (signed upload/download URLs).
4. Block private IPs — the same to_private_networks ACL defined in squid-common.conf.template denies all other private destinations.
5. Allow external internet — http_access allow all permits outbound requests to public destinations.

The agent proxy uses squid-common.conf.template for shared ACL definitions (to_private_networks, safe ports, etc.) but does not support runtime exception variables like the workflow proxy. Access control is hardcoded to the two internal endpoints and external internet only.

Adding Exceptions (Workflow Sandbox Only)#

The docker/ssrf_proxy/docker-entrypoint.sh reads two .env variables at startup and generates Squid ACL fragments into /etc/squid/dify_allow_private.conf 10. These exceptions apply only to the workflow sandbox proxy (ssrf_proxy), not to the agent sandbox proxy.

These are also exposed as environment pass-throughs in the ssrf_proxy service definition 11.

Example .env additions:

SSRF_PROXY_ALLOW_PRIVATE_DOMAINS=internal.mycompany.com
SSRF_PROXY_ALLOW_PRIVATE_IPS=10.10.5.42,192.168.1.0/24

After editing .env, restart the proxy: docker compose restart ssrf_proxy (or down/up to regenerate configs).

API-Layer SSRF Detection#

api/core/helper/ssrf_proxy.py routes all outbound requests through the Squid proxy via configurable proxy mounts 12. When Squid blocks a request and returns a 401 or 403, the code checks for squid in the Server or Via response header and raises ToolSSRFError 13. No local DNS or IP validation is performed — all enforcement is delegated to the proxy.

Key Files#