ronin 0.2.4 → 0.3.0

data/lib/ronin/formatting/extensions/binary/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
-#++
 #
 
 require 'ronin/formatting/extensions/binary/integer'
@@ -30,12 +27,22 @@ require 'base64'
 class String
 
   #
-  # 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 an Integer from a String, which was originally packed for
+  # a specific architecture and address-length.
   #
+  # @param [Ronin::Arch] arch
+  #   The architecture that the Integer was originally packed with.
+  #
+  # @param [Integer] address_length
+  #   The number of bytes to depack.
+  #
+  # @return [Integer]
+  #   The depacked Integer.
+  #
+  # @example
   #   0x41.pack(Arch('i686')) # => "A\000\000\000"
   #
+  # @example
   #   0x41.pack(Arch('ppc'),2) # => "\000A"
   #
   def depack(arch,address_length=arch.address_length)
@@ -61,8 +68,10 @@ class String
   end
 
   #
-  # Returns the hex escaped form of the string.
+  # @return [String]
+  #   The hex escaped version of the String.
   #
+  # @example
   #   "hello".hex_escape
   #   # => "\\x68\\x65\\x6c\\x6c\\x6f"
   #
@@ -71,8 +80,10 @@ class String
   end
 
   #
-  # Returns an unescaped version of the hex escaped string.
+  # @return [String]
+  #   The unescaped version of the hex escaped String.
   #
+  # @example
   #   "\\x68\\x65\\x6c\\x6c\\x6f".hex_unescape
   #   # => "hello"
   #
@@ -126,7 +137,17 @@ class String
   end
 
   #
-  # XOR encodes the string using the specified _key_.
+  # XOR encodes the String.
+  #
+  # @param [Integer] key
+  #   The byte to XOR against each byte in the String.
+  #
+  # @return [String]
+  #   The XOR encoded String.
+  #
+  # @example
+  #   "hello".xor(0x41)
+  #   # => ")$--."
   #
   def xor(key)
     encoded = ''
@@ -136,14 +157,20 @@ class String
   end
 
   #
-  # Returns the base64 encoded form of the string.
+  # Base64 encodes a string.
+  #
+  # @return [String]
+  #   The base64 encoded form of the string.
   #
   def base64_encode
     Base64.encode64(self)
   end
 
   #
-  # Returns the base64 decoded form of the string.
+  # Base64 decodes a string.
+  #
+  # @return [String]
+  #   The base64 decoded form of the string.
   #
   def base64_decode
     Base64.decode64(self)
@@ -151,31 +178,27 @@ class String
 
   #
   # Converts a multitude of hexdump formats back into the original
-  # raw-data using the given _options_.
+  # raw-data.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Symbol] :format
+  #   The expected format of the hexdump. Must be either +:od+ or
+  #   +:hexdump+.
+  #
+  # @option options [Symbol] :encoding
+  #   Denotes the encoding used for the bytes within the hexdump.
+  #   Must be one of the following: +:binary+, +:octal+, +:octal_bytes+
+  #   +:octal_shorts+, +:octal_ints+, :octal_quads+, +:decimal+,
+  #   +:decimal_bytes+, +:decimal_shorts+, +:decimal_ints+,
+  #   +:decimal_quads+, +:hex+ +:hex_bytes+, +:hex_shorts+, +:hex_ints+ or
+  #   +:hex_quads+.
+  #
+  # @option options [Integer] :segment (16)
+  #   The length in bytes of each segment in the hexdump.
   #
-  # _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.
+  # @return [String] The raw-data from the hexdump.
   #
   def unhexdump(options={})
     case (format = options[:format])

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

data/lib/ronin/formatting/extensions/digest/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
-#++
 #
 
 require 'digest/md5'
@@ -28,35 +25,60 @@ require 'digest/sha2'
 class String
 
   #
-  # Returns the MD5 checksum of the String.
+  # @return [String]
+  #   The MD5 checksum of the String.
+  #
+  # @example
+  #   "hello".md5
+  #   # => "5d41402abc4b2a76b9719d911017c592"
   #
   def md5
     Digest::MD5.hexdigest(self)
   end
 
   #
-  # Returns the SHA1 checksum of the String.
+  # @return [String]
+  #   The SHA1 checksum of the String.
+  #
+  # @example
+  #   "hello".sha1
+  #   # => "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
   #
   def sha1
     Digest::SHA1.hexdigest(self)
   end
 
   #
-  # Returns the SHA2 checksum of the String.
+  # @return [String]
+  #   The SHA2 checksum of the String.
+  #
+  # @example
+  #   "hello".sha2
+  #   # => "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
   #
   def sha2
     Digest::SHA2.hexdigest(self)
   end
 
   #
-  # Returns the SHA256 checksum of the String.
+  # @return [String]
+  #   The SHA256 checksum of the String.
+  #
+  # @example
+  #   "hello".sha256
+  #   # => "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
   #
   def sha256
     Digest::SHA256.hexdigest(self)
   end
 
   #
-  # Returns the SHA512 checksum of the String.
+  # @return [String]
+  #   The SHA512 checksum of the String.
+  #
+  # @example
+  #   "hello".sha512
+  #   # => "9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"
   #
   def sha512
     Digest::SHA512.hexdigest(self)

data/lib/ronin/formatting/extensions/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,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/http/string'

data/lib/ronin/formatting/extensions/http/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
-#++
 #
 
 require 'ronin/formatting/extensions/text'
@@ -29,8 +26,10 @@ require 'cgi'
 class String
 
   #
-  # Returns the URI encoded form of the string.
+  # @return [String]
+  #   The URI encoded form of the String.
   #
+  # @example
   #   "art is graffiti".uri_encode
   #   # => "art%20is%20graffiti"
   #
@@ -39,8 +38,10 @@ class String
   end
 
   #
-  # Returns the decoded URI form of the string.
+  # @return [String]
+  #   The decoded URI form of the String.
   #
+  # @example
   #   "genre%3f".uri_decode
   #   # => "genre?"
   #
@@ -49,8 +50,10 @@ class String
   end
 
   #
-  # Returns the URI escaped form of the string.
+  # @return [String]
+  #   The URI escaped form of the String.
   #
+  # @example
   #   "x > y".uri_escape
   #   # => "x+%3E+y"
   #
@@ -59,8 +62,10 @@ class String
   end
 
   #
-  # Returns the unescaped URI form of the string.
+  # @return [String]
+  #   The unescaped URI form of the String.
   #
+  # @example
   #   "sweet+%26+sour".uri_unescape
   #   # => "sweet & sour"
   #
@@ -69,8 +74,10 @@ class String
   end
 
   #
-  # Returns the HTTP hexidecimal encoded form of the string.
+  # @return [String]
+  #   The HTTP hexidecimal encoded form of the String.
   #
+  # @example
   #   "hello".format_http
   #   # => "hello"
   #

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

data/lib/ronin/formatting/extensions/text/array.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,17 +16,22 @@
 # 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 Array
 
   #
-  # Returns the bytes contained in the array.
+  # Decodes the bytes contained within the Array. The Array may contain
+  # both Integer and String objects.
   #
+  # @return [Array]
+  #   The bytes contained in the Array.
+  #
+  # @example
   #   [0x41, 0x41, 0x20].bytes
   #   # => [0x41, 0x41, 0x20]
   #
+  # @example
   #   ['A', 'BB', 0x90].bytes
   #   # => [0x41, 0x42, 0x42, 0x90]
   #
@@ -45,8 +48,13 @@ class Array
   end
 
   #
-  # Returns the Array of characters generated from the array.
+  # Decodes the characters contained within the Array. The Array may contain
+  # either Integer or String objects.
+  #
+  # @return [Array]
+  #   The characters generated from the array.
   #
+  # @example
   #   [0x41, 0x41, 0x20].chars
   #   # => ["A", "A", " "]
   #
@@ -55,8 +63,10 @@ class Array
   end
 
   #
-  # Returns the String created from the characters within the array.
+  # @return [String]
+  #   The String created from the characters within the Array.
   #
+  # @example
   #   [0x41, 0x41, 0x20].char_string
   #   # => "AA "
   #

data/lib/ronin/formatting/extensions/text/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
-#++
 #
 
 require 'chars'
@@ -26,23 +23,38 @@ require 'chars'
 class String
 
   #
-  # Creates a new String by passing each byte to the specified _block_
-  # using the given _options_.
+  # Creates a new String by formatting each byte.
   #
-  # _options_ may include the following keys:
-  # <tt>:included</tt>:: The set of characters that will be formated,
-  #                      defaults to <tt>Chars.all</tt>.
-  # <tt>:excluded</tt>:: The characters not to format.
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Array, Range] :included (0x00..0xff)
+  #   The bytes to format.
+  #
+  # @option options [Array, Range] :excluded
+  #   The bytes not to format.
+  #
+  # @yield [byte]
+  #   The block which will return the formatted version of each byte
+  #   within the String.
+  #
+  # @yieldparam [Integer] byte
+  #   The byte to format.
+  #
+  # @return [String]
+  #   The formatted version of the String.
   #
   def format_bytes(options={},&block)
-    included = (options[:included] || Chars.all)
+    included = (options[:included] || (0x00..0xff))
     excluded = (options[:excluded] || [])
 
-    targeted = included - excluded
     formatted = ''
 
     self.each_byte do |b|
-      if targeted.include_byte?(b)
+      c = b.chr
+
+      if ((included.include?(b) || included.include?(c)) \
+          && !(excluded.include?(b) || excluded.include?(c)))
         formatted << block.call(b)
       else
         formatted << b
@@ -53,13 +65,26 @@ class String
   end
 
   #
-  # Creates a new String by passing each character to the specified _block_
-  # using the given _options_.
+  # Creates a new String by formatting each character.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Array, Range] :included (0x00..0xff)
+  #   The bytes to format.
+  #
+  # @option options [Array, Range] :excluded
+  #   The bytes not to format.
   #
-  # _options_ may include the following keys:
-  # <tt>:included</tt>:: The set of characters that will be formated,
-  #                      defaults to <tt>Chars.all</tt>.
-  # <tt>:excluded</tt>:: The characters not to format.
+  # @yield [char]
+  #   The block which will return the formatted version of each character
+  #   within the String.
+  #
+  # @yieldparam [String] char
+  #   The character to format.
+  #
+  # @return [String]
+  #   The formatted version of the String.
   #
   def format_chars(options={},&block)
     format_bytes(options) do |b|
@@ -68,13 +93,22 @@ class String
   end
 
   #
-  # Creates a new String by randomizing the case of each character using
-  # the given _options_.
+  # Creates a new String by randomizing the case of each character in the
+  # String.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Array, Range] :included (0x00..0xff)
+  #   The bytes to format.
   #
-  # _options_ may include the following keys:
-  # <tt>:probability</tt>:: The probability that a character will have it's
-  #                         case changed; defaults to 0.5.
+  # @option options [Array, Range] :excluded
+  #   The bytes not to format.
   #
+  # @option options [Float] :probability (0.5)
+  #   The probability that a character will have it's case changed.
+  #
+  # @example
   #   "get out your checkbook".random_case
   #   # => "gEt Out YOur CHEckbook"
   #
@@ -91,10 +125,19 @@ class String
   end
 
   #
-  # Pads the string using the specified _padding_ out to the given
-  # _max_length_. _max_length_ will default to the strings own length,
-  # if not given.
+  # Creates a new String by padding the String with repeating text,
+  # out to a specified length.
+  #
+  # @param [String] padding
+  #   The text to pad the new String with.
+  #
+  # @param [String] max_length
+  #   The maximum length to pad the new String out to.
+  #
+  # @return [String]
+  #   The padded version of the String.
   #
+  # @example
   #   "hello".pad('A',50)
   #   # => "helloAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
   #