ronin-exploits 0.3.1 → 1.0.0.beta1

data/lib/ronin/exploits/exploit.rb

@@ -1,558 +1,561 @@
 #
-# Ronin Exploits - A Ruby library for Ronin that provides exploitation and
+# ronin-exploits - A Ruby library for ronin-rb that provides exploitation and
 # payload crafting functionality.
 #
-# Copyright (c) 2007-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2007-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
+# 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.
 #
-# This program is distributed in the hope that it will be useful,
+# 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 General Public License for more details.
+# GNU Lesser General Public License for more details.
 #
-# 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
+# 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/unknown_helper'
-require 'ronin/exploits/exceptions/target_unspecified'
-require 'ronin/exploits/exceptions/target_data_missing'
-require 'ronin/exploits/exceptions/restricted_char'
-require 'ronin/exploits/exceptions/exploit_not_built'
-require 'ronin/exploits/verifiers'
-require 'ronin/exploits/exploit_author'
-require 'ronin/exploits/target'
-require 'ronin/exploits/control'
-require 'ronin/payloads/has_payload'
-require 'ronin/payloads/payload'
-require 'ronin/controls/behaviors'
-require 'ronin/cacheable'
-require 'ronin/model/has_name'
-require 'ronin/model/has_description'
-require 'ronin/model/has_version'
-require 'ronin/model/has_license'
-require 'ronin/ui/output/helpers'
-require 'ronin/extensions/kernel'
-
-require 'parameters'
+require 'ronin/exploits/registry'
+require 'ronin/exploits/advisory'
+require 'ronin/exploits/test_result'
+require 'ronin/exploits/exceptions'
+require 'ronin/core/metadata/id'
+require 'ronin/core/metadata/authors'
+require 'ronin/core/metadata/summary'
+require 'ronin/core/metadata/description'
+require 'ronin/core/metadata/references'
+require 'ronin/core/params/mixin'
+require 'ronin/support/cli/printing'
+require 'ronin/post_ex'
+
 require 'chars/char_set'
 
 module Ronin
   module Exploits
+    #
+    # The {Exploit} class allows for describing exploits for security
+    # vulnerabilities, purely in Ruby. Exploits contain metadata about the
+    # exploit/vulnerability and methods which defines the functionality
+    # of the exploit. Exploits may also include additional
+    # {Mixins mixin modules} to add additional functionality, such as defining
+    # targets or loading in a payload.
+    #
+    # ## Philosophy
+    #
+    # Exploits are just programs with steps to build and launch the exploit.
+    # Exploits also typically contain metadata that describes the exploit's
+    # author(s), release date, what the exploit does, etc.
+    #
+    # The {Exploit} class defines six key parts:
+    #
+    # 1. Metadata - defines information about the exploit.
+    # 2. Params - user configurable parameters.
+    # 3. {Exploit#test test} - optional method that tests whether the target is
+    #    vulnerable or not.
+    # 4. {Exploit#build build} - method which builds the exploit.
+    # 5. {Exploit#launch launch} - method which launches the exploit.
+    # 6. {Exploit#cleanup cleanup} - optional Method which performs additional
+    #    cleanup steps.
+    #
+    # ## Example
+    # 
+    #     require 'ronin/exploits/exploit'
+    #     require 'ronin/exploits/mixins/remote_tcp'
+    #     
+    #     module Ronin
+    #       module Exploits
+    #         class MyExploit < Exploit
+    #
+    #           include Mixins::RemoteTCP
+    #     
+    #           register 'my_exploit'
+    #     
+    #           summary 'My first exploit'
+    #           description <<~EOS
+    #             This is my first exploit.
+    #             Bla bla bla bla.
+    #           EOS
+    #     
+    #           author '...'
+    #           author '...', email: '...', twitter: '...'
+    #     
+    #           disclosure_date 'YYY-MM-DD'
+    #           release_date 'YYYY-MM-DD'
+    #
+    #           advisory 'CVE-YYYY-NNNN'
+    #           advisory 'GHSA-XXXXXX'
+    #           software 'TestHTTP'
+    #           software_versions '1.0.0'..'1.5.4'
+    #
+    #           param :cmd, desc: 'The command to run'
+    #
+    #           def test
+    #             # ...
+    #           end
+    #
+    #           def build
+    #             # ...
+    #           end
+    #
+    #           def launch
+    #             # ...
+    #           end
+    #
+    #           def cleanup
+    #             # ...
+    #           end
+    #
+    #         end
+    #       end
+    #     end
+    #
+    # ### register
+    #
+    # Registers the exploit with `Exploits`.
+    #
+    #     register 'my_exploit'
+    #
+    # ### quality
+    # 
+    # Defines the quality level of the exploit. Accepted values are:
+    #
+    # * `:testing`
+    # * `:poc`
+    # * `:weaponized`
+    #
+    #     quality :poc
+    #
+    # ### summary
+    #
+    # Defines a short one-sentence description of the exploit.
+    #
+    #     summary 'My first exploit'
+    #
+    # ### description
+    #
+    # Defines a longer multi-paragraph escription of the exploit.
+    #
+    #     description <<~EOS
+    #       This is my first exploit.
+    #       Bla bla bla bla.
+    #     EOS
+    #
+    # **Note:** that `<<~` heredoc, unlike the regular `<<` heredoc, removes
+    # leading whitespace.
+    #
+    # ### author
+    #
+    # Add an author's name and additional information to the exploit.
+    #
+    #     author 'John Smith'
+    #
+    #     author 'doctor_doom', email: '...', twitter: '...'
+    #
+    # ### software
+    # 
+    # Defines the software which the exploit targets.
+    #
+    #     software 'TestApp'
+    #
+    # ### software_versions
+    #
+    # Defines the software versions which the exploit targets:
+    #
+    #     software_versions %w[
+    #       1.0.0
+    #       1.0.1
+    #       1.0.2
+    #       1.1.0
+    #     ]
+    #
+    #     software_versions '1.0.0'..'1.5.4'
+    #
+    # ### param
+    #
+    # Defines a user configurable param. Params may have a type class, but
+    # default to `String`. Params must have a one-line description.
+    #
+    #     param :str, desc: 'A basic string param'
+    #     
+    #     param :feature_flag, Boolean, desc: 'A boolean param'
+    #     
+    #     param :enum, Enum[:one, :two, :three],
+    #                  desc: 'An enum param'
+    #
+    #     param :num1, Integer, desc: 'An integer param'
+    #     
+    #     param :num2, Integer, default: 42,
+    #                          desc: 'A param with a default value'
+    #     
+    #     param :num3, Integer, default: ->{ rand(42) },
+    #                           desc: 'A param with a dynamic default value'
+    #     
+    #     param :float, Float, 'Floating point param'
+    #
+    #     param :url, URI, desc: 'URL param'
+    #
+    #     param :pattern, Regexp, desc: 'Regular Expression param'
+    # 
+    # Params may then be accessed in instance methods using `params` Hash.
+    #
+    #     param :padding, Integer, desc: 'Amount of additional padding'
+    #
+    #     def build
+    #       # ...
+    #     
+    #       if params[:padding]
+    #         @buffer << 'A' * params[:padding]
+    #       end
+    #     end
+    #
+    # ### test
+    #
+    # The method which may define tests which confirm whether the target is
+    # vulnerable. The method must return a {Exploit#Vulnerable Vulnerable},
+    # {Exploit#NotVulnerable NotVulnerable}, or an {Exploit#Unknown} object.
+    #
+    #     def test
+    #       case http.get_body('/')
+    #       when /Powered by Foo 4\.19\./
+    #         Vulnerable('host is vulnerable')
+    #       when /Powered by Foo 4\.2[0-9]\./
+    #         NotVulnerable('host is patched')
+    #       else
+    #         Unknown('cannot determine whether the host is vulnerable or not')
+    #       end
+    #     end
+    #
+    # ### build
+    # 
+    # The method which defines the logic that builds the exploit before
+    # launching it.
+    #
+    #     def build
+    #       @buffer = "..."
+    #       @buffer << "..."
+    #     end
+    #
+    # ### launch
+    #
+    # The method which launches the built exploit against the target.
+    #
+    #     def launch
+    #       @socket = tcp_connect do |socket|
+    #         socket.write(@buffer)
+    #       end
+    #     end
+    #
+    # ### cleanup
+    #
+    # The method which defines additional cleanup tasks after the exploit has
+    # successfully launched and any post-exploitation tasks have been completed.
+    #
+    #     def cleanup
+    #       @socket.close
+    #     end
+    #
     class Exploit
 
-      include Parameters
-      include Cacheable
-      include Model::HasName
-      include Model::HasDescription
-      include Model::HasVersion
-      include Model::HasLicense
-      include Payloads::HasPayload
-      include Controls::Behaviors
-      include UI::Output::Helpers
-      include Verifiers
+      include Core::Metadata::ID
+      include Core::Metadata::Authors
+      include Core::Metadata::Summary
+      include Core::Metadata::Description
+      include Core::Metadata::References
+      include Core::Params::Mixin
+      include Support::CLI::Printing
 
       #
-      # Creates a new Ronin::Exploits::Exploit object using the given
-      # _block_.
+      # Registers the exploit with the given name.
       #
-      #   ronin_exploit do
-      #     ...
-      #   end
+      # @param [String] exploit_id
+      #   The exploit's `id`.
       #
-      contextify :ronin_exploit
-      
-      # Primary key of the exploit
-      property :id, Serial
-
-      # The status of the exploit (either, :potential, :proven or
-      # :weaponized)
-      property :status, Enum[
-        :potential,
-        :proven,
-        :weaponized
-      ], :default => :potential
-
-      # The disclosure status of the exploit (any of, :private,
-      # :vendor_aware, :in_wild and :public)
-      property :disclosure, Flag[
-        :private,
-        :in_wild,
-        :vendor_aware,
-        :public
-      ]
-
-      # Author(s) of the exploit
-      has n, :authors, :model => 'Ronin::Exploits::ExploitAuthor'
-
-      # Behaviors that the exploit allows
-      has n, :controls, :model => 'Ronin::Exploits::Control'
-
-      # Targets for the exploit
-      has n, :targets
-
-      # Validations
-      validates_present :name
-      validates_is_unique :version, :scope => [:name]
-
-      # Exploit target
-      attr_writer :target
-
-      # Characters to restrict
-      attr_reader :restricted_chars
-
-      # Encoders to run on the payload
-      attr_reader :encoders
-
-      # The raw unencoded payload
-      attr_reader :raw_payload
-
-      # The encoded payload
-      attr_reader :encoded_payload
-
-      #
-      # Creates a new Exploit object.
+      # @api public
       #
-      # @param [Hash] attributes
-      #   Additional attributes used to initialize the exploit's model
-      #   attributes and parameters.
-      #
-      # @yield []
-      #   If a block is given, it will be evaluated in the newly created
-      #   Exploit object.
-      #
-      def initialize(attributes={},&block)
-        super(attributes)
-
-        initialize_params(attributes)
-
-        @target = nil
-        @built = false
-        @deployed = false
-
-        @restricted_chars = Chars::CharSet.new
-        @encoders = []
-
-        instance_eval(&block) if block
+      def self.register(exploit_id)
+        id(exploit_id)
+        Exploits.register(exploit_id,self)
       end
 
       #
-      # Finds all exploits written by a specific author.
+      # Gets or sets the quality of the exploit.
       #
-      # @param [String] name
-      #   The name of the author.
+      # @param [:testing, :poc, :weaponized, nil] new_quality
+      #   The optional new quality to set.
       #
-      # @return [Array<Exploit>]
-      #   The exploits written by the author.
+      # @return [:testing, :poc, :weaponized, nil]
+      #   The exploit's quality.
       #
-      def self.written_by(name)
-        all(self.authors.name.like => "%#{name}%")
+      # @api public
+      #
+      def self.quality(new_quality=nil)
+        if new_quality then @new_quality = new_quality
+        else                @new_quality
+        end
       end
 
       #
-      # Finds all exploits written for a specific organization.
+      # Gets or sets the release date for the exploit.
       #
-      # @param [String] name
-      #   The name of the organization.
+      # @param [String, nil] new_date
+      #   The optional new release date to set.
       #
-      # @return [Array<Exploit>]
-      #   The exploits written for the organization.
+      # @return [Date, nil]
+      #   The exploit's release date.
       #
-      def self.written_for(name)
-        all(self.authors.organization.like => "%#{name}%")
+      def self.release_date(new_date=nil)
+        if new_date then @release_date = Date.parse(new_date)
+        else             @release_date
+        end
       end
 
       #
-      # Finds all exploits which target a given architecture.
-      #
-      # @param [String, Symbol] name
-      #   The name of the architecture.
+      # Determines whether the exploit has been publically released yet.
       #
-      # @return [Array<Exploit>]
-      #   The exploits targeting the architecture.
+      # @return [Boolean]
       #
-      def self.targeting_arch(name)
-        all(self.targets.arch.name => name.to_s)
+      def self.released?
+        !release_date.nil?
       end
 
       #
-      # Finds all exploits which target a given OS.
+      # Gets or sets the disclosure date for the exploit.
       #
-      # @param [String, Symbol] name
-      #   The name of the OS.
+      # @param [String, nil] new_date
+      #   The optional new disclosure date to set.
       #
-      # @return [Array<Exploit>]
-      #   The exploits targeting the OS.
+      # @return [Date, nil]
+      #   The exploit's disclosure date.
       #
-      def self.targeting_os(name)
-        all(self.targets.os.name => name.to_s)
+      # @example
+      #   disclosure_date '2022-04-20'
+      #
+      def self.disclosure_date(new_date=nil)
+        if new_date then @disclosure_date = Date.parse(new_date)
+        else             @disclosure_date
+        end
       end
 
       #
-      # Finds all exploits which target a given product.
+      # Determines whether the exploit has been disclosed yet.
       #
-      # @param [String, Symbol] name
-      #   The name of the product.
-      #
-      # @return [Array<Exploit>]
-      #   The exploits targeting the product.
+      # @return [Boolean]
       #
-      def self.targeting_product(name)
-        all(self.targets.product.name => "%#{name}%")
+      def self.disclosed?
+        !disclosure_date.nil?
       end
 
       #
-      # Adds a new author to the exploit.
-      #
-      # @param [Hash] attributes
-      #   Additional attributes to create the ExploitAuthor object with.
+      # The advisory IDs for the exploit.
       #
-      # @yield [author]
-      #   If a block is given, it will be passed the newly created author
-      #   object.
+      # @return [Set<Advisory>]
+      #   The set of advisories for the exploit.
       #
-      # @yieldparam [ExploitAuthor] author
-      #   The author object tied to the exploit.
-      #
-      # @example
-      #   author :name => 'Anonymous',
-      #          :email => 'anon@example.com',
-      #          :organization => 'Anonymous LLC'
+      # @api semipublic
       #
-      def author(attributes={},&block)
-        self.authors << ExploitAuthor.new(attributes,&block)
+      def self.advisories
+        @advisories ||= Set.new
       end
 
       #
-      # Adds a new target to the exploit.
+      # Adds an advisory for the exploit.
       #
-      # @param [Hash] attributes
-      #   Additional attributes to create the target with.
+      # @param [String] id
+      #   The advisory ID.
       #
-      # @yield [target]
-      #   If a block is given, it will be passed the newly created target.
+      # @param [String] url
+      #   The optional advisory URL. If the advisory `id` begins with `CVE-`
+      #   or `GHSA-`, then the URL will automatically be derived from the `id`.
       #
-      # @yieldparam [Target] target
-      #   The newly created target.
+      # @api public
       #
-      # @example
-      #   targeting do |target|
-      #     target.arch :i686
-      #     target.os :name => 'Linux'
-      #   end
-      #
-      def targeting(attributes={},&block)
-        self.targets << Target.new(attributes,&block)
+      def self.advisory(id,url=Advisory.url_for(id))
+        advisories << Advisory.new(id,url)
       end
 
       #
-      # Adds new characters to the list of restricted characters.
+      # Gets or sets the software which the exploit targets.
       #
-      # @param [Array<String>] chars
-      #   The character to restrict.
+      # @param [String, nil] new_software
+      #   the optional new software name to set.
       #
-      # @return [Array<String>]
-      #   The new list of restricted characters.
+      # @return [String, nil]
+      #   The name of the software which the exploit targets.
       #
-      # @example
-      #   restrict 0x00, "\n"
-      #   # => #<Chars::CharSet: {"\0", "\n"}>
+      # @api public
       #
-      def restrict(*chars)
-        @restricted_chars += chars
+      def self.software(new_software=nil)
+        if new_software
+          @software = new_software
+        else
+          @software ||= if superclass < Exploit
+                          superclass.software
+                        end
+        end
       end
 
       #
-      # Adds a new encoder to the list of encoders to use for encoding the
-      # payload.
-      #
-      # @param [#encode] encoder
-      #   The payload encoder object to use.
-      #   Must provide an encode method.
-      #
-      # @yield [payload]
-      #   If a block is given, and an encoder object is not, the block will
-      #   be used to encode the payload.
-      #
-      # @yieldparam [String] payload
-      #   The payload to be encoded.
-      #
-      # @return [Array]
-      #   The new list of encoders to use to encode the payload.
+      # Gets or sets the software version(s) which the exploit targets.
       #
-      # @raise [RuntimeError]
-      #   The payload encoder object does not provide an encode method.
+      # @param [Array<String>, Range<String,String>, nil] new_software_versions
+      #   the optional new software version(s) to set.
       #
-      # @raise [ArgumentError]
-      #   Either a payload encoder object or a block can be given.
+      # @return [Array<String>, Range<String,String>, nil]
+      #   The name of the software version which the exploit targets.
       #
-      # @example
-      #   exploit.encode_payload(some_encoder)
-      #
-      # @example
-      #   exploit.encode_payload do |payload|
-      #     # ...
-      #   end
+      # @api public
       #
-      def encode_payload(encoder=nil,&block)
-        if encoder
-          unless encoder.respond_to?(:encode)
-            raise(RuntimeError,"The payload encoder must provide an encode method",caller)
-          end
-
-          @encoders << encoder
-        elsif (encoder.nil? && block)
-          @encoders << block
+      def self.software_versions(new_software_versions=nil)
+        if new_software_versions
+          @software_versions = new_software_versions
         else
-          raise(ArgumentError,"either a payload encoder or a block can be given",caller)
+          @software_versions ||= if superclass < Exploit
+                                   superclass.software_versions
+                                 end
         end
       end
 
       #
-      # Lists the behaviors controlled by the exploit and the payload, if
-      # one is being used.
+      # Returns the type or kind of exploit.
       #
-      # @return [Array<Symbol>]
-      #   The combined behaviors controlled by the exploit.
+      # @return [Symbol]
       #
-      def behaviors
-        total_behaviors = super
-
-        if @payload
-          total_behaviors = (total_behaviors + @payload.behaviors).uniq
-        end
-
-        return total_behaviors
-      end
-
+      # @note
+      #   This is used internally to map an exploit class to a printable type.
       #
-      # @return [Array<Arch>]
-      #   The targeted architectures.
+      # @api private
       #
-      def targeted_archs
-        self.targets.map { |target| target.arch }.compact
+      def self.exploit_type
+        :exploit
       end
 
       #
-      # @return [Array<OS>]
-      #   The targeted OSes.
+      # Initializes the exploit.
       #
-      def targeted_oses
-        self.targets.map { |target| target.os }.compact
-      end
-
-      #
-      # @return [Array<Product>]
-      #   The targeted Products.
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
       #
-      def targeted_products
-        self.targets.map { |target| target.product }.compact
+      def initialize(**kwargs)
+        super(**kwargs)
       end
 
       #
-      # Selects a target to use in exploitation.
+      # Initializes and runs the exploit.
       #
-      # @param [Integer, Hash] index_or_query
-      #   The index within #targets or a query to select the target.
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments for {#initialize}.
       #
-      # @yield [target]
-      #   If a block is given, it will be used to select the desired
-      #   target from #targets.
+      # @yield [exploit]
+      #   If a block is given, it will be yielded the exploit after it has been
+      #   launched. Once the block has returned, {#cleanup} will automatically
+      #   be called.
       #
-      # @yieldparam [Target] target
-      #   The potential target to review.
+      # @yieldparam [Exploit] exploit
+      #   The launched exploit.
       #
-      # @example
-      #   use_target!(2)
+      # @return [Exploit]
+      #   The launched exploit.
       #
-      # @example
-      #   use_target!(Target.arch.name => 'i686')
+      # @since 1.0.0
       #
-      # @example
-      #   use_target! { |target| target.arch == Arch.i686 }
-      #
-      # @since 0.3.0
-      #
-      def use_target!(index_or_query=0,&block)
-        @target = if block
-                    self.targets.find(&block)
-                  elsif index_or_query.kind_of?(Hash)
-                    self.targets.first(index_or_query)
-                  elsif index_or_query.kind_of?(Integer)
-                    self.targets[index_or_query]
-                  end
+      def self.exploit(**kwargs,&block)
+        new(**kwargs).exploit(&block)
       end
 
       #
-      # @return [Target]
-      #   The current target to use in exploitation.
+      # Validates that the exploit is ready to be used.
       #
-      def target
-        @target ||= self.targets.first
-      end
-
+      # @raise [Ronin::Core::Params::RequiredParam]
+      #   One of the required params was not set.
       #
-      # @return [Arch]
-      #   The current targeted architecture.
+      # @raise [ValidationError]
+      #   Another kind of validation error occurred.
       #
-      def arch
-        target.arch if target
+      # @api semipublic
+      #
+      def perform_validate
+        validate_params
+        validate
       end
 
       #
-      # @return [OS]
-      #   The current targeted OS.
+      # Tests whether the target is vulnerable or not.
       #
-      def os
-        target.os if target
-      end
-
+      # @api semipublic
       #
-      # @return [Product]
-      #   The current targeted product.
+      # @since 1.0.0
       #
-      def product
-        target.product if target
+      def perform_test
+        test
       end
 
       #
-      # Associates a payload with the exploit, and the exploit with the
-      # payload.
+      # Builds the exploit.
       #
-      # @param [Payload] new_payload
-      #   The new payload to associate with the exploit.
+      # @api semipublic
       #
-      # @return [Payload]
-      #   The new payload.
+      # @since 1.0.0
       #
-      # @since 0.3.0
-      #
-      def payload=(new_payload)
-        if (@payload && new_payload.nil?)
-          @payload.exploit = nil
-        end
-
-        super(new_payload)
-
-        if @payload
-          print_info "Using payload: #{new_payload}"
-
-          @payload.exploit = self
-        end
-
-        return @payload
+      def perform_build
+        build
       end
 
       #
-      # Sets the raw payload to use with the exploit.
+      # Launches the exploit.
       #
-      # @param [String, #to_s] new_raw_payload
-      #   The new raw payload to use with the exploit.
+      # @api semipublic
       #
-      # @return [String]
-      #   The new raw payload of the exploit.
+      # @since 1.0.0
       #
-      def raw_payload=(new_raw_payload)
-        new_raw_payload = new_raw_payload.to_s
-
-        print_debug "Using raw payload: #{new_raw_payload.dump}"
-
-        @raw_payload = new_raw_payload
+      def perform_launch
+        launch
       end
 
       #
-      # Builds the current payload, saving the result to the +@raw_payload+
-      # instance variable.
-      #
-      # @param [Hash] options
-      #   Additional options to build the paylod with.
+      # Cleans up the exploit.
       #
-      # @return [String]
-      #   The built payload.
+      # @api semipublic
       #
-      # @see Payload#build!
-      # @since 0.3.0
+      # @since 1.0.0
       #
-      def build_payload!(options={})
-        if @payload
-          @raw_payload = ''
-
-          @payload.build!(options)
-          @raw_payload = @payload.raw_payload
-        else
-          @raw_payload ||= ''
-        end
-
-        return @raw_payload
+      def perform_cleanup
+        cleanup
       end
 
       #
-      # Encodes the current payload and saves the result in the
-      # +@encoded_payload+ instance variable.
+      # Builds the exploit and then launchs the exploit.
       #
-      # @return [String]
-      #   The encoded payload.
+      # @param [Boolean] dry_run
+      #   If `true` performs a dry-run by only calling {#build} and **not**
+      #   launching the exploit.
       #
-      def encode_payload!
-        @encoded_payload = @raw_payload.to_s
-
-        @encoders.each do |encoder|
-          print_debug "Encoding payload: #{@encoded_payload.dump}"
-
-          new_payload = if encoder.respond_to?(:encode)
-                          encoder.encode(@encoded_payload)
-                        elsif encoder.respond_to?(:call)
-                          encoder.call(@encoded_payload)
-                        end
-
-          @encoded_payload = (new_payload || @encoded_payload).to_s
-        end
-
-        return @encoded_payload
-      end
-
+      # @yield [exploit]
+      #   If a block is given, it will be yielded the exploit after it has been
+      #   launched. Once the block has returned, {#cleanup} will automatically
+      #   be called.
       #
-      # @return [Boolean]
-      #   Specifies whether the exploit is built.
+      # @yieldparam [Exploit] exploit
+      #   The launched exploit.
       #
-      def built?
-        @built == true
-      end
-
+      # @return [Exploit]
+      #   The launched exploit.
       #
-      # Builds the exploit and checks for restricted characters or patterns.
+      # @api public
       #
-      # @param [Hash] options
-      #   Additional options to also use as parameters.
+      # @since 1.0.0
       #
-      def build!(options={},&block)
-        self.params = options
-
-        print_debug "Exploit parameters: #{self.params.inspect}"
-
-        @built = false
+      def exploit(dry_run: false)
+        perform_build
 
-        build_payload!(options)
-        encode_payload!
+        unless dry_run
+          perform_launch
 
-        print_info "Building exploit ..."
-
-        build
-        
-        print_info "Exploit built!"
-
-        @built = true
-
-        if block
-          if block.arity == 1
-            block.call(self)
-          else
-            block.call()
+          if block_given?
+            yield self
+            perform_cleanup
           end
         end
 
@@ -560,230 +563,146 @@ module Ronin
       end
 
       #
-      # Verifies the exploit is built, properly configured, built and
-      # ready deployment.
+      # @group Exploit API Methods
       #
-      # @return [true]
-      #   The exploit is built and ready for deployment.
+
       #
-      # @raise [ExploitNotBuilt]
-      #   The exploit has not been built, and cannot be deployed.
+      # Place holder methods for additional validation logic.
       #
-      def verify!
-        unless built?
-          raise(ExploitNotBuilt,"cannot deploy an unbuilt exploit",caller)
-        end
-
-        print_info "Verifying exploit ..."
-
-        verify
-
-        print_info "Exploit verified!"
-        return true
-      end
-
+      # @abstract
       #
-      # @return [Boolean]
-      #   Specifies whether the exploit has previously been deployed.
+      # @api public
+      #
+      # @since 1.0.0
       #
-      def deployed?
-        @deployed == true
+      def validate
       end
 
       #
-      # Verifies then deploys the exploit. If a payload has been set,
-      # the payload will also be deployed.
-      #
-      # @yield [exploit]
-      #   If a block is given, it will be passed the deployed exploit.
+      # Returns a vulnerable test result for the {#test} method.
       #
-      # @yieldparam [Exploit] exploit
-      #   The deployed exploit.
+      # @return [TestResult::Vulnerable]
       #
-      # @return [Exploit]
-      #   The deployed exploit.
+      # @example
+      #   def test
+      #     # ...
+      #     return Vulnerable("the host is vulnerable")
+      #     # ...
+      #   end
       #
-      # @raise [ExploitNotBuilt]
-      #   The exploit has not been built, and cannot be deployed.
+      # @since 1.0.0
       #
-      def deploy!(&block)
-        verify!
-
-        print_info "Deploying exploit ..."
-        @deployed = false
-
-        deploy()
-
-        print_info "Exploit deployed!"
-        @deployed = true
-
-        @payload.deploy!() if @payload
-
-        if block
-          if block.arity == 1
-            block.call(self)
-          else
-            block.call()
-          end
-        end
-
-        return self
+      def Vulnerable(message)
+        TestResult::Vulnerable.new(message)
       end
 
       #
-      # Builds, verified and then deploys the exploit.
+      # Returns a not vulnerable test result for the {#test} method.
+      #
+      # @return [TestResult::NotVulnerable]
+      #
+      # @example
+      #   def test
+      #     # ...
+      #     return NotVulnerable("the host is not vulnerable")
+      #     # ...
+      #   end
       #
-      # @param [Hash] options
-      #   Additional options to build the exploit with.
+      # @since 1.0.0
       #
-      # @option options [Boolean] :dry_run (false)
-      #   Specifies whether to do a dry-run of the exploit, where the
-      #   exploit will be built, verified but *not* deployed.
+      def NotVulnerable(message)
+        TestResult::NotVulnerable.new(message)
+      end
+
       #
-      # @yieldparam [Exploit] exploit
-      #   The deployed exploit.
+      # Returns an unknown test result for the {#test} method.
       #
-      # @return [Exploit]
-      #   The deployed exploit.
+      # @return [TestResult::Unknown]
       #
-      # @return [Exploit]
-      #   The deployed exploit.
+      # @example
+      #   def test
+      #     # ...
+      #     return Unknown("cannot determine whether the host is vulnerable")
+      #     # ...
+      #   end
       #
-      # @since 0.3.0
+      # @since 1.0.0
       #
-      def exploit!(options={},&block)
-        build!(options)
-
-        unless options[:dry_run]
-          deploy!(&block)
-        end
-
-        return self
+      def Unknown(message)
+        TestResult::Unknown.new(message)
       end
 
       #
-      # Converts the exploit to a String.
+      # Place holder method for testing whether the targeet is vulnerable.
       #
-      # @return [String]
-      #   The name and version of the exploit.
+      # @return [Test::Vulnerable, Test::NotVulnerable, Test::Unknown]
       #
-      def to_s
-        if (self.name && self.version)
-          "#{self.name} #{self.version}"
-        elsif self.name
-          self.name
-        elsif self.version
-          self.version
-        end
-      end
-
+      # @example
+      #   def test
+      #     case http.get_body('/')
+      #     when /Powered by Foo 4\.19\./
+      #       Vulnerable('host is vulnerable')
+      #     when /Powered by Foo 4\.2[0-9]\./
+      #       NotVulnerable('host is patched')
+      #     else
+      #       Unknown('cannot determine whether the host is vulnerable or not')
+      #     end
+      #   end
       #
-      # Inspects the contents of the exploit.
+      # @abstract
       #
-      # @return [String]
-      #   The inspected exploit.
+      # @since 1.0.0
       #
-      def inspect
-        str = "#{self.class}: #{self}"
-        str << " #{self.params.inspect}" unless self.params.empty?
-
-        return "#<#{str}>"
+      def test
+        Unknown("no vulnerability testing logic defined")
       end
 
-      protected
-
       #
-      # Extends the exploit with the helper module defined in
-      # Ronin::Exploits::Helpers that has the similar name.
+      # Place holder method that builds the exploit.
       #
-      # @param [Symbol, String] name
-      #   The snake-case name of the exploit helper to load and extend the
-      #   exploit with.
+      # @abstract
       #
-      # @return [true]
-      #   The exploit helper was successfully loaded.
+      # @api public
       #
-      # @raise [UnknownHelper]
-      #   No valid helper module could be found or loaded with the similar
-      #   name.
+      # @since 1.0.0
       #
-      # @example
-      #   helper :buffer_overflow
-      #
-      def helper(name)
-        name = name.to_s
-        module_name = name.to_const_string
-
-        begin
-          require_within File.join('ronin','exploits','helpers'), name
-        rescue Gem::LoadError => e
-          raise(e)
-        rescue ::LoadError
-          raise(UnknownHelper,"unknown helper #{name.dump}",caller)
-        end
-
-        unless Ronin::Exploits::Helpers.const_defined?(module_name)
-          raise(UnknownHelper,"unknown helper #{name.dump}",caller)
-        end
-
-        helper_module = Ronin::Exploits::Helpers.const_get(module_name)
-
-        unless helper_module.kind_of?(Module)
-          raise(UnknownHelper,"unknown helper #{name.dump}",caller)
-        end
-
-        extend helper_module
-        return true
+      def build
       end
 
       #
-      # Reviews the text for restricted characters.
+      # Place holder method that launches the exploit.
       #
-      # @param [String] text
-      #   The text to check for restricted characters within.
-      #
-      # @return [Boolean]
-      #   Specifies whether the text contains any restricted characters.
+      # @abstract
       #
-      def is_restricted?(text)
-        text.each_byte do |b|
-          return true if @restricted_chars.include?(b)
-        end
-
-        return false
-      end
-
+      # @api public
       #
-      # Default build method.
+      # @since 1.0.0
       #
-      def build
+      def launch
       end
 
       #
-      # Default exploit verify method.
+      # Place holder method that cleans up after the exploit.
       #
-      def verify
-      end
-
+      # @abstract
+      #
+      # @api public
       #
-      # Default exploit deploy method.
+      # @since 1.0.0
       #
-      def deploy(&block)
-        block.call(self) if block
+      def cleanup
       end
 
       #
-      # Relays method calls to the payload, if the payload is a kind of 
-      # Ronin::Payloads::Payload.
+      # Indicates that the exploit has failed.
       #
-      # @since 0.3.0
+      # @param [String] message
+      #   The failure message.
       #
-      def method_missing(name,*arguments,&block)
-        if @payload.kind_of?(Ronin::Payloads::Payload)
-          return @payload.send(name,*arguments,&block)
-        end
-
-        super(name,*arguments,&block)
+      # @raise [ExploitFailed]
+      #
+      def fail(message)
+        raise(ExploitFailed,message)
       end
 
     end