ronin 0.2.4 → 0.3.0

data/lib/ronin/platform/overlay_cache.rb

@@ -1,7 +1,5 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
@@ -18,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/platform/exceptions/overlay_cached'
@@ -42,9 +39,17 @@ module Ronin
       attr_reader :path
 
       #
-      # Create a new OverlayCache object with the specified _path_. The
-      # _path_ defaults to <tt>CACHE_FILE</tt>. If a _block_ is given,
-      # it will be passed the newly created OverlayCache object.
+      # Create a new OverlayCache object.
+      #
+      # @param [String] path
+      #   The path of the overlay cache file.
+      #
+      # @yield [cache]
+      #   If a block is given, it will be passed the newly created overlay
+      #   cache.
+      #
+      # @yieldparam [OverlayCache] cache
+      #   The newly created overly cache.
       #
       def initialize(path=CACHE_FILE,&block)
         super()
@@ -52,23 +57,7 @@ module Ronin
         @path = path
         @dirty = false
 
-        if File.file?(@path)
-          descriptions = YAML.load_file(@path)
-
-          if descriptions.kind_of?(Array)
-            descriptions.each do |overlay|
-              if overlay.kind_of?(Hash)
-                overlay = Overlay.new(
-                  overlay[:path],
-                  overlay[:media],
-                  overlay[:uri]
-                )
-
-                self[overlay.name] = overlay
-              end
-            end
-          end
-        end
+        load!()
 
         at_exit(&method(:save))
 
@@ -76,15 +65,50 @@ module Ronin
       end
 
       #
-      # Returns +true+ if the overlay cache has been modified, returns
-      # +false+ otherwise.
+      # Loads the overlays from the cache-file at the +path+.
+      #
+      def load!
+        return false unless File.file?(@path)
+
+        descriptions = YAML.load_file(@path)
+
+        return false unless descriptions.kind_of?(Array)
+
+        descriptions.each do |overlay|
+          if overlay.kind_of?(Hash)
+            overlay = Overlay.new(
+              overlay[:path],
+              overlay[:media],
+              overlay[:uri]
+            )
+
+            self[overlay.name] = overlay
+          end
+        end
+
+        return true
+      end
+
+      #
+      # Clears the overlay cache, and reloads it's contents from the same
+      # cache-file.
+      #
+      def reload!
+        clear
+        load!
+      end
+
+      #
+      # @return [Boolean]
+      #   Specifies whether the overlay cache has been modified.
       #
       def dirty?
         @dirty == true
       end
 
       #
-      # Returns the sorted names of the overlays within the cache.
+      # @return [Array]
+      #   The sorted names of the overlays within the cache.
       #
       def names
         keys.sort
@@ -94,8 +118,19 @@ module Ronin
       alias each_overlay each_value
 
       #
-      # Returns the Ovlerays which match the specified _block_.
+      # Selects overlays from the overlay cache.
       #
+      # @yield [overlay]
+      #   The block that will be passed each overlay. Overlays will be
+      #   selected based on the return value of the block.
+      #
+      # @yieldparam [Overlay] overlay
+      #   An overlay from the cache.
+      #
+      # @return [Array]
+      #   The selected overlay.
+      #
+      # @example
       #   cache.with do |overlay|
       #     overlay.author == 'the dude'
       #   end
@@ -105,15 +140,31 @@ module Ronin
       end
 
       #
-      # Returns +true+ if the cache contains the Overlay with the
-      # matching _name_, returns +false+ otherwise.
+      # Searches for the overlay with the specified _name_.
+      #
+      # @param [String] name
+      #   The name of the overlay to search for.
+      #
+      # @return [Boolean]
+      #   Specifies whether the cache contains the Overlay with the
+      #   matching _name_.
       #
       def has?(name)
         has_key?(name.to_s)
       end
 
       #
-      # Returns the Overlay with the matching _name_.
+      # Searches for the overlay with the specified _name_.
+      #
+      # @param [String] name
+      #   The name of the overlay to search for.
+      #
+      # @return [Overlay]
+      #   The overlay with the matching _name_.
+      #
+      # @raise [OverlayNotFound]
+      #   No overlay with the matching _name_ could be found in the
+      #   overlay cache.
       #
       def get(name)
         name = name.to_s
@@ -126,16 +177,22 @@ module Ronin
       end
 
       #
-      # Returns the paths of the Overlays contained in the cache.
+      # @return [Array]
+      #   The paths of the overlays contained in the cache.
       #
       def paths
         overlays.map { |overlay| overlay.path }
       end
 
       #
-      # Returns +true+ if the extension with the specified _name_ exists
-      # within any of the overlays in the overlay cache, returns +false+
-      # otherwise.
+      # Searches for an extension within all overlays in the overlay cache.
+      #
+      # @param [String] name
+      #   The name of the extension to search for.
+      #
+      # @return [Boolean]
+      #   Specifies whether the extension with the specified _name_ exists
+      #   within any of the overlays in the overlay cache.
       #
       def has_extension?(name)
         each_overlay do |overlay|
@@ -146,7 +203,8 @@ module Ronin
       end
 
       #
-      # Returns the names of all extensions within the overlay cache.
+      # @return [Array]
+      #   The names of all extensions within the overlay cache.
       #
       def extensions
         ext_names = []
@@ -161,7 +219,14 @@ module Ronin
       end
 
       #
-      # Returns the paths of all extensions with the specified _name_.
+      # Selects the paths of extensions that have the specified _name_, in
+      # all overlays in the overlay cache.
+      #
+      # @param [String] name
+      #   The name of the extension to gather paths for.
+      #
+      # @return [Array]
+      #   The paths of all extensions with the matching _name_.
       #
       def extension_paths(name)
         ext_paths = []
@@ -176,8 +241,16 @@ module Ronin
       end
 
       #
-      # Adds the specified _overlay_ with the specified _name_ to the
-      # overlay cache.
+      # Adds an overlay with the specified _name_ to the overlay cache.
+      #
+      # @param [String] name
+      #   The name of the overlay.
+      #
+      # @param [Overlay] overlay
+      #   The new overlay.
+      #
+      # @return [Overlay]
+      #   The new overlay.
       #
       def []=(name,overlay)
         super(name.to_s,overlay)
@@ -187,38 +260,62 @@ module Ronin
       end
 
       #
-      # Adds the _overlay_ to the cache. If a _block_ is given, it will
-      # be passed the cache after the _overlay_ is added. The _overlay_
-      # will be returned.
+      # Adds an overlay to the cache.
+      #
+      # @param [Overlay] overlay
+      #   The overlay to add.
+      #
+      # @yield [overlay]
+      #   If a block is given, it will be passed the overlay after it has
+      #   been added to the cache.
+      #
+      # @yieldparam [Overlay] overlay
+      #   The newly added overlay.
       #
+      # @return [Overlay]
+      #   The newly added overlay.
+      #
+      # @example
       #   cache.add(overlay)
       #   # => #<Ronin::Platform::Overlay: ...>
       #
+      # @example
       #   cache.add(overlay) do |cache|
       #     puts "Overlay #{overlay} added"
       #   end
       #
+      # @raise [OverlayCache]
+      #   The specified _overlay_ has already been cached.
+      #
       def add(overlay,&block)
         name = overlay.name.to_s
 
         if has?(name)
-          raise(OverlayCached,"overlay #{name.dump} already present in the cache #{self.to_s.dump}",caller)
+          raise(OverlayCached,"overlay #{name.dump} is already present in the cache #{self.to_s.dump}",caller)
         end
 
         self[overlay.name.to_s] = overlay
         dirty!
 
-        block.call(self) if block
-        return self
+        block.call(overlay) if block
+        return overlay
       end
 
       #
-      # Updates all the cached Overlays. If a _block_ is given it will
-      # be passed the overlays as they are updated.
+      # Updates all overlays in the cache.
+      #
+      # @yield [overlay]
+      #   If a block is given, it will be passed each overlay after it has
+      #   been updated.
       #
+      # @yieldparam [Overlay] overlay
+      #   Each updated overlay in the cache.
+      #
+      # @example
       #   update
       #   # => #<Ronin::Platform::OverlayCache: ...>
       #
+      # @example
       #   update do |overlay|
       #     puts "#{overaly} is updated"
       #   end
@@ -234,13 +331,26 @@ module Ronin
       end
 
       #
-      # Removes the overlay with the specified _name_ from the cache. If a
-      # _block_ is given, it will be passed the removed overlay. The cache
-      # will be returned, after the overlay is removed.
+      # Removes an overlay from the overlay cache, but leaves the contents
+      # of the overlay intact.
+      #
+      # @param [String] name
+      #   The name of the overlay to remove.
+      #
+      # @yield [overlay]
+      #   If a block is given, it will be passed the removed overlay.
       #
+      # @yieldparam [Overlay] overlay
+      #   The removed overlay.
+      #
+      # @return [Overlay]
+      #   The removed overlay.
+      #
+      # @example
       #   cache.remove('hello_word')
       #   # => #<Ronin::Platform::Overlay: ...>
       #
+      # @example
       #   cache.remove('hello_word') do |overlay|
       #     puts "Overlay #{overlay} removed"
       #   end
@@ -255,17 +365,27 @@ module Ronin
         dirty!
 
         block.call(overlay) if block
-        return self
+        return overlay
       end
 
       #
-      # Uninstalls the overlay with the specified _name_. If a _block_
-      # is given, it will be passed the uninstalled overlay. The cache
-      # will be returned, after the overlay is removed.
+      # Uninstalls an overlay and its contents from the overlay cache.
       #
+      # @param [String] name
+      #   The name of the overlay to uninstall.
+      # 
+      # @yield [overlay]
+      #   If a block is given, it will be passed the overlay, after it has
+      #   been uninstalled.
+      #
+      # @yieldparam [Overlay] overlay
+      #   The uninstalled overlay.
+      #
+      # @example
       #   cache.uninstall('hello_word')
       #   # => #<Ronin::Platform::Overlay: ...>
       #
+      # @example
       #   cache.uninstall('hello_word') do |overlay|
       #     puts "Overlay #{overlay} uninstalled"
       #   end
@@ -274,10 +394,12 @@ module Ronin
         remove(name) do |overlay|
           overlay.uninstall(&block)
         end
+
+        return nil
       end
 
       #
-      # Saves the overlay cache.
+      # Saves the overlay cache to the path.
       #
       def save
         return false unless dirty?
@@ -304,7 +426,8 @@ module Ronin
       end
 
       #
-      # Returns the +path+ of the cache.
+      # @return [String]
+      #   The path of the cache.
       #
       def to_s
         @path.to_s

data/lib/ronin/platform/platform.rb

@@ -1,7 +1,5 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
@@ -18,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/platform/exceptions/overlay_not_found'
@@ -31,34 +28,66 @@ require 'uri'
 module Ronin
   module Platform
     #
-    # Load the overlay cache from the given _path_. If a _block_ is
-    # given it will be passed the current overlay cache.
+    # Load the overlay cache.
     #
+    # @param [String] path
+    #   The optional path to the overlay cache file.
+    #
+    # @return [OverlayCache]
+    #   The newly loaded overlay cache.
+    #
+    # @example
+    #   Overlay.load_overlays
+    #   # => #<Ronin::Platform::OverlayCache: ...>
+    #
+    # @example
     #   Overlay.load_overlays('/custom/overlays/cache.yaml')
     #   # => #<Ronin::Platform::OverlayCache: ...>
     #
-    def Platform.load_overlays(path)
+    def Platform.load_overlays(path=OverlayCache::CACHE_FILE)
       @@ronin_overlay_cache = OverlayCache.new(path)
     end
 
     #
-    # Returns the current overlay cache, or loads the default overlay
-    # cache if not already loaded.
+    # @return [OverlayCache]
+    #   The current overlay cache. If no overlay cache is present, the
+    #   default overlay will be loaded.
     #
     def Platform.overlays
       @@ronin_overlay_cache ||= OverlayCache.new
     end
 
     #
-    # Adds a new Overlay with the given _options_. If a _block_ is given
-    # it will be passed the newly added overlay.
+    # Adds a new overlay to the overlay cache.
+    #
+    # @param [Hash] options
+    #   Additional options.
+    #
+    # @option options [String] :path
+    #   A pre-existing path to the overlay.
+    #
+    # @option options [Symbol] :media
+    #   The media type of the overlay, may be either +:git+, +:hg+,
+    #   +:svn+ or +:rsync+.
+    #
+    # @option options [String, URI::HTTP, URI::HTTPS] uri
+    #   The URI of the overlay.
+    #
+    # @yield [overlay]
+    #   If a block is given, it will be passed the overlay after it has
+    #   been added to the cache.
+    #
+    # @yieldparam [Overlay] overlay
+    #   The newly added overlay.
+    #
+    # @return [Overlay]
+    #   The newly added overlay.
     #
-    # _options_ must contain the following key:
-    # <tt>:path</tt>:: The path of the overlay.
+    # @raise [ArgumentError]
+    #   The +:path+ option was not specified.
     #
-    # _options_ may contain the following key:
-    # <tt>:media</tt>:: The media of the overlay.
-    # <tt>:uri</tt>:: The URI of the overlay.
+    # @raise [OverlayNotFound]
+    #   The +:path+ option did not represent a valid directory.
     #
     def Platform.add(options={},&block)
       path = options[:path]
@@ -78,24 +107,40 @@ module Ronin
 
       overlay = Overlay.new(path,media,uri)
 
-      Platform.overlays.add(overlay) do
+      Platform.overlays.add(overlay) do |overlay|
         ObjectCache.cache(overlay.objects_dir)
       end
 
+      block.call(overlay) if block
       return overlay
     end
 
     #
-    # Installs an Overlay specified by _options_ into the
-    # OverlayCache::CACHE_DIR. If a _block_ is given, it will be
-    # passed the newly created overlay after it has been added to
-    # the overlay cache.
+    # Installs an overlay into the OverlayCache::CACHE_DIR and adds it
+    # to the overlay cache.
     #
-    # _options_ must contain the following key:
-    # <tt>:uri</tt>:: The URI of the overlay.
+    # @param [Hash] options
+    #   Additional options.
     #
-    # _options_ may contain the following key:
-    # <tt>:media</tt>:: The media of the overlay.
+    # @option options [String, URI::HTTP, URI::HTTPS] :uri
+    #   The URI to the overlay.
+    #
+    # @option options [Symbol] :media
+    #   The media type of the overlay, may be either +:git+, +:hg+,
+    #   +:svn+ or +:rsync+.
+    #
+    # @yield [overlay]
+    #   If a block is given, it will be passed the overlay, after it has
+    #   been installed.
+    #
+    # @yieldparam [Overlay] overlay
+    #   The newly installed overlay.
+    #
+    # @return [Overlay]
+    #   The newly installed overlay.
+    #
+    # @raise [ArgumentError]
+    #   The +:uri+ option must be specified.
     #
     def Platform.install(options={},&block)
       unless options[:uri]
@@ -111,14 +156,18 @@ module Ronin
         return Platform.add(
           :path => repo.path,
           :media => repo.media_name,
-          :uri => uri
+          :uri => uri,
+          &block
         )
       end
     end
 
     #
-    # Updates all previously installed overlays. If a _block_ is given
-    # it will be called after the overlays have been updated.
+    # Updates all previously installed overlays within the overlay cache.
+    #
+    # @yield []
+    #   If a block is given, it will be called after all overlays have been
+    #   updated within the cache.
     #
     def Platform.update(&block)
       Platform.overlays.update do |overlay|
@@ -130,10 +179,22 @@ module Ronin
     end
 
     #
-    # Removes the overlay with the specified _name_. If no overlay
-    # has the specified _name_, an OverlayNotFound exception will be
-    # raised. If a _block_ is given, it will be called after the overlay
-    # has been removed.
+    # Removes an overlay from the overlay cache, but leaves the contents
+    # of the overlay intact.
+    #
+    # @param [String] name
+    #   The name of the overlay to remove.
+    #
+    # @yield [overlay]
+    #   If a block is given, it will be passed the overlay after it has
+    #   been removed.
+    #
+    # @yieldparam [Overlay] overlay
+    #   The removed overlay.
+    #
+    # @raise [OverlayNotFound]
+    #   The overlay with the specified _name_ could not be found in the
+    #   overlay cache.
     #
     def Platform.remove(name,&block)
       Platform.overlays.remove(name,&block)
@@ -141,10 +202,19 @@ module Ronin
     end
 
     #
-    # Uninstalls the overlay with the specified _name_. If no overlay
-    # has the specified _name_, an OverlayNotFound exception will be
-    # raised. If a _block_ is given, it will be called after the overlay
-    # has been uninstalled.
+    # Uninstalls an overlay from the overlay cache, and deletes the
+    # contents of the overlay.
+    #
+    # @param [String] name
+    #   The name of the overlay to uninstall.
+    #
+    # @yield []
+    #   If a block is given, it will be called after the overlay has been
+    #   uninstalled.
+    #
+    # @raise [OverlayNotFound]
+    #   The overlay with the specified _name_ could not be found in the
+    #   overlay cache.
     #
     def Platform.uninstall(name,&block)
       Platform.overlays.uninstall(name) do |overlay|
@@ -156,36 +226,36 @@ module Ronin
     end
 
     #
-    # Returns the names of all extensions within the overlay cache.
+    # @return [Array]
+    #   The names of all extensions within the overlays in the overlay
+    #   cache.
     #
     def Platform.extension_names
-      names = []
-
-      Platform.overlays.each_overlay do |overlay|
-        overlay.extensions.each do |name|
-          names << name unless names.include?(name)
-        end
-      end
-
-      return names
+      Platform.overlays.extensions
     end
 
     #
-    # Returns +true+ if the cache has the extension with the matching
-    # _name_, returns +false+ otherwise.
+    # Searches for the extension with the specified _name_, in all
+    # overlays within the overlay cache.
+    #
+    # @param [String] name
+    #   The name of the extension to search for.
+    #
+    # @return [Boolean]
+    #   Specifies whether the overlay cache contains the extension with
+    #   the matching _name_.
     #
     def Platform.has_extension?(name)
-      Platform.overlays.each_overlay do |overlay|
-        return true if overlay.has_extension?(name)
-      end
-
-      return false
+      Platform.overlays.has_extension?(name)
     end
 
     #
-    # Returns a +Hash+ of all loaded extensions. Extensions can be loaded
-    # on-the-fly by accessing the +Hash+.
+    # The extension cache.
+    #
+    # @return [ExtensionCache]
+    #   The extension cache of all currently loaded extensions.
     #
+    # @example
     #   Platform.extensions['shellcode']
     #   # => #<Ronin::Platform::Extension: ...>
     #
@@ -194,9 +264,25 @@ module Ronin
     end
 
     #
-    # Loads the extension with the specified _name_. If a _block_ is given
-    # it will be passed the loaded extension. If the extension cannot be
-    # loaded, an ExtensionNotFound exception will be raised.
+    # Loads an extension into the extension cache, if it has yet to be
+    # loaded.
+    #
+    # @param [String] name
+    #   The name of the desired extension.
+    #
+    # @yield [ext]
+    #   If a block is given, it will be passed the extension with the
+    #   matching _name_.
+    #
+    # @yieldparam [Extension] ext
+    #   The desired extension.
+    #
+    # @return [Extension]
+    #   The desired extension.
+    #
+    # @raise [ExtensionNotFound]
+    #   The extension with the specified _name_ could not be found in any
+    #   of the overlays or in the extension cache.
     #
     def Platform.extension(name,&block)
       ext = Platform.extensions[name]
@@ -204,5 +290,15 @@ module Ronin
       block.call(ext) if block
       return ext
     end
+
+    #
+    # Reloads the overlay cache and the extension cache.
+    #
+    # @return [Boolean]
+    #   Specifies whether the reload was successful or not.
+    #
+    def Platform.reload!
+      Platform.overlays.reload! && Platform.extensions.reload!
+    end
   end
 end