Faraday SSRF Filter

A Faraday middleware that prevents Server-Side Request Forgery (SSRF) attacks by validating resolved IP addresses against known private and reserved IP ranges before allowing requests to proceed.

Inspired by ssrf_filter (which uses Net::HTTP directly), this gem brings the same level of SSRF protection to any Faraday-based HTTP client.

• Blocks requests to all private/reserved IPv4 and IPv6 ranges (RFC 1918, RFC 6598, loopback, link-local, multicast, etc.)
• Detects IPv4-mapped/compatible/translated IPv6 addresses (e.g., ::ffff:127.0.0.1)
• Detects NAT64 well-known prefix addresses (e.g., 64:ff9b::10.0.0.1)
• DNS resolution with IP pinning to prevent DNS rebinding attacks
• Blocks direct IP address usage by default
• Configurable allowlist/denylist for fine-grained control
• Custom DNS resolver support
• Scheme validation (only http/https by default)
• Works with all Faraday adapters (HTTPS connect-time pinning requires the default Net::HTTP adapter)

• Ruby 3.3+
• Faraday 1.x or 2.x

Add to your Gemfile:

gem 'faraday-ssrf-filter'

Or install directly:

gem install faraday-ssrf-filter

require 'faraday/ssrf_filter'

conn = Faraday.new(url: 'https://api.example.com') do |f|
  f.request :ssrf_filter
  f.adapter Faraday.default_adapter
end

# Safe requests work normally
response = conn.get('/data')

# Requests to private IPs are blocked
# e.g., if evil.com resolves to 127.0.0.1
# => raises Faraday::SsrfFilter::PrivateIPError

conn = Faraday.new(url: 'https://api.example.com') do |f|
  f.request :ssrf_filter,
    # Allow specific private ranges (e.g., internal services)
    allowlist: ['10.0.0.0/8'],

    # Block specific public ranges
    denylist: ['93.184.216.0/24'],

    # Allow direct IP addresses in URLs (default: false)
    allow_ip_addresses: true,

    # Restrict allowed URI schemes (default: ['http', 'https'])
    allowed_schemes: %w[http https],

    # Custom DNS resolver (default: Resolv.getaddresses)
    resolver: ->(hostname) { Resolv.getaddresses(hostname) }

  f.adapter Faraday.default_adapter
end

All errors inherit from Faraday::SsrfFilter::SSRFError (which inherits from Faraday::Error):

begin
  conn.get('/data')
rescue Faraday::SsrfFilter::PrivateIPError => e
  # Hostname resolved to a private/reserved IP
rescue Faraday::SsrfFilter::DirectIPError => e
  # URL contains a direct IP address (blocked by default)
rescue Faraday::SsrfFilter::InvalidSchemeError => e
  # URI scheme not in allowed list
rescue Faraday::SsrfFilter::DNSResolutionError => e
  # Could not resolve hostname
rescue Faraday::SsrfFilter::UnsafeRedirectError => e
  # Response redirects to a private/reserved IP or disallowed scheme
rescue Faraday::SsrfFilter::MiddlewareOrderError => e
  # A redirect-following middleware is registered inside the filter
rescue Faraday::SsrfFilter::SSRFError => e
  # Catch-all for any SSRF error
end

Additionally, all IPv4 blacklisted ranges are also blocked in their IPv4-compatible (::x.x.x.x), IPv4-mapped (::ffff:x.x.x.x), IPv4-translated (::ffff:0:x.x.x.x), and NAT64 (64:ff9b::x.x.x.x) IPv6 representations.

1. Scheme validation — Only http and https are allowed by default
2. Direct IP blocking — URLs with IP addresses instead of hostnames are blocked by default
3. DNS resolution — The hostname is resolved to IP addresses using Resolv.getaddresses
4. IP validation — Each resolved IP is checked against the comprehensive denylist
5. Hostname replacement (HTTP) — For HTTP requests, the URL hostname is replaced with the validated IP and the Host header is set to the original hostname, preventing DNS rebinding
6. Connect-time pinning (HTTPS) — For HTTPS requests, the hostname is preserved in the URL to maintain correct TLS SNI and certificate verification. With the Net::HTTP adapter (Faraday's default), the connection is opened to the validated IP via Net::HTTP#ipaddr=, so a second DNS lookup cannot rebind the request to a private address. Through an HTTP proxy, the CONNECT request also targets the validated IP. Other adapters, and Net::HTTP through a SOCKS proxy, resolve the hostname again when connecting, so those HTTPS requests are validated but not pinned. The resolved IP is stored in the X-Faraday-SSRF-Resolved-IP header
7. Redirect validation — Redirect responses (3xx with Location header) are inspected. The redirect target is resolved and validated against the same denylist, raising UnsafeRedirectError if it points to a private/reserved IP

When using a redirect-following middleware (e.g., faraday-follow_redirects), place it before the SSRF filter so each redirect is validated:

conn = Faraday.new(url: 'https://api.example.com') do |f|
  f.response :follow_redirects  # outer — follows redirects
  f.request :ssrf_filter         # inner — validates each request including redirects
  f.adapter Faraday.default_adapter
end

The filter only validates a redirect Location when the 3xx response passes back through it. A redirect middleware registered after the filter follows each hop itself, so the filter never sees the intermediate 3xx and redirect targets are not validated. To prevent that silent bypass, the filter raises Faraday::SsrfFilter::MiddlewareOrderError on the first request when it detects faraday-follow_redirects or faraday_middleware's FollowRedirects inside it.

On a redirect to a different host, the Host header pinned for the previous HTTP hop is dropped before the next hop is validated and pinned, so it never reaches the new host.

This gem is heavily inspired by ssrf_filter by Arkadiy Tetelman. The comprehensive IP blacklist, IPv4-mapped IPv6 detection, and NAT64 handling are all based on his excellent work. Thank you for building such a thorough and well-tested SSRF protection library for the Ruby ecosystem.

MIT License. See LICENSE for details.