ronin-support 0.4.1 → 0.5.0.rc1

data/lib/ronin/extensions/regexp.rb

@@ -19,9 +19,19 @@
 
 require 'ronin/extensions/resolv'
 
+#
+# @since 0.3.0
+#
 class Regexp
 
+  # Regular expression for finding words
+  #
+  # @since 0.5.0
+  WORD = /[A-Za-z][A-Za-z'\-\.]*[A-Za-z]/
+
   # Regular expression for finding a decimal octet (0 - 255)
+  #
+  # @since 0.4.0
   OCTET = /25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9]/
 
   # Regular expression for finding MAC addresses in text
@@ -64,49 +74,84 @@ class Regexp
   # Regular expression to find email addresses in text
   EMAIL_ADDR = /#{USER_NAME}\@#{HOST_NAME}/
 
+  # Regular expression to find phone numbers in text
+  #
+  # @since 0.5.0
+  PHONE_NUMBER = /(?:\d[ \-\.]?)?(?:\d{3}[ \-\.]?)?\d{3}[ \-\.]?\d{4}(?:x\d+)?/
+
   # Regular expression to find deliminators in text
+  #
+  # @since 0.4.0
   DELIM = /[;&\n\r]/
 
   # Regular expression to find identifier in text
+  #
+  # @since 0.4.0
   IDENTIFIER = /[_]*[a-zA-Z]+[a-zA-Z0-9_-]*/
 
   # Regular expression to find File extensions in text
+  #
+  # @since 0.4.0
   FILE_EXT = /(?:\.[A-Za-z0-9]+)+/
 
   # Regular expression to find File names in text
+  #
+  # @since 0.4.0
   FILE_NAME = /(?:[^\/\\\. ]|\\[\/\\ ])+/
 
   # Regular expression to find Files in text
+  #
+  # @since 0.4.0
   FILE = /#{FILE_NAME}(?:#{FILE_EXT})?/
 
   # Regular expression to find Directory names in text
+  #
+  # @since 0.4.0
   DIRECTORY = /(?:\.\.|\.|#{FILE})/
 
   # Regular expression to find local UNIX Paths in text
+  #
+  # @since 0.4.0
   RELATIVE_UNIX_PATH = /(?:#{DIRECTORY}\/)+#{DIRECTORY}\/?/
 
   # Regular expression to find absolute UNIX Paths in text
+  #
+  # @since 0.4.0
   ABSOLUTE_UNIX_PATH = /(?:\/#{FILE})+\/?/
 
   # Regular expression to find UNIX Paths in text
+  #
+  # @since 0.4.0
   UNIX_PATH = /#{ABSOLUTE_UNIX_PATH}|#{RELATIVE_UNIX_PATH}/
 
   # Regular expression to find local Windows Paths in text
+  #
+  # @since 0.4.0
   RELATIVE_WINDOWS_PATH = /(?:#{DIRECTORY}\\)+#{DIRECTORY}\\?/
 
   # Regular expression to find absolute Windows Paths in text
+  #
+  # @since 0.4.0
   ABSOLUTE_WINDOWS_PATH = /[A-Za-z]:(?:\\#{FILE})+\\?/
 
   # Regular expression to find Windows Paths in text
+  #
+  # @since 0.4.0
   WINDOWS_PATH = /#{ABSOLUTE_WINDOWS_PATH}|#{RELATIVE_WINDOWS_PATH}/
 
   # Regular expression to find local Paths in text
+  #
+  # @since 0.4.0
   RELATIVE_PATH = /#{RELATIVE_UNIX_PATH}|#{RELATIVE_WINDOWS_PATH}/
 
   # Regular expression to find absolute Paths in text
+  #
+  # @since 0.4.0
   ABSOLUTE_PATH = /#{ABSOLUTE_UNIX_PATH}|#{ABSOLUTE_WINDOWS_PATH}/
 
   # Regular expression to find Paths in text
+  #
+  # @since 0.4.0
   PATH = /#{UNIX_PATH}|#{WINDOWS_PATH}/
 
 end

data/lib/ronin/extensions/string.rb

@@ -137,7 +137,7 @@ class String
   #
   # Finds the common suffix of the string and the specified other string.
   #
-  # @param [String] pther
+  # @param [String] other
   #   The other String to compare against.
   #
   # @return [String]
@@ -175,14 +175,14 @@ class String
   end
 
   #
-  # Finds the uncommon substring within the specified other string,
+  # Finds the uncommon sub-string within the specified other string,
   # which does not occur within the string.
   #
   # @param [String] other
   #   The other String to compare against.
   #
   # @return [String]
-  #   The uncommon substring between the two Strings.
+  #   The uncommon sub-string between the two Strings.
   #
   # @api public
   #

data/lib/ronin/formatting/extensions/binary.rb

@@ -18,6 +18,7 @@
 #
 
 require 'ronin/formatting/extensions/binary/integer'
+require 'ronin/formatting/extensions/binary/float'
 require 'ronin/formatting/extensions/binary/string'
 require 'ronin/formatting/extensions/binary/file'
 

data/lib/ronin/formatting/extensions/binary/array.rb

@@ -0,0 +1,63 @@
+#
+# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This file is part of Ronin Support.
+#
+# Ronin Support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ronin Support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'ronin/binary/template'
+
+class Array
+
+  alias pack_original pack
+
+  #
+  # Packs the Array into a String.
+  #
+  # @param [String, Array<Symbol>] arguments
+  #   The `Array#pack` template or a list of {Ronin::Binary::Template} types.
+  #
+  # @return [String]
+  #   The packed Array.
+  #
+  # @raise [ArgumentError]
+  #   The arguments were not a String or a list of Symbols.
+  #
+  # @example using {Ronin::Binary::Template} types:
+  #   [0x1234, "hello"].pack(:uint16_le, :string)
+  #   # => "\x34\x12hello\0"
+  #
+  # @example using a `String#unpack` template:
+  #   [0x1234, "hello"].pack('vZ*')
+  #   # => "\x34\x12hello\0"
+  #
+  # @see http://rubydoc.info/stdlib/core/Array:pack
+  #
+  # @since 0.5.0
+  #
+  # @api public
+  #
+  def pack(*arguments)
+    case arguments.first
+    when String
+      pack_original(arguments.first)
+    when Symbol
+      pack_original(Ronin::Binary::Template.compile(arguments))
+    else
+      raise(ArgumentError,"first argument to Array#pack must be a String or Symbol")
+    end
+  end
+
+end

data/lib/ronin/formatting/extensions/binary/base64.rb

@@ -0,0 +1,106 @@
+#
+# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This file is part of Ronin Support.
+#
+# Ronin Support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ronin Support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'base64'
+
+#
+# Adds Ruby 1.9 specific methods when running on Ruby 1.8.7.
+#
+module Base64
+  if RUBY_VERSION < '1.9.'
+    module_function
+
+    #
+    # Strictly encodes a base64 String.
+    #
+    # @param [String] bin
+    #   The String to encode.
+    #
+    # @return [String]
+    #   The strictly encoded base64 String.
+    #
+    # @note
+    #   This method complies with RFC 4648.
+    #   No line feeds are added.
+    #
+    def strict_encode64(bin)
+      encode64(bin).tr("\n",'')
+    end
+
+    #
+    # Decodes a strictly base64 encoded String.
+    #
+    # @param [String] str
+    #   The strictly encoded base64 String.
+    #
+    # @return [String]
+    #   The decoded String.
+    #
+    # @raise [ArgumentError]
+    #   The String is incorrectly padded or contains non-alphabet characters.
+    #   Note: CR or LF are also rejected.
+    #
+    # @note
+    #   This method complies with RFC 4648.
+    #
+    def strict_decode64(str)
+      unless str.include?("\n")
+        decode64(str)
+      else
+        raise(ArgumentError,"invalid base64")
+      end
+    end
+
+    #
+    # Encodes a URL-safe base64 String.
+    #
+    # @param [String] bin
+    #   The String to encode.
+    #
+    # @return [String]
+    #   The URL-safe encoded base64 String.
+    #
+    # @note
+    #   This method complies with ``Base 64 Encoding with URL and filename Safe
+    #   Alphabet'' in RFC 4648.
+    #   The alphabet uses '-' instead of '+' and '_' instead of '/'.
+    #
+    def urlsafe_encode64(bin)
+      strict_encode64(bin).tr("+/", "-_")
+    end
+
+    #
+    # Decodes a URL-safe base64 encoded String.
+    #
+    # @param [String] str
+    #   The URL-safe encoded base64 String.
+    #
+    # @return [String]
+    #   The decoded String.
+    #
+    # @note
+    #   This method complies with ``Base 64 Encoding with URL and filename Safe
+    #   Alphabet'' in RFC 4648.
+    #   The alphabet uses '-' instead of '+' and '_' instead of '/'.
+    #
+    def urlsafe_decode64(str)
+      strict_decode64(str.tr("-_", "+/"))
+    end
+  end
+end

data/lib/ronin/formatting/extensions/binary/file.rb

@@ -17,7 +17,7 @@
 # along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-require 'ronin/formatting/extensions/binary/string'
+require 'ronin/binary/hexdump/parser'
 
 class File
 
@@ -28,17 +28,50 @@ class File
   #   The path of the hexdump file.
   #
   # @param [Hash] options
-  #   Hexdump options.
+  #   Additional options.
   #
-  # @return [String]
-  #   The original binary data.
+  # @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` (Ruby 1.9 only)
+  #   * `:decimal`
+  #   * `:decimal_bytes`
+  #   * `:decimal_shorts`
+  #   * `:decimal_ints`
+  #   * `:decimal_quads` (Ruby 1.9 only)
+  #   * `:hex`
+  #   * `:hex_chars`
+  #   * `:hex_bytes`
+  #   * `:hex_shorts`
+  #   * `:hex_ints`
+  #   * `:hex_quads`
+  #   * `:named_chars` (Ruby 1.9 only)
+  #   * `:floats`
+  #   * `:doubles`
   #
-  # @see String#unhexdump.
+  # @option options [:little, :big, :network] :endian (:little)
+  #   The endianness of the words.
+  #
+  # @option options [Integer] :segment (16)
+  #   The length in bytes of each segment in the hexdump.
+  #
+  # @return [String]
+  #   The raw-data from the hexdump.
   #
   # @api public
   #
   def File.unhexdump(path,options={})
-    File.read(path).unhexdump(options)
+    Ronin::Binary::Hexdump::Parser.new(options).parse(File.new(path))
   end
 
 end

data/lib/ronin/formatting/extensions/binary/float.rb

@@ -0,0 +1,65 @@
+#
+# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This file is part of Ronin Support.
+#
+# Ronin Support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ronin Support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'ronin/binary/template'
+
+class Float
+
+  #
+  # Packs the Float into a String.
+  #
+  # @param [String, Symbol] argument
+  #   The `Array#pack` String code or {Ronin::Binary::Template} type.
+  #
+  # @return [String]
+  #   The packed float.
+  #
+  # @raise [ArgumentError]
+  #   The argument was not a String code or a Symbol.
+  #
+  # @example using `Array#pack` template:
+  #   0.42.pack('F')
+  #   # => =\n\xD7>"
+  #
+  # @example using {Ronin::Binary::Template} types:
+  #   0x42.pack(:float_be)
+  #   # => ">\xD7\n="
+  #
+  # @see http://rubydoc.info/stdlib/core/Array:pack
+  #
+  # @since 0.5.0
+  #
+  # @api public
+  #
+  def pack(argument)
+    case argument
+    when String
+      [self].pack(argument)
+    when Symbol
+      unless Ronin::Binary::Template::FLOAT_TYPES.include?(argument)
+        raise(ArgumentError,"unsupported integer type: #{argument}")
+      end
+
+      [self].pack(Ronin::Binary::Template::TYPES[argument])
+    else
+      raise(ArgumentError,"argument must be a String or a Symbol")
+    end
+  end
+
+end

data/lib/ronin/formatting/extensions/binary/integer.rb

@@ -17,21 +17,23 @@
 # along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
 #
 
+require 'ronin/binary/template'
+
 class Integer
 
   #
   # Extracts a sequence of bytes which represent the Integer.
   #
-  # @param [Integer] address_length
+  # @param [Integer] length
   #   The number of bytes to decode from the Integer.
   #
   # @param [Symbol, String] endian
   #   The endianness to use while decoding the bytes of the Integer.
   #   May be one of:
   #
-  #   * `:big` / `"big"`
-  #   * `:little` / `"little"`
-  #   * `:net` / `"net"`
+  #   * `big`
+  #   * `little`
+  #   * `net`
   #
   # @return [Array]
   #   The bytes decoded from the Integer.
@@ -39,9 +41,9 @@ class Integer
   # @raise [ArgumentError]
   #   The given `endian` was not one of:
   #
-  #   * `:little` / `"little"`
-  #   * `:net` / `"net"`
-  #   * `:big` / `"big"`
+  #   * `little`
+  #   * `net`
+  #   * `big`
   #
   # @example
   #   0xff41.bytes(2)
@@ -53,7 +55,7 @@ class Integer
   #
   # @api public
   #
-  def bytes(address_length,endian=:little)
+  def bytes(length,endian=:little)
     endian = endian.to_sym
     buffer = []
 
@@ -62,17 +64,17 @@ class Integer
       mask  = 0xff
       shift = 0
 
-      address_length.times do |i|
+      length.times do |i|
         buffer << ((self & mask) >> shift)
 
         mask <<= 8
         shift += 8
       end
     when :big
-      shift = ((address_length - 1) * 8)
+      shift = ((length - 1) * 8)
       mask  = (0xff << shift)
 
-      address_length.times do |i|
+      length.times do |i|
         buffer << ((self & mask) >> shift)
 
         mask >>= 8
@@ -86,63 +88,74 @@ class Integer
   end
 
   #
-  # Packs the Integer into a String, for a specific architecture and
-  # address-length.
-  #
-  # @param [Ronin::Arch, #endian, #address_length, String] arch
-  #   The architecture to pack the Integer for.
+  # Packs the Integer into a String.
   #
-  # @param [Integer] address_length
-  #   The number of bytes to pack.
+  # @param [String, Symbol, arch] arguments
+  #   The `Array#pack` code, {Ronin::Binary::Template} type or Architecture
+  #   object with `#endian` and `#address_length` methods.
   #
   # @return [String]
   #   The packed Integer.
   #
   # @raise [ArgumentError]
-  #   The given `arch` does not respond to the `endian` or
-  #   `address_length` methods.
+  #   The arguments were not a String, Symbol or Architecture object.
+  #
+  # @example using a `Array#pack` template:
+  #   0x41.pack('V')
+  #   # => "A\0\0\0"
+  #
+  # @example using {Ronin::Binary::Template} types:
+  #   0x41.pack(:uint32_le)
   #
-  # @example using archs other than `Ronin::Arch`.
+  # @example using archs other than `Ronin::Arch` (**deprecated**):
   #   arch = OpenStruct.new(:endian => :little, :address_length => 4)
-  #   
+  #
   #   0x41.pack(arch)
   #   # => "A\0\0\0"
   #
-  # @example using a `Ronin::Arch` arch.
+  # @example using a `Ronin::Arch` arch (**deprecated**):
   #   0x41.pack(Arch.i686)
   #   # => "A\0\0\0"
   #
-  # @example specifying a custom address-length.
+  # @example specifying a custom address-length (**deprecated**):
   #   0x41.pack(Arch.ppc,2)
   #   # => "\0A"
   #
-  # @example using a `Array#pack` template String for the arch.
-  #   0x41.pack('L')
-  #   # => "A\0\0\0"
-  #
-  # @see http://ruby-doc.org/core/classes/Array.html#M002222
+  # @see http://rubydoc.info/stdlib/core/Array:pack
   #
   # @api public
   #
-  def pack(arch,address_length=nil)
-    if arch.kind_of?(String)
-      return [self].pack(arch)
-    end
+  def pack(*arguments)
+    argument = arguments.first
 
-    unless arch.respond_to?(:address_length)
-      raise(ArgumentError,"first argument to Ineger#pack must respond to address_length")
-    end
+    case argument
+    when String
+      [self].pack(argument)
+    when Symbol
+      unless Ronin::Binary::Template::INT_TYPES.include?(argument)
+        raise(ArgumentError,"unsupported integer type: #{argument}")
+      end
 
-    unless arch.respond_to?(:endian)
-      raise(ArgumentError,"first argument to Ineger#pack must respond to endian")
-    end
+      [self].pack(Ronin::Binary::Template::TYPES[argument])
+    else
+      # TODO: deprecate this calling convention
+      arch, address_length = arguments
 
-    address_length ||= arch.address_length
+      unless arch.respond_to?(:address_length)
+        raise(ArgumentError,"first argument to Ineger#pack must respond to address_length")
+      end
 
-    integer_bytes = bytes(address_length,arch.endian)
-    integer_bytes.map! { |b| b.chr }
+      unless arch.respond_to?(:endian)
+        raise(ArgumentError,"first argument to Ineger#pack must respond to endian")
+      end
+
+      address_length ||= arch.address_length
 
-    return integer_bytes.join
+      integer_bytes = bytes(address_length,arch.endian)
+      integer_bytes.map! { |b| b.chr }
+
+      return integer_bytes.join
+    end
   end
 
   #