ronin-exploits 0.3.1 → 1.0.0.beta2

data/lib/ronin/exploits/cli/commands/run.rb

@@ -0,0 +1,396 @@
+#
+# 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/cli/exploit_command'
+require 'ronin/exploits/cli/ruby_shell'
+require 'ronin/exploits/mixins/has_payload'
+require 'ronin/exploits/mixins/has_targets'
+require 'ronin/exploits/mixins/loot'
+
+require 'ronin/payloads/cli/encoder_methods'
+require 'ronin/payloads/cli/payload_methods'
+require 'ronin/payloads/mixins/post_ex'
+
+require 'ronin/core/cli/options/param'
+require 'ronin/core/cli/options/values/arches'
+require 'ronin/core/cli/options/values/oses'
+require 'ronin/core/cli/logging'
+
+require 'command_kit/printing/indent'
+
+module Ronin
+  module Exploits
+    class CLI
+      module Commands
+        #
+        # Runs an exploit.
+        #
+        # ## Usage
+        #
+        #     ronin-exploits run [options] {NAME | -f FILE}
+        #
+        # ## Options
+        #
+        #     -f, --file FILE                  The exploit file to load
+        #     -p, --param NAME=VALUE           Sets a param
+        #     -D, --dry-run                    Builds the exploit but does not launch it
+        #         --payload-file FILE          Load the payload from the given Ruby file
+        #         --read-payload FILE          Reads the payload string from the file
+        #         --payload-string STRING      Uses the raw payload string instead
+        #     -P, --payload NAME               The payload to load and use
+        #         --payload-param NAME=VALUE   Sets a param in the payload
+        #         --encoder-file FILE          Load the payload encoder from the Ruby file
+        #     -E, --encoder NAME               Loads the payload encoder by name
+        #         --encoder-param ENCODER.NAME=VALUE
+        #                                      Sets a param of the ENCODER
+        #     -t, --target INDEX               Selects the target by index
+        #     -A x86|x86-64|amd64|ia64|ppc|ppc64|arm|armbe|arm64|arm64be|mips|mipsle|mips64|mips64le,
+        #         --target-arch                Selects the target with the matching arch
+        #     -O linux|macos|windows|freebsd|openbsd|netbsd,
+        #         --target-os                  Selects the target with the matching OS
+        #         --target-os-version VERSION  Selects the target with the matching OS version
+        #     -S, --target-software NAME       Selects the target with the matching software name
+        #     -V, --target-version VERSION     Selects the target with the matching software version
+        #     -L, --save-loot DIR              Saves any found loot to the DIR
+        #     -D, --debug                      Enables debugging messages
+        #         --irb                        Open an interactive Ruby shell inside the exploit
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     [NAME]                           The exploit name to load
+        #
+        class Run < ExploitCommand
+
+          include Payloads::CLI::EncoderMethods
+          include Payloads::CLI::PayloadMethods
+          include Core::CLI::Options::Param
+          include Core::CLI::Logging
+          include CommandKit::Printing::Indent
+
+          # Exploit options
+          option :dry_run, short: '-D',
+                           desc: 'Builds the exploit but does not launch it'
+
+          # Payload options
+          option :payload_file, value: {
+                                  type: String,
+                                  usage: 'FILE',
+                                },
+                                desc: 'Load the payload from the given Ruby file'
+          option :read_payload, value: {
+                                  type:  String,
+                                  usage: 'FILE'
+                                },
+                                desc: 'Reads the payload string from the file'
+
+          option :payload_string, value: {
+                                    type:  String,
+                                    usage: 'STRING'
+                                  },
+                                  desc: 'Uses the raw payload string instead'
+
+          option :payload, short: '-P',
+                           value: {
+                             type: String,
+                             usage: 'NAME'
+                           },
+                           desc: 'The payload to load and use'
+
+          option :payload_param, value: {
+                                   type: /\A[^=\s]+=.+\z/,
+                                   usage: 'NAME=VALUE'
+                                 },
+                                 desc: 'Sets a param on the payload'
+
+          # Encoder options
+          option :encoder_file, value: {
+                                  type: String,
+                                  usage: 'FILE'
+                                },
+                                desc: 'Load the payload encoder from the Ruby file' do |file|
+                                  @load_encoders << [:file, file]
+                                end
+
+          option :encoder, short: '-E',
+                           value: {
+                             type: String,
+                             usage: 'NAME'
+                           },
+                           desc: 'Loads the payload encoder by name' do |name|
+                             @load_encoders << [:name, name]
+                           end
+
+          option :encoder_param, value: {
+                                   type: /\A[^\.\=\s]+\.[^=\s]+=.+\z/,
+                                   usage: 'ENCODER.NAME=VALUE'
+                                 },
+                                 desc: 'Sets a param on the ENCODER' do
+                                   prefix, value = str.split('=',2)
+                                   ecndoer, name = prefix.split('.',2)
+
+                                   @encodeer_params[encoder][name] = value
+                                 end
+
+          # Target options
+          option :target, short: '-t',
+                          value: {
+                            type: Integer,
+                            usage: 'INDEX'
+                          },
+                          desc: 'Selects the target by index'
+
+          option :target_arch, short: '-A',
+                               value: {
+                                 type: Core::CLI::Options::Values::ARCHES
+                               },
+                               desc: 'Selects the target with the matching arch' do |arch|
+                                 @target_kwargs[:arch] = arch
+                               end
+
+          option :target_os, short: '-O',
+                             value: {
+                               type: Core::CLI::Options::Values::OSES
+                             },
+                             desc: 'Selects the target with the matching OS' do |os|
+                               @target_kwargs[:os] = os
+                             end
+
+          option :target_os_version, value: {
+                                       type: String,
+                                       usage: 'VERSION'
+                                     },
+                                     desc: 'Selects the target with the matching OS version' do |version|
+                                       @target_kwargs[:os_version] = version
+                                     end
+
+          option :target_software, short: '-S',
+                                   value: {
+                                     type: String,
+                                     usage: 'NAME'
+                                   },
+                                   desc: 'Selects the target with the matching software name' do |software|
+                                     @target_kwargs[:software] = software
+                                   end
+
+          option :target_version, short: '-V',
+                                  value: {
+                                    type: String,
+                                    usage: 'VERSION'
+                                  },
+                                  desc: 'Selects the target with the matching software version' do |version|
+                                    @target_kwargs[:version] = version
+                                  end
+
+          option :save_loot, short: '-L',
+                             value: {
+                               type:  String,
+                               usage: 'DIR'
+                             },
+                             desc: 'Saves any found loot to the DIR'
+
+          option :debug, short: '-D',
+                         desc: 'Enables debugging messages' do
+                           Support::CLI::Printing.debug = true
+                         end
+
+          option :irb, desc: 'Open an interactive Ruby shell inside the exploit'
+
+          description 'Runs an exploit'
+
+          man_page 'ronin-exploits-run.1'
+
+          #
+          # Initializes the `ronin-exploits run` command.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments.
+          #
+          def initialize(**kwargs)
+            super(**kwargs)
+
+            @load_encoders  = []
+            @encoder_params = Hash.new { |hash,key| hash[key] = {} }
+            @target_kwargs  = {}
+          end
+
+          #
+          # Runs the `ronin-exploits run` command.
+          #
+          # @param [String, nil] name
+          #   The optional exploit name to load.
+          #
+          def run(name=nil)
+            super(name)
+
+            load_encoders
+            load_payload
+            initialize_encoders
+            initialize_payload
+            initialize_exploit
+            validate_exploit
+            run_exploit
+
+            if options[:irb]
+              start_shell
+            else
+              post_exploitation
+            end
+
+            perform_cleanup
+          end
+
+          def load_encoders
+            @encoder_classes = @load_encoders.map do |(type,value)|
+              case type
+              in :name then load_encoder(value)
+              in :file then load_encoder_from(value)
+              end
+            end
+          end
+
+          def initialize_encoders
+            @encoders = @encoder_classes.map do |encoder_class|
+              encoder_class.new(params: @encoder_params[encoder_class.id])
+            end
+          end
+
+          def load_payload
+            @payload_class = if options[:payload]
+                               super(options[:payload])
+                             elsif options[:payload_file]
+                               load_payload_from(options[:payload_file])
+                             end
+          end
+
+          def initialize_payload
+            @payload = if @payload_class
+                         super(@payload_class, params:   @payload_params,
+                                               encoders: @encoders)
+                       elsif options[:read_payload]
+                         File.binread(options[:read_payload])
+                       elsif options[:payload_string]
+                         options[:payload_string]
+                       end
+          end
+
+          def initialize_exploit
+            kwargs = {params: @params}
+
+            if @exploit_class.include?(Mixins::HasPayload)
+              kwargs[:payload] = @payload
+            end
+
+            if @exploit_class.include?(Mixins::HasTargets)
+              kwargs[:target] = if options[:target]
+                                  options[:target]
+                                elsif !@target_kwargs.empty?
+                                  @target_kwargs
+                                end
+            end
+
+            super(**kwargs)
+          end
+
+          def run_exploit
+            log_info "Running exploit #{@exploit.class_id} ..."
+
+            begin
+              @exploit.exploit(dry_run: options[:dry_run])
+            rescue ExploitError => error
+              print_error("failed to run exploit #{@exploit.class_id}: #{error.message}")
+              exit(1)
+            rescue => error
+              print_exception(error)
+              print_error "an unhandled exception occurred while running the exploit #{@exploit.class_id}"
+              exit(-1)
+            end
+          end
+
+          def start_shell
+            log_info "Exploit #{@exploit.class_id} launched!"
+            log_info "Starting interactive Ruby shell ..."
+
+            RubyShell.start(name: @exploit_class.name, context: @exploit)
+          end
+
+          def post_exploitation
+            if @exploit_class.include?(Mixins::HasPayload) &&
+               @exploit.payload.kind_of?(Ronin::Payloads::Payload) &&
+               @exploit.payload.kind_of?(Ronin::Payloads::Mixins::PostExt)
+              unless @exploit.payload.session
+                print_error("payload (#{@exploit.payload.class_id}) did not create a post-exploitation session")
+
+                perform_cleanup
+                eixt(1)
+              end
+
+              @exploit.payload.session.system.interact
+            elsif @exploit_class.include?(Mixins::Loot)
+              print_loot
+              save_loot if options[:save_loot]
+            end
+          end
+
+          def print_loot
+            unless @exploit.loot.empty?
+              log_info "Exploit found the following loot:"
+
+              indent do
+                @exploit.loot.each do |file|
+                  puts
+                  puts "#{file.path}:"
+                  puts
+
+                  indent do
+                    file.to_s.each_line do |line|
+                      puts line
+                    end
+                  end
+                  puts
+                end
+              end
+            else
+              log_error "Exploit did not find any loot :("
+            end
+          end
+
+          def save_loot
+            @exploit.loot.save(options.fetch(:save_loot))
+          end
+
+          def perform_cleanup
+            begin
+              @exploit.perform_cleanup
+            rescue ExploitError => error
+              print_error("failed to cleanup exploit #{@exploit.class_id}: #{error.message}")
+              exit(1)
+            rescue => error
+              print_exception(error)
+              print_error "an unhandled exception occurred while cleaning up the exploit #{@exploit.class_id}"
+              exit(-1)
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/exploits/cli/commands/show.rb

@@ -0,0 +1,290 @@
+#
+# 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/cli/exploit_command'
+
+require 'ronin/payloads/cli/printing'
+
+require 'ronin/core/cli/printing/metadata'
+require 'ronin/core/cli/printing/arch'
+require 'ronin/core/cli/printing/os'
+require 'ronin/core/cli/printing/params'
+require 'ronin/core/metadata/version'
+
+require 'command_kit/printing/fields'
+
+module Ronin
+  module Exploits
+    class CLI
+      module Commands
+        #
+        # Prints information about an exploit.
+        #
+        # ## Usage
+        #
+        #     ronin-exploits show [options] {NAME | --file FILE}
+        #
+        # ## Options
+        #
+        #     -f, --file FILE                  The exploit file to load
+        #     -v, --verbose                    Enables verbose output
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        # 
+        #     [NAME]                           The exploit name to load
+        #
+        class Show < ExploitCommand
+
+          include Core::CLI::Printing::Metadata
+          include Core::CLI::Printing::Arch
+          include Core::CLI::Printing::OS
+          include Core::CLI::Printing::Params
+          include CommandKit::Printing::Fields
+          include Payloads::CLI::Printing
+
+          description 'Prints information about an exploit'
+
+          man_page 'ronin-exploits-show.1'
+
+          #
+          # Runs the `ronin-exploits show` command.
+          #
+          # @param [String] name
+          #   The optional name of the exploit to load and print metadata about.
+          #
+          def run(name=nil)
+            super(name)
+
+            print_exploit(exploit_class)
+          end
+
+          #
+          # Prints the exploit class'es metadata.
+          #
+          # @param [Class<Exploit>] exploit
+          #   The loaded exploit class.
+          #
+          def print_exploit(exploit)
+            puts "[ #{exploit.id} ]"
+            puts
+
+            indent do
+              print_metadata(exploit)
+              print_advisories(exploit)
+              print_authors(exploit)
+              print_description(exploit)
+              print_references(exploit)
+
+              if defined?(Mixins::HasTargets) &&
+                 exploit.include?(Mixins::HasTargets)
+                unless exploit.targets.empty?
+                  exploit.targets.each_with_index do |target,index|
+                    puts "[ Target ##{index+1} ]"
+                    puts
+
+                    indent { print_target(target) }
+                  end
+                end
+              end
+
+              print_shouts(exploit)
+            end
+
+            print_params(exploit)
+          end
+
+          #
+          # Print the main metadata fields for the exploit.
+          #
+          # @param [Class<Exploit>] exploit
+          #   The loaded exploit class.
+          #
+          def print_metadata(exploit)
+            fields = {}
+            fields['Type'] = exploit_type(exploit)
+
+            if defined?(Core::Metadata::Version) &&
+               exploit.include?(Core::Metadata::Version)
+              fields['Version'] = exploit.version if exploit.version
+            end
+
+            fields['Quality']   = exploit.quality   if exploit.quality
+            fields['Released']  = exploit.release_date  if exploit.release_date
+            fields['Disclosed'] = exploit.disclosure_date if exploit.disclosure_date
+
+            if defined?(Metadata::Arch) && exploit.include?(Metadata::Arch)
+              if (arch = target.arch)
+                fields['Arch'] = arch
+              end
+            end
+
+            if defined?(Metadata::OS) && exploit.include?(Metadata::OS)
+              if (os = exploit.os)
+                fields['OS'] = if (os_version = exploit.os_version)
+                                 "#{os} #{os_version}"
+                               else
+                                 os
+                               end
+              end
+           end
+
+            if (software = exploit.software)
+              fields['Software'] = software
+            end
+
+            if (versions = exploit.software_versions)
+              case versions
+              when Array
+                fields['Software Versions'] = versions.join(', ')
+              when Range
+                fields['Software Versions'] = "#{versions.begin} - #{versions.end}"
+              end
+            end
+
+            if defined?(Mixins::HasPayload) &&
+               exploit.include?(Mixins::HasPayload)
+              fields['Payload Type'] = payload_type(exploit.payload_class)
+            end
+
+            fields['Summary']   = exploit.summary   if exploit.summary
+            print_fields(fields)
+          end
+
+          #
+          # Prints any advisories defined by an exploit class.
+          #
+          # @param [Class<Exploit>] exploit
+          #   The loaded exploit class.
+          #
+          def print_advisories(exploit)
+            unless exploit.advisories.empty?
+              puts "Advisories:"
+              puts
+
+              indent do
+                exploit.advisories.each do |advisory|
+                  print_advisory(advisory)
+                end
+              end
+              puts
+            end
+          end
+
+          #
+          # Prints the shouts section.
+          #
+          # @param [Class<Exploit>] exploit
+          #   The loaded exploit class.
+          #
+          def print_shouts(exploit)
+            if defined?(Metadata::Shouts) && exploit.include?(Metadata::Shouts)
+              puts "Shouts: #{exploit.shouts.join(', ')}"
+            end
+          end
+
+          # Known exploit types and their printable names.
+          EXPLOIT_TYPES = {
+            exploit: 'Custom',
+
+            # memory corruption exploits
+            memory_corruption: 'Memory Corruption',
+            stack_overflow:    'Stack Overflow',
+            seh_overflow:      'SEH Overflow',
+            heap_overflow:     'Heap Overflow',
+            use_after_free:    'Use After Free',
+
+            # web exploits
+            web:  'Web',
+            lfi:  'Local File Inclusion (LFI)',
+            rfi:  'Remote File Inclusion (RFI)',
+            sqli: 'SQL injection (SQLI)',
+            xss:  'Cross-Site Scripting (XSS)',
+            open_redirect: 'Open Redirect',
+            ssti: 'Server-Side Template Injection (SSTI)'
+          }
+
+          #
+          # Returns the printable exploit type for the exploit class.
+          #
+          # @param [Class<Exploit>] exploit_class
+          #
+          # @return [String]
+          #
+          def exploit_type(exploit_class)
+            EXPLOIT_TYPES.fetch(exploit_class.exploit_type,'unknown')
+          end
+
+          #
+          # Prints an advisory.
+          #
+          # @param [Advisory] advisory
+          #   The advisory to print.
+          #
+          def print_advisory(advisory)
+            if advisory.url then puts "* #{advisory.id} (#{advisory.url})"
+            else                 puts "* #{advisory.id}"
+            end
+          end
+
+          #
+          # Prints an exploit target.
+          #
+          # @param [Target] target
+          #   A target defined on the exploit.
+          #
+          def print_target(target)
+            fields = {}
+            fields['Arch'] = target.arch if target.arch
+
+            if target.os
+              fields['OS'] = if target.os_version
+                               "#{target.os} #{target.os_version}"
+                             else
+                               target.os
+                             end
+            end
+
+            if target.software
+              fields['Software'] = if target.software_version
+                                     "#{target.software} #{target.software_version}"
+                                   else
+                                     target.software
+                                   end
+            end
+
+            print_fields(fields)
+
+            if verbose?
+              unless target.empty?
+                puts "Params:"
+
+                indent { print_fields(target.to_h) }
+              end
+            end
+
+            puts
+          end
+
+        end
+      end
+    end
+  end
+end