winrm 1.8.1 → 2.0.0

data/lib/winrm/psrp/session_capability.xml.erb

@@ -0,0 +1,7 @@
+<Obj RefId="0">
+  <MS>
+    <Version N="protocolversion">2.3</Version>
+    <Version N="PSVersion">2.0</Version>
+    <Version N="SerializationVersion">1.1.0.1</Version>
+  </MS>
+</Obj>

data/lib/winrm/psrp/uuid.rb

@@ -0,0 +1,40 @@
+# encoding: UTF-8
+#
+# Copyright 2016 Shawn Neal <sneal@sneal.net>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module WinRM
+  module PSRP
+    # UUID helper methods
+    module UUID
+      # Format a UUID into a GUID compatible byte array for Windows
+      #
+      # https://msdn.microsoft.com/en-us/library/windows/desktop/aa373931(v=vs.85).aspx
+      # typedef struct _GUID {
+      #   DWORD Data1;
+      #   WORD  Data2;
+      #   WORD  Data3;
+      #   BYTE  Data4[8];
+      # } GUID;
+      #
+      # @param uuid [String] Canonical hex format with hypens.
+      # @return [Array<byte>] UUID in a Windows GUID compatible byte array layout.
+      def uuid_to_windows_guid_bytes(uuid)
+        return [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] unless uuid
+        b = uuid.scan(/[0-9a-fA-F]{2}/).map { |x| x.to_i(16) }
+        b[0..3].reverse + b[4..5].reverse + b[6..7].reverse + b[8..15]
+      end
+    end
+  end
+end

data/lib/winrm/shells/base.rb

@@ -0,0 +1,175 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Shawn Neal <sneal@sneal.net>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'retryable'
+require_relative '../http/transport'
+require_relative '../wsmv/cleanup_command'
+require_relative '../wsmv/close_shell'
+require_relative '../wsmv/command'
+require_relative '../wsmv/command_output'
+require_relative '../wsmv/receive_response_reader'
+require_relative '../wsmv/create_shell'
+require_relative '../wsmv/soap'
+
+module WinRM
+  module Shells
+    # Base class for remote shell
+    class Base
+      TOO_MANY_COMMANDS = '2150859174'.freeze
+      ERROR_OPERATION_ABORTED = '995'.freeze
+
+      FAULTS_FOR_RESET = [
+        '2150858843', # Shell has been closed
+        '2147943418', # Error reading registry key
+        TOO_MANY_COMMANDS, # Maximum commands per user exceeded
+      ].freeze
+
+      include Retryable
+
+      # Create a new Cmd shell
+      # @param connection_opts [ConnectionOpts] The WinRM connection options
+      # @param transport [HttpTransport] The WinRM SOAP transport
+      # @param logger [Logger] The logger to log diagnostic messages to
+      def initialize(connection_opts, transport, logger)
+        @connection_opts = connection_opts
+        @transport = transport
+        @logger = logger
+      end
+
+      # @return [String] shell id of the currently opn shell or nil if shell is closed
+      attr_reader :shell_id
+
+      # @return [String] uri that SOAP calls use to identify shell type
+      attr_reader :shell_uri
+
+      # @return [ConnectionOpts] connection options of the shell
+      attr_reader :connection_opts
+
+      # @return [WinRM::HTTP::HttpTransport] transport used to talk with endpoint
+      attr_reader :transport
+
+      # @return [Logger] logger used for diagnostic messages
+      attr_reader :logger
+
+      # Runs the specified command with optional arguments
+      # @param command [String] The command or executable to run
+      # @param arguments [Array] The optional command arguments
+      # @param block [&block] The optional callback for any realtime output
+      # @yieldparam [string] standard out response text
+      # @yieldparam [string] standard error response text
+      # @yieldreturn [WinRM::Output] The command output
+      def run(command, arguments = [], &block)
+        with_command_shell(command, arguments) do |shell, cmd|
+          response_reader.read_output(command_output_message(shell, cmd), &block)
+        end
+      end
+
+      # Closes the shell if one is open
+      def close
+        return unless shell_id
+        self.class.close_shell(connection_opts, transport, shell_id)
+        remove_finalizer
+        @shell_id = nil
+      end
+
+      protected
+
+      def send_command(_command, _arguments)
+        raise NotImplementedError
+      end
+
+      def response_reader
+        raise NotImplementedError
+      end
+
+      def open_shell
+        raise NotImplementedError
+      end
+
+      def out_streams
+        raise NotImplementedError
+      end
+
+      def command_output_message(shell_id, command_id)
+        cmd_out_opts = {
+          shell_id: shell_id,
+          command_id: command_id,
+          shell_uri: shell_uri,
+          out_streams: out_streams
+        }
+        WinRM::WSMV::CommandOutput.new(connection_opts, cmd_out_opts)
+      end
+
+      def with_command_shell(command, arguments = [])
+        tries ||= 2
+
+        open unless shell_id
+        command_id = send_command(command, arguments)
+        logger.debug("[WinRM] creating command_id: #{command_id} on shell_id #{shell_id}")
+        yield shell_id, command_id
+      rescue WinRMWSManFault => e
+        raise unless FAULTS_FOR_RESET.include?(e.fault_code) && (tries -= 1) > 0
+        reset_on_error(e)
+        retry
+      ensure
+        cleanup_command(command_id) if command_id
+      end
+
+      private
+
+      def reset_on_error(error)
+        close if error.fault_code == TOO_MANY_COMMANDS
+        logger.debug('[WinRM] opening new shell since the current one was deleted')
+        @shell_id = nil
+      end
+
+      def cleanup_command(command_id)
+        logger.debug("[WinRM] cleaning up command_id: #{command_id} on shell_id #{shell_id}")
+        cleanup_msg = WinRM::WSMV::CleanupCommand.new(
+          connection_opts,
+          shell_uri: shell_uri,
+          shell_id: shell_id,
+          command_id: command_id)
+        transport.send_request(cleanup_msg.build)
+      rescue WinRMWSManFault => e
+        raise unless e.fault_code == ERROR_OPERATION_ABORTED
+      rescue WinRMHTTPTransportError => t
+        # dont let the cleanup raise so we dont lose any errors from the command
+        logger.info("[WinRM] #{t.status_code} returned in cleanup with error: #{t.message}")
+      end
+
+      def open
+        close
+        retryable(connection_opts[:retry_limit], connection_opts[:retry_delay]) do
+          logger.debug("[WinRM] opening remote shell on #{connection_opts[:endpoint]}")
+          @shell_id = open_shell
+        end
+        logger.debug("[WinRM] remote shell created with shell_id: #{shell_id}")
+        add_finalizer
+      end
+
+      def add_finalizer
+        ObjectSpace.define_finalizer(
+          self,
+          self.class.finalize(connection_opts, transport, shell_id))
+      end
+
+      def remove_finalizer
+        ObjectSpace.undefine_finalizer(self)
+      end
+    end
+  end
+end

data/lib/winrm/shells/cmd.rb

@@ -0,0 +1,65 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Shawn Neal <sneal@sneal.net>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative 'base'
+
+module WinRM
+  module Shells
+    # Proxy to a remote cmd.exe shell
+    class Cmd < Base
+      include WinRM::WSMV::SOAP
+      class << self
+        def finalize(connection_opts, transport, shell_id)
+          proc { Cmd.close_shell(connection_opts, transport, shell_id) }
+        end
+
+        def close_shell(connection_opts, transport, shell_id)
+          msg = WinRM::WSMV::CloseShell.new(connection_opts, shell_id: shell_id)
+          transport.send_request(msg.build)
+        end
+      end
+
+      protected
+
+      def send_command(command, arguments)
+        cmd_msg = WinRM::WSMV::Command.new(
+          connection_opts,
+          shell_id: shell_id,
+          command: command,
+          arguments: arguments
+        )
+        resp_doc = transport.send_request(cmd_msg.build)
+        command_id = REXML::XPath.first(resp_doc, "//#{NS_WIN_SHELL}:CommandId").text
+        logger.debug("[WinRM] Command created for #{command} with id: #{command_id}")
+        command_id
+      end
+
+      def response_reader
+        @response_reader ||= WinRM::WSMV::ReceiveResponseReader.new(transport, logger)
+      end
+
+      def open_shell
+        msg = WinRM::WSMV::CreateShell.new(connection_opts)
+        resp_doc = transport.send_request(msg.build)
+        REXML::XPath.first(resp_doc, "//*[@Name='ShellId']").text
+      end
+
+      def out_streams
+        %w(stdout stderr)
+      end
+    end
+  end
+end

data/lib/winrm/shells/power_shell.rb

@@ -0,0 +1,201 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Shawn Neal <sneal@sneal.net>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'securerandom'
+require_relative 'base'
+require_relative '../psrp/message_fragmenter'
+require_relative '../psrp/receive_response_reader'
+require_relative '../wsmv/configuration'
+require_relative '../wsmv/create_pipeline'
+require_relative '../wsmv/send_data'
+require_relative '../wsmv/init_runspace_pool'
+require_relative '../wsmv/keep_alive'
+
+module WinRM
+  module Shells
+    # Proxy to a remote PowerShell instance
+    class Powershell < Base
+      include WinRM::WSMV::SOAP
+
+      class << self
+        def finalize(connection_opts, transport, shell_id)
+          proc { PowerShell.close_shell(connection_opts, transport, shell_id) }
+        end
+
+        def close_shell(connection_opts, transport, shell_id)
+          msg = WinRM::WSMV::CloseShell.new(
+            connection_opts,
+            shell_id: shell_id,
+            shell_uri: WinRM::WSMV::Header::RESOURCE_URI_POWERSHELL
+          )
+          transport.send_request(msg.build)
+        end
+      end
+
+      # Create a new powershell shell
+      # @param connection_opts [ConnectionOpts] The WinRM connection options
+      # @param transport [HttpTransport] The WinRM SOAP transport
+      # @param logger [Logger] The logger to log diagnostic messages to
+      def initialize(connection_opts, transport, logger)
+        super
+        @shell_uri = WinRM::WSMV::Header::RESOURCE_URI_POWERSHELL
+      end
+
+      # Runs the specified command
+      # @param command [String] The powershell script to run
+      # @param block [&block] The optional callback for any realtime output
+      # @yield [Message] PSRP Message in response
+      # @yieldreturn [Array<Message>] All messages in response
+      def send_pipeline_command(command, &block)
+        with_command_shell(command) do |shell, cmd|
+          response_reader.read_message(command_output_message(shell, cmd), true, &block)
+        end
+      end
+
+      # calculate the maimum fragment size so that they will be as large as possible yet
+      # no greater than the max_envelope_size_kb on the end point. To calculate this
+      # threshold, we:
+      # - determine the maximum number of bytes accepted on the endpoint
+      # - subtract the non-fragment characters in the SOAP envelope
+      # - determine the number of bytes that could be base64 encded to the above length
+      # - subtract the fragment header bytes (ids, length, etc)
+      def max_fragment_blob_size
+        @max_fragment_blob_size ||= begin
+          fragment_header_length = 21
+
+          begin
+            max_fragment_bytes = (max_envelope_size_kb * 1024) - empty_pipeline_envelope.length
+            base64_deflated(max_fragment_bytes) - fragment_header_length
+          rescue WinRMWSManFault => e
+            # A non administrator user will encounter an access denied
+            # error attempting to query winrm configuration.
+            # we will assin a small default and adjust to a protocol
+            # appropriate max length when that info is available
+            raise unless e.fault_code == '5'
+            WinRM::PSRP::MessageFragmenter::DEFAULT_BLOB_LENGTH
+          end
+        end
+      end
+
+      protected
+
+      def response_reader
+        @response_reader ||= WinRM::PSRP::ReceiveResponseReader.new(transport, logger)
+      end
+
+      def send_command(command, _arguments)
+        command_id = SecureRandom.uuid.to_s.upcase
+        message = PSRP::MessageFactory.create_pipeline_message(@runspace_id, command_id, command)
+        fragmenter.fragment(message) do |fragment|
+          command_args = [connection_opts, shell_id, command_id, fragment]
+          if fragment.start_fragment
+            resp_doc = transport.send_request(WinRM::WSMV::CreatePipeline.new(*command_args).build)
+            command_id = REXML::XPath.first(resp_doc, "//#{NS_WIN_SHELL}:CommandId").text
+          else
+            transport.send_request(WinRM::WSMV::SendData.new(*command_args).build)
+          end
+        end
+
+        logger.debug("[WinRM] Command created for #{command} with id: #{command_id}")
+        command_id
+      end
+
+      def open_shell
+        @runspace_id = SecureRandom.uuid.to_s.upcase
+        runspace_msg = WinRM::WSMV::InitRunspacePool.new(
+          connection_opts,
+          @runspace_id,
+          open_shell_payload(@runspace_id)
+        )
+        resp_doc = transport.send_request(runspace_msg.build)
+        shell_id = REXML::XPath.first(resp_doc, "//*[@Name='ShellId']").text
+        wait_for_running(shell_id)
+        shell_id
+      end
+
+      def out_streams
+        %w(stdout)
+      end
+
+      private
+
+      def base64_deflated(inflated_length)
+        inflated_length / 4 * 3
+      end
+
+      def empty_pipeline_envelope
+        WinRM::WSMV::CreatePipeline.new(
+          connection_opts,
+          '00000000-0000-0000-0000-000000000000',
+          '00000000-0000-0000-0000-000000000000'
+        ).build
+      end
+
+      def max_envelope_size_kb
+        @max_envelope_size_kb ||= begin
+          config_msg = WinRM::WSMV::Configuration.new(connection_opts)
+          msg = config_msg.build
+          resp_doc = transport.send_request(msg)
+          REXML::XPath.first(resp_doc, "//#{NS_WSMAN_CONF}:MaxEnvelopeSizekb").text.to_i
+        end
+      end
+
+      def open_shell_payload(shell_id)
+        [
+          WinRM::PSRP::MessageFactory.session_capability_message(shell_id),
+          WinRM::PSRP::MessageFactory.init_runspace_pool_message(shell_id)
+        ].map do |message|
+          fragmenter.fragment(message).bytes
+        end.flatten
+      end
+
+      def wait_for_running(shell_id)
+        state = WinRM::PSRP::MessageData::RunspacepoolState::OPENING
+        keepalive_msg = WinRM::WSMV::KeepAlive.new(connection_opts, shell_id)
+
+        # 2 is "openned". if we start issuing commands while in "openning" the runspace
+        # seems to hang
+        until state == WinRM::PSRP::MessageData::RunspacepoolState::OPENED
+          response_reader.read_message(keepalive_msg) do |message|
+            logger.debug("[WinRM] polling for pipeline state. message: #{message.inspect}")
+            parsed = message.parsed_data
+            case parsed
+            when WinRM::PSRP::MessageData::RunspacepoolState
+              state = parsed.runspace_state
+            when WinRM::PSRP::MessageData::SessionCapability
+              # if the user lacks admin privileges, we cannot query the MaxEnvelopeSizeKB
+              # on the server and will assign to a "best effort" default based on protocol version
+              if fragmenter.max_blob_length == WinRM::PSRP::MessageFragmenter::DEFAULT_BLOB_LENGTH
+                fragmenter.max_blob_length = default_protocol_envelope_size(parsed.protocol_version)
+              end
+            end
+          end
+        end
+      end
+
+      # Powershell v2.0 has a protocol version of 2.1
+      # which defaults to a 150 MaxEnvelopeSizeKB
+      # later versions default to 500
+      def default_protocol_envelope_size(protocol_version)
+        protocol_version > '2.1' ? 512000 : 153600
+      end
+
+      def fragmenter
+        @fragmenter ||= WinRM::PSRP::MessageFragmenter.new(max_fragment_blob_size)
+      end
+    end
+  end
+end