train-winrm 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9ef423ad3bbdda0bb8bef459e8a124e0cc40d53b33d7a288fcf76e4a62c134c
-  data.tar.gz: b0c1dd4c13379e8e3c2ff3ebb6d18e3e8cdd43ac2f0a3bbe4bbe4abc8477cc5c
+  metadata.gz: 5b04c6c445681047b4681b59960762a6a4493340596dad7285f5f2f4ea1639e5
+  data.tar.gz: 77cddd410ec5e3053c727674c7338432479bc0b315ffc97ddaace31711435c06
 SHA512:
-  metadata.gz: c77123919b5639f935f9c4a7944ba423e63fecb73fc4028fa29ae879ecb80d921406076a96f0ccb7b4ec15aeed95aed622ef9a15dc6f0b214533eddd0151eb34
-  data.tar.gz: 79693ec60c636a3b705b463a623484b1b27b5cc0c8df19fb8991f02a9a5d86c65fa8b7a5fb9361368e4d3518360c4f20075f29b817de928c93c0816d63a351d7
+  metadata.gz: c1edf24433ce19b6e0a778a224b9a882e70e31a07f108d5a9c5d6224ef2b6f4d736502844fbd384d00a88dbc8a97c2dec90885f84804e230e25b5ffff311d4fc
+  data.tar.gz: 0c2127482ba6cd7747871b53c41c3b72b2ed20abe29968e6675bf1e9ff53967b3ae2745a745d2d4349183062b5caaeccd0d3bb16a1fa70b157d56b9e408181d0

data/lib/train-winrm/connection.rb

@@ -31,6 +31,8 @@
 # * marshalling to / from JSON
 # You don't have to worry about most of this.
 
+# frozen_string_literal: true
+
 require "train"
 require "train/plugins"
 # This module may need to directly require WinRM to reference its exception classes
@@ -50,6 +52,9 @@ module TrainPlugins
         @max_wait_until_ready   = @options.delete(:max_wait_until_ready)
         @operation_timeout      = @options.delete(:operation_timeout)
         @shell_type             = @options.delete(:winrm_shell_type)
+
+        # SOCKS proxy patch for HTTPClient
+        apply_socks_proxy_patch if @options[:socks_proxy]
       end
 
       # (see Base::Connection#close)
@@ -104,7 +109,7 @@ module TrainPlugins
 
       private
 
-      PING_COMMAND = "Write-Host '[WinRM] Established\n'".freeze
+      PING_COMMAND = "Write-Host '[WinRM] Established\n'"
 
       def file_via_connection(path)
         Train::File::Remote::Windows.new(self, path)
@@ -114,7 +119,7 @@ module TrainPlugins
         return if command.nil?
 
         logger.debug("[WinRM] #{self} (#{command})")
-        out = ""
+        out = +""
         response = nil
         timeout = opts[:timeout]&.to_i
 
@@ -234,6 +239,16 @@ module TrainPlugins
         end
       end
 
+      def apply_socks_proxy_patch
+        require_relative "socks_proxy_patch"
+
+        ::SocksProxyPatch.apply(
+          socks_proxy: @options[:socks_proxy],
+          socks_user: @options[:socks_user],
+          socks_password: @options[:socks_password]
+        )
+      end
+
       # String representation of object, reporting its connection details and
       # configuration.
       #

data/lib/train-winrm/socks_proxy_patch.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Patches the `HTTPClient` and `TCPSocket` classes to use a SOCKS5H proxy.
+# This class modifies the behavior of `HTTPClient` to route HTTP requests
+# through a SOCKS proxy by overriding the socket creation method.
+# It also configures `TCPSocket` to use the specified SOCKS proxy server,
+# and validates that the provided proxy is correct, resolvable, and accessible.
+
+require "socksify"
+require "httpclient"
+require "socket" unless defined?(Socket)
+
+class SocksProxyPatch
+  # Applies the SOCKS proxy settings to `HTTPClient` and `TCPSocket`.
+  #
+  # @param socks_proxy [String] The SOCKS proxy address in the format `host:port`.
+  # @param socks_user [String, nil] Optional SOCKS proxy username.
+  # @param socks_password [String, nil] Optional SOCKS proxy password.
+  # @example
+  #   SocksProxyPatch.apply(socks_proxy: "127.0.0.1:1080", socks_user: "user", socks_password: "pass")
+  def self.apply(socks_proxy:, socks_user: nil, socks_password: nil)
+    new(socks_proxy: socks_proxy, socks_user: socks_user, socks_password: socks_password).apply
+  end
+
+  def initialize(socks_proxy:, socks_user:, socks_password:)
+    @socks_proxy = socks_proxy
+    @socks_user = socks_user
+    @socks_password = socks_password
+  end
+
+  def apply
+    @proxy_host, @proxy_port = parse_and_validate_proxy(@socks_proxy)
+    configure_socks
+    patch_http_client
+  end
+
+  private
+
+  attr_reader :proxy_host, :proxy_port, :socks_user, :socks_password
+
+  # Parses the proxy string and validates its format, DNS resolution, and port.
+  def parse_and_validate_proxy(socks_proxy)
+    proxy_host, proxy_port = socks_proxy.split(":")
+
+    unless proxy_host && proxy_port
+      raise Train::ClientError, "Invalid SOCKS proxy format: '#{socks_proxy}'. Expected format is 'host:port'."
+    end
+
+    port = validate_port(proxy_port)
+    validate_dns_resolution(proxy_host)
+
+    [proxy_host, port]
+  end
+
+  # Ensures port is a valid integer in range.
+  def validate_port(port_str)
+    port = Integer(port_str)
+    unless port.between?(1, 65_535)
+      raise Train::ClientError, "SOCKS proxy port '#{port}' is out of valid range (1-65535)."
+    end
+
+    port
+  rescue ArgumentError
+    raise Train::ClientError, "Invalid SOCKS proxy port '#{port_str}'. Port must be an integer."
+  end
+
+  # Checks if the hostname is resolvable.
+  def validate_dns_resolution(host)
+    Socket.getaddrinfo(host, nil)
+  rescue SocketError => e
+    raise Train::ClientError, "DNS resolution failed for SOCKS proxy host '#{host}': #{e.message}"
+  end
+
+  # Applies the validated proxy settings to TCPSocket.
+  def configure_socks
+    TCPSocket.socks_username = socks_user if socks_user
+    TCPSocket.socks_password = socks_password if socks_password
+    TCPSocket.socks_server = proxy_host
+    TCPSocket.socks_port   = proxy_port
+  end
+
+  # Patches HTTPClient to route all connections through the SOCKS proxy.
+  def patch_http_client
+    HTTPClient::Session.class_eval do
+      unless method_defined?(:original_create_socket)
+        alias_method :original_create_socket, :create_socket
+
+        # Override the `create_socket` method to use `TCPSocket` with SOCKS proxy.
+        def create_socket(host, port, *args)
+          socket = ::TCPSocket.new(host, port)
+          socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [5, 0].pack("l_2"))
+          socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, [5, 0].pack("l_2"))
+          socket
+        rescue HTTPClient::ConnectTimeoutError
+          raise Train::ClientError, "SOCKS proxy connection to #{host}:#{port} timed out (HTTPClient::ConnectTimeoutError)"
+        rescue Errno::ETIMEDOUT
+          raise Train::ClientError, "Connection to #{host}:#{port} timed out through SOCKS proxy."
+        rescue Errno::EHOSTUNREACH, Errno::ENETUNREACH
+          raise Train::ClientError, "Network unreachable when connecting to #{host}:#{port} via SOCKS proxy."
+        rescue Errno::ECONNREFUSED
+          raise Train::ClientError, "Connection refused by SOCKS proxy when connecting to #{host}:#{port}."
+        rescue SocketError => e
+          raise Train::ClientError, "Socket error while connecting to #{host}:#{port} via SOCKS proxy: #{e.message}"
+        rescue StandardError => e
+          raise Train::ClientError, "Unexpected error during SOCKS proxy connection: #{e.class} - #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/train-winrm/transport.rb

@@ -79,6 +79,11 @@ module TrainPlugins
       option :client_key , default: nil
       option :client_key_pass , default: nil
 
+      # new socks proxy options
+      option :socks_proxy, default: nil
+      option :socks_user, default: nil
+      option :socks_password, default: nil
+
       def initialize(opts)
         super(opts)
         load_needed_dependencies!
@@ -102,24 +107,40 @@ module TrainPlugins
       def validate_options(opts)
         super(opts)
 
-        # set scheme and port based on ssl activation
-        scheme = opts[:ssl] ? "https" : "http"
-        port = opts[:port]
-        port = (opts[:ssl] ? 5986 : 5985) if port.nil?
-        winrm_transport = opts[:winrm_transport].to_sym
+        # Normalize to symbols
+        opts[:winrm_transport] = opts[:winrm_transport].to_s.downcase.to_sym if opts[:winrm_transport]
+        opts[:winrm_shell_type] = opts[:winrm_shell_type].to_s.downcase.to_sym if opts[:winrm_shell_type]
+
+        winrm_transport = opts[:winrm_transport]
+        winrm_shell_type = opts[:winrm_shell_type]
+
         unless SUPPORTED_WINRM_TRANSPORTS.include?(winrm_transport)
           raise Train::ClientError, "Unsupported transport type: #{winrm_transport.inspect}"
         end
 
-        winrm_shell_type = opts[:winrm_shell_type].to_sym
         unless SUPPORTED_WINRM_SHELL_TYPES.include?(winrm_shell_type)
           raise Train::ClientError, "Unsupported winrm shell type: #{winrm_shell_type.inspect}"
         end
 
-        # remove leading '/'
+        # Set scheme, port, endpoint
+        scheme = opts[:ssl] ? "https" : "http"
+        port = opts[:port] || (opts[:ssl] ? 5986 : 5985)
         path = (opts[:path] || "").sub(%r{^/+}, "")
 
         opts[:endpoint] = "#{scheme}://#{opts[:host]}:#{port}/#{path}"
+
+        # Auto-detect realm when not provided
+        if winrm_transport == :kerberos && opts[:kerberos_realm].nil?
+          begin
+            krb_realm = File.read("/etc/krb5.conf")[/default_realm\s*=\s*(\S+)/i, 1]
+            if krb_realm
+              opts[:kerberos_realm] = krb_realm
+              logger.debug("Kerberos realm auto-detected: #{krb_realm}")
+            end
+          rescue => e
+            logger.warn("Could not auto-detect Kerberos realm: #{e.message}")
+          end
+        end
       end
 
       WINRM_FS_SPEC_VERSION = ">= 1.3.7".freeze
@@ -134,7 +155,7 @@ module TrainPlugins
       def connection_options(opts)
         {
           logger: logger,
-          transport: opts[:winrm_transport].to_sym,
+          transport: opts[:winrm_transport],
           disable_sspi: opts[:winrm_disable_sspi],
           basic_auth_only: opts[:winrm_basic_auth_only],
           hostname: opts[:host],
@@ -154,6 +175,9 @@ module TrainPlugins
           client_cert: opts[:client_cert],
           client_key: opts[:client_key],
           key_pass: opts[:client_key_pass],
+          socks_proxy: opts[:socks_proxy],
+          socks_user: opts[:socks_user],
+          socks_password: opts[:socks_password],
         }
       end
 

data/lib/train-winrm/version.rb

@@ -5,6 +5,6 @@
 
 module TrainPlugins
   module WinRM
-    VERSION = "0.3.1".freeze
+    VERSION = "0.4.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: train-winrm
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Chef InSpec Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-05-06 00:00:00.000000000 Z
+date: 2025-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chef-winrm
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: 2.4.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: 2.4.4
 - !ruby/object:Gem::Dependency
   name: chef-winrm-elevated
   requirement: !ruby/object:Gem::Requirement
@@ -44,28 +44,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.4.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.4.0
+        version: 1.4.1
 - !ruby/object:Gem::Dependency
-  name: syslog
+  name: socksify
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.8'
 description: Allows applictaions using Train to speak to Windows using Remote Management;
   handles authentication, cacheing, and SDK dependency management.
 email:
@@ -77,6 +77,7 @@ files:
 - LICENSE
 - lib/train-winrm.rb
 - lib/train-winrm/connection.rb
+- lib/train-winrm/socks_proxy_patch.rb
 - lib/train-winrm/transport.rb
 - lib/train-winrm/version.rb
 homepage: https://github.com/inspec/train-winrm