librex 0.0.12 → 0.0.13

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', '..', '..','..','..','..','..', 'lib')) 
+
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll_function'
+require 'test/unit'
+
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+class DLLFunction::UnitTest < Test::Unit::TestCase
+
+	VALID_RETURN_TYPE = 'DWORD'
+	NON_RETURN_DATATYPE = 'INVALID_RETURN_TYPE'
+
+	VALID_DIRECTION = 'out'
+	UNKNOWN_DIRECTION = 'unknown'
+
+	VALID_DATATYPE = 'PBLOB'
+	UNKNOWN_DATATYPE = 'UNKNOWN_DATATYPE'
+
+	def test_initialize
+		# TODO: haven't gotten around to writing this yet. Feel free to
+#		skip("incomplete test coverage")
+#
+#		assert_nothing_raised("valid initialization should not raise") do
+#		end
+#
+#		assert_raised(ArgumentError, "check_type_exists should raise ArgumentError on unknown datatypes") do
+#		end
+	
+	end
+end
+end
+end
+end
+end
+end
+end

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

@@ -26,7 +26,8 @@ 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/model'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll_helper'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/buffer_item'
 
 module Rex
 module Post

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

@@ -28,11 +28,13 @@
 
 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/util'
-require 'rex/post/meterpreter/extensions/stdapi/railgun/model'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/win_const_manager'
 require 'rex/post/meterpreter/extensions/stdapi/railgun/multicall'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll'
 
 module Rex
 module Post
@@ -45,7 +47,6 @@ module Railgun
 # The Railgun class to dynamically expose the Windows API.
 #
 class Railgun
-
 	def initialize( client )
 
 		@client = client

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

@@ -1,4 +1,4 @@
-require 'rex/post/meterpreter/extensions/stdapi/railgun/model'
+require 'rex/post/meterpreter/extensions/stdapi/railgun/dll_helper'
 
 module Rex
 module Post

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

@@ -0,0 +1,75 @@
+# 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
+
+#
+# Manages our library of windows constants
+#
+class WinConstManager
+
+	def initialize(initial_consts = {})
+		@consts = {}
+
+		initial_consts.each_pair do |name, value|
+			add_const(name, value)			
+		end
+
+		# Load utility 
+	end
+
+	def add_const(name, value)
+		@consts[name] = value
+	end
+
+	# parses a string constaining constants and returns an integer
+	# the string can be either "CONST" or "CONST1 | CONST2"
+	#
+	# this function will NOT throw an exception but return "nil" if it can't parse a string
+	def parse(s)
+		if s.class != String
+			return nil # it's not even a string'
+		end
+		return_value = 0
+		for one_const in s.split('|')
+			one_const = one_const.strip()
+			if not @consts.has_key? one_const
+				return nil # at least one "Constant" is unknown to us
+			end
+			return_value |= @consts[one_const]
+		end
+		return return_value
+	end
+
+	def is_parseable(s)
+		return parse(s) != nil
+	end
+end
+
+end; end; end; end; end; end

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', '..', '..','..','..','..','..', 'lib')) 
+
+require 'rex/post/meterpreter/extensions/stdapi/railgun/win_const_manager'
+require 'test/unit'
+
+module Rex
+module Post
+module Meterpreter
+module Extensions
+module Stdapi
+module Railgun
+class WinConstManager::UnitTest < Test::Unit::TestCase
+	def test_is_parseable
+		const_manager = WinConstManager.new
+
+		first_key = 'SOME_NUMBER'
+		second_key = 'SOME_OTHER_NUMBER'
+		boolean_logic = first_key + ' | ' + second_key
+
+		# XXX: Should check (un)parseability before adding constants too?
+
+		const_manager.add_const(first_key, 43123)
+		const_manager.add_const(second_key, 234)
+
+		assert(const_manager.is_parseable(boolean_logic),
+			"is_parseable should consider boolean logic statements parseable")
+
+		assert(const_manager.is_parseable(first_key),
+			"is_parseable should consider constants parseable")
+
+		assert(! const_manager.is_parseable(5),
+			"is_parseable should not consider non-string keys as parseable")
+
+		assert(! const_manager.is_parseable('| FOO |'),
+			"is_parseable should not consider malformed boolean expressions parseable")
+	end
+
+	def test_add_const
+		target_key = 'VALID_KEY'
+		target_value = 23
+		
+		const_manager = WinConstManager.new
+
+		const_manager.add_const(target_key, target_value)
+
+		assert_equal(target_value, const_manager.parse(target_key),
+			"add_const should add a constant/value pair that can be trieved with parse")
+		
+	end
+
+	def test_initialization
+		target_key = 'VALID_KEY'
+		target_value = 23
+
+		const_manager = WinConstManager.new(target_key => target_value)
+
+		assert_equal(target_value, const_manager.parse(target_key),
+			"upon initialization, should add any provided constants.")
+	end
+
+	def test_parse
+		target_key = 'VALID_KEY'
+		target_value = 23
+		invalid_key = 8
+
+		const_manager = WinConstManager.new
+
+		const_manager.add_const(target_key, target_value)
+
+		assert_equal(target_value, const_manager.parse(target_key),
+			"parse should retrieve the corresponding value when a key is provided")
+
+		# From API: "should not throw an exception given an invalid key"
+		assert_nothing_thrown do 
+			const_manager.parse(invalid_key)
+		end
+
+		assert_equal(nil, const_manager.parse(invalid_key),
+			"parse should return nil when an invalid key is provided")
+
+		x_key = 'X'
+		x_value = 228
+		y_key = 'Y'
+		y_value = 15 
+
+		boolean_logic = x_key + ' | ' + y_key
+		target_boolean_logic_result = x_value | y_value
+
+		const_manager.add_const(x_key, x_value)
+		const_manager.add_const(y_key, y_value)
+
+		assert_equal(target_boolean_logic_result, const_manager.parse(boolean_logic),
+			"parse should evaluate boolean expressions consisting of OR")
+	end
+end
+end
+end
+end
+end
+end
+end