ronin-exploits 0.3.1 → 1.0.0.beta2

data/lib/ronin/exploits/mixins/file_builder.rb

@@ -0,0 +1,102 @@
+#
+# ronin-exploits - A Ruby library for ronin-rb that provides exploitation and
+# payload crafting functionality.
+#
+# Copyright (c) 2007-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-exploits 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-exploits 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-exploits.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/exploits/params/filename'
+
+module Ronin
+  module Exploits
+    module Mixins
+      #
+      # Adds methods for building exploit files. Also adds a `filenam`
+      # param and a
+      # {Metadata::DefaultFilename::ClassMethods#default_filename default_filename}
+      # class method.
+      #
+      # ## Examples
+      #
+      #     include Mixins::FileBuilder
+      #
+      #     default_filename 'exploit.docx'
+      #
+      #     def build
+      #       # ...
+      #     
+      #       build_file do |file|
+      #         # ...
+      #         file.write(buffer)
+      #         # ...
+      #       end
+      #     
+      #       # ...
+      #     end
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      module FileBuilder
+        #
+        # Includes {Params::Filename} into the exploit including {FileBuilder}.
+        #
+        # @param [Class<Exploit>] exploit
+        #   The exploit including {FileBuilder}.
+        #
+        # @api private
+        #
+        def self.included(exploit)
+          exploit.include Params::Filename
+        end
+
+        #
+        # Opens the file to be built.
+        #
+        # @param [String] name
+        #   Optional name of the file to build.
+        #
+        # @yield [file]
+        #   If a block is given, it will be passed the newly opened file.
+        #   After the block has returned, the file will be closed.
+        #
+        # @yieldparam [Tempfile, File] file
+        #   The newly opened file.
+        #
+        # @return [String]
+        #   Path to the built file.
+        #
+        # @example
+        #   build_file do |file|
+        #     file << 'some data'
+        #   end
+        #
+        # @example Generate a specifically named file.
+        #   build_file('file1.xml') do |file|
+        #     file << "<evil />"
+        #   end
+        #
+        def build_file(name=filename,&block)
+          path = File.expand_path(name)
+
+          File.open(name,'wb',&block)
+          return path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+#
+# ronin-exploits - A Ruby library for ronin-rb that provides exploitation and
+# payload crafting functionality.
+#
+# Copyright (c) 2007-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-exploits 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-exploits 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-exploits.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/exploits/mixins/binary'
+
+module Ronin
+  module Exploits
+    module Mixins
+      #
+      # Adds methods to exploits for generating format strings to be used
+      # in format string vulnerabilities.
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      module FormatString
+        include Binary
+
+        #
+        # Builds a format string.
+        #
+        # @param [Integer] overwrite
+        #   The address to overwrite.
+        #
+        # @param [Integer] pop_length
+        #
+        # @param [Integer] address
+        #   The address to write.
+        #
+        # @param [#to_s] payload
+        #   The payload append to the format string.
+        #
+        # @return [String]
+        #   The built format string.
+        #
+        def build_format_string(overwrite: , pop_length: , address: , payload: )
+          machine_word = platform[:machine_word]
+
+          buffer = String.new(encoding: Encoding::ASCII_8BIT)
+          buffer << pack(:machine_word,overwrite)
+          buffer << pack(:machine_word,overwrite + (machine_word.size  / 2))
+
+          low_mask = 0xff
+
+          (machine_word.size / 2).times do
+            low_mask <<= 8
+            low_mask |= 0xff
+          end
+
+          high_mask = low_mask << ((machine_word.size * 8) / 2)
+
+          high = (address & high_mask) >> (machine_word.size / 2)
+          low  = address & low_mask
+
+          if low < high
+            low    -= (machine_word.size * 2)
+            buffer << format("%%.%ud%%%u$hn%%.%ud%%%u$hn",low,pop_length,high-low,pop_length+1)
+          else
+            high   -= (machine_word.size * 2)
+            buffer << format("%%.%ud%%%u$hn%%.%ud%%%u$hn",high,pop_length+1,low-high,pop_length)
+          end
+
+          buffer << payload.to_s
+          return buffer
+        end
+      end
+    end
+  end
+end

data/lib/ronin/exploits/mixins/has_payload.rb

@@ -0,0 +1,202 @@
+#
+# ronin-exploits - A Ruby library for ronin-rb that provides exploitation and
+# payload crafting functionality.
+#
+# Copyright (c) 2007-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-exploits 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-exploits 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-exploits.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/exploits/exceptions'
+require 'ronin/payloads/payload'
+
+module Ronin
+  module Exploits
+    module Mixins
+      #
+      # Adds the ability to use a payload in an exploit.
+      #
+      # ## Examples
+      #
+      #     module Ronin
+      #       module Exploits
+      #         class MyExploit < Exploit
+      #     
+      #           include Mixins::HasPayload
+      #     
+      #           payload_class Ronin::Payloads::JavaScriptPayload
+      #     
+      #         end
+      #       end
+      #     end
+      #
+      # @api public
+      #
+      module HasPayload
+        #
+        # Adds {ClassMethods} to the exploit.
+        #
+        # @param [Class] exploit
+        #   The exploit class including {HasPayload}.
+        #
+        # @api private
+        #
+        def self.included(exploit)
+          exploit.extend ClassMethods
+        end
+
+        #
+        # Class methods.
+        #
+        module ClassMethods
+          #
+          # Gets or sets the payload base class that is compatible with the
+          # exploit.
+          #
+          # @param [Class<Ronin::Payloads::Payload>, nil] new_payload_class
+          #   The optional new payload base class to set.
+          #
+          # @return [Class<Ronin::Payloads::Payload>]
+          #   The exploit's compatible payload base class.
+          #
+          def payload_class(new_payload_class=nil)
+            if new_payload_class
+              @payload_class = new_payload_class
+            else
+              @payload_class ||= if superclass.kind_of?(ClassMethods)
+                                   superclass.payload_class
+                                 else
+                                   Ronin::Payloads::Payload
+                                 end
+            end
+          end
+        end
+
+        # The payload the exploit can use.
+        #
+        # @return [Ronin::Payloads::Payload, String, nil]
+        attr_reader :payload
+
+        #
+        # Initializes the exploit and sets the {#payload}.
+        #
+        # @param [Ronin::Payloads::Payload, String, nil] payload
+        #   The payload to use.
+        #
+        def initialize(payload: nil, **kwargs)
+          super(**kwargs)
+
+          self.payload = payload
+        end
+
+        #
+        # Sets the payload to use with the exploit.
+        #
+        # @param [Ronin::Payloads::Payload, String, nil] new_payload
+        #   The new payload to use with the exploit.
+        #
+        # @return [Ronin::Payloads::Payload, String, nil]
+        #   The new payload of the exploit.
+        #
+        def payload=(new_payload)
+          if new_payload.kind_of?(Payloads::Payload)
+            unless new_payload.kind_of?(self.class.payload_class)
+              raise(IncompatiblePayload,"incompatible payload, must be a #{self.class.payload_class} payload: #{new_payload.inspect}")
+            end
+          end
+
+          @payload = new_payload
+        end
+
+        #
+        # Validates {#payload} and the exploit.
+        #
+        # @raise [MissingPayload]
+        #   {#payload} was never set.
+        #
+        # @raise [Ronin::Core::Params::RequiredParam]
+        #   One of the required params in the exploit or {#payload} is not
+        #   set.
+        #
+        # @api semipublic
+        #
+        def perform_validate
+          unless @payload
+            raise(MissingPayload,"exploit requires a payload")
+          end
+
+          if @payload.kind_of?(Ronin::Core::Params::Mixin)
+            @payload.validate_params
+          end
+
+          super
+        end
+
+        #
+        # Calls the payload's `perform_build` method first before the exploit
+        # is built.
+        #
+        def perform_build
+          if @payload.kind_of?(Ronin::Payloads::Payload)
+            @payload.perform_build
+          end
+
+          super
+        end
+
+        #
+        # Overrides the payload's `perform_prelaunch` method, then calls the
+        # exploit's {Exploit#perform_launch perform_launch} method, and finally
+        # calls the payload's `perform_postlaunch` method.
+        #
+        # @note
+        #   If any exception is raised by the exploit's `launch` method, then
+        #   the payload's `perform_cleanup` method is called and the exception
+        #   is re-raised.
+        #
+        def perform_launch
+          if @payload.kind_of?(Ronin::Payloads::Payload)
+            @payload.perform_prelaunch
+          end
+
+          begin
+            super()
+
+            if @payload.kind_of?(Ronin::Payloads::Payload)
+              @payload.perform_postlaunch
+            end
+          rescue => error
+            if @payload.kind_of?(Ronin::Payloads::Payload)
+              @payload.perform_cleanup
+            end
+
+            raise(error)
+          end
+        end
+
+        #
+        # Calls the payload's `perform_cleanup` method first after the exploit
+        # is cleaned up.
+        #
+        def perform_cleanup
+          super
+
+          if @payload.kind_of?(Ronin::Payloads::Payload)
+            @payload.perform_cleanup
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/exploits/mixins/has_targets.rb

@@ -0,0 +1,297 @@
+#
+# ronin-exploits - A Ruby library for ronin-rb that provides exploitation and
+# payload crafting functionality.
+#
+# Copyright (c) 2007-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-exploits 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-exploits 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-exploits.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/exploits/target'
+require 'ronin/exploits/exceptions'
+
+module Ronin
+  module Exploits
+    module Mixins
+      #
+      # Adds target information to an exploit class.
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      module HasTargets
+        class TargetError < ExploitError
+        end
+
+        class NoMatchingTarget < TargetError
+        end
+
+        class NoTargetSelected < TargetError
+        end
+
+        #
+        # Adds {ClassMethods} to the including exploit class.
+        #
+        # @param [Class] exploit
+        #   The exploit class including {HasTargets}.
+        #
+        # @api private
+        #
+        def self.included(exploit)
+          exploit.extend ClassMethods
+        end
+
+        #
+        # Class methods for defining targets.
+        #
+        module ClassMethods
+          #
+          # The targets for the exploit.
+          #
+          # @return [Array<Target>]
+          #
+          # @api semipublic
+          #
+          def targets
+            @targets ||= if superclass.kind_of?(ClassMethods)
+                           superclass.targets.dup
+                         else
+                           []
+                         end
+          end
+
+          #
+          # Adds a target to the exploit.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for {Target#initialize}.
+          #
+          # @option kwargs [Symbol, nil] :arch
+          #   The architecture of the target.
+          #
+          # @option kwargs [Symbol, nil] :os
+          #   The Operating System (OS) of the target.
+          #
+          # @option kwargs [String, nil] :os_version
+          #   The Operating System (OS) version of the target.
+          #
+          # @option kwargs [Symbol, nil] :software
+          #   The software name of the target.
+          #
+          # @option kwargs [String, nil] :version
+          #   The software version of the target.
+          #
+          # @example
+          #   target arch: :x86_64, os: :linux, software: 'Apache' do |t|
+          #     t.foo = 0x123456
+          #     t.bar = '...'
+          #   end
+          #
+          # @api public
+          #
+          def target(**kwargs,&block)
+            targets << Target.new(**kwargs,&block)
+          end
+        end
+
+        # Currently selected exploit target.
+        #
+        # @return [Target, nil]
+        #
+        # @api public
+        attr_reader :target
+
+        #
+        # Sets that {#target} if the `target:` keyword argument is giving.
+        #
+        # @param [Hash{Symbol => Object}, Integer, nil] target
+        #   The optional target information to select.
+        #
+        # @param [Hash{Symbol => Object}] kwargs
+        #   Additional keyword arguments.
+        #
+        # @api public
+        #
+        def initialize(target: nil, **kwargs)
+          super(**kwargs)
+
+          if target
+            case target
+            when Hash    then select_target(**target)
+            when Integer then self.target = target
+            else
+              raise(ArgumentError,"target: must be either a Hash or an Integer")
+            end
+          end
+        end
+
+        #
+        # Validates that a target was selected and all required params are set.
+        #
+        # @raise [Ronin::Core::Params::RequiredParam]
+        #   One of the required params was not set.
+        #
+        # @raise [NoTargetSelected]
+        #   No target was selected.
+        #
+        # @api semipublic
+        #
+        def perform_validate
+          unless target
+            raise(NoTargetSelected,"no target was selected")
+          end
+
+          super()
+        end
+
+        #
+        # Selects the target to use in exploitation.
+        #
+        # @param [Symbol] arch
+        #   The targeted Architecture.
+        #
+        # @param [Symbol] os
+        #   The targeted Operating System (OS).
+        #
+        # @param [Symbol] os_version
+        #   The targeted Operating System (OS) version.
+        #
+        # @param [Symbol] software
+        #   The targeted software.
+        #
+        # @param [Symbol] version
+        #   The targeted software version.
+        #
+        # @raise [NoMatchingTarget]
+        #   No matching target could be found.
+        #
+        # @api semipublic
+        #
+        def select_target(arch: nil, os: nil, os_version: nil, software: nil, version: nil)
+          targets = self.class.targets.lazy
+
+          if arch
+            targets = targets.select { |target| target.arch == arch }
+          end
+
+          if os
+            targets = targets.select { |target| target.os == os }
+          end
+
+          if os_version
+            targets = targets.select { |target| target.os_version == os_version }
+          end
+
+          if software
+            targets = targets.select { |target| target.software == software }
+          end
+
+          if version
+            targets = targets.select do |target|
+              target.version == version
+            end
+          end
+
+          unless (@target = targets.first)
+            raise(NoMatchingTarget,"could not find any matching targets")
+          end
+        end
+
+        #
+        # Sets the target.
+        #
+        # @param [Target, Integer, nil] new_target
+        #   The new target value or a target index.
+        #
+        # @return [Target, nil]
+        #   The updated target value.
+        #
+        # @raise [ArgumentError]
+        #   The new target value must be a {Target}, an Integer or nil.
+        #
+        # @raise [NoMatchingTarget]
+        #   The target index was out of bounds.
+        #
+        def target=(new_target)
+          case new_target
+          when Integer
+            @target = self.class.targets.fetch(new_target) do
+              raise(NoMatchingTarget,"target index is out of bounds: #{new_target.inspect}")
+            end
+          when Target, nil
+            @target = new_target
+          else
+            raise(ArgumentError,"target value must be a #{Target}, Integer or nil")
+          end
+        end
+
+        #
+        # The current targeted architecture.
+        #
+        # @return [Symbol, nil]
+        #
+        # @api public
+        #
+        def arch
+          target.arch if target
+        end
+
+        #
+        # The current targeted OS.
+        #
+        # @return [Symbol, nil]
+        #
+        # @api public
+        #
+        def os
+          target.os if target
+        end
+
+        #
+        # The current targeted OS version.
+        #
+        # @return [String, nil]
+        #
+        # @api public
+        #
+        def os_version
+          target.os_version if target
+        end
+
+        #
+        # The current targeted software.
+        #
+        # @return [String, nil]
+        #
+        # @api public
+        #
+        def software
+          target.software if target
+        end
+
+        #
+        # The current targeted software version.
+        #
+        # @return [String, nil]
+        #
+        # @api public
+        #
+        def version
+          target.version if target
+        end
+      end
+    end
+  end
+end