ronin 0.2.4 → 0.3.0

data/lib/ronin/path.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 'pathname'
@@ -27,13 +24,22 @@ module Ronin
   class Path < Pathname
 
     #
-    # Creates a new Path object with _n_ number of <tt>..</tt> directories.
+    # Creates a new path object for upward directory traversal.
     #
+    # @param [Integer, Array, Range] n
+    #   The number of directories to go up.
+    #
+    # @return [Path]
+    #   The new path object.
+    #
+    # @example Generate a relative path that goes up 7 directories.
     #   Path.up(7)
     #   # => #<Ronin::Path:../../../../../../..>
     #
+    # @example Generate multiple relative paths, going up 1 to 3 directories.
     #   Path.up(1..3)
-    #   # => [#<Ronin::Path:..>, #<Ronin::Path:../..>, #<Ronin::Path:../../..>]
+    #   # => [#<Ronin::Path:..>, #<Ronin::Path:../..>,
+    #   #<Ronin::Path:../../..>]
     #
     def self.up(n)
       if n.kind_of?(Integer)
@@ -44,9 +50,16 @@ module Ronin
     end
 
     #
-    # Joins the _names_ with the path, but does not resolve the resulting
-    # path.
+    # Joins directory names together with the path, but does not resolve
+    # the resulting path.
+    #
+    # @param [Array] names
+    #   The names to join together.
     #
+    # @return [Path]
+    #   The joined path.
+    #
+    # @example
     #   Path.up(7).join('etc/passwd')
     #   # => #<Ronin::Path:../../../../../../../etc/passwd>
     #
@@ -57,11 +70,18 @@ module Ronin
     end
 
     #
-    # Joins _name_ with the path, but does not resolve the resulting path.
+    # Joins a directory name to the path, but does not resolve the resulting
+    # path.
+    #
+    # @param [String] name
+    #   A directory name.
     #
+    # @example
     #   Path.up(7) / 'etc' / 'passwd'
     #   # => #<Ronin::Path:../../../../../../../etc/passwd>
     #
+    # @see join
+    #
     def /(name)
       join(name)
     end

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

data/lib/ronin/platform/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/platform/exceptions/extension_not_found'

data/lib/ronin/platform/exceptions/extension_not_found.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/platform/exceptions/overlay_cached.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/platform/exceptions/overlay_not_found.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/platform/extension.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'
@@ -26,7 +23,7 @@ require 'ronin/platform/extension_cache'
 require 'ronin/platform/platform'
 require 'ronin/extensions/kernel'
 require 'ronin/static/finders'
-require 'ronin/ui/diagnostics'
+require 'ronin/ui/output/helpers'
 
 require 'contextify'
 
@@ -36,8 +33,16 @@ module Ronin
 
       include Contextify
       include Static::Finders
-      include UI::Diagnostics
+      include UI::Output::Helpers
 
+      #
+      # Creates a new Ronin::Platform::Extension object using the given
+      # _block_.
+      #
+      #   ronin_extension do
+      #     ...
+      #   end
+      #
       contextify :ronin_extension
 
       # Extension file name
@@ -56,14 +61,21 @@ module Ronin
       attr_reader :paths
 
       #
-      # Creates a new Extension with the specified _name_. If a
-      # _block_ is given, it will be passed the newly created
-      # Extension.
+      # Creates a new Extension object.
       #
+      # @param [String] name
+      #   The name to give the newly created Extension object.
+      #
+      # @yield []
+      #   The block that will be instance-evaled inside the newly created
+      #   Extension object.
+      #
+      # @example
       #   Extension.new('exploits')
       #
+      # @example
       #   Extension.new('awesome') do |ext|
-      #     ...
+      #     # ...
       #   end
       #
       def initialize(name,&block)
@@ -80,38 +92,20 @@ module Ronin
       end
 
       #
-      # Loads all extensions with the specified _name_ into a newly created
-      # Extension object. If a _block_ is given, it will be passed the
-      # newly created Extension object.
+      # Includes all extensions with the matching _name_ into the extension.
       #
-      #   Extension.load('shellcode') do |ext|
-      #     puts ext.search('moon_lander')
-      #   end
+      # @param [String] name
+      #   The name of the extensions to include.
       #
-      def Extension.load(name,&block)
-        ext = Extension.new(name)
-        ext.include(name)
-
-        block.call(ext) if block
-        return ext
-      end
-
-      #
-      # Loads all extensions with the specified _name_ into a newly created
-      # Extension object and then runs it with the specified _block_.
+      # @yield [ext]
+      #   If a block is given, it will be passed the extension, after the
+      #   other extensions have been included into it.
       #
-      #   Extension.run('exploits') do |ext|
-      #     puts ext.search(:product => 'Apache')
-      #   end
-      #
-      def Extension.run(name,&block)
-        Extension.load(name) { |ext| ext.run(&block) }
-      end
-
+      # @yieldparam [Extension] ext
+      #   The extension.
       #
-      # Includes all extensions of the specified _name_ into the extension.
-      # If a _block_ is given, it will be passed the newly created
-      # extension after the extensions of _name_ have been included.
+      # @return [Extension]
+      #   The extension.
       #
       def include(name,&block)
         Platform.overlays.extension_paths(name).each do |path|
@@ -124,8 +118,21 @@ module Ronin
 
       #
       # Includes the extension at the specified _path_ into the extension.
-      # If a _block_ is given, it will be passed the newly created
-      # extension.
+      #
+      # @param [String] path
+      #   The path of the extension directory to include from.
+      #
+      # @yield [ext]
+      #   If a block is given, it will be passed the extension.
+      #
+      # @yieldparam [Extension] ext
+      #   The extension.
+      #
+      # @return [Extension]
+      #   The extension.
+      #
+      # @raise [ExtensionNotFound]
+      #   The specified _path_ was not a valid directory.
       #
       def include_path(path,&block)
         path = File.expand_path(path)
@@ -153,16 +160,24 @@ module Ronin
       end
 
       #
-      # Returns the list of methods exposed by the extension.
+      # @return [Array]
+      #   The list of public methods exposed by the extension.
       #
       def exposed_methods
         methods(false).map { |name| name.to_sym }
       end
 
       #
-      # Returns +true+ if the extension context has a public instance method
-      # of the matching _name_, returns +false+ otherwise.
+      # Searches for a public method with the specified _name_.
       #
+      # @param [Symbol, String] name
+      #   The method name to search for.
+      #
+      # @return [Boolean]
+      #   Specifies whether there is a public method with the specified
+      #   _name_.
+      #
+      # @example
       #   ext.has_method?(:console)
       #   # => true
       #
@@ -171,12 +186,23 @@ module Ronin
       end
 
       #
-      # Calls the setup blocks of the extension. If a _block_ is given, it 
-      # will be passed the extension after it has been setup.
+      # Calls the setup blocks of the extension.
+      #
+      # @yield [ext]
+      #   If a block is given, it will be passed the extension, once it
+      #   has been setup.
+      #
+      # @yieldparam [Extension] ext
+      #   The extension.
       #
+      # @return [Extension]
+      #   The extension.
+      #
+      # @example
       #   ext.setup!
       #   # => #<Ronin::Platform::Extension: ...>
       #
+      # @example
       #   ext.setup! do |ext|
       #     puts "Extension #{ext} has been setup..."
       #   end
@@ -196,20 +222,31 @@ module Ronin
       end
 
       #
-      # Returns +true+ if the extension has been setup, returns +false+
-      # otherwise.
+      # @return [Boolean]
+      #   Specifies whether the extension has been setup.
       #
       def setup?
         @setup == true
       end
 
       #
-      # Run the teardown blocks of the extension. If a _block_ is given,
-      # it will be passed the extension before it has been tore down.
+      # Run the teardown blocks of the extension.
+      #
+      # @yield [ext]
+      #   If a block is given, it will be passed the extension, before it
+      #   has been toredown.
+      #
+      # @yieldparam [Extension] ext
+      #   The extension.
+      #
+      # @return [Extension]
+      #   The extension.
       #
+      # @example
       #   ext.teardown!
       #   # => #<Ronin::Platform::Extension: ...>
       #
+      # @example
       #   ext.teardown! do |ext|
       #     puts "Extension #{ext} is being tore down..."
       #   end
@@ -230,8 +267,8 @@ module Ronin
       end
 
       #
-      # Returns +true+ if the extension has been toredown, returns +false+
-      # otherwise.
+      # @return [Boolean]
+      #   Specifies whether the extension has been toredown.
       #
       def toredown?
         @toredown == true
@@ -241,6 +278,18 @@ module Ronin
       # Sets up the extension, passes the extension to the specified
       # _block_ and then tears down the extension.
       #
+      # @yield [(ext)]
+      #   If a block is given, it will be called after the extension has
+      #   been setup. When the block has finished, the extension will be
+      #   toredown.
+      #
+      # @yieldparam [Extension] ext
+      #   The extension.
+      #
+      # @return [Extension]
+      #   The extension.
+      #
+      # @example
       #   ext.run do |ext|
       #     ext.console(ARGV)
       #   end
@@ -260,6 +309,17 @@ module Ronin
         return self
       end
 
+      #
+      # The temporary directory for the extension.
+      #
+      # @return [String]
+      #   The path to the extensions temporary directory within
+      #   {Config::TMP_DIR}.
+      #
+      def tmp_dir
+        @tmp_dir ||= Config.tmp_dir(@name)
+      end
+
       def static_paths(path,&block)
         @paths.each do |dir|
           static_dir = File.join(dir,STATIC_DIR)
@@ -272,7 +332,8 @@ module Ronin
       end
 
       #
-      # Returns the name of the extension context in string form.
+      # @return [String]
+      #   The name of the extension.
       #
       def to_s
         @name.to_s
@@ -280,10 +341,87 @@ module Ronin
 
       protected
 
+      #
+      # Defines reader methods for the listed instance variables.
+      #
+      # @param [Array<Symbol, String>] names
+      #   The names of instance variables to add reader methods for.
+      #
+      # @example
+      #   attr_reader :var1, :var2
+      #
+      #   self.var1
+      #   # => nil
+      #
+      def attr_reader(*names)
+        names.each do |name|
+          name = name.to_sym
+          ivar_name = "@#{name}"
+
+          instance_eval %{
+            def #{name}
+              instance_variable_get(#{ivar_name.dump})
+            end
+          }
+        end
+      end
+
+      #
+      # Defines writer methods for the listed instance variables.
+      #
+      # @param [Array<Symbol, String>] names
+      #   The names of the instance variables to define writer methods for.
+      #
+      # @example
+      #   attr_writer :var1, :var2
+      #   
+      #   self.var1 = :foo
+      #   self.var2 = :bar
+      #
+      def attr_writer(*names)
+        names.each do |name|
+          name = name.to_sym
+          ivar_name = "@#{name}"
+
+          instance_eval %{
+            def #{name}=(value)
+              instance_variable_set(#{ivar_name.dump},value)
+            end
+          }
+        end
+      end
+
+      #
+      # Defines reader and writer methods for the listed instance variables.
+      #
+      # @param [Array<Symbol, String>] names
+      #   The names of the instance variables to define reader and writer
+      #   methods for.
+      #
+      # @example
+      #   attr_accessor :var1, :var2
+      #
+      #   self.var1 = :foo
+      #   self.var1
+      #   # => :foo
+      #
+      # @see attr_reader
+      # @see attr_writer
+      #
+      def attr_accessor(*names)
+        attr_reader(*names)
+        attr_writer(*names)
+      end
+
       #
       # Adds the specified _block_ to the list of blocks to run in order
       # to properly setup the extension.
       #
+      # @example
+      #   setup do
+      #     @var = 'hello'
+      #   end
+      #
       def setup(&block)
         @setup_blocks << block if block
         return self
@@ -293,6 +431,11 @@ module Ronin
       # Adds the specified _block_ to the list of blocks to run in order
       # to properly tear-down the extension.
       #
+      # @example
+      #   teardown do
+      #     @file.close
+      #   end
+      #
       def teardown(&block)
         @teardown_blocks << block if block
         return self