winrm 1.8.1 → 2.0.0

data/lib/winrm/psrp/message.rb

@@ -0,0 +1,130 @@
+# encoding: UTF-8
+#
+# Copyright 2015 Matt Wrock <matt@mattwrock.com>
+# 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 'uuid'
+require_relative 'message_data'
+
+module WinRM
+  # PowerShell Remoting Protcol module
+  module PSRP
+    # PowerShell Remoting Protocol base message.
+    # http://download.microsoft.com/download/9/5/E/95EF66AF-9026-4BB0-A41D-A4F81802D92C/%5BMS-PSRP%5D.pdf
+    class Message
+      include UUID
+
+      # Value of message destination when sent to a client
+      CLIENT_DESTINATION = 1
+
+      # Value of message destination when sent to a server
+      SERVER_DESTINATION = 2
+
+      # All known PSRP message types
+      MESSAGE_TYPES = {
+        session_capability:         0x00010002,
+        init_runspacepool:          0x00010004,
+        public_key:                 0x00010005,
+        encrypted_session_key:      0x00010006,
+        public_key_request:         0x00010007,
+        connect_runspacepool:       0x00010008,
+        runspace_init_data:         0x0002100b,
+        reset_runspace_state:       0x0002100c,
+        set_max_runspaces:          0x00021002,
+        set_min_runspaces:          0x00021003,
+        runspace_availability:      0x00021004,
+        runspacepool_state:         0x00021005,
+        create_pipeline:            0x00021006,
+        get_available_runspaces:    0x00021007,
+        user_event:                 0x00021008,
+        application_private_data:   0x00021009,
+        get_command_metadata:       0x0002100a,
+        runspacepool_host_call:     0x00021100,
+        runspacepool_host_response: 0x00021101,
+        pipeline_input:             0x00041002,
+        end_of_pipeline_input:      0x00041003,
+        pipeline_output:            0x00041004,
+        error_record:               0x00041005,
+        pipeline_state:             0x00041006,
+        debug_record:               0x00041007,
+        verbose_record:             0x00041008,
+        warning_record:             0x00041009,
+        progress_record:            0x00041010,
+        information_record:         0x00041011,
+        pipeline_host_call:         0x00041100,
+        pipeline_host_response:     0x00041101
+      }.freeze
+
+      # Creates a new PSRP message instance
+      # @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 type [Fixnum] The PSRP MessageType. This is most commonly
+      # specified in hex, e.g. 0x00010002.
+      # @param data [String] The PSRP payload as serialized XML
+      # @param destination [Fixnum] The destination for this message - client or server
+      def initialize(
+        runspace_pool_id,
+        type,
+        data,
+        pipeline_id = nil,
+        destination = SERVER_DESTINATION
+      )
+        raise 'invalid message type' unless MESSAGE_TYPES.values.include?(type)
+
+        @data = data
+        @destination = destination
+        @type = type
+        @pipeline_id = pipeline_id
+        @runspace_pool_id = runspace_pool_id
+      end
+
+      attr_reader :destination, :type, :runspace_pool_id, :pipeline_id, :data
+
+      # Returns the raw PSRP message bytes ready for transfer to Windows inside a
+      # WinRM message.
+      # @return [Array<Byte>] Unencoded raw byte array of the PSRP message.
+      def bytes
+        [
+          int16le(destination),
+          int16le(type),
+          uuid_to_windows_guid_bytes(runspace_pool_id),
+          uuid_to_windows_guid_bytes(pipeline_id),
+          byte_order_mark,
+          data_bytes
+        ].flatten
+      end
+
+      # Parses the raw data to a MessageData class
+      # @return [MessageData::Base] MessageData corresponding to this message type
+      def parsed_data
+        @parsed_data ||= MessageData.parse(self)
+      end
+
+      private
+
+      def byte_order_mark
+        [239, 187, 191]
+      end
+
+      def data_bytes
+        @data_bytes ||= data.force_encoding('utf-8').bytes
+      end
+
+      def int16le(int16)
+        [int16].pack('N').unpack('C4').reverse
+      end
+    end
+  end
+end

data/lib/winrm/psrp/message_data.rb

@@ -0,0 +1,41 @@
+# 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 'message_data/base'
+require_relative 'message_data/error_record'
+require_relative 'message_data/pipeline_output'
+require_relative 'message_data/pipeline_host_call'
+require_relative 'message_data/runspacepool_host_call'
+require_relative 'message_data/runspacepool_state'
+require_relative 'message_data/session_capability'
+
+module WinRM
+  # PowerShell Remoting Protcol module
+  module PSRP
+    # PowerShell Remoting Protocol message data.
+    module MessageData
+      def self.parse(message)
+        type_key = WinRM::PSRP::Message::MESSAGE_TYPES.key(message.type)
+        type = camelize(type_key.to_s).to_sym
+        const_get(type).new(message.data) if MessageData.constants.include?(type)
+      end
+
+      def self.camelize(underscore)
+        underscore.split('_').collect(&:capitalize).join
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# 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'
+
+module WinRM
+  # PowerShell Remoting Protcol module
+  module PSRP
+    # PowerShell Remoting Protocol message data.
+    module MessageData
+      # base class for message data
+      class Base
+        def initialize(data)
+          @raw = data
+        end
+
+        # @return [String] raw message data
+        attr_reader :raw
+
+        protected
+
+        def clixml
+          @clixml ||= begin
+            parser = Nori.new(
+              parser: :rexml,
+              advanced_typecasting: false,
+              convert_tags_to: ->(tag) { tag.snakecase.to_sym },
+              strip_namespaces: true
+            )
+            parser.parse(raw)[:obj][:ms]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# -*- 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
+      # pipeline host call message type
+      class ErrorRecord < Base
+        def exception
+          @exception ||= property_hash('Exception')
+        end
+
+        def fully_qualified_error_id
+          @fully_qualified_error_id ||= string_prop('FullyQualifiedErrorId')
+        end
+
+        def invocation_info
+          @invocation_info ||= property_hash('InvocationInfo')
+        end
+
+        def error_category_message
+          @error_category_message ||= string_prop('ErrorCategory_Message')
+        end
+
+        def error_details_script_stack_trace
+          @error_details_script_stack_trace ||= string_prop('ErrorDetails_ScriptStackTrace')
+        end
+
+        def doc
+          @doc ||= REXML::Document.new(raw)
+        end
+
+        def string_prop(prop_name)
+          prop = REXML::XPath.first(doc, "//*[@N='#{prop_name}']")
+          prop.text if prop
+        end
+
+        def property_hash(prop_name)
+          prop_nodes = REXML::XPath.first(doc, "//*[@N='#{prop_name}']/Props")
+          prop_nodes.elements.each_with_object({}) do |node, props|
+            name = node.attributes['N']
+            props[underscore(name).to_sym] = node.text if node.text
+          end
+        end
+
+        def underscore(camel)
+          camel.gsub(/::/, '/')
+               .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+               .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+               .tr('-', '_').downcase
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# -*- 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
+      # pipeline host call message type
+      class PipelineHostCall < Base
+        def method_identifier
+          clixml[:obj][0][:to_string]
+        end
+
+        def method_parameters
+          clixml[:obj][1][:lst]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# -*- 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 'rexml/document'
+
+module WinRM
+  module PSRP
+    module MessageData
+      # Handles decoding a raw powershell output response
+      class PipelineOutput < Base
+        def output
+          extract_out_string(remove_bom(raw.force_encoding('utf-8')))
+        end
+
+        private
+
+        def extract_out_string(text)
+          doc = REXML::Document.new(text)
+          doc.root.get_elements('//S').map do |node|
+            text = ''
+            if node.text
+              text << node.text.gsub(/_x(\h\h\h\h)_/) do
+                Regexp.last_match[1].hex.chr
+              end.chomp
+            end
+            text << "\r\n"
+          end.join
+        end
+
+        def remove_bom(text)
+          text.sub("\xEF\xBB\xBF", '')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# -*- 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
+      # runspace pool host call message type
+      class RunspacepoolHostCall < Base
+        def method_identifier
+          clixml[:obj][0][:to_string]
+        end
+
+        def method_parameters
+          clixml[:obj][1][:lst]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# -*- 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
+      # runspace pool state message type
+      class RunspacepoolState < Base
+        BEFORE_OPEN = 0
+        OPENING = 1
+        OPENED = 2
+        CLOSED = 3
+        CLOSING = 4
+        BROKEN = 5
+        NEGOTIATION_SENT = 6
+        NEGOTIATION_SUCCEEDED = 7
+        CONNECTING = 8
+        DISCONNECTED = 9
+
+        def runspace_state
+          clixml[:i32].to_i
+        end
+      end
+    end
+  end
+end