socks_handler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38955165952ad878f7e2bef2bd818cc4b15232879c3ba967ab1ca62e1ad90bc1
+  data.tar.gz: 126326454aa18b570e72f02d3336c507c4ed63effbe3f95e09ac1eeb8ea019eb
+SHA512:
+  metadata.gz: f1793dfddaede01289c23c9d319b1be7144526fdf65eae3ed0eca36a842cc44d4886447b4397b98c98816b9b556e7448b614f4b4ae07a6ec4a2a4149ca5ea695
+  data.tar.gz: fee6367cfd655a0266be4e71d323a0bfa6ffcf2794ab4fdc57afd2344cfe1fcac93226867d7a5b5c6afd86e1590f8bb23294311a79af7efda379f0c86b578c56

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in socks_handler.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+# For generating sig/defs.rbs
+gem "yard"
+gem "sord"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 abicky
+
+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,323 @@
+# SocksHandler
+
+SocksHandler is a flexible socksifier for sockets created by `TCPSocket.new`, `Socket.tcp`, or `UDPSocket.new` that solves the following issues:
+
+* `SOCKSSocket` is not easy to use
+    - It is unavailable unless ruby is built with `--enable-socks`, and even if it is available, we cannot use domain names that the network where the program runs cannot resolve since socket classes, including `SOCKSSocket`, call `getaddrinfo` at initialization.
+* Famous socksifiers such as [socksify](https://www.inet.no/dante/doc/1.3.x/socksify.1.html) and [proxychains4](https://github.com/rofl0r/proxychains-ng) don't support rules using domain names
+    - Besides, they don't work on macOS if Ruby is managed by rbenv maybe due to SIP (System Integrity Protection)
+
+For more details, see the section "Related Work."
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add socks_handler
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install socks_handler
+
+## Usage
+
+### Socksify TCP Connections
+
+Assuming that a SOCKS server that can access the host "nginx" is listening on 127.0.0.1:1080. You can prepare such an environment with the following docker-compose.yml:
+
+```yaml
+version: "2.4"
+services:
+  sockd:
+    image: wernight/dante
+    ports:
+      - 1080:1080
+
+  nginx:
+    image: nginx
+```
+
+Here is an example to create a socket that can access the host "nginx" from the Docker host:
+
+```ruby
+require "socks_handler"
+
+socket = TCPSocket.new("127.0.0.1", 1080) # or Socket.tcp("127.0.0.1", 1080)
+SocksHandler::TCP.establish_connection(socket, "nginx", 80)
+
+socket.write(<<~REQUEST.gsub("\n", "\r\n"))
+  HEAD / HTTP/1.1
+  Host: nginx
+
+REQUEST
+puts socket.gets #=> HTTP/1.1 200 OK
+```
+
+If you want to access the host through the SOCKS server implicitly, you can use `SocksHandler.socksify` as follows:
+
+```ruby
+require "socks_handler"
+
+SocksHandler::TCP.socksify([
+  SocksHandler::ProxyAccessRule.new(
+    host_patterns: ["nginx"],
+    socks_server: "127.0.0.1:1080",
+  )
+])
+
+socket = TCPSocket.new("nginx", 80)
+socket.write(<<~REQUEST.gsub("\n", "\r\n"))
+  HEAD / HTTP/1.1
+  Host: nginx
+
+REQUEST
+puts socket.gets #=> HTTP/1.1 200 OK
+```
+
+With `SocksHandler::TCP.socksify`, other methods using `TCPSocket.new` or `Socket.tcp` also access the remote host through the SOCKS server:
+
+```ruby
+require "net/http"
+require "socks_handler"
+
+SocksHandler::TCP.socksify([
+  SocksHandler::ProxyAccessRule.new(
+    host_patterns: ["nginx"],
+    socks_server: "127.0.0.1:1080",
+  )
+])
+
+Net::HTTP.start("nginx", 80) do |http|
+  pp http.head("/") #=> #<Net::HTTPOK 200 OK readbody=true>
+end
+```
+
+For more details, see the document of `SocksHandler::TCP.socksify`:
+
+```
+$ ri SocksHandler::TCP.socksify
+```
+
+### Socksify UDP Connections
+
+Assuming that a SOCKS server that can access the host "echo", which is a UDP echo server, is listening on 127.0.0.1:1080. You can prepare such an environment with the following docker-compose.yml:
+
+```yaml
+version: "2.4"
+services:
+  sockd:
+    image: wernight/dante
+    ports:
+      - 1080:1080
+      - 1024-1030:1024-1030/udp
+    sysctls:
+      net.ipv4.ip_local_port_range: "1024 1030"
+
+  echo:
+    image: abicky/ncat:latest
+    command: -e /bin/cat -kul 7
+    init: true
+```
+
+Here is an example to create a socket that can access the host "nginx" from the Docker host:
+
+```ruby
+require "socks_handler"
+
+tcp_socket = TCPSocket.new("127.0.0.1", 1080) # or Socket.tcp("127.0.0.1", 1080)
+udp_socket = SocksHandler::UDP.associate_udp(tcp_socket, "0.0.0.0", 0)
+
+udp_socket.send("hello", 0, "echo", 7)
+puts udp_socket.gets #=> hello
+```
+
+
+## Limitation
+
+As `SocksHandler` only socksifies TCP connections created by `TCPSocket.new` or `Socket.tcp`, it doesn't socksify connections created by native extensions.
+
+For example, assuming that a SOCKS server that can access the host "mysql" is listening on 127.0.0.1:1080 as follows:
+
+```yaml
+version: "2.4"
+services:
+  sockd:
+    image: wernight/dante
+
+  mysql:
+    image: mysql:8
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+```
+
+The following code raises `Mysql2::Error::ConnectionError` because the gem "mysql2" tries to connect to the server via a native extension:
+
+```ruby
+require "mysql2"
+
+SocksHandler.socksify([
+  SocksHandler::ProxyAccessRule.new(
+    host_patterns: ["mysql"],
+    socks_server: "127.0.0.1:1080",
+  )
+])
+
+client = Mysql2::Client.new(
+  host: "mysql",
+  port: 3306,
+  username: "root",
+  password: "password",
+)
+client.ping
+#=> Unknown MySQL server host 'mysql' (8) (Mysql2::Error::ConnectionError)
+```
+
+## Related Work
+
+### Gems
+
+The following projects provide similar gems:
+
+* [ruby-proxifier](https://github.com/samuelkadolph/ruby-proxifier)
+    - This project seems to no longer be maintained.
+* [socksify-ruby](https://github.com/astro/socksify-ruby)
+
+### SOCKSSocket
+
+On macOS, you can build ruby with `SOCKSSocket` as follows:
+
+```
+$ brew install dante bison
+$ git clone https://github.com/ruby/ruby.git
+$ cd ruby
+$ git checkout v3_2_2
+$ ./configure --enable-socks
+$ PATH="/usr/local/opt/bison/bin:$PATH" make -j$(nproc) install
+$ cat <<EOF >/etc/socks.conf
+route {
+  from: 0.0.0.0/0 to: 0.0.0.0/0 via: 127.0.0.1 port = 1080
+  proxyprotocol: socks_v5
+  method: none
+}
+EOF
+```
+
+Here is example code to access nginx launched using docker-compose.yml in the section "Usage":
+
+```ruby
+require "socket"
+
+ip = `docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker compose ps -q nginx)`.chomp
+[ip, "nginx"].each do |host|
+  puts "Send an HTTP request to #{host}"
+  socket = SOCKSSocket.new(host, 80)
+  socket.write(<<~REQUEST.gsub("\n", "\r\n"))
+    HEAD / HTTP/1.1
+    Host: nginx
+
+  REQUEST
+  puts "Received: #{socket.gets}"
+end
+```
+
+As you can see below, we cannot use the domain name "nginx" since socket classes, including `SOCKSSocket`, call `getaddrinfo` at initialization:
+
+```
+$ /usr/local/bin/ruby /path/to/code.rb
+Send an HTTP request to 192.168.160.4
+Received: HTTP/1.1 200 OK
+Send an HTTP request to nginx
+code.rb:6:in `initialize': getaddrinfo: nodename nor servname provided, or not known (SocketError)
+        from code.rb:6:in `new'
+        from code.rb:6:in `block in <main>'
+        from code.rb:4:in `each'
+        from code.rb:4:in `<main>'
+```
+
+### ProxyChains-NG
+
+[ProxyChains-NG](https://github.com/rofl0r/proxychains-ng) is a socksifier that works well even on macOS.
+
+On macOS, you can install it as follows:
+
+```
+$ brew install proxychains-ng
+```
+
+Then edit `/usr/local/etc/proxychains.conf` to use the socks server listening on 127.0.0.1:1080:
+
+```
+[ProxyList]
+socks5 127.0.0.1 1080
+```
+
+ProxyChains-NG can socksify even connections created by native extensions. Here is example code to demonstrate it:
+
+```ruby
+require "net/http"
+require "mysql2"
+
+Net::HTTP.start("nginx", 80) do |http|
+  pp http.head("/")
+end
+
+client = Mysql2::Client.new(
+  host: "mysql",
+  port: 3306,
+  username: "root",
+  password: "password",
+)
+puts client.ping
+```
+
+As you can see below, the program can access containers though the socks server:
+
+```
+$ proxychains4 /usr/local/bin/ruby /path/to/code.rb
+[proxychains] config file found: /usr/local/etc/proxychains.conf
+[proxychains] preloading /usr/local/Cellar/proxychains-ng/4.16/lib/libproxychains4.dylib
+[proxychains] DLL init: proxychains-ng 4.16
+[proxychains] Strict chain  ...  127.0.0.1:1080  ...  nginx:80  ...  OK
+#<Net::HTTPOK 200 OK readbody=true>
+[proxychains] Strict chain  ...  127.0.0.1:1080  ...  mysql:3306  ...  OK
+true
+```
+
+However, it doesn't work if Ruby is managed by rbenv:
+
+```
+$ rbenv local
+3.2.2
+$ proxychains4 ruby /path/to/code.rb
+[proxychains] config file found: /usr/local/etc/proxychains.conf
+[proxychains] preloading /usr/local/Cellar/proxychains-ng/4.16/lib/libproxychains4.dylib
+/Users/arabiki/.anyenv/envs/rbenv/versions/3.2.2/lib/ruby/3.2.0/net/http.rb:1271:in `initialize': Failed to open TCP connection to nginx:80 (getaddrinfo: nodename nor servname provided, or not known) (SocketError)
+-- snip --
+```
+
+Maybe the reason is that macOS doesn't allow any system binaries to preload libraries and rbenv uses `/usr/bin/env`:
+
+```
+$ proxychains4 env /usr/local/bin/ruby /path/to/code.rb
+[proxychains] config file found: /usr/local/etc/proxychains.conf
+[proxychains] preloading /usr/local/Cellar/proxychains-ng/4.16/lib/libproxychains4.dylib
+/usr/local/lib/ruby/3.2.0/net/http.rb:1271:in `initialize': Failed to open TCP connection to nginx:80 (getaddrinfo: nodename nor servname provided, or not known) (SocketError)
+-- snip --
+```
+
+Although ProxyChains-NG works well in almost all cases, it cannot use domain names to determine whether to access them through a socks proxy.
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/abicky/socks_handler.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+task :generate_rbs do
+  sh "sord sig/defs.rbs"
+  sh %Q{sed -i#{" " if RUBY_PLATFORM.include?("darwin")}'' '1s/^/# This file was generated by "rake generate_rbs"\\n\\n/' sig/defs.rbs}
+  # Workaround for the error "Detected recursive ancestors: ::SocksHandler::UDPSocket < ::SocksHandler::UDPSocket"
+  sh %Q{sed -i#{" " if RUBY_PLATFORM.include?("darwin")}'' 's/UDPSocket < UDPSocket/UDPSocket < ::UDPSocket/' sig/defs.rbs}
+end

data/docker-compose.yml

@@ -0,0 +1,89 @@
+version: "2.4"
+services:
+  create-work-directory:
+    image: wernight/dante
+    entrypoint: ""
+    command: |
+      sh -c '
+      cat <<EOF >/work/entrypoint.sh
+      #!/bin/sh
+      set -e
+
+      # Allow IPv6 access
+      sed -i "s|from: 0.0.0.0/0 to: 0.0.0.0/0|from: 0/0 to: 0/0|" /etc/sockd.conf
+
+      if [ -n "\$$USERNAME" ]; then
+        sed -i "s/^    \#socksmethod: username/    socksmethod: username/" /etc/sockd.conf
+
+        printf "\$$PASSWORD\\n\$$PASSWORD\\n" | adduser \$$USERNAME
+      fi
+      exec sockd
+
+      EOF
+
+      chmod +x /work/entrypoint.sh
+      '
+    volumes:
+      - type: volume
+        source: workdir
+        target: /work
+
+  sockd-auth-none:
+    image: wernight/dante
+    command: /work/entrypoint.sh
+    ports:
+      - 1080:1080
+      - 1024-1030:1024-1030/udp
+    volumes:
+      - type: volume
+        source: workdir
+        target: /work
+    sysctls:
+      net.ipv4.ip_local_port_range: "1024 1030"
+    depends_on:
+      create-work-directory:
+        condition: service_completed_successfully
+
+  sockd-auth-username-password:
+    image: wernight/dante
+    command: /work/entrypoint.sh
+    environment:
+      USERNAME: user
+      PASSWORD: pass
+    ports:
+      - 1081:1080
+    volumes:
+      - type: volume
+        source: workdir
+        target: /work
+    depends_on:
+      create-work-directory:
+        condition: service_completed_successfully
+
+  nginx:
+    image: nginx
+
+  echo:
+    image: abicky/ncat:latest
+    command: -e /bin/cat -kul 7
+    init: true
+
+  ruby:
+    image: ruby:3.2.2
+    command: "sleep 86400"
+    volumes:
+      - type: bind
+        source: "."
+        target: "/work"
+    working_dir: /work
+    init: true
+volumes:
+  workdir:
+
+networks:
+  default:
+    enable_ipv6: true
+    ipam:
+      config:
+        - subnet: 2001:3984:3989::/64
+          gateway: 2001:3984:3989::1

data/lib/socks_handler/address_type.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SocksHandler
+  module AddressType
+    # @return [Integer]
+    IPV4 = 0x01
+    # @return [Integer]
+    DOMAINNAME = 0x03
+    # @return [Integer]
+    IPV6 = 0x04
+  end
+end

data/lib/socks_handler/authentication_method.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SocksHandler
+  module AuthenticationMethod
+    # @return [Integer]
+    NONE = 0x00
+    # @return [Integer]
+    GSSAPI = 0x01 # Not supported yet (https://www.ietf.org/rfc/rfc1961.txt)
+    # @return [Integer]
+    USERNAME_PASSWORD = 0x02
+  end
+end

data/lib/socks_handler/command.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SocksHandler
+  module Command
+    # @return [Integer]
+    CONNECT = 0x01
+    # @return [Integer]
+    BIND = 0x02 # Not supported yet
+    # @return [Integer]
+    UDP_ASSOCIATE = 0x03
+  end
+end

data/lib/socks_handler/direct_access_rule.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+require "socks_handler/rule"
+
+module SocksHandler
+  class DirectAccessRule < Rule
+    # @param host_patterns [Array<String, Regexp>]
+    def initialize(host_patterns:)
+      super(host_patterns: host_patterns)
+    end
+
+    # @return [true]
+    def direct
+      true
+    end
+  end
+end

data/lib/socks_handler/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SocksHandler
+  class UnsupportedProtocol < StandardError; end
+
+  class NoAcceptableMethods < StandardError; end
+
+  class AuthenticationFailure < StandardError; end
+
+  class RelayRequestFailure < StandardError
+    # @param code [Integer]
+    def initialize(code)
+      case code
+      when 0x01
+        super("general SOCKS server failure")
+      when 0x02
+        super("connection not allowed by ruleset")
+      when 0x03
+        super("Network unreachable")
+      when 0x04
+        super("Host unreachable")
+      when 0x05
+        super("Connection refused")
+      when 0x06
+        super("TTL expired")
+      when 0x07
+        super("Command not supported")
+      when 0x08
+        super("Address type not supported")
+      else
+        super("Unknown error")
+      end
+    end
+  end
+end

data/lib/socks_handler/proxy_access_rule.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+require "socks_handler/rule"
+
+module SocksHandler
+  class ProxyAccessRule < Rule
+    # @param host_patterns [Array<String, Regexp>]
+    # @param socks_server [String] a string in the format "<host>:<port>"
+    # @param username [String, nil]
+    # @param password [String, nil]
+    def initialize(host_patterns:, socks_server:, username: nil, password: nil)
+      host, port = socks_server.split(":")
+      super(host_patterns: host_patterns, host: host, port: port.to_i, username: username, password: password)
+    end
+
+    # @return [false]
+    def direct
+      false
+    end
+  end
+end

data/lib/socks_handler/rule.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module SocksHandler
+  # @!attribute [r] host
+  #   @return [String, nil]
+  # @!attribute [r] port
+  #   @return [Integer, nil]
+  # @!attribute [r] username
+  #   @return [String, nil]
+  # @!attribute [r] password
+  #   @return [String, nil]
+  # @!attribute [r] host_patterns
+  #   @return [Array<String, Regexp>]
+  class Rule
+    attr_reader :host, :port, :username, :password, :host_patterns
+
+    # @return [Rule]
+    def self.new(**kwargs)
+      raise "Rule is an abstract class" if self == Rule
+      super
+    end
+
+    # @param host_patterns [Array<String, Regexp>]
+    # @param host [String, nil]
+    # @param port [Integer, nil]
+    # @param username [String, nil]
+    # @param password [String, nil]
+    def initialize(host_patterns:, host: nil, port: nil, username: nil, password: nil)
+      @host = host
+      @port = port
+      @username = username
+      @password = password
+      self.host_patterns = host_patterns
+    end
+
+    # @return [Boolean]
+    def direct
+      raise NotImplementedError
+    end
+
+    # @param value [Array<String, Regexp>]
+    # @return [Array<String, Regexp>]
+    def host_patterns=(value)
+      raise ArgumentError, "host_patterns is not an array" unless value.is_a?(Array)
+      @host_patterns = value.frozen? ? value : value.dup.freeze
+      @remote_host_pattern_regex = Regexp.union(convert_regexps(value))
+      value
+    end
+
+    # @param remote_host [String]
+    # @return [Boolean]
+    def match?(remote_host)
+      @remote_host_pattern_regex.match?(remote_host)
+    end
+
+    private
+
+    # @param value [Array<String, Regexp>]
+    # @return [Array<Regexp>]
+    def convert_regexps(value)
+      value.map do |v|
+        v.is_a?(Regexp) ? v : Regexp.new("\\A#{Regexp.escape(v)}\\z")
+      end
+    end
+  end
+end

data/lib/socks_handler/socket_socksify.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+ module SocksHandler
+   module SocketSocksify
+     # @param remote_host [String]
+     # @param remote_port [Integer, String]
+     # @param local_host [String, nil]
+     # @param local_port [Integer, String]
+     # @param connect_timeout [Integer, Float, nil]
+     # @param resolv_timeout [Integer, Float, nil]
+     # @return [Socket]
+     def tcp(remote_host, remote_port, local_host = nil, local_port = nil, connect_timeout: nil, resolv_timeout: nil, &block)
+       rule = SocksHandler::TCP.find_rule(remote_host)
+       return super if rule.nil? || rule.direct
+
+       socket = super(rule.host, rule.port, local_host, local_port, connect_timeout: connect_timeout, resolv_timeout: resolv_timeout, &block)
+       begin
+         SocksHandler::TCP.establish_connection(socket, remote_host, remote_port, rule.username, rule.password)
+       rescue
+         socket.close
+         raise
+       end
+
+       socket
+     end
+   end
+ end