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

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::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. TLS preservation (HTTPS) — For HTTPS requests, the hostname is preserved in the URL to maintain correct TLS SNI and certificate verification. 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 SSRF filter also validates redirect Location headers in responses as defense-in-depth, regardless of middleware ordering.

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.