ronin 0.2.4 → 0.3.0

data/lib/ronin/platform/extension_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/extension'
@@ -29,8 +26,14 @@ module Ronin
     class ExtensionCache < Hash
 
       #
-      # Creates a new empty ExtensionCache object. If a _block_ is given
-      # it will be passed the newly created ExtensionCache object.
+      # Creates a new empty ExtensionCache object.
+      #
+      # @yield [cache]
+      #   If a block is given, it will be passed the newly created
+      #   extension cache.
+      #
+      # @yieldparam [ExtensionCache] cache
+      #   The newly created extension cache.
       #
       def initialize(&block)
         super() do |hash,key|
@@ -47,7 +50,8 @@ module Ronin
       end
 
       #
-      # Returns the sorted names of the extensions within the cache.
+      # @return [Array]
+      #   The sorted names of the extensions within the cache.
       #
       def names
         keys.sort
@@ -60,46 +64,78 @@ module Ronin
       # Selects the extensions within the cache that match the specified
       # _block_.
       #
-      def extensions_with(&block)
+      # @yield [ext]
+      #   The block will be passed each extension, and the extension will
+      #   be selected based on the return value of the block.
+      #
+      # @yieldparam [Extension] ext
+      #   An extension from the cache.
+      #
+      # @return [Array]
+      #   The selected extensions.
+      #
+      def with(&block)
         values.select(&block)
       end
 
       #
-      # Returns +true+ if the cache contains the extension with the
-      # specified _name_, returns +false+ otherwise.
+      # Searches within the cache for the extension with the specified
+      # _name_.
+      #
+      # @return [Boolean]
+      #   Specifies whether the cache contains the extension with the
+      #   specified _name_.
       #
-      def has_extension?(name)
+      def has?(name)
         has_key?(name.to_s)
       end
 
       #
-      # Loads the extension with the specified _name_. If no such extension
-      # exists an ExtensionNotFound exception will be raised. If a _block_
-      # is given, it will be passed the loaded extension.
+      # Loads the extension with the specified _name_.
+      #
+      # @param [String, Symbol] name
+      #   The name of the extension to load.
       #
-      def load_extension(name,&block)
+      # @raise [ExtensionNotFound]
+      #   The extension with the specified _name_ could not be found in
+      #   the extension cache.
+      #
+      def load_extension(name)
         name = name.to_s
 
         unless Platform.overlays.has_extension?(name)
           raise(ExtensionNotFound,"extension #{name.dump} does not eixst",caller)
         end
 
-        return Extension.load(name) do |ext|
-          ext.setup!
-
-          block.call(ext) if block
+        return Extension.new(name) do |ext|
+          include(self.name)
+          setup!
         end
       end
 
       #
-      # Reloads the extensions within the extension cache.
+      # Reloads one or all extensions within the extension cache.
+      #
+      # @param [String, Symbol] name
+      #   The specific extension to reload.
       #
-      def reload!
-        each do |name,ext|
-          ext.teardown!
+      # @return [true]
+      #   Specifies the reload was successful.
+      #
+      def reload!(name=nil)
+        reloader = lambda { |ext_name|
+          self[ext_name].teardown! if has?(ext_name)
+
+          self[ext_name] = load_extension(ext_name)
+        }
 
-          self[name] = load_extension(name)
+        if name
+          reloader.call(name)
+        else
+          each_key(&reloader)
         end
+
+        return true
       end
 
     end

data/lib/ronin/platform/maintainer.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
-#++
 #
 
 module Ronin
@@ -32,8 +29,13 @@ module Ronin
       attr_reader :email
 
       #
-      # Creates a new Maintainer object with the specified _name_ and the
-      # given _email_.
+      # Creates a new Maintainer object.
+      #
+      # @param [String] name
+      #   The name of the maintainer.
+      #
+      # @param [String] email
+      #   The optional email of the maintainer.
       #
       def initialize(name,email=nil)
         @name = name
@@ -41,7 +43,9 @@ module Ronin
       end
 
       #
-      # Returns the String form of the maintainer object.
+      # @return [String]
+      #   The String representation of the maintainer object.
+      #
       def to_s
         if @email
           return "#{@name} <#{@email}>"
@@ -51,7 +55,10 @@ module Ronin
       end
 
       #
-      # Inspects the maintainer object.
+      # @return [String]
+      #   Inspects the maintainer object.
+      #
+      # @see Maintainer#to_s
       #
       def inspect
         "#<#{self.class.name}: #{self}>"

data/lib/ronin/platform/object_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/database'
@@ -29,15 +26,30 @@ module Ronin
   module Platform
     module ObjectCache
       #
-      # Returns all paths within the specified _directory_ pointing
-      # to object files.
+      # Searches for object files within the specified _directory_.
+      #
+      # @param [String] directory
+      #   The directory to search for object files within.
+      #
+      # @return [Array]
+      #   All paths within the specified _directory_ pointing to object
+      #   files.
       #
       def ObjectCache.paths(directory)
         Dir[File.join(File.expand_path(directory),'**','*.rb')]
       end
 
       #
-      # Finds all cached objects, passing each to the given _block_.
+      # Finds all cached objects.
+      #
+      # @param [String] directory
+      #   Optional directory to search within for cached objects.
+      #
+      # @yield [obj]
+      #   The block that will receive all cached object.
+      #
+      # @yieldparam [Cacheable] obj
+      #   The cached object.
       #
       def ObjectCache.each(directory=nil,&block)
         attributes = {}
@@ -57,6 +69,9 @@ module Ronin
       # Cache all objects loaded from the paths within the specified
       # _directory_.
       #
+      # @param [String] directory
+      #   The directory to cache all objects from.
+      #
       def ObjectCache.cache(directory)
         Database.setup unless Database.setup?
 
@@ -70,7 +85,10 @@ module Ronin
       #
       # Syncs all objects that were previously cached from paths within
       # the specified _directory_. Also cache objects which have yet to
-      # be cached.
+      # be cached from the _directory_.
+      #
+      # @param [String] directory
+      #   The directory to sync all objects with.
       #
       def ObjectCache.sync(directory)
         new_paths = ObjectCache.paths(directory)
@@ -92,6 +110,9 @@ module Ronin
       # Deletes all cached objects that existed in the specified
       # _directory_.
       #
+      # @param [String] directory
+      #   Deletes all cached objects from the specified _directory_.
+      #
       def ObjectCache.clean(directory)
         Database.setup unless Database.setup?
 

data/lib/ronin/platform/overlay.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/extension_not_found'
@@ -77,6 +74,9 @@ module Ronin
       # Website URI for the overlay
       attr_reader :website
 
+      # Ruby Gems required by the overlay
+      attr_reader :gems
+
       # Maintainers of the overlay
       attr_reader :maintainers
 
@@ -94,7 +94,24 @@ module Ronin
 
       #
       # Creates a new Overlay object with the specified _path_, _media_
-      # and _uri_.
+      # and _uri_. If a _block_ is given it will be passed the newly
+      # created Overlay object.
+      #
+      # @param [String] path
+      #   The path to the overlay.
+      #
+      # @param [Symbol] media
+      #   The media of the overlay. Can be either +:git+, +:hg+, +:snv+ or
+      #   +:rsync+.
+      #
+      # @param [String, URI::HTTP, URI::HTTPS] uri
+      #   The URI the overlay resides at.
+      #
+      # @yield [overlay]
+      #   If a block is given, the overlay will be passed to it.
+      #
+      # @yieldparam [Overlay] overlay
+      #   The newly created overlay.
       #
       def initialize(path,media=nil,uri=nil,&block)
         @path = File.expand_path(path)
@@ -104,18 +121,22 @@ module Ronin
         @uri = uri
         @repository = Repository.new(@path,Media.types[media])
 
-        initialize_metadata(&block)
+        initialize_metadata()
+
+        block.call(self) if block
       end
 
       #
-      # Media type of the overlay.
+      # @return [Symbol]
+      #   The media type of the overlay.
       #
       def media
         @repository.media_name
       end
 
       #
-      # Returns the paths of all extensions within the overlay.
+      # @return [Array]
+      #   The paths of all extensions within the overlay.
       #
       def extension_paths
         @repository.directories.reject do |dir|
@@ -126,15 +147,23 @@ module Ronin
       end
 
       #
-      # Returns the names of all extensions within the overlay.
+      # @return [Array]
+      #   The names of all extensions within the overlay.
       #
       def extensions
         extension_paths.map { |dir| File.basename(dir) }
       end
 
       #
-      # Returns +true+ if the overlay contains the extension with the
-      # specified _name_, returns +false+ otherwise.
+      # Searches for the extension with the specified _name_ within the
+      # overlay.
+      #
+      # @param [String, Symbol] name
+      #   The name of the extension to search for.
+      #
+      # @return [Boolean]
+      #   Specifies whether the overlay contains the extension with the
+      #   specified _name_.
       #
       def has_extension?(name)
         name = File.basename(name.to_s)
@@ -144,8 +173,9 @@ module Ronin
       end
 
       #
-      # Returns the <tt>lib/</tt> directories of the extensions within
-      # the overlay.
+      # @return [Array]
+      #   The +lib+ directories of the overlay and the extensions within
+      #   the overlay.
       #
       def lib_dirs
         dirs = []
@@ -164,8 +194,8 @@ module Ronin
       end
 
       #
-      # Activates the overlay by adding the lib_dirs to the
-      # <tt>$LOAD_PATH</tt> global variable.
+      # Activates the overlay by adding all of the lib_dirs to the
+      # +$LOAD_PATH+ global variable.
       #
       def activate!
         # add the static/ directory
@@ -185,7 +215,7 @@ module Ronin
 
       #
       # Deactivates the overlay by removing the lib_dirs from the
-      # <tt>$LOAD_PATH</tt> global variable.
+      # +$LOAD_PATH+ global variable.
       #
       def deactivate!
         Static.static_dirs.reject! { |dir| dir == @static_dir }
@@ -196,21 +226,41 @@ module Ronin
       end
 
       #
-      # Updates the overlay and reloads it's metadata. If a _block_
-      # is given it will be called after the overlay has been updated.
+      # Updates the overlay and reloads it's metadata.
+      #
+      # @yield [overlay]
+      #   If a block is given, it will be passed after the overlay has
+      #   been updated.
+      #
+      # @yieldparam [Overlay] overlay
+      #   The updated overlay.
+      #
+      # @return [Overlay]
+      #   The updated overlay.
       #
       def update(&block)
-        if @repository.update(@uri)
-          initialize_metadata(&block)
+        if (@uri && @media)
+          if @repository.update(@uri)
+            initialize_metadata()
+          end
         end
 
+        block.call(self) if block
         return self
       end
 
       #
-      # Deletes the overlay then removes it from the overlay cache.
-      # If a _block_ is given, it will be passed the overlay after it
-      # has been uninstalled.
+      # Deletes the contents of the overlay.
+      #
+      # @yield [overlay]
+      #   If a block is given, it will be passed the overlay after it's
+      #   contents have been deleted.
+      #
+      # @yieldparam [Overlay] overlay
+      #   The deleted overlay.
+      #
+      # @return [Overlay]
+      #   The deleted overlay.
       #
       def uninstall(&block)
         @repository.delete
@@ -220,7 +270,8 @@ module Ronin
       end
 
       #
-      # Returns the +name+ of the Overlay.
+      # @return [String]
+      #   The name of the overlay.
       #
       def to_s
         @name.to_s
@@ -233,7 +284,7 @@ module Ronin
       # overlay +path+. If a _block_ is given, it will be passed the
       # overlay after the metadata has been loaded.
       #
-      def initialize_metadata(&block)
+      def initialize_metadata()
         metadata_path = File.join(@path,METADATA_FILE)
 
         # set to default values
@@ -244,6 +295,8 @@ module Ronin
         @source_view = @source
         @website = @source_view
 
+        @gems = []
+
         @maintainers = []
         @description = nil
 
@@ -271,6 +324,10 @@ module Ronin
             @website = website_tag.inner_text.strip
           end
 
+          overlay.search('dependencies/gem').each do |gem|
+            @gems << gem.inner_text.strip
+          end
+
           overlay.search('maintainers/maintainer').each do |maintainer|
             if (name = maintainer.at('name'))
               name = name.inner_text.strip
@@ -288,7 +345,6 @@ module Ronin
           end
         end
 
-        block.call(self) if block
         return self
       end