ronin 0.2.4 → 0.3.0

data/lib/ronin/extensions/kernel.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,21 +16,26 @@
 # 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 Kernel
   #
   # Calls the given _block_ and ignores any raised exceptions.
-  # If an exception is raised, +nil+ will be returned.
   #
+  # @yield []
+  #   The block to be called.
+  #
+  # @return [nil]
+  #   An exception was ignored, or the block returned nil.
+  #
+  # @example
   #   attempt do
   #     Resolv.getaddress('might.not.exist.com')
   #   end
   #
   def attempt(&block)
     begin
-      block.call if block
+      block.call() if block
     rescue Exception
       return nil
     end
@@ -40,16 +43,26 @@ module Kernel
 
   #
   # Attempts to run the given _block_ and catches any SyntaxError,
-  # RuntimeError or StandardError exceptions. If any exceptions are
-  # caught, they will be printed out and +nil+ will be returned.
+  # RuntimeError or StandardError exceptions.
+  #
+  # @param [Boolean] verbose
+  #   Specifies wether a backtrace will be printed when an exception
+  #   has been raised.
+  #
+  # @yield []
+  #   The block to be called.
   #
+  # @return [nil]
+  #   An exception was ignored, or the block returned nil.
+  #
+  # @example
   #   catch_all do
   #     load 'suspicious.rb'
   #   end
   #
   def catch_all(verbose=true,&block)
     begin
-      block.call if block
+      block.call() if block
     rescue Exception => e
       if verbose
         STDERR.puts "#{e.class}: #{e}"
@@ -59,4 +72,26 @@ module Kernel
       return nil
     end
   end
+
+  #
+  # Safely requires the specified _sub_path_ from within the specified
+  # _directory_.
+  #
+  # @param [String] directory
+  #   The directory to require the _sub_path_ within.
+  #
+  # @param [String] sub_path
+  #   The relative path to require, specifically within the specified
+  #   _directory_.
+  #
+  # @return [Boolean]
+  #   Specifies wether or not the _sub_path_ has not been loaded before.
+  #
+  # @example
+  #   require_within 'ronin/exploits/helpers', helper_name
+  #
+  def require_within(directory,sub_path)
+    path = File.expand_path(File.join('',sub_path))
+    require File.join(directory,path)
+  end
 end

data/lib/ronin/extensions/meta.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/extensions/meta/object'

data/lib/ronin/extensions/string.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
-#++
 #
 
 class String
@@ -49,8 +46,8 @@ class String
     min_length = [length, other.length].min
 
     (min_length - 1).times do |i|
-      index = (length - i -1)
-      other_index = (other.length - i -1)
+      index = (length - i - 1)
+      other_index = (other.length - i - 1)
 
       if self[index] != other[other_index]
         return self[(index + 1)..-1]
@@ -73,8 +70,12 @@ class String
   end
 
   #
-  # Dumps the string, returning a C style encoded version of the string.
+  # Dumps the string as a C-style string.
   #
+  # @return [String]
+  #   The C-style encoded version of the String.
+  #
+  # @example
   #   "hello\x00\073\x90\r\n".dump
   #   # => "hello\0;\x90\r\n"
   #

data/lib/ronin/extensions/uri.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/extensions/uri/http'

data/lib/ronin/extensions/uri/http.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,11 +16,9 @@
 # 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/extensions/uri/query_params'
-require 'ronin/extensions/hash'
 
 require 'uri/http'
 
@@ -31,48 +27,5 @@ module URI
 
     include QueryParams
 
-    #
-    # Explodes the HTTP URI query_params into a Hash of HTTP URIs using the
-    # given _options_, where each HTTP URI has the value of one of the
-    # query_params replaced with the specified _value_. If a _block_ is
-    # given, it will be passed each query_param and the resulting HTTP URI.
-    #
-    #   url = URI('http://search.dhgate.com/search.do?dkp=1&searchkey=yarn&catalog=')
-    #   url.explode_query_params("'")
-    #   # => {"searchkey"=>#<URI::HTTP:0xfdb915e82 URL:http://search.dhgate.com/search.do?searchkey='&catalog=&dkp=1>, 
-    #   # "catalog"=>#<URI::HTTP:0xfdb915e6e URL:http://search.dhgate.com/search.do?searchkey=yarn&catalog='&dkp=1>,
-    #   # "dkp"=>#<URI::HTTP:0xfdb915e5a URL:http://search.dhgate.com/search.do?searchkey=yarn&catalog=&dkp='>}
-    #
-    def explode_query_params(value,options={},&block)
-      urls = {}
-
-      @query_params.explode(value,options).each do |param,params|
-        new_url = clone
-        new_url.query_params = params
-
-        block.call(param,new_url) if block
-        urls[param] = new_url
-      end
-
-      return urls
-    end
-
-    #
-    # Explodes the HTTP URI's query_params using the given _options_ and
-    # builds a Hash of return-values generated from calling the specified
-    # _block_ with each exploded HTTP URI.
-    #
-    def test_query_params(value,options={},&block)
-      results = {}
-
-      explode_query_params(value,options) do |param,url|
-        result = block.call(param,url)
-
-        results[param] = result if result
-      end
-
-      return results
-    end
-
   end
 end

data/lib/ronin/extensions/uri/query_params.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 'cgi'
@@ -41,7 +38,17 @@ module URI
     end
 
     #
-    # Sets the query data and updates query_params.
+    # Sets the query string and updates query_params.
+    #
+    # @param [String] query_str
+    #   The new URI query string to use.
+    #
+    # @return [String]
+    #   The new URI query string.
+    #
+    # @example
+    #   url.query = 'a=1&b=2'
+    #   # => "a=1&b=2"
     #
     def query=(query_str)
       new_query = super(query_str)
@@ -50,8 +57,21 @@ module URI
     end
 
     #
-    # Iterates over every query parameter, passing each to the given
-    # _block_.
+    # Iterates over every query parameter.
+    #
+    # @yield [name, value]
+    #   The block to pass each query parameter to.
+    #
+    # @yieldparam [String] name
+    #   The name of the query parameter.
+    #
+    # @yieldparam [String] value
+    #   The value of the query parameter.
+    #
+    # @example
+    #   url.each_query_param do |name,value|
+    #     puts "#{name} = #{value}"
+    #   end
     #
     def each_query_param(&block)
       @query_params.each(&block)
@@ -81,7 +101,6 @@ module URI
 
     private
 
-    # :nodoc
     def path_query
       str = @path
 

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

data/lib/ronin/formatting/binary.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/formatting/extensions/binary'

data/lib/ronin/formatting/digest.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/formatting/extensions/digest'

data/lib/ronin/formatting/extensions.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/formatting/extensions/binary'

data/lib/ronin/formatting/extensions/binary.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/formatting/extensions/binary/integer'

data/lib/ronin/formatting/extensions/binary/file.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/formatting/extensions/binary/string'
@@ -27,31 +24,9 @@ class File
 
   #
   # Converts the hexdump at the specified _path_ back into the original
-  # raw-data using the given _options_.
+  # raw-data.
   #
-  # _options_ may contain the following keys:
-  # <tt>:format</tt>:: The expected format of the hexdump. Must be either
-  #                    <tt>:od</tt> or <tt>:hexdump</tt>.
-  # <tt>:encoding</tt>:: Denotes the encoding used for the bytes within the
-  #                      hexdump. Must be one of the following:
-  #                      <tt>:binary</tt>:: Binary encoded bytes.
-  #                      <tt>:octal</tt>:: Octal encoding.
-  #                      <tt>:octal_bytes</tt>:: Octal encoded bytes.
-  #                      <tt>:octal_shorts</tt>:: Octal encoded shorts.
-  #                      <tt>:octal_ints</tt>:: Octal encoded integers.
-  #                      <tt>:octal_quads</tt>:: Octal encoded quads.
-  #                      <tt>:decimal</tt>:: Unsigned decimal encoding.
-  #                      <tt>:decimal_bytes</tt>:: Unsigned decimal bytes.
-  #                      <tt>:decimal_shorts</tt>:: Unsigned decimal shorts.
-  #                      <tt>:decimal_ints</tt>:: Unsigned decimal ints.
-  #                      <tt>:decimal_quads</tt>:: Unsigned decimal quads.
-  #                      <tt>:hex</tt>:: Hexadecimal encoding.
-  #                      <tt>:hex_bytes</tt>:: Hexadecimal bytes.
-  #                      <tt>:hex_shorts</tt>:: Hexadecimal shorts.
-  #                      <tt>:hex_ints</tt>:: Hexadecimal ints.
-  #                      <tt>:hex_quads</tt>:: Hexadecimal quads.
-  # <tt>:segment</tt>:: The length in bytes of each segment in the hexdump.
-  #                     Defaults to 16, if not specified.
+  # @see String#unhexdump.
   #
   def File.unhexdump(path,options={})
     File.read(path).unhexdump(options)

data/lib/ronin/formatting/extensions/binary/integer.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/arch'
@@ -26,15 +23,23 @@ require 'ronin/arch'
 class Integer
 
   #
-  # Returns an Array of bytes which represent the integer, using the
-  # specified _address_length_ and given _endian_.
+  # Extracts a sequence of bytes which represent the Integer.
   #
-  # _endian_ must be either <tt>:little</tt>, <tt>:big</tt> or
-  # <tt>:net</tt>.
+  # @param [Integer] address_length
+  #   The number of bytes to decode from the Integer.
   #
+  # @param [Symbol] endian
+  #   The endianness to use while decoding the bytes of the Integer.
+  #   May be either +:big+, +:little+ or +:net+.
+  #
+  # @return [Array]
+  #   The bytes decoded from the Integer.
+  #
+  # @example
   #   0xff41.bytes(2)
   #   # => [65, 255]
   #
+  # @example
   #   0xff41.bytes(4, :big)
   #   # => [0, 0, 255, 65]
   #
@@ -62,12 +67,22 @@ class Integer
   end
 
   #
-  # Packs the integer using the specified _arch_ and the given
-  # _address_length_. The _address_length_ will default to the address
-  # length of the _arch_.
+  # Packs the Integer into a String, for a specific architecture and
+  # address-length.
+  #
+  # @param [Ronin::Arch] arch
+  #   The architecture to pack the Integer for.
   #
+  # @param [Integer] address_length
+  #   The number of bytes to pack.
+  #
+  # @return [String]
+  #   The packed Integer.
+  #
+  # @example
   #   0x41.pack(Arch.i686) # => "A\000\000\000"
   #
+  # @example
   #   0x41.pack(Arch.ppc,2) # => "\000A"
   #
   def pack(arch,address_length=arch.address_length)
@@ -75,8 +90,10 @@ class Integer
   end
 
   #
-  # Returns the hex escaped form of the integer.
+  # @return [String]
+  #   The hex escaped version of the Integer.
   #
+  # @example
   #   42.hex_escape
   #   # => "\\x2a"
   #
@@ -84,4 +101,6 @@ class Integer
     "\\x%.2x" % self
   end
 
+  alias char chr
+
 end