winrm 1.8.1 → 2.0.0

data/lib/winrm/psrp/message_data/session_capability.rb

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Matt Wrock <matt@mattwrock.com>
+#
+# 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
+    module MessageData
+      # session capability message type
+      class SessionCapability < Base
+        def protocol_version
+          clixml[:version].select { |v| v.attributes['N'] == 'protocolversion' }.first
+        end
+
+        def ps_version
+          clixml[:version].select { |v| v.attributes['N'] == 'PSVersion' }.first
+        end
+
+        def serialization_version
+          clixml[:version].select { |v| v.attributes['N'] == 'SerializationVersion' }.first
+        end
+      end
+    end
+  end
+end

data/lib/winrm/psrp/message_defragmenter.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+#
+# Copyright 2016 Matt Wrock <matt@mattwrock.com>
+#
+# 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 'fragment'
+
+module WinRM
+  # PowerShell Remoting Protcol module
+  module PSRP
+    # PowerShell Remoting Protocol message fragmenter.
+    class MessageDefragmenter
+      def initialize
+        @messages = {}
+      end
+
+      def defragment(base64_bytes)
+        fragment = fragment_from(Base64.decode64(base64_bytes))
+
+        @messages[fragment.object_id] ||= []
+        @messages[fragment.object_id].push fragment
+
+        if fragment.end_fragment
+          blob = []
+          @messages.delete(fragment.object_id).each { |frag| blob += frag.blob }
+          return message_from(blob.pack('C*'))
+        end
+      end
+
+      def fragment_from(byte_string)
+        Fragment.new(
+          byte_string[0..7].reverse.unpack('Q')[0],
+          byte_string[21..-1].bytes,
+          byte_string[8..15].reverse.unpack('Q')[0],
+          byte_string[16].unpack('C')[0][0] == 1,
+          byte_string[16].unpack('C')[0][1] == 1
+        )
+      end
+
+      def message_from(byte_string)
+        Message.new(
+          '00000000-0000-0000-0000-000000000000',
+          byte_string[4..7].unpack('V')[0],
+          byte_string[40..-1],
+          '00000000-0000-0000-0000-000000000000',
+          byte_string[0..3].unpack('V')[0]
+        )
+      end
+    end
+  end
+end

data/lib/winrm/psrp/message_factory.rb

@@ -0,0 +1,75 @@
+# 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 'erubis'
+require_relative 'message'
+
+module WinRM
+  module PSRP
+    # Creates WinRM::PSRP::Message instances for various PSRP messages
+    class MessageFactory
+      class << self
+        # Creates a new session capability PSRP message.
+        # @param runspace_pool_id [String] The UUID of the remote shell/runspace pool.
+        def session_capability_message(runspace_pool_id)
+          Message.new(
+            runspace_pool_id,
+            Message::MESSAGE_TYPES[:session_capability],
+            render('session_capability')
+          )
+        end
+
+        # Creates a new init runspace pool PSRP message.
+        # @param runspace_pool_id [String] The UUID of the remote shell/runspace pool.
+        def init_runspace_pool_message(runspace_pool_id)
+          Message.new(
+            runspace_pool_id,
+            Message::MESSAGE_TYPES[:init_runspacepool],
+            render('init_runspace_pool')
+          )
+        end
+
+        # Creates a new PSRP message that creates pipline to execute a command.
+        # @param runspace_pool_id [String] The UUID of the remote shell/runspace pool.
+        # @param pipeline_id [String] The UUID to correlate the command/pipeline
+        # response.
+        # @param command [String] The command passed to Invoke-Expression.
+        def create_pipeline_message(runspace_pool_id, pipeline_id, command)
+          Message.new(
+            runspace_pool_id,
+            Message::MESSAGE_TYPES[:create_pipeline],
+            render('create_pipeline', command: command.encode(xml: :text)),
+            pipeline_id
+          )
+        end
+
+        private
+
+        # Renders the specified template with the given context
+        # @param template [String] The base filename of the PSRP message template.
+        # @param context [Hash] Any options required for rendering the template.
+        # @return [String] The rendered XML PSRP message.
+        # @api private
+        def render(template, context = nil)
+          template_path = File.expand_path(
+            "#{File.dirname(__FILE__)}/#{template}.xml.erb")
+          template = File.read(template_path)
+          Erubis::Eruby.new(template).result(context)
+        end
+      end
+    end
+  end
+end

data/lib/winrm/psrp/message_fragmenter.rb

@@ -0,0 +1,60 @@
+# encoding: UTF-8
+#
+# Copyright 2016 Matt Wrock <matt@mattwrock.com>
+#
+# 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 'fragment'
+
+module WinRM
+  # PowerShell Remoting Protcol module
+  module PSRP
+    # PowerShell Remoting Protocol message fragmenter.
+    class MessageFragmenter
+      DEFAULT_BLOB_LENGTH = 32_768
+
+      def initialize(max_blob_length = DEFAULT_BLOB_LENGTH)
+        @object_id = 0
+        @max_blob_length = max_blob_length || DEFAULT_BLOB_LENGTH
+      end
+
+      attr_reader :object_id
+      attr_accessor :max_blob_length
+
+      def fragment(message)
+        @object_id += 1
+        message_bytes = message.bytes
+        bytes_fragmented = 0
+        fragment_id = 0
+        fragment = nil
+
+        while bytes_fragmented < message_bytes.length
+          last_byte = bytes_fragmented + max_blob_length
+          last_byte = message_bytes.length if last_byte > message_bytes.length
+          fragment = Fragment.new(
+            object_id,
+            message.bytes[bytes_fragmented..last_byte - 1],
+            fragment_id,
+            bytes_fragmented == 0,
+            last_byte == message_bytes.length
+          )
+          fragment_id += 1
+          bytes_fragmented = last_byte
+          yield fragment if block_given?
+        end
+
+        fragment
+      end
+    end
+  end
+end

data/lib/winrm/psrp/powershell_output_decoder.rb

@@ -0,0 +1,120 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Matt Wrock <matt@mattwrock.com>
+#
+# 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 'base64'
+require_relative 'message'
+
+module WinRM
+  module PSRP
+    # Handles decoding a raw powershell output response
+    class PowershellOutputDecoder
+      # Decode the raw SOAP output into decoded PSRP message,
+      # Removes BOM and replaces encoded line endings
+      # @param raw_output [String] The raw encoded output
+      # @return [String] The decoded output
+      def decode(message)
+        case message.type
+        when WinRM::PSRP::Message::MESSAGE_TYPES[:pipeline_output]
+          decode_pipeline_output(message)
+        when WinRM::PSRP::Message::MESSAGE_TYPES[:runspacepool_host_call]
+          decode_host_call(message)
+        when WinRM::PSRP::Message::MESSAGE_TYPES[:pipeline_host_call]
+          decode_host_call(message)
+        when WinRM::PSRP::Message::MESSAGE_TYPES[:error_record]
+          decode_error_record(message)
+        end
+      end
+
+      protected
+
+      def decode_pipeline_output(message)
+        message.parsed_data.output
+      end
+
+      def decode_host_call(message)
+        text = begin
+          case message.parsed_data.method_identifier
+          when /WriteLine/, 'WriteErrorLine'
+            "#{message.parsed_data.method_parameters[:s]}\r\n"
+          when 'WriteDebugLine'
+            "Debug: #{message.parsed_data.method_parameters[:s]}\r\n"
+          when 'WriteWarningLine'
+            "Warning: #{message.parsed_data.method_parameters[:s]}\r\n"
+          when 'WriteVerboseLine'
+            "Verbose: #{message.parsed_data.method_parameters[:s]}\r\n"
+          when /Write[1-2]/
+            message.parsed_data.method_parameters[:s]
+          end
+        end
+
+        hex_decode(text)
+      end
+
+      def decode_error_record(message)
+        parsed = message.parsed_data
+        text = begin
+          case parsed.fully_qualified_error_id
+          when 'Microsoft.PowerShell.Commands.WriteErrorException'
+            render_write_error_exception(parsed)
+          when 'NativeCommandError'
+            render_native_command_error(parsed)
+          when 'NativeCommandErrorMessage'
+            parsed.exception[:message]
+          else
+            render_exception(parsed)
+          end
+        end
+
+        hex_decode(text)
+      end
+
+      def render_write_error_exception(parsed)
+        <<EOH
+#{parsed.invocation_info[:line]} : #{parsed.exception[:message]}
+    + CategoryInfo          : #{parsed.error_category_message}
+    + FullyQualifiedErrorId : #{parsed.fully_qualified_error_id}
+EOH
+      end
+
+      def render_exception(parsed)
+        <<EOH
+#{parsed.exception[:message]}
+#{parsed.invocation_info[:position_message]}
+    + CategoryInfo          : #{parsed.error_category_message}
+    + FullyQualifiedErrorId : #{parsed.fully_qualified_error_id}
+EOH
+      end
+
+      def render_native_command_error(parsed)
+        <<EOH
+#{parsed.invocation_info[:my_command]} : #{parsed.exception[:message]}
+    + CategoryInfo          : #{parsed.error_category_message}
+    + FullyQualifiedErrorId : #{parsed.fully_qualified_error_id}
+EOH
+      end
+
+      private
+
+      def hex_decode(text)
+        return unless text
+
+        text.gsub(/_x(\h\h\h\h)_/) do
+          Regexp.last_match[1].hex.chr
+        end
+      end
+    end
+  end
+end

data/lib/winrm/psrp/receive_response_reader.rb

@@ -0,0 +1,93 @@
+# -*- encoding: utf-8 -*-
+#
+# Copyright 2016 Matt Wrock <matt@mattwrock.com>
+#
+# 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 'nori'
+require_relative 'powershell_output_decoder'
+require_relative 'message_defragmenter'
+
+module WinRM
+  module PSRP
+    # Class for reading powershell responses in Receive_Response messages
+    class ReceiveResponseReader < WSMV::ReceiveResponseReader
+      # Creates a new ReceiveResponseReader
+      # @param transport [HttpTransport] The WinRM SOAP transport
+      # @param logger [Logger] The logger to log diagnostic messages to
+      def initialize(transport, logger)
+        super
+        @output_decoder = PowershellOutputDecoder.new
+      end
+
+      # Reads PSRP messages sent in one or more receive response messages
+      # @param wsmv_message [WinRM::WSMV::Base] A wsmv message to send to endpoint
+      # @param wait_for_done_state whether to poll for a CommandState of Done
+      # @yield [Message] PSRP Message in response
+      # @yieldreturn [Array<Message>] All messages in response
+      def read_message(wsmv_message, wait_for_done_state = false)
+        messages = []
+        defragmenter = MessageDefragmenter.new
+        read_response(wsmv_message, wait_for_done_state) do |stream|
+          message = defragmenter.defragment(stream[:text])
+          next unless message
+          if block_given?
+            yield message
+          else
+            messages.push(message)
+          end
+        end
+        messages unless block_given?
+      end
+
+      # Reads streams and returns decoded output
+      # @param wsmv_message [WinRM::WSMV::Base] A wsmv message to send to endpoint
+      # @yieldparam [string] standard out response text
+      # @yieldparam [string] standard error response text
+      # @yieldreturn [WinRM::Output] The command output
+      def read_output(wsmv_message)
+        with_output do |output|
+          read_message(wsmv_message, true) do |message|
+            exit_code = find_exit_code(message)
+            output.exitcode = exit_code if exit_code
+            decoded_text = @output_decoder.decode(message)
+            next unless decoded_text
+            out = { stream_type(message) => decoded_text }
+            output << out
+            yield [out[:stdout], out[:stderr]] if block_given?
+          end
+        end
+      end
+
+      private
+
+      def stream_type(message)
+        type = :stdout
+        case message.type
+        when WinRM::PSRP::Message::MESSAGE_TYPES[:error_record]
+          type = :stderr
+        when WinRM::PSRP::Message::MESSAGE_TYPES[:pipeline_host_call]
+          type = :stderr if message.data.include?('WriteError')
+        end
+        type
+      end
+
+      def find_exit_code(message)
+        parsed = message.parsed_data
+        return nil unless parsed.is_a?(MessageData::PipelineHostCall)
+
+        parsed.method_parameters[:i32].to_i if parsed.method_identifier == 'SetShouldExit'
+      end
+    end
+  end
+end