ronin 0.2.4 → 0.3.0

data/lib/ronin/platform/ronin.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/platform'
@@ -31,8 +28,19 @@ module Ronin
   #
   # Provides transparent access to Platform.extension via constants.
   #
+  # @param [String] name
+  #   The constant name to map to an extension in the extension cache.
+  #
+  # @return [Extension]
+  #   The extension that maps to the constant _name_.
+  #
+  # @raise [NameError]
+  #   No extension could be found in the extension cache, that maps to the
+  #   constant _name_.
+  #
+  # @example
   #   Ronin::Shellcode
-  #   # => #<Ronin::Platform::Extension: ...>
+  #   # => #<Ronin::Platform::Extension: @name="shellcode" ...>
   #
   def Ronin.const_missing(name)
     name = name.to_s
@@ -48,23 +56,42 @@ module Ronin
   #
   # Provides transparent access to Platform.extension via methods.
   #
+  # @param [Symbol, String] name
+  #   The name of the extension to search for within the extension cache.
+  #
+  # @yield [ext]
+  #   If a block is given, it will be passed the extension which has the
+  #   matching _name_.
+  #
+  # @yieldparam [Extension] ext
+  #   The matching extension.
+  #
+  # @return [Extension]
+  #   The matching extension.
+  #
+  # @raise [NoMethodError]
+  #   No extension could be found in the extension cache with the
+  #   matching _name_.
+  #
+  # @example
   #   shellcode
   #   # => #<Ronin::Platform::Extension: ...>
   #
+  # @example
   #   shellcode do |ext|
-  #     ...
+  #     puts ext.exposed_methods
   #   end
   #
-  def method_missing(sym,*args,&block)
+  def method_missing(name,*args,&block)
     if args.length == 0
-      name = sym.id2name
+      ext_name = name.id2name
 
       # return an extension if available
-      if Platform.has_extension?(name)
-        return Platform.extension(name,&block)
+      if Platform.has_extension?(ext_name)
+        return Platform.extension(ext_name,&block)
       end
     end
 
-    return super(sym,*args,&block)
+    return super(name,*args,&block)
   end
 end

data/lib/ronin/product.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/model'
@@ -46,15 +43,19 @@ module Ronin
     validates_present :name, :version
 
     #
-    # Creates a new Product object with the given _attributes_.
+    # Creates a new Product object.
     #
-    # _attributes_ must contain the following keys:
-    # <tt>:name</tt>:: The name of the product.
-    # <tt>:vendor</tt>:: The vendor of the product. Will default to the
-    #                    product name, if not given.
+    # @param [Hash] attributes
+    #   Attributes of the product.
     #
-    # _attributes_ may contain the following keys:
-    # <tt>:version</tt>:: The version of the product.
+    # @option attributes [String] :name
+    #   The name of the product.
+    #
+    # @option attributes [String] :vendor
+    #   The vendor of the product.
+    #
+    # @option attributes [String] :version
+    #   The vesion of the product.
     #
     def initialize(attributes={})
       attributes[:vendor] ||= attributes[:name]
@@ -63,14 +64,13 @@ module Ronin
     end
 
     #
-    # Returns the String form of the product.
+    # Converts the product to a String.
+    #
+    # @return [String]
+    #   The product vendor, name and version.
     #
     def to_s
-      unless self.vendor == self.name
-        return "#{self.vendor} #{self.name} #{self.version}"
-      else
-        return "#{self.name} #{self.version}"
-      end
+      [self.vendor, self.name, self.version].compact.join(' ')
     end
 
   end

data/lib/ronin/rpc.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/rpc/exceptions'

data/lib/ronin/rpc/call.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/rpc/exceptions/not_implemented'

data/lib/ronin/rpc/client.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/rpc/exceptions/not_implemented'

data/lib/ronin/rpc/console.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/rpc/service'

data/lib/ronin/rpc/exceptions.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/rpc/exceptions/not_implemented'

data/lib/ronin/rpc/exceptions/not_implemented.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

data/lib/ronin/rpc/exceptions/response_missing.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

data/lib/ronin/rpc/response.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/rpc/exceptions/not_implemented'

data/lib/ronin/rpc/service.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

data/lib/ronin/rpc/shell.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/rpc/service'

data/lib/ronin/scanners.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/scanners/exceptions'

data/lib/ronin/scanners/exceptions.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/scanners/exceptions/unknown_category'

data/lib/ronin/scanners/exceptions/unknown_category.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

data/lib/ronin/scanners/scanner.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/scanners/exceptions/unknown_category'
@@ -32,15 +29,22 @@ module Ronin
       def self.included(base)
         base.metaclass_eval do
           #
-          # Returns the +Hash+ of the categories and the scanners defined
-          # for the class.
+          # The defined categories and their scanners for the class.
+          #
+          # @return [Hash]
+          #   The categories and the scanners defined for the them within
+          #   the class.
           #
           def scanners
             @scanners ||= {}
           end
 
           #
-          # Returns the category names of all defined scanners.
+          # Collects all categories that the class and ancestors scan
+          # for.
+          #
+          # @return [Set]
+          #   The category names of all defined scanners.
           #
           def scans_for
             names = Set[]
@@ -55,8 +59,15 @@ module Ronin
           end
 
           #
-          # Returns +true+ if there is a scanner with the specified category
-          # _name_ was defined, returns +false+ otherwise.
+          # Specifies whether or not there are scanners defined for the
+          # specified category.
+          #
+          # @param [Symbol, String] name
+          #   The name of the category to search for scanners within.
+          #
+          # @return [Boolean]
+          #   Specifies whether there is a scanner defined for the
+          #   specified category.
           #
           def scans_for?(name)
             name = name.to_sym
@@ -71,7 +82,16 @@ module Ronin
           end
 
           #
-          # Returns all scanner tests in the specified _category_.
+          # Collects all scanners in the specified category.
+          #
+          # @param [Symbol, String] name
+          #   The category name to return all scanners for.
+          #
+          # @return [Array]
+          #   All scanners in the specified category.
+          #
+          # @raise [UnknownCategory]
+          #   No category has the specified name.
           #
           def scanners_in(name)
             name = name.to_sym
@@ -94,22 +114,34 @@ module Ronin
           end
 
           #
-          # Defines a scanner with the specified category _name_ and
-          # _block_.
+          # Defines a scanner in the category for the class.
+          #
+          # @param [Symbol, String] name
+          #   The name of the category to define the scanner for.
+          #
+          # @yield [target, results, (options)]
+          #   The block that will be called when the scanner is ran.
           #
-          # When scanning against a target, a callback for saving results
-          # and the target object to be scanned will be passed to the
-          # _block_.
+          # @yieldparam [Object] target
+          #   The target object to scan.
           #
+          # @yieldparam [Proc] results
+          #   A callback for enqueuing results from the scanner in
+          #   real-time.
+          #
+          # @yieldparam [Hash] options
+          #   Additional scanner-options that can be used to configure
+          #   the scanning.
+          #
+          # @example Defining a scanner for the +:lfi+ category.
           #   scanner(:lfi) do |url,results|
-          #     ...
+          #     # ...
           #   end
           #
-          # If the scanner accepts a 3rd argument, it will be passed a
-          # +Hash+ of configuration options when the scanner is called.
-          #
+          # @example Defining a scanner for the +:sqli+ category, that
+          #          accepts additional scanner-options.
           #   scanner(:sqli) do |url,results,options|
-          #     ...
+          #     # ...
           #   end
           #
           def scanner(name,&block)
@@ -160,18 +192,36 @@ module Ronin
       end
 
       #
-      # Runs the scanners in the given _categories_ against each_target.
-      # If _categories_ is not specified, all categories will be ran
-      # against each_target. Returns a +Hash+ of results grouped by
-      # scanner category.
+      # Runs all scanners in the given categories against +each_target+.
+      # If no categories are specified, all categories will be ran
+      # against +each_target+.
+      #
+      # @param [Hash{Symbol => true,Hash}] categories
+      #   The categories to scan for, with additional per-category
+      #   scanner-options.
+      #
+      # @return [Hash]
+      #   The results grouped by scanner category.
       #
-      # If a _block_ is given, it will be passed each result and the
-      # category the result belongs to.
+      # @yield [category, result]
+      #   The block that may receive the scanner results for categories
+      #   in real-time.
       #
+      # @yieldparam [Symbol] category
+      #   The category the result belongs to.
+      #
+      # @yieldparam [Object] result
+      #   The result object enqueued by the scanner.
+      #
+      # @example Scanning a specific category.
       #   url.scan(:rfi => true)
+      #   # => {:rfi => [...]}
       #
+      # @example Scanning multiple categories, with scanner-options.
       #   url.scan(:lfi => true, :sqli => {:params => ['id', 'catid']})
+      #   # => {:lfi => [...], :sqli => [...]}
       #
+      # @example Receiving scanner results from categories in real-time.
       #   url.scan(:lfi => true, :rfi => true) do |category,result|
       #     puts "[#{category}] #{result.inspect}"
       #   end
@@ -231,6 +281,12 @@ module Ronin
       # each target object to be scanned. By default, the method will call
       # the specified _block_ once, simply passing it the +self+ object.
       #
+      # @yield [target]
+      #   The block that will be passed each target object to be scanned.
+      #
+      # @yieldparam [Object] target
+      #   The target object to be scanned.
+      #
       def each_target(&block)
         block.call(self)
       end