librex 0.0.20 → 0.0.21

data/lib/rex/post/meterpreter/extensions/stdapi/railgun/dll_helper.rb

@@ -0,0 +1,148 @@
+# Copyright (c) 2010, patrickHVE@googlemail.com
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * The names of the author may not be used to endorse or promote products
+#       derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL patrickHVE@googlemail.com BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+
+#
+# shared functions
+#
+# 
+module DLLHelper
+
+	# converts ruby string to zero-terminated ASCII string
+	def str_to_ascii_z(str)
+		return str+"\x00"
+	end
+
+	# converts 0-terminated ASCII string to ruby string
+	def asciiz_to_str(asciiz)
+		zero_byte_idx = asciiz.index("\x00")
+		if zero_byte_idx != nil
+			return asciiz[0, zero_byte_idx]
+		else
+			return asciiz
+		end
+	end
+
+	# converts ruby string to zero-terminated WCHAR string
+	def str_to_uni_z(str)
+		enc = str.unpack("C*").pack("v*")
+		enc += "\x00\x00"
+		return enc
+	end
+
+	# converts 0-terminated UTF16 to ruby string
+	def uniz_to_str(uniz)
+		uniz.unpack("v*").pack("C*").unpack("A*")[0]
+	end
+
+	# parses a number param and returns the value
+	# raises an exception if the param cannot be converted to a number
+	# examples:
+	#   nil => 0
+	#   3 => 3
+	#   "MB_OK" => 0
+	#   "SOME_CONSTANT | OTHER_CONSTANT" => 17
+	#   "tuna" => !!!!!!!!!!Exception
+	#
+	# Parameter "win_consts" is a WinConstantManager
+	def param_to_number(v, win_consts = @win_consts)
+		if v.class == NilClass then
+			return 0
+		elsif v.class == Fixnum then
+			return v # ok, it's already a number
+		elsif v.class == Bignum then
+			return v # ok, it's already a number
+		elsif v.class == String then
+			dw = win_consts.parse(v) # might raise an exception
+			if dw != nil
+				return dw
+			else
+				raise ArgumentError, "Param #{v} (class #{v.class}) cannot be converted to a number. It's a string but matches no constants I know."
+			end
+		else
+			raise "Param #{v} (class #{v.class}) should be a number but isn't"
+		end
+	end
+
+	# assembles the buffers "in" and "inout"
+	def assemble_buffer(direction, function, args)
+		layout = {} # paramName => BufferItem
+		blob = ""
+		#puts " building buffer: #{direction}"
+		function.params.each_with_index do |param_desc, param_idx|
+			#puts "  processing #{param_desc[0]} #{param_desc[1]} #{param_desc[2]}"
+			# we care only about inout buffers
+			if param_desc[2] == direction
+				buffer = nil
+				# Special case:
+				# The user can choose to supply a Null pointer instead of a buffer
+				# in this case we don't need space in any heap buffer
+				if param_desc[0][0,1] == 'P' # type is a pointer
+					if args[param_idx] == nil
+						next
+					end
+				end
+
+				case param_desc[0] # required argument type
+					when "PDWORD"
+						dw = param_to_number(args[param_idx])
+						buffer = [dw].pack('V')
+					when "PWCHAR"
+						raise "param #{param_desc[1]}: string expected" unless args[param_idx].class == String
+						buffer = str_to_uni_z(args[param_idx])
+					when "PCHAR"
+						raise "param #{param_desc[1]}: string expected" unless args[param_idx].class == String
+						buffer = str_to_ascii_z(args[param_idx])
+					when "PBLOB"
+						raise "param #{param_desc[1]}: please supply your BLOB as string!" unless args[param_idx].class == String
+						buffer = args[param_idx]
+					# other types (non-pointers) don't reference buffers
+					# and don't need any treatment here
+				end
+
+				if buffer != nil
+					#puts "   adding #{buffer.length} bytes to heap blob"
+					layout[param_desc[1]] = BufferItem.new(param_idx, blob.length, buffer.length, param_desc[0])
+					blob += buffer
+					# sf: force 8 byte alignment to satisfy x64, wont matter on x86.
+					while( blob.length % 8 != 0 )
+						blob += "\x00" 
+					end
+					#puts "   heap blob size now #{blob.length}"
+				end
+			end
+		end
+		#puts "  built buffer: #{direction}"
+		return [layout, blob]
+	end
+	
+end
+
+end; end; end; end; end; end; 

data/lib/rex/post/meterpreter/extensions/stdapi/railgun/dll_helper.rb.ut.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', '..', '..','..','..','..','..', 'lib'))
+
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll_helper'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/win_const_manager'
+require 'rex/text'
+require 'test/unit'
+
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+class DLLHelper::UnitTest < Test::Unit::TestCase
+
+	###
+	# We will test against this instance of DLLHelper (a module) 
+	# 
+	# We freeze the instance and make the reference constant to ensure consistency
+	##
+	TEST_DLL_HELPER = Object.new.extend(DLLHelper).freeze
+
+	def test_str_to_ascii_z
+		original_string = '23 Skidoo!'
+
+		# converts ruby string to zero-terminated ASCII string
+		zero_terminated_ascii_attempt = TEST_DLL_HELPER.str_to_ascii_z(original_string)
+
+		assert(zero_terminated_ascii_attempt.end_with?("\x00"), 
+			"str_to_ascii_z should result in a 0 terminated string")
+
+		assert(zero_terminated_ascii_attempt.start_with?(original_string), 
+			"str_to_ascii_z should still start with original string")
+
+		assert_equal(original_string.length + 1, zero_terminated_ascii_attempt.length, 
+			"str_to_ascii_z should have length of original pluss room for a terminal 0")
+	end
+
+	def test_asciiz_to_str
+		target_string = '23 Skidoo!'
+		post_zero_noise = 'Loud noises!'
+		zero_terminated_string = target_string + "\x00" + post_zero_noise
+
+		actual_string =  TEST_DLL_HELPER.asciiz_to_str(zero_terminated_string)
+
+		assert(actual_string.start_with?(target_string),
+			"asciiz_to_str should preserve string before zero")
+
+		assert(!actual_string.end_with?(post_zero_noise),
+			"asciiz_to_str should ignore characters after zero")
+
+		assert_equal(target_string, actual_string,
+			"asciiz_to_str should only return the contents of the string before (exclusive) the zero")
+
+		assert_equal(target_string, TEST_DLL_HELPER.asciiz_to_str(target_string),
+			"asciiz_to_str should return input verbatim should that input not be zero-terminated")
+
+	end
+
+	def test_str_to_uni_z
+		ruby_string = "If I were a rich man..."
+
+		target_zero_terminated_unicode = Rex::Text.to_unicode(ruby_string) + "\x00\x00"
+		actual_zero_terminated_unicode = TEST_DLL_HELPER.str_to_uni_z(ruby_string)
+
+		assert(actual_zero_terminated_unicode.end_with?("\x00\x00"),
+			"str_to_uni_z should result in a double-zero terminated string")
+
+		assert_equal(target_zero_terminated_unicode, actual_zero_terminated_unicode,
+			"str_to_uni_z should convert ruby string to zero-terminated WCHAR string")
+	end
+
+	def test_uniz_to_str
+		target_string = 'Foo bar baz'
+
+		zero_terminated_unicode = Rex::Text.to_unicode(target_string) + "\x00\x00"
+
+		assert_equal(target_string, TEST_DLL_HELPER.uniz_to_str(zero_terminated_unicode),
+			'uniz_to_str should convert 0-terminated UTF16 to ruby string')
+
+	end
+
+	def test_assemble_buffer
+		# TODO: provide test coverage 
+		#skip("Currently DLLHelper.assemble_buffer does not have coverage")
+	end
+
+	def test_param_to_number
+		consts_manager = WinConstManager.new
+
+		x_key = 'X'
+		x_value = 23
+
+		y_key = 'Y'
+		y_value = 5
+		
+		logical_or = x_key +  '|' +  y_key
+		target_result_of_logical_or = x_value | y_value
+
+		consts_manager.add_const(y_key, y_value)
+		consts_manager.add_const(x_key, x_value)
+
+		assert_equal(x_value, TEST_DLL_HELPER.param_to_number(x_key, consts_manager),
+			"param_to_number should return the appropriate value for a given constant")
+
+		assert_equal(y_value, TEST_DLL_HELPER.param_to_number(y_key, consts_manager),
+			"param_to_number should return the appropriate value for a given constant")
+
+		assert_equal(0, TEST_DLL_HELPER.param_to_number(nil, consts_manager),
+			"param_to_number should return zero when given nil")
+
+		assert_equal(target_result_of_logical_or, TEST_DLL_HELPER.param_to_number(logical_or, consts_manager),
+			"param_to_number should perform an OR should the input be in the form '#{logical_or}'")
+
+		assert_raise(ArgumentError, 'param_to_number should raise an error when a given key does not exist') do
+			TEST_DLL_HELPER.param_to_number('DOESNT_EXIST', consts_manager)
+		end
+	end
+end
+end
+end
+end
+end
+end
+end

data/lib/rex/post/meterpreter/extensions/stdapi/railgun/multicall.rb

@@ -0,0 +1,309 @@
+# Copyright (c) 2010, patrickHVE@googlemail.com
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#     * Redistributions of source code must retain the above copyright
+#       notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * The names of the author may not be used to endorse or promote products
+#       derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL patrickHVE@googlemail.com BE LIABLE FOR ANY
+# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'pp'
+require 'enumerator'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/api_constants'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/tlv'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll_helper'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/buffer_item'
+
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+
+# A easier way to call multiple functions in a single request
+class MultiCaller
+
+		include DLLHelper
+		
+		def initialize( client, parent, win_consts )
+			@parent     = parent
+			@client     = client
+			@win_consts = win_consts
+			if( @client.platform =~ /x64/i )
+				@native = 'Q'
+			else
+				@native = 'V'
+			end
+		end
+
+		def call(functions)
+
+			request = Packet.create_request('stdapi_railgun_api_multi')
+			function_results = []
+			layouts          = []
+			functions.each do |f|
+				dll_name,funcname,args = f
+				dll_host = @parent.get_dll( dll_name )
+
+				if not dll_host
+					raise "DLL #{dll_name} has not been loaded"
+				end
+
+				function = dll_host.functions[funcname]
+				if not function
+					raise "DLL #{dll_name} function #{funcname} has not been defined"
+				end
+
+				raise "#{function.params.length} arguments expected. #{args.length} arguments provided." unless args.length == function.params.length
+				#puts "process_function_call(function.windows_name,#{PP.pp(args, "")})"
+
+				# We transmit the immediate stack and three heap-buffers:
+				# in, inout and out. The reason behind the separation is bandwidth.
+				# We don't want to transmit uninitialized data in or no-longer-needed data out.
+
+				# out-only-buffers that are ONLY transmitted on the way BACK
+				out_only_layout = {} # paramName => BufferItem
+				out_only_size_bytes = 0
+				#puts " assembling out-only buffer"
+				function.params.each_with_index do |param_desc, param_idx|
+					#puts " processing #{param_desc[1]}"
+
+					# Special case:
+					# The user can choose to supply a Null pointer instead of a buffer
+					# in this case we don't need space in any heap buffer
+					if param_desc[0][0,1] == 'P' # type is a pointer
+						if args[param_idx] == nil
+							next
+						end
+					end
+
+					# we care only about out-only buffers
+					if param_desc[2] == "out"
+						raise "error in param #{param_desc[1]}: Out-only buffers must be described by a number indicating their size in bytes " unless args[param_idx].class == Fixnum
+						buffer_size = args[param_idx]
+						# bump up the size for an x64 pointer
+						if( @native == 'Q' and buffer_size == 4 )
+							args[param_idx] = 8
+							buffer_size = args[param_idx]
+						end
+						
+						if( @native == 'Q' )
+							raise "Please pass 8 for 'out' PDWORDS, since they require a buffer of size 8" unless buffer_size == 8
+						elsif( @native == 'V' )
+							raise "Please pass 4 for 'out' PDWORDS, since they require a buffer of size 4" unless buffer_size == 4
+						end
+
+						out_only_layout[param_desc[1]] = BufferItem.new(param_idx, out_only_size_bytes, buffer_size, param_desc[0])
+						out_only_size_bytes += buffer_size
+					end
+				end
+
+				tmp = assemble_buffer("in", function, args)
+				in_only_layout = tmp[0]
+				in_only_buffer = tmp[1]
+
+				tmp = assemble_buffer("inout", function, args)
+				inout_layout = tmp[0]
+				inout_buffer = tmp[1]
+
+
+				# now we build the stack
+				# every stack dword will be described by two dwords:
+				# first dword describes second dword:
+				#	0 - literal,
+				#	1 = relative to in-only buffer
+				#	2 = relative to out-only buffer
+				#	3 = relative to inout buffer
+
+				# (literal numbers and pointers to buffers we have created)
+				literal_pairs_blob = ""
+				#puts " assembling literal stack"
+				function.params.each_with_index do |param_desc, param_idx|
+					#puts "  processing (#{param_desc[0]}, #{param_desc[1]}, #{param_desc[2]})"
+					buffer = nil
+					# is it a pointer to a buffer on our stack
+					if ["PDWORD", "PWCHAR", "PCHAR", "PBLOB"].include? param_desc[0]
+						#puts "   pointer"
+						if args[param_idx] == nil # null pointer?
+							buffer = [0].pack(@native) # type: DWORD  (so the dll does not rebase it)
+							buffer += [0].pack(@native) # value: 0
+						elsif param_desc[2] == "in"
+							buffer = [1].pack(@native)
+							buffer += [in_only_layout[param_desc[1]].addr].pack(@native)
+						elsif param_desc[2] == "out"
+							buffer = [2].pack(@native)
+							buffer += [out_only_layout[param_desc[1]].addr].pack(@native)
+						elsif param_desc[2] == "inout"
+							buffer = [3].pack(@native)
+							buffer += [inout_layout[param_desc[1]].addr].pack(@native)
+						else
+							raise "unexpected direction"
+						end
+					else
+						#puts "   not a pointer"
+						# it's not a pointer
+						buffer = [0].pack(@native)
+						case param_desc[0]
+							when "LPVOID", "HANDLE"
+								num     = param_to_number(args[param_idx])
+								buffer += [num].pack(@native)
+							when "DWORD"
+								num     = param_to_number(args[param_idx])
+								buffer += [num % 4294967296].pack(@native)
+							when "WORD"
+								num     = param_to_number(args[param_idx])
+								buffer += [num % 65536].pack(@native)
+							when "BYTE"
+								num     = param_to_number(args[param_idx])
+								buffer += [num % 256].pack(@native)
+							when "BOOL"
+								case args[param_idx]
+									when true
+										buffer += [1].pack('V')
+									when false
+										buffer += [0].pack('V')
+									else
+										raise "param #{param_desc[1]}: true or false expected"
+								end
+							else
+								raise "unexpected type for param #{param_desc[1]}"
+						end
+					end
+
+					#puts "   adding pair to blob"
+					literal_pairs_blob += buffer
+					#puts "   buffer size %X" % buffer.length
+					#puts "   blob size so far: %X" % literal_pairs_blob.length
+				end
+
+				#puts "\n\nsending Stuff to meterpreter"
+
+				group = Rex::Post::Meterpreter::GroupTlv.new(TLV_TYPE_RAILGUN_MULTI_GROUP)
+				group.add_tlv(TLV_TYPE_RAILGUN_SIZE_OUT, out_only_size_bytes)
+				group.add_tlv(TLV_TYPE_RAILGUN_STACKBLOB, literal_pairs_blob)
+				group.add_tlv(TLV_TYPE_RAILGUN_BUFFERBLOB_IN, in_only_buffer)
+				group.add_tlv(TLV_TYPE_RAILGUN_BUFFERBLOB_INOUT, inout_buffer)
+				group.add_tlv(TLV_TYPE_RAILGUN_DLLNAME, dll_name )
+				group.add_tlv(TLV_TYPE_RAILGUN_FUNCNAME, function.windows_name)
+				request.tlvs << group
+
+				layouts << [inout_layout, out_only_layout]
+			end
+
+			call_results = []
+			res = @client.send_request(request)
+			res.each(TLV_TYPE_RAILGUN_MULTI_GROUP) do |val|
+				call_results << val
+			end
+
+			functions.each do |f|
+				dll_name,funcname,args = f
+				dll_host = @parent.get_dll( dll_name )
+				function = dll_host.functions[funcname]
+				response = call_results.shift
+				inout_layout, out_only_layout = layouts.shift
+
+				rec_inout_buffers = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_BUFFERBLOB_INOUT)
+				rec_out_only_buffers = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_BUFFERBLOB_OUT)
+				rec_return_value = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_RET)
+				rec_last_error = response.get_tlv_value(TLV_TYPE_RAILGUN_BACK_ERR)
+
+				# The hash the function returns
+				return_hash={"GetLastError" => rec_last_error}
+
+				#process return value
+				case function.return_type
+					when "LPVOID", "HANDLE"
+						if( @native == 'Q' )
+							return_hash["return"] = rec_return_value
+						else
+							return_hash["return"] = rec_return_value % 4294967296
+						end
+					when "DWORD"
+						return_hash["return"] = rec_return_value % 4294967296
+					when "WORD"
+						return_hash["return"] = rec_return_value % 65536
+					when "BYTE"
+						return_hash["return"] = rec_return_value % 256
+					when "BOOL"
+						return_hash["return"] = (rec_return_value != 0)
+					when "VOID"
+						return_hash["return"] = nil
+					else
+						raise "unexpected return type: #{function.return_type}"
+				end
+				#puts return_hash
+				#puts "out_only_layout:"
+				#puts out_only_layout
+
+
+				# process out-only buffers
+				#puts "processing out-only buffers:"
+				out_only_layout.each_pair do |param_name, buffer_item|
+					#puts "   #{param_name}"
+					buffer = rec_out_only_buffers[buffer_item.addr, buffer_item.length_in_bytes]
+					case buffer_item.datatype
+						when "PDWORD"
+							return_hash[param_name] = buffer.unpack('V')[0]
+						when "PCHAR"
+							return_hash[param_name] = asciiz_to_str(buffer)
+						when "PWCHAR"
+							return_hash[param_name] = uniz_to_str(buffer)
+						when "PBLOB"
+							return_hash[param_name] = buffer
+						else
+							raise "unexpected type in out-only buffer of #{param_name}: #{buffer_item.datatype}"
+					end
+				end
+				#puts return_hash
+
+				# process in-out buffers
+				#puts "processing in-out buffers:"
+				inout_layout.each_pair do |param_name, buffer_item|
+					#puts "   #{param_name}"
+					buffer = rec_inout_buffers[buffer_item.addr, buffer_item.length_in_bytes]
+					case buffer_item.datatype
+						when "PDWORD"
+							return_hash[param_name] = buffer.unpack('V')[0]
+						when "PCHAR"
+							return_hash[param_name] = asciiz_to_str(buffer)
+						when "PWCHAR"
+							return_hash[param_name] = uniz_to_str(buffer)
+						when "PBLOB"
+							return_hash[param_name] = buffer
+						else
+							raise "unexpected type in in-out-buffer of #{param_name}: #{buffer_item.datatype}"
+					end
+				end
+				#puts return_hash
+				#puts "finished"
+
+				function_results << return_hash
+			end
+			function_results
+		end
+		# process_multi_function_call
+	
+	protected
+	
+	attr_accessor :win_consts
+	
+end # MultiCall
+	
+end; end; end; end; end; end