Dify SSRF proxy configuration and allowlisting

Why the Dify SSRF proxy decides what your workflows can reach

The Squid SSRF proxy decides which internal and external addresses your Dify workflows can call. A regulated team that self-hosts Dify usually meets this control in one of two ways: an HTTP node, tool or external knowledge call fails with a connection error against a service on the internal network, or a workflow reaches a host it should never see. Both symptoms point to the same component. In the Docker Compose deployment, the SSRF proxy runs as its own service alongside the api, worker, sandbox and plugin daemon. The Dify environment reference says SSRF_PROXY settings route outbound requests through this proxy, and the proxy blocks internal and private IP ranges by default. Requests from the workflow engine therefore leave through the proxy rather than going straight to the network.

The default block is the right starting point for most deployments, but teams change it when a legitimate business dependency sits on a private address, such as an internal ticketing API, a document store behind a corporate firewall or a self-hosted model endpoint. Before editing anything, list every internal host, port and domain that workflows must reach, and record which app or tool needs each one. Confirm the exact configuration keys and allowlist format in the Dify environment reference and the Docker Compose documentation for your target version, because these can change between releases. The Dify 1.16.1 release notes also describe Squid-based network isolation for the agent sandbox, which means the same proxy layer affects code execution as well as HTTP calls. Check that release note against your version before assuming sandbox egress behaves as you expect.

Treat every allowlist entry as a standing exception to the network boundary. An entry for a single host is far narrower than a domain entry, and a domain entry is narrower than opening a private range. Write down the owner, the business reason and the review date for each entry, and test both the allowed and blocked paths after each change. The sibling topics on sandbox security and TLS cover what happens after a request is allowed, so this section's job is the gate itself: confirm it blocks what it should, permits only what you listed and produces logs your security team can read.

Which proxy setting fits which outbound need

This table compares six outbound configuration choices for Dify's SSRF proxy, from keeping default blocking to changing the agent sandbox path. Read each row for when the choice fits, what exposure it adds and what to check in your target version. Key names come from the environment variable reference, so verify exact names in the .env.example for the version you deploy.

Outbound need	When it fits	Risk it adds	What to confirm
Keep default blocking	Fits when HTTP nodes, tools and knowledge calls only need public endpoints.	Calls to internal services fail until a rule is added, which is the intended control.	SSRF_PROXY settings stay enabled and point to the bundled proxy in .env.example.
Allow one internal host	Fits a single internal API or knowledge system that workflows must call.	Opens a path from Dify workers to that host, reachable by every app in the workspace.	The exact host and port in the proxy rule for your Squid version, and nothing wider.
Allow a domain	Fits SaaS endpoints whose IP addresses change and cannot be tracked by hand.	A domain rule can match more hosts than intended and depends on DNS answers at request time.	Whether domain rules are checked against private IP ranges after DNS resolution.
Route to an upstream egress proxy	Fits when policy sends all outbound traffic through a corporate proxy.	Private range blocking now depends on the upstream proxy, and logs split across two hops.	Whether the bundled proxy can chain upstream in your target version, and how private ranges stay blocked.
Change the agent sandbox path	Fits when sandboxed code must reach an approved endpoint through the Squid proxy.	Sandboxed code inherits the same allowed destinations, so a compromised sandbox reaches them too.	Sandbox network settings described in the 1.16.1 release notes and matching keys in .env.example.
Disable the proxy for outbound calls	Fits only isolated lab tests, not production workloads that handle regulated data.	Dify workers can reach any private address their network route allows.	Whether host or cluster network policy blocks the same private ranges independently.

How to allow one internal host without opening the network

This sequence inventories outbound calls, keeps the SSRF proxy's default private-network blocking in place, and adds narrow allow rules for named internal hosts or domains. The result is a tested, recorded configuration where only the destinations the team approved can be reached.

Inventory every outbound call
The platform owner lists each place Dify makes an outbound request: HTTP request nodes in workflows, custom tools and API-based tool providers, external knowledge API connections, and any model or webhook endpoint that resolves to an internal address. For each one, record the workflow or tool name, the destination host or domain, the protocol, and the business owner who approved it. Pay attention to hostnames that resolve to private addresses, since a public-looking name can still land on your internal network. The step is done when the list is complete, reviewed by the owner of the internal system, and stored with the change record. Confirm the inventory against the apps in your workspace, because a workflow added by one team can introduce a new destination without any infrastructure change.
Set SSRF proxy variables and restart
Before changing anything, record the current values of the SSRF_PROXY settings in the .env file used by your Docker Compose deployment, and keep a copy of the file. Confirm the exact key names and proxy configuration for your release in the environment variable reference and in the .env.example file that ships with that version, since names can change between releases. Make only the change the inventory requires, then restart the services that read these values so the new settings apply to the API, worker and sandbox paths. The step is done when the running containers show the expected environment values and the change is saved in version control or your change log.
Confirm default blocking with a private-address test
Create a test workflow in a non-production workspace with a single HTTP request node. Point it at a private address on your test network that no one needs to reach, such as a host in a private range that has no service behind it, and run the workflow. The expected result is a failed request with an error from the proxy rather than a response from the host. Repeat the test with a second private address to confirm the block is not limited to one destination. The step is done when both attempts fail as expected and the run logs and error messages are captured in the change record. If a request succeeds, stop, because the proxy is not routing outbound traffic as documented, and resolve that before adding any allow rule.
Add narrow allow rules for named hosts
For each approved destination from the inventory, add an allow rule that names one host or one domain. Prefer full hostnames over wildcard domains, and avoid rules that cover an entire subnet unless the owner has justified the scope in writing. Check how the proxy handles IP-literal entries and name-based entries in your release, because a rule that matches a name may not cover a direct address that resolves to the same host. Keep each rule tied to one row of the inventory so that a later reviewer can trace it back to an owner and a reason. The step is done when every rule maps to an approved destination and the rule set is committed to the same record as the inventory.
Retest blocked and allowed paths
Restart the affected services after the rule change, then rerun the private-address test from the previous step, which should still fail. Run one allowed-path test per approved destination from a workflow or tool that uses the same node type as the production configuration. Use an endpoint that returns a known response so that success is unambiguous, and confirm that the request reaches the intended host rather than a fallback. Also test a destination that was not approved but sits on the same subnet, which should remain blocked. The step is done when every approved path succeeds, every unapproved path still fails, and the results are written down with the release version in use.
Record changes and schedule review
Write a change record that lists the final proxy settings, every allow rule with its owner and justification, the test results from both retests, and the Dify version in use at the time. Store the record with the deployment configuration so it travels with backups and upgrades. Because Dify releases arrive roughly monthly and the proxy configuration may change between versions, add a check to the upgrade procedure that repeats the blocked and allowed tests and compares the .env.example file against your recorded settings. The step is done when the record is stored, linked from the upgrade runbook, and assigned a named reviewer who can approve future rule additions or removals.

Risks that come with loosening outbound filtering

Every allowance you add to the SSRF proxy trades a blocked path for an open one. The cards below pair each risk with the control that keeps the allowance narrow, so changes are deliberate, visible and reversible in a self-hosted Dify.

Broad ranges reopen internal services

A wildcard or wide CIDR entry in the proxy allowlist can expose cloud metadata endpoints, admin consoles and databases that sit on the same private network. Allow exact hosts and ports, one entry at a time, and test each entry against the private addresses nearby. Review every rule for a range that covers more than the named service. A single CIDR can undo the whole private-network block.

DNS rebinding and redirect paths

A domain that is allowed at request time can resolve to a private address later, or send a redirect to an internal host the proxy never checked. Confirm how your proxy configuration handles redirects and resolution, and test with a domain you control that points to a private address. Keep allowed domains to services you operate or trust, and avoid domains that accept user-supplied redirects.

Sandbox egress depends on the proxy

Code and Template nodes run in the code sandbox, and in 1.16.1 agent sandbox network isolation runs through the Squid proxy. Removing or misconfiguring the proxy can either break sandbox calls or let sandboxed code reach destinations the workflow never intended. Check sandbox outbound behavior after every change to proxy settings, and record which destinations sandboxed code actually needs.

Authors add destinations silently

Anyone who can build an HTTP node, tool or external knowledge connection can point it at a new host, and the proxy will only block it if it is not already allowed. Without a change process, an allowlist entry added for one workflow becomes available to all of them. Require a named owner and a written reason for each entry, and review workflow exports for new URLs before publishing.

Blocked requests leave no trail

When the proxy denies a request, the workflow often shows only a generic failure, so operators cannot tell an intended block from a broken integration. Denied attempts to internal ranges are the signal you most need during an incident. Confirm where proxy access logs are written in your deployment, forward them to your log platform, and alert on repeated denials from the same workflow.

Upgrades can change proxy defaults

Minor releases arrive roughly monthly, and a new version can alter proxy settings, add variables or change which services route through the proxy. A release that is correct for the product can still widen or narrow your allowlist behavior. After each upgrade, compare your proxy configuration with .env.example and rerun your allow and deny tests before users return to the platform.

How private range blocking interacts with internal services

Private range blocking is the control teams most often have to work around, because the services they most want Dify to reach are usually inside the network: a self-hosted model endpoint, an internal embedding or rerank server, or a knowledge system behind the firewall. The SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, so an HTTP node or external knowledge call aimed at those addresses fails by default. The first decision is therefore which internal services truly need to be reachable from workflows and knowledge retrieval, and which only need to be reachable from administrators. Each one that is added to the allowlist widens what a compromised prompt, tool or plugin can call.

A common pattern is to place these internal services on a separate, reachable segment that the Dify host can route to on specific ports, instead of making them part of the general private network the proxy is designed to shield. The segment should contain only the endpoints the platform needs, with access limited to the Dify components that call them. Confirm with your network team whether the Compose stack's internal network, the SSRF proxy container and the host's routing all see that segment in the way you expect, and record which of them the proxy itself reaches. Keep the mapping of allowed hosts and ports in version control so reviewers can see every exception.

Treat the blocking as a control to verify, not a guarantee. Confirm the behavior of your own deployment by running test requests from an HTTP node or external knowledge call to a private address, a loopback address, a cloud metadata address and an internal host you have not allowed, and check that each one is refused. Repeat these tests after every upgrade and after every change to .env, because the proxy configuration and the internal network layout can change independently of the application. Where a test shows an unexpected path, document it as a finding and fix it before the allowlist is extended.

What to confirm in your environment before relying on the proxy

The SSRF proxy is the control that stops Dify's outbound requests from reaching private networks, but its behavior depends on the exact build and settings in your release. Treat each item below as a check to complete and record, not as a guarantee, because proxy images, rules and coverage can differ from one deployment to the next.

Exact proxy image and version

Record the Squid image tag your Docker Compose file actually pulls, not the one you assume from the Dify release notes. Compare it against the proxy version that shipped with your Dify release, and confirm that the agent sandbox network isolation described in the 1.16.1 release notes is present in your running stack. Re-check after every upgrade, because a pinned tag in an older file can quietly remain in place.

Custom rules survive upgrades

If you edited the proxy configuration file or added allowlist entries directly in the container, those changes may be overwritten when you move to a newer Compose file. Confirm where your allowlist lives, whether it is mounted from the host, and whether your upgrade procedure preserves it. Check .env.example for new variables after each upgrade, since proxy settings may change alongside them.

IPv6 and DNS resolution behavior

Private range blocking is only as strong as the address the proxy resolves. Test whether internal hostnames that resolve to private IPv4 or IPv6 addresses are denied, including names that return both record types, and whether DNS rebinding or redirects to internal targets are blocked after the first lookup. Ask your team to document which resolvers the proxy uses and whether your network blocks IPv6 egress in a way that is consistent with the proxy rules.

Coverage across node types and plugins

Confirm which outbound paths honor the SSRF_PROXY settings. HTTP request nodes, tools, external knowledge calls and marketplace plugins may each make requests through different code paths, and a plugin running in the plugin daemon may not inherit the same proxy configuration. Build a test workflow for each category and check the proxy logs to see which calls were routed and which connected directly.

Retention of denied call logs

Blocked requests are the evidence that a prompt, workflow or plugin tried to reach an internal system. Find out where the proxy writes its access and deny logs, how long your Docker host or log platform keeps them, and whether they are forwarded to a central store your security team reviews. Agree a retention period with your compliance owner before you depend on these logs for investigations.

External penetration test coverage

Ask any tester you engage to include the SSRF proxy in scope, including bypass attempts through redirects, alternate IP encodings, DNS names and allowed domains that point to internal services. Confirm in writing whether the test scope covers the proxy, the sandbox egress path and the plugin daemon, since a test of the web interface alone will not show whether the allowlist holds.

Questions teams ask about Dify SSRF proxy allowlisting

What drives the cost of an SSRF proxy allowlisting project in Dify?

The main cost driver is how many destinations need access and how well they are documented. Each internal host, domain or service that HTTP nodes, tools or external knowledge calls must reach adds design, testing and review work, and each one needs a named owner who can confirm it is legitimate. Other drivers include how many Dify environments you run (development, staging and production usually need separate rules), how many network zones sit between Dify and the targets, and whether your security team requires a formal change record for every rule. A fixed-scope quote from DeployOpen follows from a written list of destinations, environments and test cases, so ask for the quote to state exactly which of these it covers and what is excluded.

How long does it take to allow specific internal hosts through the Dify SSRF proxy?

Duration depends mostly on the destination inventory. A short list of well-documented hosts with known owners can be configured and tested in a short cycle, while a long list of undocumented services, shared DNS names or hosts that change IP addresses will take longer because each one needs investigation before it is allowed. Approval cycles inside your organization often take longer than the technical change itself. Before you ask for a timeline, collect the destination list, the protocol and port for each, the owner who approves it, and the test account that proves the flow works. DeployOpen will not state a duration until the written scope is agreed.

What must our team provide before an allowlisting engagement starts?

Plan to provide three things. First, network diagrams that show where the Dify containers run, which subnets and firewalls sit between Dify and each target, and where the SSRF proxy fits in that path. Second, a named owner for every destination, who can confirm the business need, the hostnames and the ports, and who signs off on changes. Third, test accounts or test data for each destination, so that HTTP nodes, tools and external knowledge calls can be exercised end to end without using production records. Also provide the Dify version in use and the environment file that controls the proxy settings, so the work starts from your real configuration.

Can our own engineers configure the SSRF proxy allowlist using the Dify documentation?

Yes, a capable platform team can configure the allowlist from the Dify documentation, starting with the environment variable reference and the Docker Compose deployment guide. The harder part is not editing the configuration but deciding which destinations deserve access, proving that a rule does not open more than intended, and testing every workflow path that depends on it. Teams that lack a Squid or container networking background, or that must document evidence for an assessment, often find an outside review useful. Your team can decide the split: keep the rule changes in-house and use a partner for the design review and test plan.

Do Dify upgrades reset our SSRF proxy allowlist rules?

Upgrades do not automatically remove rules you have written into your own configuration, but they can change what the rules need to match. Dify's Docker Compose guidance says to read the upgrade guide for the target version, back up before every upgrade, and check .env.example for new variables after upgrading. Dify 1.16.1 introduced agent sandbox network isolation through a Squid proxy, so networking behavior has already changed in a recent release. After each upgrade, re-run your destination tests, compare your settings with the new example file and confirm that the proxy still allows only the hosts you approved. Keep the allowlist in version-controlled files so that changes are traceable.

When should we move to Dify Enterprise or commission a security test for SSRF controls?

Consider Dify Enterprise when your requirements include capabilities listed for the Enterprise edition, such as SSO, multiple workspaces, advanced security or professional support, or when you need Kubernetes-based high availability. The pricing page describes Enterprise as custom priced, so ask Dify for a quote. Commission a security test when the allowlist reaches internal systems that hold sensitive data, when you open access to cloud metadata-style endpoints or other high-value services, or when an assessor will ask for evidence that private network access is blocked. DeployOpen runs application and infrastructure security testing, and a test scoped to SSRF paths is a separate written engagement. It does not issue audit reports or certifications, so independent assessors remain responsible for those.

Keeping proxy rules correct across Dify releases

Treat the proxy allowlist as part of each upgrade, not as a one-time setup. Dify's minor releases arrive roughly monthly, according to the Dify releases page on GitHub, and the 1.16.1 release notes changed how agent sandboxes are isolated on the network through the Squid proxy. A rule set that worked on your previous version can therefore behave differently after an upgrade, in either direction: a host you allowed may stop being reachable, or traffic you assumed was blocked may now take a different path. Re-run your outbound tests after every version change, not only after major changes.

Before you upgrade, take a backup of the database, file storage and your .env file, then follow the upgrade guide for the target version. The Docker Compose documentation also says to compare your .env with .env.example after upgrading, because new variables such as proxy-related settings may be introduced. Record which SSRF_PROXY values, Squid configuration changes and allowlist entries you made by hand, so you can see whether an upgrade overwrote them. Confirm with your platform team whether your deployment uses the bundled proxy or an external one, since that determines which configuration files you must diff.

Schedule a recurring retest of the proxy rules and link it to your security review scope. The test should confirm that each approved internal host and domain resolves and responds from the HTTP node, a tool and an external knowledge call, that loopback, link-local and private address ranges remain blocked, and that sandboxed code cannot reach the network beyond what policy allows. Add these cases to the scope of your periodic security review or penetration test, so the results are kept as evidence. Assign an owner for each allowlist entry and retire entries that no workflow still uses.

How DeployOpen scopes and delivers SSRF proxy hardening

DeployOpen plans, implements and documents Dify SSRF proxy configuration and allowlisting inside your own infrastructure. We start by mapping which HTTP nodes, tools and external knowledge calls need internal reach, then build narrow allowlist rules, test them against the blocked and permitted paths, and hand over the configuration with the evidence your team needs to review it.

How we scope

Inventory every workflow HTTP node, tool and external knowledge source that calls internal hosts or domains
Record the destination hosts, ports and protocols each use, and who owns each target system
Agree the written scope, deliverables and timeline in writing before any configuration change begins

How we build

Set SSRF_PROXY configuration and Squid rules so only approved internal hosts or domains are reachable
Keep private and internal IP ranges blocked by default, with explicit exceptions documented one by one
Test blocked and allowed destinations from the sandbox and API paths, and confirm the outcome of each rule

How we hand over

Deliver a runbook listing each allowlist entry, its owner, its purpose and the review date
Document how to add, change or remove an allowlist entry, and how to verify the change after an upgrade
Walk your platform and security teams through the configuration and the test results before handover

How we support

Re-check allowlist rules after each Dify upgrade, since release notes change proxy and sandbox behavior
Review new workflow or tool requests against the allowlist policy before they reach production
Offer ongoing support, upgrades and continuous testing as a retainer, priced from the written scope