Adding documentation to the methods in the post exploitation library. Will eventually generate an rdoc file and a post exploitation How To.

lib/msf/core/post/file.rb

@@ -51,6 +51,9 @@ module Msf::Post::File
 		end
 	end
 
+	#
+	# Expand any environment variables to return the full path specified by +path+.
+	#
 	def expand_path(path)
 		if session.type == "meterpreter"
 			return session.fs.file.expand_path(path)
@@ -429,6 +432,9 @@ protected
 		true
 	end
 
+	#
+	# Calculate the maximum line length for a unix shell.
+	#
 	def _unix_max_line_length
 		# Based on autoconf's arg_max calculator, see
 		# http://www.in-ulm.de/~mascheck/various/argmax/autoconf_check.html

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

@@ -12,6 +12,11 @@ module CliParse
 
 	#Msf::Post::Windows::CliParse::ParseError
 	class ParseError < ArgumentError
+
+		#
+		# Create a new ParseError object. Expects a method name, an error 
+		# message, an error code, and the command that caused the error.
+		#
 		def initialize(method, einfo='', ecode=nil, clicmd=nil)
 			@method = method
 			@info = einfo
@@ -20,6 +25,9 @@ module CliParse
 			@clicmd = clicmd || "Unknown shell command"
 		end
 
+		#
+		# Convert a ParseError to a string.
+		#
 		def to_s
 			"#{@method}: Operation failed: #{@info}:#{@code} while running #{@clicmd}"
 		end

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

@@ -78,6 +78,9 @@ module Priv
 		return uac
 	end
 
+	#
+	# Return true if the session has extended capabilities (ie meterpreter)
+	#
 	def session_has_ext
 		begin
 			return !!(session.railgun and session.sys.config)

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

@@ -12,10 +12,17 @@ module ShadowCopy
 
 	include Msf::Post::Windows::WindowsServices
 
+	#
+	# Get the device name for the shadow copy, which is used when accessing  
+	# files on the volume.
+	#
 	def get_vss_device(id)
 		result = get_sc_param(id,'DeviceObject')
 	end
 
+	#
+	# Returns a list of volume shadow copies.
+	#
 	def vss_list
 		ids = vss_get_ids
 		shadow_copies = []
@@ -26,12 +33,18 @@ module ShadowCopy
 		return shadow_copies
 	end
 
+	#
+	# Use WMIC to get a list of volume shadow copy IDs.
+	#
 	def vss_get_ids
 		result = wmicexec('shadowcopy get id')
 		ids = result.scan(/\{\w{8}-\w{4}-\w{4}-\w{4}-\w{12}\}/)
 		return ids
 	end
 
+	#
+	# Get volume shadow storage parameters.
+	# 
 	def vss_get_storage
 		storage={}
 		storage['AllocatedSpace'] = vss_get_storage_param('AllocatedSpace')
@@ -40,6 +53,9 @@ module ShadowCopy
 		return storage
 	end
 
+	#
+	# Get detailed information about the volume shadow copy specified by +id+
+	#
 	def get_sc_details(id)
 		shadowcopy={}
 		shadowcopy['ID'] = id
@@ -67,18 +83,29 @@ module ShadowCopy
 		return shadowcopy
 	end
 
+	#
+	# Return the value of the +param_name+ for the volume shadow copy 
+	# specified by +id+
+	#
 	def get_sc_param(id,param_name)
 		result = wmicexec("shadowcopy where(id=#{id}) get #{param_name}")
 		result.gsub!(param_name,'')
 		result.gsub!(/\s/,'')
 	end
 
+	#
+	# Return the value of the shadowstorage parameter specified by 
+	# +param_name+
+	#
 	def vss_get_storage_param(param_name)
 		result = wmicexec("shadowstorage get #{param_name}")
 		result.gsub!(param_name,'')
 		result.gsub!(/\s/,'')
 	end
 
+	#
+	# Set the shadowstorage MaxSpace parameter to +bytes+ size
+	#
 	def vss_set_storage(bytes)
 		result = wmicexec("shadowstorage set MaxSpace=\"#{bytes}\"")
 		if result.include?("success")
@@ -88,6 +115,9 @@ module ShadowCopy
 		end
 	end
 
+	#
+	# Create a new shadow copy of the volume specified by +volume+
+	#
 	def create_shadowcopy(volume)
 		result = wmicexec("shadowcopy call create \"ClientAccessible\", \"#{volume}\"")
 		retval = result.match(/ReturnValue = (\d)/)
@@ -126,6 +156,9 @@ module ShadowCopy
 		return nil
 	end
 
+	#
+	# Start the Volume Shadow Service
+	#
 	def start_vss
 		vss_state = wmicexec('Service where(name="VSS") get state')
 		if vss_state=~ /Running/
@@ -158,6 +191,9 @@ module ShadowCopy
 		return true
 	end
 
+	#
+	# Execute a WMIC command
+	#
 	def wmicexec(wmiccmd)
 		tmpout = ''
 		session.response_timeout=120

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

@@ -10,6 +10,11 @@ module UserProfiles
 	include Msf::Post::Windows::Registry
 	include Msf::Post::Windows::Accounts
 
+	#
+	# Load the registry hive for each user on the machine and parse out the 
+	# user profile information. Next, unload the hives we loaded and return 
+	# the user profiles.
+	#
 	def grab_user_profiles
 		hives = load_missing_hives()
 		profiles = parse_profiles(hives)
@@ -17,6 +22,9 @@ module UserProfiles
 		return profiles
 	end
 
+	#
+	# Unload any hives we loaded.
+	#
 	def unload_our_hives(hives)
 		hives.each do |hive|
 			next unless hive['OURS']==true
@@ -24,6 +32,9 @@ module UserProfiles
 		end
 	end
 
+	#
+	# Return a list of user profiles parsed each of the hives in +hives+.
+	#
 	def parse_profiles(hives)
 		profiles=[]
 		hives.each do |hive|
@@ -33,6 +44,9 @@ module UserProfiles
 		return profiles
 	end
 
+	#
+	# Get the user profile information from the hive specified by +hive+
+	#
 	def parse_profile(hive)
 		profile={}
 		sidinf = resolve_sid(hive['SID'].to_s)
@@ -54,7 +68,9 @@ module UserProfiles
 		return profile
 	end
 
-
+	#
+	# Load any user hives that are not already loaded.
+	#
 	def load_missing_hives
 		hives=[]
 		read_profile_list().each do |hive|
@@ -72,6 +88,10 @@ module UserProfiles
 		return hives
 	end
 
+	#
+	# Read HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList to 
+	# get a list of user profiles on the machine.
+	#
 	def read_profile_list
 		hives=[]
 		registry_enumkeys('HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList').each do |profkey|
@@ -88,6 +108,9 @@ module UserProfiles
 		return hives
 	end
 
+	#
+	# Return a list of loaded registry hives.
+	#
 	def loaded_hives
 		hives=[]
 		registry_enumkeys('HKU').each do |k|