faraday-ssrf-filter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2dcc958c9132d2f306a52896efa1b21455232705fa5565cde86cf6205ac74c7e
+  data.tar.gz: 37663afac9a815654d26dda87d91ab901003d60a1c80f955871156a8af23f8b7
+SHA512:
+  metadata.gz: b882da77d01e75f0da42f90d6164c4e2b5af195ec0609e0a632b4f24275c687b921b74cb3aacd8beed3184f58534cd78ed33246863f02fccf7c630325cfe34a0
+  data.tar.gz: f073b6ffd4c3253ba46b550c66a882d5f4f4c8eebbc386eb92e1098e99844c0397238feac3178ae5f95cf397f7e3861b7442783769ddc19b81d6428aa654fd10

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-05-17)
+
+- Initial release
+- Block requests to private/reserved IPv4 and IPv6 ranges
+- DNS resolution with hostname replacement (HTTP) to prevent DNS rebinding
+- TLS SNI preservation for HTTPS requests
+- Redirect validation — block 3xx responses pointing to private/reserved IPs
+- IPv4-mapped/compatible/translated IPv6 address detection
+- NAT64 well-known prefix detection
+- Configurable allowlist/denylist
+- Custom DNS resolver support
+- Scheme validation
+- CI with Ruby 3.0-3.4 x Faraday 1/2 matrix

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quentin Rousseau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# Faraday SSRF Filter
+
+[![Gem Version](https://badge.fury.io/rb/faraday-ssrf-filter.svg)](https://rubygems.org/gems/faraday-ssrf-filter)
+
+A [Faraday](https://github.com/lostisland/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](https://github.com/arkadiyt/ssrf_filter) (which uses `Net::HTTP` directly), this gem brings the same level of SSRF protection to any Faraday-based HTTP client.
+
+## Features
+
+- 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**
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'faraday-ssrf-filter'
+```
+
+Or install directly:
+
+```bash
+gem install faraday-ssrf-filter
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+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
+```
+
+### Configuration Options
+
+```ruby
+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
+```
+
+### Error Handling
+
+All errors inherit from `Faraday::SsrfFilter::SSRFError` (which inherits from `Faraday::Error`):
+
+```ruby
+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
+```
+
+## Blocked IP Ranges
+
+### IPv4
+
+| Range | Purpose |
+|---|---|
+| `0.0.0.0/8` | Current network |
+| `10.0.0.0/8` | Private (RFC 1918) |
+| `100.64.0.0/10` | Carrier-grade NAT (RFC 6598) |
+| `127.0.0.0/8` | Loopback |
+| `169.254.0.0/16` | Link-local (includes cloud metadata endpoints) |
+| `172.16.0.0/12` | Private (RFC 1918) |
+| `192.0.0.0/24` | IETF protocol assignments |
+| `192.0.2.0/24` | TEST-NET-1 |
+| `192.168.0.0/16` | Private (RFC 1918) |
+| `198.18.0.0/15` | Benchmarking |
+| `198.51.100.0/24` | TEST-NET-2 |
+| `203.0.113.0/24` | TEST-NET-3 |
+| `224.0.0.0/4` | Multicast |
+| `240.0.0.0/4` | Reserved |
+| `255.255.255.255/32` | Broadcast |
+
+### IPv6
+
+| Range | Purpose |
+|---|---|
+| `::/128` | Unspecified |
+| `::1/128` | Loopback |
+| `100::/64` | Discard prefix |
+| `2001::/32` | Teredo tunneling |
+| `2001:2::/48` | Benchmarking |
+| `2001:10::/28` | ORCHID |
+| `2001:20::/28` | ORCHIDv2 |
+| `2001:db8::/32` | Documentation |
+| `2002::/16` | 6to4 tunneling |
+| `3fff::/20` | Documentation |
+| `5f00::/16` | Segment Routing (SRv6) |
+| `fc00::/7` | Unique local |
+| `fe80::/10` | Link-local |
+| `ff00::/8` | Multicast |
+| `64:ff9b:1::/48` | NAT64 local prefix |
+
+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.
+
+## How It Works
+
+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
+
+## Middleware Ordering
+
+When using a redirect-following middleware (e.g., `faraday-follow_redirects`), place it **before** the SSRF filter so each redirect is validated:
+
+```ruby
+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.
+
+## Acknowledgments
+
+This gem is heavily inspired by [ssrf_filter](https://github.com/arkadiyt/ssrf_filter) by [Arkadiy Tetelman](https://github.com/arkadiyt). 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.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/lib/faraday/ssrf_filter/middleware.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'resolv'
+require 'uri'
+
+module Faraday
+  module SsrfFilter
+    class SSRFError < Faraday::Error; end
+    class PrivateIPError < SSRFError; end
+    class DirectIPError < SSRFError; end
+    class InvalidSchemeError < SSRFError; end
+    class DNSResolutionError < SSRFError; end
+    class UnsafeRedirectError < SSRFError; end
+
+    class Middleware < Faraday::Middleware
+      DEFAULT_SCHEMES = %w[http https].freeze
+      REDIRECT_STATUSES = (300..399)
+
+      IPV4_DENYLIST = [
+        IPAddr.new('0.0.0.0/8'),
+        IPAddr.new('10.0.0.0/8'),
+        IPAddr.new('100.64.0.0/10'),
+        IPAddr.new('127.0.0.0/8'),
+        IPAddr.new('169.254.0.0/16'),
+        IPAddr.new('172.16.0.0/12'),
+        IPAddr.new('192.0.0.0/24'),
+        IPAddr.new('192.0.2.0/24'),
+        IPAddr.new('192.168.0.0/16'),
+        IPAddr.new('198.18.0.0/15'),
+        IPAddr.new('198.51.100.0/24'),
+        IPAddr.new('203.0.113.0/24'),
+        IPAddr.new('224.0.0.0/4'),
+        IPAddr.new('240.0.0.0/4'),
+        IPAddr.new('255.255.255.255/32')
+      ].freeze
+
+      IPV6_DENYLIST = [
+        IPAddr.new('::1/128'),
+        IPAddr.new('::/128'),
+        IPAddr.new('100::/64'),
+        IPAddr.new('2001::/32'),
+        IPAddr.new('2001:2::/48'),
+        IPAddr.new('2001:10::/28'),
+        IPAddr.new('2001:20::/28'),
+        IPAddr.new('2001:db8::/32'),
+        IPAddr.new('2002::/16'),
+        IPAddr.new('3fff::/20'),
+        IPAddr.new('5f00::/16'),
+        IPAddr.new('fc00::/7'),
+        IPAddr.new('fe80::/10'),
+        IPAddr.new('ff00::/8'),
+        IPAddr.new('64:ff9b:1::/48'),
+        *IPV4_DENYLIST.flat_map do |range|
+          pfx = range.prefix
+          ip = range.to_s
+          [
+            IPAddr.new("::#{ip}/#{pfx + 96}"),
+            IPAddr.new("::ffff:#{ip}/#{pfx + 96}"),
+            IPAddr.new("::ffff:0:#{ip}/#{pfx + 96}"),
+            IPAddr.new("64:ff9b::#{ip}/#{pfx + 96}")
+          ]
+        end
+      ].freeze
+
+      def initialize(app, options = {})
+        super(app)
+        @schemes = (options[:allowed_schemes] || DEFAULT_SCHEMES).freeze
+        @resolver = options[:resolver] || method(:default_resolver)
+        @allow_ip_addresses = options[:allow_ip_addresses] == true
+        @allowlist = parse_ip_list(options[:allowlist]).freeze
+        @denylist = parse_ip_list(options[:denylist]).freeze
+      end
+
+      def call(env)
+        validate_and_pin!(env)
+        @app.call(env).on_complete { |response_env| validate_redirect!(response_env) }
+      end
+
+      private
+
+      def default_resolver(hostname)
+        Resolv.getaddresses(hostname)
+      end
+
+      def parse_ip_list(list)
+        (list || []).map { |r| r.is_a?(IPAddr) ? r : IPAddr.new(r) }
+      end
+
+      def validate_and_pin!(env)
+        validate_scheme!(env[:url])
+        hostname = env[:url].hostname
+        addr = parse_ip(hostname)
+
+        if addr
+          validate_direct_ip!(addr, hostname)
+        else
+          resolve_and_pin!(env, hostname)
+        end
+      end
+
+      def validate_scheme!(uri)
+        raise InvalidSchemeError, "URI scheme '#{uri.scheme}' not allowed" unless @schemes.include?(uri.scheme)
+      end
+
+      def validate_direct_ip!(addr, hostname)
+        raise DirectIPError, "Direct IP addresses are not allowed: #{hostname}" unless @allow_ip_addresses
+        raise PrivateIPError, "IP address '#{hostname}' is private/reserved" unless safe_addr?(addr)
+      end
+
+      def resolve_and_pin!(env, hostname)
+        addresses = Array(@resolver.call(hostname))
+        raise DNSResolutionError, "Could not resolve hostname: #{hostname}" if addresses.empty?
+
+        safe_address = addresses.find { |a| safe_ip?(a.to_s) }
+        raise PrivateIPError, "Hostname '#{hostname}' resolves to a private/reserved IP address" unless safe_address
+
+        pin_ip!(env, safe_address.to_s, hostname)
+      end
+
+      def pin_ip!(env, ip, original_hostname)
+        uri = env[:url]
+        env[:request_headers] ||= {}
+        env[:request_headers]['X-Faraday-SSRF-Original-Host'] = original_hostname
+        env[:request_headers]['X-Faraday-SSRF-Resolved-IP'] = ip
+
+        # Only rewrite hostname for HTTP. For HTTPS, rewriting breaks TLS SNI
+        # and certificate verification since the adapter would negotiate TLS
+        # with the IP address instead of the original hostname.
+        return unless uri.scheme == 'http'
+
+        env[:request_headers]['Host'] = normalized_host(uri)
+        env[:url] = uri.dup.tap { |u| u.hostname = ip }
+      end
+
+      def validate_redirect!(env)
+        return unless REDIRECT_STATUSES.cover?(env[:status])
+
+        location = env[:response_headers]&.[]('location')
+        return if location.nil? || location.empty?
+
+        uri = resolve_redirect_uri(location, env[:url])
+        validate_redirect_target!(uri)
+      end
+
+      def resolve_redirect_uri(location, original_uri)
+        uri = URI.parse(location)
+        return uri if uri.host
+
+        URI.join("#{original_uri.scheme}://#{original_uri.host}:#{original_uri.port}", location)
+      rescue URI::InvalidURIError
+        raise UnsafeRedirectError, "Invalid redirect location: #{location}"
+      end
+
+      def validate_redirect_target!(uri)
+        raise UnsafeRedirectError, "Redirect to disallowed scheme: #{uri.scheme}" unless @schemes.include?(uri.scheme)
+
+        hostname = uri.hostname || uri.host
+        return unless hostname
+
+        addr = parse_ip(hostname)
+        if addr
+          raise UnsafeRedirectError, "Redirect to private IP: #{hostname}" unless safe_addr?(addr)
+        else
+          validate_redirect_hostname!(hostname)
+        end
+      end
+
+      def validate_redirect_hostname!(hostname)
+        addresses = Array(@resolver.call(hostname))
+        raise UnsafeRedirectError, "Cannot resolve redirect hostname: #{hostname}" if addresses.empty?
+
+        safe = addresses.any? { |a| safe_ip?(a.to_s) }
+        raise UnsafeRedirectError, "Redirect to '#{hostname}' resolves to a private IP" unless safe
+      end
+
+      def normalized_host(uri)
+        host = uri.hostname
+        port = uri.port
+        return host if port.nil?
+        return host if uri.scheme == 'http' && port == 80
+        return host if uri.scheme == 'https' && port == 443
+
+        "#{host}:#{port}"
+      end
+
+      def parse_ip(hostname)
+        IPAddr.new(hostname)
+      rescue IPAddr::InvalidAddressError
+        nil
+      end
+
+      def safe_ip?(ip_string)
+        safe_addr?(IPAddr.new(ip_string))
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+
+      def safe_addr?(addr)
+        return true if @allowlist.any? { |range| range.include?(addr) }
+        return false if @denylist.any? { |range| range.include?(addr) }
+
+        !unsafe_ip?(addr)
+      end
+
+      def unsafe_ip?(addr)
+        if addr.ipv4?
+          IPV4_DENYLIST.any? { |range| range.include?(addr) }
+        elsif addr.ipv6?
+          IPV6_DENYLIST.any? { |range| range.include?(addr) }
+        else
+          true
+        end
+      end
+    end
+  end
+end

data/lib/faraday/ssrf_filter/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Faraday
+  module SsrfFilter
+    VERSION = '0.1.0'
+  end
+end

data/lib/faraday/ssrf_filter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require_relative 'ssrf_filter/middleware'
+require_relative 'ssrf_filter/version'
+
+module Faraday
+  module SsrfFilter
+    Faraday::Request.register_middleware(ssrf_filter: Faraday::SsrfFilter::Middleware)
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: faraday-ssrf-filter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Quentin Rousseau
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: 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 the request to proceed.
+email:
+- contact@quent.in
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/faraday/ssrf_filter.rb
+- lib/faraday/ssrf_filter/middleware.rb
+- lib/faraday/ssrf_filter/version.rb
+homepage: https://github.com/kwent/faraday-ssrf-filter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kwent/faraday-ssrf-filter
+  source_code_uri: https://github.com/kwent/faraday-ssrf-filter
+  changelog_uri: https://github.com/kwent/faraday-ssrf-filter/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Faraday middleware to prevent SSRF attacks
+test_files: []