ronin-exploits 0.2.1 → 0.3.0

data/lib/ronin/exploits/exploit_author.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,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/author'
@@ -27,7 +25,8 @@ module Ronin
   module Exploits
     class ExploitAuthor < Author
 
-      belongs_to :exploit
+      # The exploit the author wrote
+      belongs_to :exploit, :nullable => true
 
     end
   end

data/lib/ronin/exploits/ftp.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,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/exploits/remote_tcp'
@@ -30,6 +28,13 @@ module Ronin
       # Default port to connect to
       DEFAULT_PORT = 21
 
+      #
+      # Creates a new Ronin::Exploits::FTP object using the given _block_.
+      #
+      #   ronin_ftp_exploit do
+      #     ...
+      #   end
+      #
       contextify :ronin_ftp_exploit
 
       # Default port to connect to

data/lib/ronin/exploits/helpers.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,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/exploits/helpers/file_based'

data/lib/ronin/exploits/helpers/binary.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,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/exploits/exceptions/target_data_missing'
@@ -29,9 +27,17 @@ module Ronin
     module Helpers
       module Binary
         #
-        # Packs the specified _integer_ using the current targeted arch
-        # and the given _address_length_. The _address_length_ will
-        # default to the address length of the currently targeted arch.
+        # Packs an integer using the current targeted architecture
+        # and the address-length.
+        #
+        # @param [Integer] integer
+        #   The integer to pack.
+        #
+        # @param [Integer] address_length
+        #   The address-length to pack the integer into.
+        #
+        # @return [String]
+        #   The packed integer.
         #
         def pack(integer,address_length=nil)
           verify_arch!

data/lib/ronin/exploits/helpers/buffer_overflow.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,59 +17,72 @@
 # 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/exploits/exceptions/payload_size'
 require 'ronin/exploits/targets/buffer_overflow'
 require 'ronin/exploits/helpers/binary'
 require 'ronin/exploits/helpers/padding'
+require 'ronin/payloads/shellcode'
 
 module Ronin
   module Exploits
     module Helpers
       module BufferOverflow
-        def self.included(base)
-          base.module_eval do
-            include Ronin::Exploits::Helpers::Binary
-            include Ronin::Exploits::Helpers::Padding
-
-            has n, :targets,
-                   :class_name => 'Ronin::Exploits::Targets::BufferOverflow'
-
-            # The buffer to use for the buffer overflow
-            attr_reader :buffer
-          end
-        end
-
         def self.extended(obj)
           obj.instance_eval do
             extend Ronin::Exploits::Helpers::Binary
             extend Ronin::Exploits::Helpers::Padding
-
-            #
-            # Returns the buffer to use for the buffer overflow.
-            #
-            def buffer
-              @buffer
-            end
           end
         end
 
         #
-        # Adds a new Targets::BufferOverflow with the given _attributes_
-        # and _block_.
+        # @return [String]
+        #   The buffer to use for the buffer overflow.
+        #
+        def buffer
+          @buffer ||= ''
+        end
+
+        #
+        # Adds a new target to the exploit.
+        #
+        # @param [Hash] attributes
+        #   Additional attributes to create the new target with.
+        #
+        # @yield [target]
+        #   If a block is given, it will be passed the newly created target.
+        #
+        # @yieldparam [Targets::BufferOverflow] target
+        #   The new target.
         #
         def targeting(attributes={},&block)
           self.targets << Targets::BufferOverflow.new(attributes,&block)
         end
 
+        #
+        # @return [Payloads::Shellcode]
+        #   The model which will be searched for acceptable payloads.
+        #
+        # @since 0.3.0
+        #
+        def use_payload_class
+          Payloads::Shellcode
+        end
+
         protected
        
         #
         # Builds the buffer with the current target and payload to be
         # used in the buffer overflow exploit.
         #
+        # @return [String]
+        #   The built buffer.
+        #
+        # @raise [PayloadSize]
+        #   The encoded payload is too large to fit within the targeted
+        #   buffer length.
+        #
         def build_buffer
           verify_target!
 
@@ -91,7 +103,8 @@ module Ronin
         end
 
         #
-        # Default builder method which simply calls build_buffer.
+        # Default builder method which simply calls build_buffer and sets
+        # the +@buffer+ instance variable..
         #
         def build
           @buffer = build_buffer

data/lib/ronin/exploits/helpers/file_based.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,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/config'
@@ -30,32 +28,19 @@ module Ronin
   module Exploits
     module Helpers
       module FileBased
-        def self.included(base)
-          base.module_eval do
-            parameter :output_dir,
-                      :default => Config::TMP_DIR,
-                      :description => 'Directory to save built file in'
-
-            parameter :file_name,
-                      :default => 'exploit',
-                      :description => 'Name of the file'
-
-            parameter :clean_file,
-                      :default => true,
-                      :description => 'Delete the file on exit'
-          end
-        end
-
         def self.extended(obj)
           obj.instance_eval do
+            # The output directory for file creation
             parameter :output_dir,
                       :default => Config::TMP_DIR,
                       :description => 'Directory to save built file in'
 
-            parameter :file_name,
+            # The name of the output file
+            parameter :output_file_name,
                       :default => 'exploit',
                       :description => 'Name of the file'
 
+            # Whether or not to delete the output file at exit
             parameter :clean_file,
                       :default => true,
                       :description => 'Delete the file on exit'
@@ -63,15 +48,20 @@ module Ronin
         end
 
         #
-        # List of files to delete later.
+        # List of files to delete upon exit.
+        #
+        # @return [Set]
+        #   The list of files to delete upon exit.
         #
         def FileBased.clean_files
           @@ronin_exploits_file_based_clean_files ||= Set[]
         end
 
         #
-        # Will forcibly delete the files listed in FileBased.clean_files,
-        # as well as empty the contents of FileBased.clean_files.
+        # Will forcibly delete the files listed in FileBased.clean_files.
+        #
+        # @return [true]
+        #   The all files were successfully deleted.
         #
         def FileBased.clean!
           FileBased.clean_files.each do |path|
@@ -85,24 +75,33 @@ module Ronin
         at_exit(&FileBased.method(:clean!))
 
         #
-        # Returns the absolute path of the file to be built.
+        # @return [String]
+        #   The absolute path of the file to be built.
         #
-        def file_path
-          File.expand_path(::File.join(@output_dir,@file_name))
+        def output_file_path
+          sanitized_name = File.expand_path(File.join('',@output_file_name))
+
+          return File.expand_path(File.join(@output_dir,sanitized_name))
         end
 
         protected
 
         #
-        # Opens the file to be built, passing a new File object to the given
-        # _block_.
+        # Opens the file to be built.
+        #
+        # @yield [file]
+        #   If a block is given, it will be passed the newly opened file.
+        #
+        # @yieldparam [File] file
+        #   The newly opened file.
         #
-        #   file_open do |file|
+        # @example
+        #   build_file do |file|
         #     file << 'some data'
         #   end
         #
-        def file_open(&block)
-          path = self.file_path
+        def build_file(&block)
+          path = self.output_file_path
 
           FileBased.clean_files << path if @clean_file
           return File.open(path,'w',&block)

data/lib/ronin/exploits/helpers/format_string.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,55 +17,65 @@
 # 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/exploits/targets/format_string'
 require 'ronin/exploits/helpers/binary'
+require 'ronin/payloads/shellcode'
 
 module Ronin
   module Exploits
     module Helpers
       module FormatString
-        def self.included(base)
-          base.module_eval do
-            include Ronin::Exploits::Helpers::Binary
-
-            has n, :targets,
-                   :class_name => 'Ronin::Exploits::Targets::FormatString'
-
-            # The built format string
-            attr_reader :format_string
-          end
-        end
-
         def self.extended(obj)
           obj.instance_eval do
             extend Ronin::Exploits::Helpers::Binary
-
-            #
-            # Returns the format string of the exploit.
-            #
-            def format_string
-              @format_string
-            end
           end
         end
 
         #
-        # Adds a new Targets::FormatString with the given _attributes_
-        # and _block_.
+        # @return [String]
+        #   The format string of the exploit.
+        #
+        def format_string
+          @format_string ||= ''
+        end
+
+        #
+        # Adds a new target to the exploit.
+        #
+        # @param [Hash] attributes
+        #   Additioanl attributes to create the target with.
+        #
+        # @yield [target]
+        #   If a block is given, it will be passed the newly created target.
+        #
+        # @yieldparam [Targets::FormatString] target
+        #   The newly created target.
         #
         def targeting(attributes={},&block)
           self.targets << Targets::FormatString.new(attributes,&block)
         end
 
+        #
+        # @return [Payloads::Shellcode]
+        #   The model which will be searched for acceptable payloads.
+        #
+        # @since 0.3.0
+        #
+        def use_payload_class
+          Payload::Shellcode
+        end
+
         protected
 
         #
         # Builds a format string using the current target and payload to
         # be used in the format string exploit.
         #
+        # @return [String]
+        #   The built format string.
+        #
         def build_format_string
           verify_target!
 
@@ -96,7 +105,8 @@ module Ronin
         end
 
         #
-        # The default builder method, simply calls build_format_string.
+        # The default builder method which simply calls build_format_string
+        # and sets the +@format_string+ instance variable.
         #
         def build
           @format_string = build_format_string

data/lib/ronin/exploits/helpers/padding.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,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/text'
@@ -27,15 +25,6 @@ module Ronin
   module Exploits
     module Helpers
       module Padding
-        def self.included(base)
-          base.module_eval do
-            # String to pad extra space with
-            parameter :padding,
-                      :default => 'A',
-                      :description => 'padding string'
-          end
-        end
-
         def self.extended(obj)
           obj.instance_eval do
             # String to pad extra space with
@@ -48,8 +37,16 @@ module Ronin
         protected
 
         #
-        # Returns padding with the specified _max_length_.
+        # Creates padding out to a maximum length, using the +padding+
+        # parameter.
+        #
+        # @param [Integer] max_length
+        #   The maximum length to pad out to.
         #
+        # @return [String]
+        #   A padded string.
+        #
+        # @example
         #   pad(28)
         #   # => "AAAAAAAAAAAAAAAAAAAAAAAAAAAA"
         #
@@ -58,9 +55,19 @@ module Ronin
         end
 
         #
-        # Pads the specified _data_ to the left up to the specified
-        # _max_length_.
+        # Pads the a string on the right-hand side out to a maximum length,
+        # using the +padding+ parameter.
+        #
+        # @param [String] data
+        #   The string to add padding to.
+        #
+        # @param [Integer] max_length
+        #   The amount of padding to add.
+        #
+        # @return [String]
+        #   The left-hand side padded string.
         #
+        # @example
         #   pad_left("\xff\xff",48)
         #   # => "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\xff\xff"
         #
@@ -69,9 +76,19 @@ module Ronin
         end
 
         #
-        # Pads the specified _data_ to the right up to the specified
-        # _max_length_.
+        # Pads the a string on the right-hand side out to a maximum length,
+        # using the +padding+ parameter.
+        #
+        # @param [String] data
+        #   The string to add padding to.
+        #
+        # @param [Integer] max_length
+        #   The amount of padding to add.
+        #
+        # @return [String]
+        #   The right-hand side padded string.
         #
+        # @example
         #   pad_right("\xff\xff",48)
         #   # => "\xff\xffAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
         #