├── lib ├── private_address_check │ ├── version.rb │ └── tcpsocket_ext.rb └── private_address_check.rb ├── test ├── test_helper.rb ├── private_address_check │ └── tcpsocket_ext_test.rb └── private_address_check_test.rb ├── .gitignore ├── bin ├── setup └── console ├── Gemfile ├── Rakefile ├── .github └── workflows │ └── ci.yml ├── .rubocop.yml ├── private_address_check.gemspec ├── LICENSE.txt ├── CODE_OF_CONDUCT.md └── README.md /lib/private_address_check/version.rb: -------------------------------------------------------------------------------- 1 | module PrivateAddressCheck 2 | VERSION = "0.5.0".freeze 3 | end 4 | -------------------------------------------------------------------------------- /test/test_helper.rb: -------------------------------------------------------------------------------- 1 | $LOAD_PATH.unshift File.expand_path("../../lib", __FILE__) 2 | require "private_address_check" 3 | 4 | require "minitest/autorun" 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.bundle/ 2 | /.yardoc 3 | /Gemfile.lock 4 | /_yardoc/ 5 | /coverage/ 6 | /doc/ 7 | /pkg/ 8 | /spec/reports/ 9 | /tmp/ 10 | /vendor/bundle/ 11 | -------------------------------------------------------------------------------- /bin/setup: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | set -euo pipefail 3 | IFS=$'\n\t' 4 | set -vx 5 | 6 | bundle install 7 | 8 | # Do any other automated setup that you need to do here 9 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | source "https://rubygems.org" 4 | 5 | gemspec 6 | 7 | gem "minitest", "~> 5.14" 8 | gem "rake", "~> 13.0" 9 | gem "rubocop", "~> 1.12" 10 | gem "rubocop-minitest", "~> 0.11.1" 11 | gem "rubocop-rake", "~> 0.5.1" 12 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | # frozen_string_literal: true 2 | 3 | require "bundler/gem_tasks" 4 | require "rake/testtask" 5 | 6 | Rake::TestTask.new(:test) do |t| 7 | t.libs << "test" 8 | t.libs << "lib" 9 | t.test_files = FileList["test/**/*_test.rb"] 10 | end 11 | 12 | task default: :test 13 | -------------------------------------------------------------------------------- /bin/console: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | # frozen_string_literal: true 3 | 4 | require "bundler/setup" 5 | require "private_address_check" 6 | 7 | # You can add fixtures and/or initialization code here to make experimenting 8 | # with your gem easier. You can also use a different console, if you like. 9 | 10 | # (If you use this, don't forget to add pry to your Gemfile!) 11 | # require "pry" 12 | # Pry.start 13 | 14 | require "irb" 15 | IRB.start 16 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: [ main ] 6 | pull_request: 7 | branches: [ main ] 8 | 9 | jobs: 10 | test: 11 | runs-on: ubuntu-latest 12 | strategy: 13 | matrix: 14 | ruby-version: ['2.4', '2.5', '2.6', '2.7', '3.0', '3.1', '3.2', '3.3'] 15 | steps: 16 | - uses: actions/checkout@v4 17 | - name: Set up Ruby 18 | uses: ruby/setup-ruby@v1 19 | with: 20 | ruby-version: ${{ matrix.ruby-version }} 21 | bundler-cache: true 22 | - name: Run tests 23 | run: bundle exec rake 24 | -------------------------------------------------------------------------------- /lib/private_address_check/tcpsocket_ext.rb: -------------------------------------------------------------------------------- 1 | module PrivateAddressCheck 2 | PrivateConnectionAttemptedError = Class.new(StandardError) 3 | 4 | module_function 5 | 6 | def only_public_connections 7 | Thread.current[:private_address_check] = true 8 | yield 9 | ensure 10 | Thread.current[:private_address_check] = false 11 | end 12 | end 13 | 14 | TCPSocket.class_eval do 15 | alias_method :initialize_without_private_address_check, :initialize 16 | 17 | def initialize(*args) 18 | initialize_without_private_address_check(*args) 19 | if Thread.current[:private_address_check] && PrivateAddressCheck.resolves_to_private_address?(remote_address.ip_address) 20 | raise PrivateAddressCheck::PrivateConnectionAttemptedError 21 | end 22 | end 23 | end 24 | -------------------------------------------------------------------------------- /.rubocop.yml: -------------------------------------------------------------------------------- 1 | require: 2 | - rubocop-minitest 3 | - rubocop-rake 4 | 5 | AllCops: 6 | TargetRubyVersion: 2.4 7 | NewCops: enable 8 | Include: 9 | - Gemfile 10 | - Rakefile 11 | 12 | Layout/SpaceInsideHashLiteralBraces: 13 | EnforcedStyle: no_space 14 | 15 | Metrics/BlockLength: 16 | IgnoredMethods: 17 | - describe 18 | - task 19 | 20 | Layout/LineLength: 21 | Max: 160 22 | 23 | Style/Documentation: 24 | Enabled: false 25 | 26 | Style/EmptyMethod: 27 | EnforcedStyle: expanded 28 | 29 | Style/GlobalVars: 30 | Enabled: false 31 | 32 | Style/GuardClause: 33 | Enabled: false 34 | 35 | Style/HashEachMethods: 36 | Enabled: true 37 | 38 | Style/HashSyntax: 39 | EnforcedStyle: ruby19 40 | 41 | Style/HashTransformKeys: 42 | Enabled: true 43 | 44 | Style/HashTransformValues: 45 | Enabled: true 46 | 47 | Style/IfUnlessModifier: 48 | Enabled: false 49 | 50 | Style/StringLiterals: 51 | EnforcedStyle: double_quotes 52 | -------------------------------------------------------------------------------- /private_address_check.gemspec: -------------------------------------------------------------------------------- 1 | 2 | lib = File.expand_path("../lib", __FILE__) 3 | $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) 4 | require "private_address_check/version" 5 | 6 | Gem::Specification.new do |spec| 7 | spec.name = "private_address_check" 8 | spec.version = PrivateAddressCheck::VERSION 9 | spec.authors = ["John Downey"] 10 | spec.email = ["jdowney@gmail.com"] 11 | 12 | spec.summary = "Prevent Server Side Request Forgery attacks by checking the destination" 13 | spec.description = "Checks if a IP or hostname would cause a request to a private network (RFC 1918)" 14 | spec.homepage = "https://github.com/jtdowney/private_address_check" 15 | spec.license = "MIT" 16 | 17 | spec.files = Dir.glob("{lib,test}/**/*.rb") + %w[CODE_OF_CONDUCT.md Gemfile LICENSE.txt README.md Rakefile] 18 | spec.require_paths = ["lib"] 19 | 20 | spec.required_ruby_version = ">= 2.4.0" 21 | end 22 | -------------------------------------------------------------------------------- /test/private_address_check/tcpsocket_ext_test.rb: -------------------------------------------------------------------------------- 1 | require "test_helper" 2 | require "private_address_check/tcpsocket_ext" 3 | 4 | class TCPSocketExtTest < Minitest::Test 5 | def test_private_address 6 | server = TCPServer.new(63_453) 7 | thread = Thread.start { server.accept } 8 | assert_raises PrivateAddressCheck::PrivateConnectionAttemptedError do 9 | PrivateAddressCheck.only_public_connections do 10 | TCPSocket.new("localhost", 63_453) 11 | end 12 | end 13 | ensure 14 | thread.exit if thread 15 | end 16 | 17 | def test_public_address 18 | connected = false 19 | PrivateAddressCheck.only_public_connections do 20 | TCPSocket.new("example.com", 80) 21 | connected = true 22 | end 23 | 24 | assert connected 25 | end 26 | 27 | def test_invalid_domain 28 | assert_raises SocketError do 29 | PrivateAddressCheck.only_public_connections do 30 | TCPSocket.new("not_a_domain", 80) 31 | end 32 | end 33 | end 34 | end 35 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 John Downey 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /test/private_address_check_test.rb: -------------------------------------------------------------------------------- 1 | require "test_helper" 2 | 3 | class PrivateAddressCheckTest < Minitest::Test 4 | def test_private_address_for_public_addresses 5 | refute PrivateAddressCheck.private_address?("192.30.253.113") 6 | refute PrivateAddressCheck.private_address?("8.8.8.8") 7 | end 8 | 9 | def test_private_address_for_rfc1918_addresses 10 | assert PrivateAddressCheck.private_address?("10.10.10.2") 11 | assert PrivateAddressCheck.private_address?("172.16.2.10") 12 | assert PrivateAddressCheck.private_address?("192.168.1.10") 13 | end 14 | 15 | def test_private_address_for_rfc4193_addresses 16 | assert PrivateAddressCheck.private_address?("fc00::a") 17 | assert PrivateAddressCheck.private_address?("fd00::2") 18 | end 19 | 20 | def test_private_address_for_loopback_addresses 21 | assert PrivateAddressCheck.private_address?("127.0.0.1") 22 | assert PrivateAddressCheck.private_address?("127.2.2.2") 23 | assert PrivateAddressCheck.private_address?("::1") 24 | end 25 | 26 | def test_private_address_for_link_local_addresses 27 | assert PrivateAddressCheck.private_address?("169.254.2.5") 28 | end 29 | 30 | def test_private_hostname_for_public_addresses 31 | refute PrivateAddressCheck.resolves_to_private_address?("github.com") 32 | refute PrivateAddressCheck.resolves_to_private_address?("example.com") 33 | end 34 | 35 | def test_private_hostname_for_private_addresses 36 | assert PrivateAddressCheck.resolves_to_private_address?("localhost") 37 | end 38 | 39 | def test_private_address_for_malformed_addresses 40 | assert PrivateAddressCheck.resolves_to_private_address?("127.1") 41 | end 42 | end 43 | -------------------------------------------------------------------------------- /lib/private_address_check.rb: -------------------------------------------------------------------------------- 1 | require "ipaddr" 2 | require "socket" 3 | 4 | require "private_address_check/version" 5 | 6 | module PrivateAddressCheck 7 | module_function 8 | 9 | # https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml 10 | # https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml 11 | CIDR_LIST = [ 12 | IPAddr.new("127.0.0.0/8"), # Loopback 13 | IPAddr.new("::1/128"), # Loopback 14 | IPAddr.new("0.0.0.0/8"), # Current network (only valid as source address) 15 | IPAddr.new("169.254.0.0/16"), # Link-local 16 | IPAddr.new("10.0.0.0/8"), # Private network 17 | IPAddr.new("100.64.0.0/10"), # Shared Address Space 18 | IPAddr.new("172.16.0.0/12"), # Private network 19 | IPAddr.new("192.0.0.0/24"), # IETF Protocol Assignments 20 | IPAddr.new("192.0.2.0/24"), # TEST-NET-1, documentation and examples 21 | IPAddr.new("192.88.99.0/24"), # IPv6 to IPv4 relay (includes 2002::/16) 22 | IPAddr.new("192.168.0.0/16"), # Private network 23 | IPAddr.new("198.18.0.0/15"), # Network benchmark tests 24 | IPAddr.new("198.51.100.0/24"), # TEST-NET-2, documentation and examples 25 | IPAddr.new("203.0.113.0/24"), # TEST-NET-3, documentation and examples 26 | IPAddr.new("224.0.0.0/4"), # IP multicast (former Class D network) 27 | IPAddr.new("240.0.0.0/4"), # Reserved (former Class E network) 28 | IPAddr.new("255.255.255.255"), # Broadcast 29 | IPAddr.new("64:ff9b::/96"), # IPv4/IPv6 translation (RFC 6052) 30 | IPAddr.new("100::/64"), # Discard prefix (RFC 6666) 31 | IPAddr.new("2001::/32"), # Teredo tunneling 32 | IPAddr.new("2001:10::/28"), # Deprecated (previously ORCHID) 33 | IPAddr.new("2001:20::/28"), # ORCHIDv2 34 | IPAddr.new("2001:db8::/32"), # Addresses used in documentation and example source code 35 | IPAddr.new("2002::/16"), # 6to4 36 | IPAddr.new("fc00::/7"), # Unique local address 37 | IPAddr.new("fe80::/10"), # Link-local address 38 | IPAddr.new("ff00::/8") # Multicast 39 | ].freeze 40 | 41 | def private_address?(address) 42 | CIDR_LIST.any? do |cidr| 43 | cidr.include?(address) 44 | end 45 | end 46 | 47 | def resolves_to_private_address?(hostname) 48 | ips = Socket.getaddrinfo(hostname, nil).map { |info| IPAddr.new(info[3]) } 49 | return true if ips.empty? 50 | 51 | ips.any? do |ip| 52 | private_address?(ip) 53 | end 54 | end 55 | end 56 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Code of Conduct 2 | 3 | As contributors and maintainers of this project, and in the interest of 4 | fostering an open and welcoming community, we pledge to respect all people who 5 | contribute through reporting issues, posting feature requests, updating 6 | documentation, submitting pull requests or patches, and other activities. 7 | 8 | We are committed to making participation in this project a harassment-free 9 | experience for everyone, regardless of level of experience, gender, gender 10 | identity and expression, sexual orientation, disability, personal appearance, 11 | body size, race, ethnicity, age, religion, or nationality. 12 | 13 | Examples of unacceptable behavior by participants include: 14 | 15 | * The use of sexualized language or imagery 16 | * Personal attacks 17 | * Trolling or insulting/derogatory comments 18 | * Public or private harassment 19 | * Publishing other's private information, such as physical or electronic 20 | addresses, without explicit permission 21 | * Other unethical or unprofessional conduct 22 | 23 | Project maintainers have the right and responsibility to remove, edit, or 24 | reject comments, commits, code, wiki edits, issues, and other contributions 25 | that are not aligned to this Code of Conduct, or to ban temporarily or 26 | permanently any contributor for other behaviors that they deem inappropriate, 27 | threatening, offensive, or harmful. 28 | 29 | By adopting this Code of Conduct, project maintainers commit themselves to 30 | fairly and consistently applying these principles to every aspect of managing 31 | this project. Project maintainers who do not follow or enforce the Code of 32 | Conduct may be permanently removed from the project team. 33 | 34 | This code of conduct applies both within project spaces and in public spaces 35 | when an individual is representing the project or its community. 36 | 37 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 38 | reported by contacting a project maintainer at jdowney@gmail.com. All 39 | complaints will be reviewed and investigated and will result in a response that 40 | is deemed necessary and appropriate to the circumstances. Maintainers are 41 | obligated to maintain confidentiality with regard to the reporter of an 42 | incident. 43 | 44 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 45 | version 1.3.0, available at 46 | [http://contributor-covenant.org/version/1/3/0/][version] 47 | 48 | [homepage]: http://contributor-covenant.org 49 | [version]: http://contributor-covenant.org/version/1/3/0/ -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # PrivateAddressCheck 2 | 3 | [![CI](https://github.com/jtdowney/private_address_check/actions/workflows/ci.yml/badge.svg)](https://github.com/jtdowney/private_address_check/actions/workflows/ci.yml) 4 | [![Code Climate](https://codeclimate.com/github/jtdowney/private_address_check/badges/gpa.svg)](https://codeclimate.com/github/jtdowney/private_address_check) 5 | 6 | Checks if a URL or hostname would cause a request to a private network (RFC 1918). This is useful in preventing attacks like [Server Side Request Forgery](https://cwe.mitre.org/data/definitions/918.html). 7 | 8 | ## Requirements 9 | 10 | - Ruby >= 2.4 11 | 12 | ## Installation 13 | 14 | Add this line to your application's Gemfile: 15 | 16 | ```ruby 17 | gem 'private_address_check' 18 | ``` 19 | 20 | And then execute: 21 | 22 | $ bundle 23 | 24 | Or install it yourself as: 25 | 26 | $ gem install private_address_check 27 | 28 | ## Usage 29 | 30 | ```ruby 31 | require "private_address_check" 32 | 33 | PrivateAddressCheck.private_address?("8.8.8.8") # => false 34 | PrivateAddressCheck.private_address?("10.10.10.2") # => true 35 | PrivateAddressCheck.private_address?("127.0.0.1") # => true 36 | PrivateAddressCheck.private_address?("172.16.2.10") # => true 37 | PrivateAddressCheck.private_address?("192.168.1.10") # => true 38 | PrivateAddressCheck.private_address?("fd00::2") # => true 39 | PrivateAddressCheck.resolves_to_private_address?("github.com") # => false 40 | PrivateAddressCheck.resolves_to_private_address?("localhost") # => true 41 | 42 | require "private_address_check/tcpsocket_ext" 43 | require "net/http" 44 | require "uri" 45 | 46 | Net::HTTP.get_response(URI.parse("http://192.168.1.1")) # => attempts connection like normal 47 | 48 | PrivateAddressCheck.only_public_connections do 49 | Net::HTTP.get_response(URI.parse("http://192.168.1.1")) 50 | end 51 | # => raises PrivateAddressCheck::PrivateConnectionAttemptedError 52 | ``` 53 | 54 | ## Development 55 | 56 | After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. 57 | 58 | To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). 59 | 60 | ## Contributing 61 | 62 | Bug reports and pull requests are welcome on GitHub at https://github.com/jtdowney/private_address_check. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. 63 | 64 | ## Security 65 | 66 | If you've found a security issue in `private_address_check`, please reach out to @jtdowney via email to report. 67 | 68 | ### Time of check to time of use 69 | 70 | A library like `private_address_check` is going to be easily susceptible to attacks like [time of check to time of use](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use). DNS entries with a TTL of 0 can trigger this case where the initial resolution is a public address by the subsequent resolution is a private address. There are some possible defenses and workarounds: 71 | 72 | - Use the TCPSocket extension in this library which checks the address the socket uses. This is most useful if your system is built on native Ruby like Net::HTTP. 73 | - Use a feature like the `resolve` capability in curl and [curb](https://www.rubydoc.info/github/taf2/curb/Curl/Easy#resolve=-instance_method) to force the resolution to a pre-checked IP address. 74 | - Implement your own caching DNS resolver with something like dnsmasq or unbound. These tools let you set a minimum cache time that can override the TTL of 0. 75 | 76 | ## License 77 | 78 | The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). 79 | --------------------------------------------------------------------------------