Add yard documentation

Author: jvazquez-r7

lib/msf/core/exploit/file_dropper.rb

@@ -14,50 +14,20 @@ def initialize(info = {})
       ], self.class)
   end
 
-  #
   # When a new session is created, attempt to delete any files that the
   # exploit created.
   #
   # @param (see Msf::Exploit#on_new_session)
   # @return [void]
-  #
   def on_new_session(session)
     super
 
     print_status("new session...")
-    on_new_session_job(session)
-  end
-
-  def on_new_session_job(new_session)
-    if session
-      session_orig = session
-    end
-
-    self.session = new_session
-
-    if session.type == 'meterpreter'
-      session.core.use('stdapi') unless session.ext.aliases.include?('stdapi')
-    end
-
-    if not @dropped_files or @dropped_files.empty?
-      return true
-    end
-
-    @dropped_files.delete_if do |file|
-      puts "Deleting #{file}"
-      exists_before = file_dropper_check_file(file)
-      if file_dropper_delete(file)
-        file_dropper_deleted?(file, exists_before)
-      else
-        false
-      end
-    end
-
-    if session_orig
-      self.session = session_orig
-    else
-      self.session = nil
+    puts "#{self.session}"
+    if self.payload
+      puts "#{self.payload.session}"
     end
+    on_new_session_job(session)
   end
 
   #
@@ -123,10 +93,76 @@ def cleanup
 
   private
 
+  # Takes a new session and makes the drop files task
+  #
+  # @param (see Msf::Exploit#on_new_session)
+  # @return [void]
+  # @note This methods needs to overwrite *and restore* the original
+  # `session` attribute
+  def on_new_session_job(new_session)
+    session_orig = session
+    self.session = new_session
+
+    begin
+      file_dropper_delete_files
+    ensure
+      self.session = session_orig
+    end
+  end
+
+  # Uses the exploit `session` to delete files on the `dropped_files` list
+  #
+  # @return [void]
+  def file_dropper_delete_files
+    if session.type == 'meterpreter'
+      session.core.use('stdapi') unless session.ext.aliases.include?('stdapi')
+    end
+
+    unless @dropped_files && @dropped_files.length > 0
+      return
+    end
+
+    @dropped_files.delete_if do |file|
+      puts "Deleting #{file}"
+      exists_before = file_dropper_check_file(file)
+      if file_dropper_delete(file)
+        file_dropper_deleted?(file, exists_before)
+      else
+        false
+      end
+    end
+  end
+
+  # Check if a file exists in the `session` file system
+  #
+  # @param [String] file The file to check
+  # @return [TrueClass] If the file exists
+  # @return [FalseClass] If the file doesn't exist
+  def file_dropper_check_file(file)
+    puts "Checking file... #{file}"
+    if session.platform =~ /win/
+      normalized = file_dropper_win_file(file)
+    else
+      normalized = file
+    end
+
+    puts "Checking normalized file... #{file}"
+    Msf::Post::File.file_exist?(normalized)
+  end
+
+  # Converts a file path to use the windows separator '\'
+  #
+  # @param [String] file The file path to convert
+  # @return [String] The file path converted
   def file_dropper_win_file(file)
     file.gsub('/', "\\\\")
   end
 
+  # Sends a file deletion command to the remote `session`
+  #
+  # @param [String] file The file to delete
+  # @return [TrueClass] If the delete command has been executed in the remote machine
+  # @return [FalseClass] Otherwise
   def file_dropper_delete(file)
     puts "Deleting #{file}"
     win_file = file_dropper_win_file(file)
@@ -162,18 +198,12 @@ def file_dropper_delete(file)
     end
   end
 
-  def file_dropper_check_file(file)
-    puts "Checking file... #{file}"
-    if session.platform =~ /win/
-      normalized = file_dropper_win_file(file)
-    else
-      normalized = file
-    end
-
-    puts "Checking normalized file... #{file}"
-    Msf::Post::File.file_exist?(normalized)
-  end
-
+  # Checks if a file has been deleted by the current job
+  #
+  # @param [String] file The file to check
+  # @param [TrueClass] exists_before Indicates if the file existed before the cleanup job
+  # @return [TrueClass] if the file has been deleted or it cannot resolve
+  # @return [FalseClass] if the file hasn't been deleted
   def file_dropper_deleted?(file, exists_before)
     puts "Deleted? ... #{file}"
     if exists_before  && file_dropper_check_file(file)