Adding documentation to the post modules library.

lib/msf/core/post/common.rb

@@ -80,6 +80,10 @@ module Common
 		return o
 	end
 
+	#
+	# Reports to the database that the host is a virtual machine and reports 
+	# the type of virtual machine it is (e.g VirtualBox, VMware, Xen)
+	#
 	def report_vm(vm)
 		return unless session
 		return unless vm

lib/msf/core/post/file.rb

@@ -2,6 +2,9 @@
 
 module Msf::Post::File
 
+	#
+	# Change directory in the remote session to +path+
+	#
 	def cd(path)
 		if session.type == "meterpreter"
 			e_path = session.fs.file.expand_path(path) rescue path
@@ -11,6 +14,9 @@ module Msf::Post::File
 		end
 	end
 
+	#
+	# Returns the current working directory in the remote session
+	#
 	def pwd
 		if session.type == "meterpreter"
 			return session.fs.dir.getwd
@@ -110,7 +116,7 @@ module Msf::Post::File
 	end
 
 	#
-	# Writes a given string to a file specified
+	# Writes a given string to a given local file
 	#
 	def file_local_write(file2wrt, data2wrt)
 		if not ::File.exists?(file2wrt)
@@ -141,7 +147,6 @@ module Msf::Post::File
 	#
 	# Returns a MD5 checksum of a given remote file
 	#
-
 	def file_remote_digestmd5(file2md5)
 		data = read_file(file2md5)
 		chksum = nil
@@ -266,7 +271,8 @@ module Msf::Post::File
 	end
 
 	#
-	# Read a local file and write it to the remote file system
+	# Read a local file +local+ and write it as +remote+ on the remote file 
+	# system
 	#
 	def upload_file(remote, local)
 		write_file(remote, ::File.read(local))

lib/msf/core/post/linux/priv.rb

@@ -7,7 +7,9 @@ module Linux
 module Priv
 	include ::Msf::Post::Common
 
+	#
 	# Returns true if running as root, false if not.
+	#
 	def is_root?
 		root_priv = false
 		user_id = cmd_exec("id -u")

lib/msf/core/post/linux/system.rb

@@ -9,10 +9,11 @@ module Linux
 module System
 	include ::Msf::Post::Common
 	include ::Msf::Post::File
-
 	include ::Msf::Post::Unix
 
+	#
 	# Returns a Hash containing Distribution Name, Version and Kernel Information
+	#
 	def get_sysinfo
 		system_data = {}
 		etc_files = cmd_exec("ls /etc").split()

lib/msf/core/post/osx/system.rb

@@ -9,7 +9,9 @@ module System
 	include ::Msf::Post::Common
 	include ::Msf::Post::File
 
+	#
 	# Return a hash with system Information
+	#
 	def get_sysinfo
 		system_info = {}
 		cmd_output = cmd_exec("/usr/bin/sw_vers").split("\n")
@@ -23,8 +25,10 @@ module System
 		return system_info
 	end
 
+	#
 	# Returns an array of hashes each representing a user on the system
 	# Keys are name, gid, uid, dir and shell
+	#
 	def get_users
 		cmd_output = cmd_exec("/usr/bin/dscacheutil -q user")
 		users = []
@@ -42,8 +46,10 @@ module System
 		return users
 	end
 
+	#
 	# Returns an array of hashes each representing a system accounts on the system
 	# Keys are name, gid, uid, dir and shell
+	#
 	def get_system_accounts
 		cmd_output = cmd_exec("/usr/bin/dscacheutil -q user")
 		users = []
@@ -61,8 +67,10 @@ module System
 		return users
 	end
 
+	#
 	# Returns an array of hashes each representing non system accounts on the system
 	# Keys are name, gid, uid, dir and shell
+	#
 	def get_nonsystem_accounts
 		cmd_output = cmd_exec("/usr/bin/dscacheutil -q user")
 		users = []
@@ -80,8 +88,10 @@ module System
 		return users
 	end
 
+	#
 	# Returns an array of hashes each representing user group on the system
 	# Keys are name, guid and users
+	#
 	def get_groups
 		cmd_output = cmd_exec("/usr/bin/dscacheutil -q group")
 		groups = []

lib/msf/core/post/solaris/priv.rb

@@ -7,7 +7,9 @@ module Solaris
 module Priv
 	include ::Msf::Post::Common
 
+	#
 	# Returns true if running as root, false if not.
+	#
 	def is_root?
 		root_priv = false
 		user_id = cmd_exec("/usr/xpg4/bin/id -u")

lib/msf/core/post/solaris/system.rb

@@ -9,7 +9,6 @@ module Solaris
 module System
 	include ::Msf::Post::Common
 	include ::Msf::Post::File
-
 	include ::Msf::Post::Unix
 
 	#

lib/msf/core/post/unix.rb

@@ -4,8 +4,10 @@ module Msf
 class Post
 module Unix
 
+	#
 	# Returns an array of hashes each representing a user
 	# Keys are name, uid, gid, info, dir and shell
+	#
 	def get_users
 		users = []
 		etc_passwd = nil
@@ -34,8 +36,10 @@ module Unix
 		return users
 	end
 
+	#
 	# Returns an array of hashes each hash representing a user group
 	# Keys are name, gid and users
+	#
 	def get_groups
 		groups = []
 		cmd_out = read_file("/etc/group").split("\n")
@@ -50,7 +54,9 @@ module Unix
 		return groups
 	end
 
-	# returns all user directories found
+	#
+	# Enumerates the user directories in /Users or /home
+	#
 	def enum_user_directories
 		user_dirs = []
 

lib/msf/core/post/windows/eventlog.rb

@@ -4,7 +4,10 @@ class Post
 module Windows
 
 module Eventlog
-	#enumerate eventlogs
+
+	#
+	# Enumerate eventlogs
+	#
 	def eventlog_list
 		key = "HKLM\\SYSTEM\\CurrentControlSet\\Services\\"
 		if session.sys.config.sysinfo['OS'] =~ /Windows 2003|.Net|XP|2000/
@@ -16,7 +19,10 @@ module Eventlog
 		return eventlogs
 	end
 
-	#clears a given eventlog or all eventlogs if none is given. Returns an array of eventlogs that where cleared.
+	#
+	# Clears a given eventlog or all eventlogs if none is given. Returns an array of eventlogs 
+	# that where cleared.
+	#
 	def eventlog_clear(evt = "")
 		evntlog = []
 		if evt.empty?

lib/msf/core/post/windows/powershell.rb

@@ -15,13 +15,18 @@ module Powershell
 
 	# Suffix for environment variables
 
-
+	#
+	# Returns true if powershell is installed
+	#
 	def have_powershell?
 		cmd_out = cmd_exec("powershell get-host")
 		return true if cmd_out =~ /Name.*Version.*InstanceID/
 		return false
 	end
 
+	#
+	# Insert substitutions into the powershell script
+	#
 	def make_subs(script, subs)
 		subs.each do |set|
 			script.gsub!(set[0],set[1])
@@ -32,6 +37,9 @@ module Powershell
 		end
 	end
 
+	#
+	# Return an array of substitutions for use in make_subs
+	#
 	def process_subs(subs)
 		return [] if subs.nil? or subs.empty?
 		new_subs = []
@@ -41,6 +49,9 @@ module Powershell
 		return new_subs
 	end
 
+	#
+	# Read in a powershell script stored in +script+
+	#
 	def read_script(script)
 		script_in = ''
 		begin
@@ -60,9 +71,11 @@ module Powershell
 	end
 
 
+	#
+	# Return a zlib compressed powershell script
+	#
 	def compress_script(script_in, eof = nil)
 
-
 		# Compress using the Deflate algorithm
 		compressed_stream = ::Zlib::Deflate.deflate(script_in,
 			::Zlib::BEST_COMPRESSION)
@@ -96,6 +109,10 @@ module Powershell
 		return encoded_expression
 	end
 
+	#
+	# Execute a powershell script and return the results. The script is never written
+	# to disk.
+	#
 	def execute_script(script, time_out = 15)
 		running_pids, open_channels = [], []
 		# Execute using -EncodedCommand
@@ -112,6 +129,13 @@ module Powershell
 		return [cmd_out, running_pids, open_channels]
 	end
 
+
+	#
+	# Powershell scripts that are longer than 8000 bytes are split into 8000 
+	# 8000 byte chunks and stored as environment variables. A new powershell 
+	# script is built that will reassemble the chunks and execute the script.
+	# Returns the reassembly script.
+	#
 	def stage_to_env(compressed_script, env_suffix = Rex::Text.rand_text_alpha(8))
 
 		# Check to ensure script is encoded and compressed
@@ -159,6 +183,9 @@ module Powershell
 		return encoded_script
 	end
 
+	#
+	# Log the results of the powershell script
+	#
 	def write_to_log(cmd_out, log_file, eof)
 		# Open log file for writing
 		fd = ::File.new(log_file, 'w+')
@@ -181,6 +208,9 @@ module Powershell
 		return
 	end
 
+	#
+	# Clean up powershell script including process and chunks stored in environment variables
+	#
 	def clean_up(script_file = nil, eof = '', running_pids =[], open_channels = [], env_suffix = Rex::Text.rand_text_alpha(8), delete = false)
 		# Remove environment variables
 		env_del_command =  "[Environment]::GetEnvironmentVariables('User').keys|"
@@ -206,5 +236,8 @@ module Powershell
 		return
 	end
 
-end; end; end; end
+end
+end
+end
+end
 

lib/msf/core/post/windows/railgun.rb

@@ -40,10 +40,16 @@ module Railgun
 		end
 	end
 
+	#
+	# Read +length+ bytes starting at +address+
+	#
 	def memread(address, length)
 		railgun.memread(address, length)
 	end
 
+	#
+	# Write +length+ bytes starting at +address+
+	#
 	def memwrite(address, length)
 		railgun.memwrite(address, length)
 	end
@@ -52,6 +58,9 @@ module Railgun
 		client.railgun
 	end
 
+	#
+	# Returns the pointer size of the remote system
+	#
 	def pointer_size
 		railgun.util.pointer_size
 	end

lib/msf/core/post/windows/registry.rb

@@ -10,7 +10,9 @@ module Registry
 
 	include Msf::Post::Windows::CliParse
 
-
+	#
+	# Load a hive file
+	#
 	def registry_loadkey(key,file)
 		if session_has_registry_ext
 			retval=meterpreter_registry_loadkey(key,file)
@@ -20,6 +22,9 @@ module Registry
 		return retval
 	end
 
+	#
+	# Unload a hive file
+	#
 	def registry_unloadkey(key)
 		if session_has_registry_ext
 			retval=meterpreter_registry_unloadkey(key)
@@ -141,7 +146,9 @@ protected
 	# Generic registry manipulation methods based on reg.exe
 	##
 
-
+	#
+	# Use reg.exe to load the hive file +file+ into +key+
+	#
 	def shell_registry_loadkey(key,file)
 		key = normalize_key(key)
 		boo = false
@@ -158,6 +165,9 @@ protected
 		return boo
 	end
 
+	#
+	# Use reg.exe to unload the hive in +key+
+	#
 	def shell_registry_unloadkey(key)
 		key = normalize_key(key)
 		boo = false
@@ -174,6 +184,9 @@ protected
 	end
 
 
+	#
+	# Use reg.exe to create a new registry key
+	#
 	def shell_registry_createkey(key)
 		key = normalize_key(key)
 		boo = false
@@ -191,6 +204,9 @@ protected
 		end
 	end
 
+	#
+	# Use reg.exe to delete +valname+ in +key+
+	#
 	def shell_registry_deleteval(key, valname)
 		key = normalize_key(key)
 		boo = false
@@ -209,6 +225,9 @@ protected
 		return boo
 	end
 
+	#
+	# Use reg.exe to delete +key+ and all its subkeys and values
+	#
 	def shell_registry_deletekey(key)
 		key = normalize_key(key)
 		boo = false
@@ -227,6 +246,9 @@ protected
 		return boo
 	end
 
+	#
+	# Use reg.exe to enumerate all the subkeys in +key+
+	#
 	def shell_registry_enumkeys(key)
 		key = normalize_key(key)
 		subkeys = []
@@ -258,6 +280,9 @@ protected
 		return subkeys
 	end
 
+	#
+	# Use reg.exe to enumerate all the values in +key+
+	#
 	def shell_registry_enumvals(key)
 		key = normalize_key(key)
 		values = []
@@ -285,6 +310,9 @@ protected
 		return values
 	end
 
+	#
+	# Returns the data portion of the value +valname+
+	#
 	def shell_registry_getvaldata(key, valname)
 		value = nil
 		begin
@@ -294,6 +322,10 @@ protected
 		return value
 	end
 
+	#
+	# Enumerate the type and data stored in the registry value +valname+ in 
+	# +key+
+	#
 	def shell_registry_getvalinfo(key, valname)
 		key = normalize_key(key)
 		value = {}
@@ -319,6 +351,10 @@ protected
 		return value
 	end
 
+	#
+	# Use reg.exe to add a value +valname+ in the key +key+ with the specified
+	# +type+ and +data+
+	#
 	def shell_registry_setvaldata(key, valname, data, type)
 		key = normalize_key(key)
 		boo = false
@@ -343,6 +379,9 @@ protected
 	# Meterpreter-specific registry manipulation methods
 	##
 
+	#
+	# Load a registry hive stored in +file+ into +key+
+	#
 	def meterpreter_registry_loadkey(key,file)
 		begin
 			client.sys.config.getprivs()
@@ -376,6 +415,9 @@ protected
 
 	end
 
+	#
+	# Unload the hive file stored in +key+
+	#
 	def meterpreter_registry_unloadkey(key)
 		begin
 			client.sys.config.getprivs()
@@ -400,6 +442,9 @@ protected
 		end
 	end
 
+	#
+	# Create a new registry key
+	#
 	def meterpreter_registry_createkey(key)
 		begin
 			root_key, base_key = session.sys.registry.splitkey(key)
@@ -412,6 +457,9 @@ protected
 		end
 	end
 
+	#
+	# Delete the registry value +valname+ store in +key+
+	#
 	def meterpreter_registry_deleteval(key, valname)
 		begin
 			root_key, base_key = session.sys.registry.splitkey(key)
@@ -424,6 +472,9 @@ protected
 		end
 	end
 
+	#
+	# Delete the registry key +key+
+	#
 	def meterpreter_registry_deletekey(key)
 		begin
 			root_key, base_key = session.sys.registry.splitkey(key)
@@ -434,6 +485,9 @@ protected
 		end
 	end
 
+	#
+	# Enumerate the subkeys in +key+
+	#
 	def meterpreter_registry_enumkeys(key)
 		subkeys = []
 		begin
@@ -450,6 +504,9 @@ protected
 		return subkeys
 	end
 
+	#
+	# Enumerate the values in +key+
+	#
 	def meterpreter_registry_enumvals(key)
 		values = []
 		begin
@@ -467,6 +524,9 @@ protected
 		return values
 	end
 
+	#
+	# Get the data stored in the value +valname+
+	#
 	def meterpreter_registry_getvaldata(key, valname)
 		value = nil
 		begin
@@ -481,6 +541,9 @@ protected
 		return value
 	end
 
+	#
+	# Enumerate the type and data of the value +valname+
+	#
 	def meterpreter_registry_getvalinfo(key, valname)
 		value = {}
 		begin
@@ -496,6 +559,9 @@ protected
 		return value
 	end
 
+	#
+	# Add the value +valname+ to the key +key+ with the specified +type+ and +data+
+	#
 	def meterpreter_registry_setvaldata(key, valname, data, type)
 		begin
 			root_key, base_key = session.sys.registry.splitkey(key)