From 5e30919aa18ec976a901f4acd61c11e06b32169f Mon Sep 17 00:00:00 2001 From: Tomi Turtiainen <10324676+tomi@users.noreply.github.com> Date: Sat, 14 Mar 2026 11:56:51 +0200 Subject: [PATCH] Add SSRF protection documentation (#4335) --- .../environment-variables/ssrf-protection.md | 24 +++++++ docs/hosting/securing/overview.md | 1 + docs/hosting/securing/ssrf-protection.md | 64 +++++++++++++++++++ nav.yml | 2 + 4 files changed, 91 insertions(+) create mode 100644 docs/hosting/configuration/environment-variables/ssrf-protection.md create mode 100644 docs/hosting/securing/ssrf-protection.md diff --git a/docs/hosting/configuration/environment-variables/ssrf-protection.md b/docs/hosting/configuration/environment-variables/ssrf-protection.md new file mode 100644 index 000000000..be49a1177 --- /dev/null +++ b/docs/hosting/configuration/environment-variables/ssrf-protection.md @@ -0,0 +1,24 @@ +--- +title: SSRF protection environment variables +description: Configure SSRF protection for your self-hosted n8n instance. +contentType: reference +tags: + - environment variables +hide: + - toc + - tags +--- + +# SSRF protection environment variables + +--8<-- "_snippets/self-hosting/file-based-configuration.md" + +These variables control [SSRF protection](/hosting/securing/ssrf-protection.md) for nodes that make HTTP requests to user-controllable targets. + +| Variable | Type | Default | Description | +| :------- | :---- | :------- | :---------- | +| `N8N_SSRF_PROTECTION_ENABLED` | Boolean | `false` | Whether to enable SSRF protection for nodes making HTTP requests. | +| `N8N_SSRF_BLOCKED_IP_RANGES` | String | Standard private/reserved ranges | Comma-separated CIDR ranges to block. Use `default` to include the [standard blocked ranges](/hosting/securing/ssrf-protection.md#default-blocked-ranges), optionally combined with custom ranges (for example: `default,100.0.0.0/8`). | +| `N8N_SSRF_ALLOWED_IP_RANGES` | String | - | Comma-separated CIDR ranges to allow. Takes precedence over the blocked ranges. | +| `N8N_SSRF_ALLOWED_HOSTNAMES` | String | - | Comma-separated hostname patterns to allow. Supports wildcards (for example: `*.n8n.internal`). Takes precedence over blocked IP ranges. | +| `N8N_SSRF_DNS_CACHE_MAX_SIZE` | Number | `1048576` | Maximum DNS cache size in bytes. Uses LRU eviction when the limit is reached. Default is 1 MB. | diff --git a/docs/hosting/securing/overview.md b/docs/hosting/securing/overview.md index e3ddad48f..3efdcb356 100644 --- a/docs/hosting/securing/overview.md +++ b/docs/hosting/securing/overview.md @@ -19,4 +19,5 @@ More granularly, consider blocking or opting out of features or data collection * [Disable the public API](/hosting/securing/disable-public-api.md) if you aren't using it. * [Opt out of data collection](/hosting/securing/telemetry-opt-out.md) of the anonymous data n8n collects automatically. * [Block certain nodes](/hosting/securing/blocking-nodes.md) from being available to your users. +* [Protect against SSRF attacks](/hosting/securing/ssrf-protection.md) to control which hosts and IP ranges workflow nodes can connect to. * [Restrict account registration](/hosting/securing/restrict-by-email-verification.md) to email-verified users. \ No newline at end of file diff --git a/docs/hosting/securing/ssrf-protection.md b/docs/hosting/securing/ssrf-protection.md new file mode 100644 index 000000000..35c4963ca --- /dev/null +++ b/docs/hosting/securing/ssrf-protection.md @@ -0,0 +1,64 @@ +--- +title: SSRF protection +description: "Protect your self-hosted n8n instance from Server-Side Request Forgery (SSRF) attacks." +contentType: howto +--- + +# SSRF protection + +/// info | Available since 2.12.0 +/// + +Server-Side Request Forgery (SSRF) attacks abuse workflow nodes to make requests to internal network resources, cloud metadata endpoints, or localhost services that shouldn't be accessible. + +/// warning +SSRF protection is an additional application-level defense. You should always configure network-level protections (firewalls, security groups, network policies) on your infrastructure as your primary line of defense. n8n's SSRF protection adds defense-in-depth on top of those controls. +/// + +## Enable SSRF protection + +``` +N8N_SSRF_PROTECTION_ENABLED=true +``` + +When enabled, n8n validates all outbound HTTP requests from user-controllable nodes (such as the HTTP Request node) against the configured blocked and allowed ranges. This includes redirect targets and DNS resolution to prevent bypass techniques like DNS rebinding. + +## Default blocked ranges + +When SSRF protection is enabled, the following IP ranges are blocked by default: + +| Range | Description | +| :---- | :---------- | +| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC 1918 private addresses | +| `127.0.0.0/8`, `::1/128` | Loopback | +| `169.254.0.0/16`, `fe80::/10` | Link-local | +| `fc00::/7`, `fd00::/8` | IPv6 unique local | +| `0.0.0.0/8`, `192.0.0.0/24`, `192.0.2.0/24`, `198.18.0.0/15`, `198.51.100.0/24`, `203.0.113.0/24` | Reserved/special purpose | + +You can extend this list with `N8N_SSRF_BLOCKED_IP_RANGES=default,100.0.0.0/8`. + +## Allow access to internal services + +If your workflows need to reach legitimate internal services, use allowlists. Allowlists take precedence over blocklists, following this order: hostname allowlist > IP allowlist > IP blocklist. + +Allow by hostname pattern (supports wildcards like `*.n8n.internal`): + +``` +N8N_SSRF_ALLOWED_HOSTNAMES=*.n8n.internal,*.company.local +``` + +Allow by IP range: + +``` +N8N_SSRF_ALLOWED_IP_RANGES=10.0.1.0/24,10.0.2.50/32 +``` + +/// warning +Only allowlist hostnames within your control (internal DNS zones). Hostname allowlists bypass IP blocklist checks. +/// + +## Related resources + +Refer to [SSRF protection environment variables](/hosting/configuration/environment-variables/ssrf-protection.md) for the full list of configuration options. + +Refer to [Configuration methods](/hosting/configuration/configuration-methods.md) for more information on setting environment variables. diff --git a/nav.yml b/nav.yml index a0b9909ef..401250780 100644 --- a/nav.yml +++ b/nav.yml @@ -1246,6 +1246,7 @@ nav: - Nodes: hosting/configuration/environment-variables/nodes.md - Queue mode: hosting/configuration/environment-variables/queue-mode.md - Security: hosting/configuration/environment-variables/security.md + - SSRF protection: hosting/configuration/environment-variables/ssrf-protection.md - Source control: hosting/configuration/environment-variables/source-control.md - Task runners: hosting/configuration/environment-variables/task-runners.md - Timezone and localization: hosting/configuration/environment-variables/timezone-localization.md @@ -1291,6 +1292,7 @@ nav: - Opt out of data collection: hosting/securing/telemetry-opt-out.md - Blocking nodes: hosting/securing/blocking-nodes.md - Hardening task runners: hosting/securing/hardening-task-runners.md + - SSRF protection: hosting/securing/ssrf-protection.md - Restrict account registration to email-verified users: hosting/securing/restrict-by-email-verification.md - Starter Kits: - AI Starter Kit: hosting/starter-kits/ai-starter-kit.md