librex 0.0.13 → 0.0.15

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

@@ -1,148 +0,0 @@
-# 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

@@ -1,127 +0,0 @@
-#!/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

@@ -1,309 +0,0 @@
-# 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