standardized comment format

git-svn-id: file:///home/svn/incoming/trunk@2372 4d416f70-5f16-0410-b530-b9f4589650da

lib/rex/post/meterpreter/extensions/stdapi/Dir.rb

@@ -9,26 +9,44 @@ module Meterpreter
 module Extensions
 module Stdapi
 
+###
+#
+# Dir
+# ---
+#
+# This class implements directory operations against the remote endpoint
+#
+###
 class Dir < Rex::Post::Dir
 
 	class <<self
 		attr_accessor :client
 	end
 
+	##
+	#
+	# Constructor
+	#
+	##
+
+	# Initializes the directory instance
 	def initialize(path)
 		self.path   = path
 		self.client = self.class.client
 	end
 
+	##
+	#
+	# Enumeration
+	#
+	##
+
+	# Enumerates all of the contents of the directory
 	def each(&block)
 		client.dir.foreach(self.path, &block)
 	end
 
-=begin
-	entries(name)
-
-	Enumerates all of the files/folders in a given directory.
-=end
+	# Enumerates all of the files/folders in a given directory.
 	def Dir.entries(name)
 		request = Packet.create_request('stdapi_fs_ls')
 		files   = []
@@ -44,11 +62,7 @@ class Dir < Rex::Post::Dir
 		return files
 	end
 
-=begin
-	chdir(path)
-
-	Changes the working directory of the remote process.
-=end
+	# Changes the working directory of the remote process.
 	def Dir.chdir(path)
 		request = Packet.create_request('stdapi_fs_chdir')
 
@@ -59,11 +73,7 @@ class Dir < Rex::Post::Dir
 		return 0
 	end
 
-=begin
-	mkdir(path)
-
-	Creates a directory.
-=end
+	# Creates a directory.
 	def Dir.mkdir(path)
 		request = Packet.create_request('stdapi_fs_mkdir')
 
@@ -74,11 +84,7 @@ class Dir < Rex::Post::Dir
 		return 0
 	end
 
-=begin
-	pwd
-
-	Returns the current working directory of the remote process.
-=end
+	# Returns the current working directory of the remote process.
 	def Dir.pwd
 		request = Packet.create_request('stdapi_fs_getwd')
 
@@ -87,18 +93,12 @@ class Dir < Rex::Post::Dir
 		return response.get_tlv(TLV_TYPE_DIRECTORY_PATH).value
 	end
 
-=begin
-	Synonym for pwd
-=end
+	# Synonym for pwd
 	def Dir.getwd
 		pwd
 	end
 
-=begin
-	delete
-
-	Removes the supplied directory if it's empty
-=end
+	# Removes the supplied directory if it's empty
 	def Dir.delete(path)
 		request = Packet.create_request('stdapi_fs_delete_dir')
 
@@ -109,15 +109,12 @@ class Dir < Rex::Post::Dir
 		return 0
 	end
 
-=begin
-	rmdir, unlink
-
-	Synonyms for delete
-=end
+	# Synonyms for delete
 	def Dir.rmdir(path)
 		delete(path)
 	end
 
+	# Synonyms for delete
 	def Dir.unlink(path)
 		delete(path)
 	end
@@ -127,7 +124,6 @@ protected
 	attr_accessor :client
 	attr_writer   :path
 
-
 end
 
 end; end; end; end; end

lib/rex/post/meterpreter/extensions/stdapi/File.rb

@@ -53,26 +53,11 @@ class File < Rex::Post::Meterpreter::Extensions::Stdapi::IO
 		return self.sysseek(offset, whence)
 	end
 
-	# Reads, at most, the supplied number of bytes from the file
-	def sysread(length)
-		return self.filed.read(length)
-	end
-
 	# Seeks to the supplied offset based on the supplied relativity
 	def sysseek(offset, whence = SEEK_SET)
 		return self.filed.seek(offset, whence)
 	end
 
-	# Writes the supplied buffer to the file
-	def syswrite(buf)
-		return self.filed.write(buf)
-	end
-
-	# Closes the file descriptor
-	def close
-		return self.filed.close
-	end
-
 protected
 
 	##

lib/rex/post/meterpreter/extensions/stdapi/FileStat.rb

@@ -9,6 +9,14 @@ module Meterpreter
 module Extensions
 module Stdapi
 
+###
+#
+# FileStat
+# --------
+#
+# This class wrappers gathering information about a given file
+#
+###
 class FileStat < Rex::Post::FileStat
 
 	@@struct_stat = [
@@ -30,12 +38,26 @@ class FileStat < Rex::Post::FileStat
 		attr_accessor :client
 	end
 
+	##
+	#
+	# Constructor
+	#
+	##
+
 	def initialize(file)
 		self.stathash = stat(file)
 	end
 
-	protected
+protected
 
+	##
+	#
+	# Initializer
+	#
+	##
+
+	# Gets information about the supplied file and returns a populated
+	# hash to the requestor
 	def stat(file)
 		request = Packet.create_request('stdapi_fs_stat')
 

lib/rex/post/meterpreter/extensions/stdapi/IO.rb

@@ -8,28 +8,41 @@ module Meterpreter
 module Extensions
 module Stdapi
 
+##
+#
+# IO
+# --
+#
+# The IO class acts as a base class for things that would normally implement
+# the IO interface.  The methods it implements are for general operations that
+# are common to all channels, such as read, write, and close.
+#
+##
 class IO < Rex::Post::IO
 
-	def read(length = nil, flags = nil)
-		filed.read(length)
+	# Read the specified number of bytes from the channel
+	def sysread(length = nil)
+		self.filed.read(length)
 	end
 
-	# Synonym for read
-	def recv(length = nil, flags = nil)
-		read(length, flags)
+	# Synonym for sysread
+	def read(length = nil)
+		sysread
 	end
 
-	def write(buf, length = nil, flags = nil)
-		filed.write(buf, length)
+	# Writes the supplied buffer to the channel
+	def syswrite(buf)
+		self.filed.write(buf)
 	end
 
-	# Synonym for write
-	def send(buf, length = nil, flags = nil)
-		write(buf, length, flags)
+	# Synonym for syswrite
+	def write(buf)
+		syswrite
 	end
 
+	# Closes the channel
 	def close
-		filed.close
+		self.filed.close
 	end
 
 end

lib/rex/post/meterpreter/extensions/stdapi/Process.rb

@@ -11,24 +11,27 @@ module Meterpreter
 module Extensions
 module Stdapi
 
+##
+#
+# Process
+# -------
+#
+# This class implements the Rex::Post::Process interface.
+#
+##
 class Process < Rex::Post::Process
 
 	class <<self
 		attr_accessor :client
 	end
 
+	# Gets the process id that the remote side is executing under
 	def Process.getpid
 		request = Packet.create_request('stdapi_process_getpid')
 
 		response = client.send_request(request)
 
-		tlv = response.get_tlv(TLV_TYPE_PID)
-
-		if (tlv != nil)
-			return tlv.value
-		else
-			return 0
-		end
+		return response.get_tlv_value(TLV_TYPE_PID)
 	end
 
 end

lib/rex/post/meterpreter/extensions/stdapi/Registry.rb

@@ -14,6 +14,15 @@ module Meterpreter
 module Extensions
 module Stdapi
 
+###
+#
+# Registry
+# --------
+#
+# This class provides access to the Windows registry on the remote 
+# machine.
+#
+###
 class Registry
 
 	class <<self
@@ -26,22 +35,14 @@ class Registry
 	#
 	##
 
-=begin
-	open_key(root_key, base_key, perm)
-
-	Opens the supplied registry key relative to the root key with
-	the supplied permissions.  Right now this is merely a wrapper around 
-	create_key.
-=end
+	# Opens the supplied registry key relative to the root key with
+	# the supplied permissions.  Right now this is merely a wrapper around 
+	# create_key.
 	def Registry.open_key(root_key, base_key, perm = KEY_READ)
 		return self.create_key(root_key, base_key, perm)
 	end
 
-=begin
-	create_key(root_key, base_key, perm)
-
-	Creates the supplied registry key or opens it if it already exists.
-=end
+	# Creates the supplied registry key or opens it if it already exists.
 	def Registry.create_key(root_key, base_key, perm = KEY_READ)
 		request = Packet.create_request('stdapi_registry_create_key')
 		
@@ -55,11 +56,7 @@ class Registry
 				response.get_tlv(TLV_TYPE_HKEY).value)
 	end
 
-=begin
-	delete_key(root_key, base_key, recursive)
-
-	Deletes the supplied registry key.
-=end
+	# Deletes the supplied registry key.
 	def Registry.delete_key(root_key, base_key, recursive = true)
 		request = Packet.create_request('stdapi_registry_delete_key')
 		flags   = 0
@@ -79,11 +76,7 @@ class Registry
 		return false
 	end
 
-=begin
-	close_key(hkey)
-
-	Closes the supplied registry key.
-=end
+	# Closes the supplied registry key.
 	def Registry.close_key(hkey)
 		request = Packet.create_request('stdapi_registry_close_key')
 
@@ -94,11 +87,7 @@ class Registry
 		return true
 	end
 
-=begin
-	enum_key(hkey)
-
-	Enumerates the supplied registry key returning an array of key names
-=end
+	# Enumerates the supplied registry key returning an array of key names
 	def Registry.enum_key(hkey)
 		keys    = []
 		request = Packet.create_request('stdapi_registry_enum_key')
@@ -121,11 +110,7 @@ class Registry
 	#
 	##
 
-=begin
-	set_value(hkey, name, type, data)
-
-	Sets the registry value relative to the supplied hkey.
-=end
+	# Sets the registry value relative to the supplied hkey.
 	def Registry.set_value(hkey, name, type, data)
 		request = Packet.create_request('stdapi_registry_set_value')
 
@@ -146,12 +131,8 @@ class Registry
 		return true
 	end
 
-=begin
-	query_value(hkey, name)
-
-	Queries the registry value supplied in name and returns an
-	initialized RegistryValue instance if a match is found.
-=end
+	# Queries the registry value supplied in name and returns an
+	# initialized RegistryValue instance if a match is found.
 	def Registry.query_value(hkey, name)
 		request = Packet.create_request('stdapi_registry_query_value')
 
@@ -172,12 +153,8 @@ class Registry
 		return RegistryValue.new(client, hkey, name, type, data)
 	end
 
-=begin
-	delete_value(hkey, name)
-
-	Deletes the registry value supplied in name from the supplied
-	registry key.
-=end
+	# Deletes the registry value supplied in name from the supplied
+	# registry key.
 	def Registry.delete_value(hkey, name)
 		request = Packet.create_request('stdapi_registry_delete_value')
 
@@ -191,12 +168,8 @@ class Registry
 		return false
 	end
 
-=begin
-	enum_value(hkey)
-
-	Enumerates all of the values at the supplied hkey including their
-	names.  An array of RegistryValue's is returned.
-=end
+	# Enumerates all of the values at the supplied hkey including their
+	# names.  An array of RegistryValue's is returned.
 	def Registry.enum_value(hkey)
 		request = Packet.create_request('stdapi_registry_enum_value')
 		values  = []

lib/rex/post/meterpreter/extensions/stdapi/RegistryKey.rb

@@ -32,40 +32,24 @@ class RegistryKey
 	#
 	##
 
-=begin
-	each_key(&block)
-
-	Enumerates all of the child keys within this registry key.
-=end
+	# Enumerates all of the child keys within this registry key.
 	def each_key(&block)
 		return enum_key.each(&block)
 	end
 
-=begin
-	each_value(&block)
-
-	Enumerates all of the child values within this registry key.
-=end
+	# Enumerates all of the child values within this registry key.
 	def each_value(&block)
 		return enum_value.each(&block)
 	end
 
-=begin
-	enum_key()
-
-	Retrieves all of the registry keys that are direct descendents of
-	the class' registry key.
-=end
+	# Retrieves all of the registry keys that are direct descendents of
+	# the class' registry key.
 	def enum_key()
 		return self.client.registry.enum_key(self.hkey)
 	end
 
-=begin
-	enum_value
-
-	Retrieves all of the registry values that exist within the opened 
-	registry key.
-=end
+	# Retrieves all of the registry values that exist within the opened 
+	# registry key.
 	def enum_value()
 		return self.client.registry.enum_value(self.hkey)
 	end
@@ -77,39 +61,23 @@ class RegistryKey
 	#
 	##
 
-=begin
-	open_key(base_key, perm)
-
-	Opens a registry key that is relative to this registry key.
-=end
+	# Opens a registry key that is relative to this registry key.
 	def open_key(base_key, perm = KEY_READ)
 		return self.client.registry.open_key(self.hkey, base_key, perm)
 	end
 
-=begin
-	create_key(base_key, perm)
-
-	Creates a registry key that is relative to this registry key.
-=end
+	# Creates a registry key that is relative to this registry key.
 	def create_key(base_key, perm = KEY_READ)
 		return self.client.registry.create_key(self.hkey, base_key, perm)
 	end
 
-=begin
-	delete_key(base_key, recursive)
-
-	Deletes a registry key that is relative to this registry key.
-=end
+	# Deletes a registry key that is relative to this registry key.
 	def delete_key(base_key, recursive = true)
 		return self.client.registry.delete_key(self.hkey, base_key, recursive)
 	end
 
-=begin
-	close()
-
-	Closes the open key.  This must be called if the registry
-	key was opened.
-=end
+	# Closes the open key.  This must be called if the registry
+	# key was opened.
 	def close()
 		if (self.hkey != nil)
 			return self.client.registry.close_key(hkey)			
@@ -124,21 +92,13 @@ class RegistryKey
 	#
 	##
 
-=begin
-	set_value(name, type, data)
-
-	Sets a value relative to the opened registry key.
-=end
+	# Sets a value relative to the opened registry key.
 	def set_value(name, type, data)
 		return self.client.registry.set_value(self.hkey, name, type, data)
 	end
 
-=begin
-	query_value(name)
-
-	Queries the attributes of the supplied registry value relative to
-	the opened registry key.
-=end
+	# Queries the attributes of the supplied registry value relative to
+	# the opened registry key.
 	def query_value(name)
 		return self.client.registry.query_value(self.hkey, name)
 	end
@@ -149,6 +109,7 @@ class RegistryKey
 	#
 	##
 
+	# Returns the path to the key
 	def to_s
 		return self.root_key.to_s + "\\" + self.base_key
 	end

lib/rex/post/meterpreter/extensions/stdapi/RegistryValue.rb

@@ -26,11 +26,7 @@ class RegistryValue
 		self.data   = data
 	end	
 
-=begin
-	set(data, type)
-
-	Sets the value's data.
-=end
+	# Sets the value's data.
 	def set(data, type = nil)
 		if (type == nil)
 			type = self.type
@@ -46,11 +42,7 @@ class RegistryValue
 		return false
 	end
 
-=begin
-	query()
-
-	Queries the value's data.
-=end
+	# Queries the value's data.
 	def query()
 		val =  self.client.registry.query_value(self.hkey, self.name)
 
@@ -62,23 +54,13 @@ class RegistryValue
 		return self.data
 	end
 
-=begin
-	delete()
-
-	Deletes the value.
-=end
+	# Deletes the value.
 	def delete()
 		return self.client.registry.delete_value(self.hkey, self.name)
 	end
 
-	##
-	#
-	# Attributes
-	#
-	##
-
 	attr_reader   :hkey, :name, :type, :data
-	protected
+protected
 	attr_accessor :client
 	attr_writer   :hkey, :name, :type, :data
 end

lib/rex/post/meterpreter/extensions/stdapi/constants.rb

@@ -1,9 +1,17 @@
 #!/usr/bin/ruby
 
+###
+#
 # These are put into the global namespace for now
 # so that they can be referenced globally
+#
+###
 
+##
+#
 # Permissions
+#
+##
 DELETE                   = 0x00010000
 READ_CONTROL             = 0x00020000
 WRITE_DAC                = 0x00040000
@@ -21,7 +29,11 @@ GENERIC_WRITE            = 0x40000000
 GENERIC_EXECUTE          = 0x20000000
 GENERIC_ALL              = 0x10000000
 
+##
+#
 # Registry Permissions
+#
+##
 KEY_QUERY_VALUE          = 0x00000001
 KEY_SET_VALUE            = 0x00000002
 KEY_CREATE_SUB_KEY       = 0x00000004
@@ -37,8 +49,12 @@ KEY_ALL_ACCESS           = (STANDARD_RIGHTS_ALL | KEY_QUERY_VALUE |
                             KEY_SET_VALUE | KEY_CREATE_SUB_KEY | 
                             KEY_ENUMERATE_SUB_KEYS | KEY_NOTIFY |
                             KEY_CREATE_LINK) & ~SYNCHRONIZE
-									 
+
+##
+#
 # Registry
+#
+##
 HKEY_CLASSES_ROOT        = 0x80000000
 HKEY_CURRENT_USER        = 0x80000001
 HKEY_LOCAL_MACHINE       = 0x80000002

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

@@ -33,7 +33,6 @@ TLV_TYPE_FILE_PATH      = TLV_META_TYPE_STRING  | 1202
 TLV_TYPE_FILE_MODE      = TLV_META_TYPE_STRING  | 1203
 TLV_TYPE_STAT_BUF       = TLV_META_TYPE_COMPLEX | 1220
 
-
 DELETE_KEY_FLAG_RECURSIVE = (1 << 0)
 
 ###
@@ -57,28 +56,34 @@ class Stdapi < Extension
 		client.register_extension_alias('registry', self.registry)
 	end
 
+	# Sets the client instance on a duplicated copy of the supplied class
 	def brand(klass)
 		klass = klass.dup
 		klass.client = self.client
 		return klass
 	end
 
+	# Returns a copy of the Dir class
 	def dir
 		brand(Rex::Post::Meterpreter::Extensions::Stdapi::Dir)
 	end
 
+	# Returns a copy of the File class
 	def file
 		brand(Rex::Post::Meterpreter::Extensions::Stdapi::File)
 	end
 
+	# Returns a copy of the FileStat class
 	def filestat
 		brand(Rex::Post::Meterpreter::Extensions::Stdapi::FileStat)
 	end
 
+	# Returns a copy of the Process class
 	def process
 		brand(Rex::Post::Meterpreter::Extensions::Stdapi::Process)
 	end
-	
+
+	# Returns a copy of the Registry class
 	def registry
 		brand(Rex::Post::Meterpreter::Extensions::Stdapi::Registry)
 	end