#
#--
# Ronin Exploits - A Ruby library for Ronin that provides exploitation and
# payload crafting functionality.
#
# Copyright (c) 2007-2009 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
# (at your option) any later version.
#
# This program 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.
#
# 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/requirement'
require 'ronin/exploits/impact'
require 'ronin/exploits/exploit_author'
require 'ronin/vulnerability/behavior'
require 'ronin/objectify'
require 'ronin/has_license'

module Ronin
  module Exploits
    class Exploit

      include Objectify
      include HasLicense

      objectify :ronin_exploit
      
      # Primary key of the exploit
      property :id, Serial

      # Name of the exploit
      property :name, String, :index => true

      # Version of the exploit
      property :version, String, :default => '0.1', :index => true

      # Description of the exploit
      property :description, Text

      # Author(s) of the exploit
      has n, :authors, :class_name => 'ExploitAuthor'

      # The requirements of the exploit
      has n, :requirements

      # Impact of the exploit
      has n, :impact, :class_name => 'Impact'

      # Validations
      validates_present :name
      validates_is_unique :version, :scope => [:name]

      # Exploit payload
      attr_accessor :payload

      #
      # Creates a new Exploit object with the given _attributes_.
      #
      def initialize(attributes={},&block)
        super(attributes)

        @built = false

        instance_eval(&block) if block
      end

      #
      # Finds all exploits with names like the specified _name_.
      #
      def self.named(name)
        self.all(:name.like => "%#{name}%")
      end

      #
      # Finds all exploits with descriptions like the specified
      # _description_.
      #
      def self.describing(description)
        self.all(:description.like => "%#{description}%")
      end

      #
      # Finds the exploit with the most recent vesion.
      #
      def self.latest
        self.first(:order => [:version.desc])
      end

      #
      # Adds an ExploitAuthor with the given _attributes_ to the exploit.
      # If a _block_ is given, it will be passed the ExploitAuthro object.
      #
      def author(attributes={},&block)
        self.authors << ExploitAuthor.first_or_create(attributes,&block)
      end

      #
      # Adds a new Requirement for the Ability with the specified
      # _behavior_.
      #
      def requires(behavior)
        self.requirements << Requirement.new(
          :behavior => behavior,
          :exploit => self
        )

        return self
      end

      #
      # Adds a new Impact granting the specified _behavior_.
      #
      def allows(behavior)
        self.impact << Impact.new(
          :behavior => behavior,
          :exploit => self
        )

        return self
      end

      #
      # Switches to the _new_payload_ then calls the specified _block_.
      # After the _block_ has been called the payload will be reverted to
      # it's previous value.
      #
      def switch_payload(new_payload,&block)
        old_payload = @payload
        @payload = new_payload

        block.call(self)

        @payload = old_payload
        return self
      end

      #
      # Default vulnerability test method. Returning +true+ symbolizes
      # that the target of the exploit is vulnerable. Returning +nil+
      # symbolizes that the exploit cannot determine if the target is
      # vulnerable or not. Returning +false+ symbolizes that the target
      # of the exploit is definitely not vulnerable. Returns +nil+ by
      # default.
      #
      def vulnerable?
        nil
      end

      #
      # Default builder method.
      #
      def builder
      end

      #
      # Returns +true+ if the exploit is built, returns +false+ otherwise.
      #
      def built?
        @built == true
      end

      #
      # Builds the exploit with the given _options_ and checks for
      # restricted characters or patterns. If any restricted characters or
      # patterns are found in the built exploit, a RestrictedText exception
      # will be raised.
      #
      def build(options={})
        self.params = options

        @payload = (options[:payload] || @payload)

        if (@payload && @payload.include?(Parameters))
          @payload.params = options
        end

        @built = false

        result = builder

        @built = true
        return result
      end

      #
      # Default exploit verifier method.
      #
      def verifier
      end

      #
      # Verifies the exploit is properly configured, built and ready to be
      # deployed. An exception should be raised if the exploit is not ready
      # to be deployed, returns +true+ otherwise.
      #
      def verify
        unless built?
          raise(ExploitNotBuilt,"cannot deploy an unbuilt exploit",caller)
        end

        verifier
        return true
      end

      #
      # Default exploit deployer method, passes the exploit object to the
      # given _block_ by default.
      #
      def deployer(&block)
        block.call(self) if block
      end

      #
      # Deploys the exploit. If a _block_ is given and the payload used is
      # a kind of Payload, then the payloads deploy method will be passed
      # the given _block_. If the payload used is not a kind of Payload and
      # a _block_ is given, the _block_ will be passed to the exploits
      # deployer method. If the exploit has not been previously built, an
      # ExploitNotBuilt exception will be raised.
      #
      def deploy(&block)
        verify

        if (@payload && @payload.kind_of?(Payloads::Payload))
          deployer()

          return @payload.deploy(&block)
        else
          return deployer(&block)
        end
      end

      #
      # Builds, deploys and then cleans the exploit with the given _options_.
      #
      def exploit(options={},&block)
        build(options)

        return deploy(&block)
      end

      #
      # Returns the built exploit.
      #
      def to_s
        "#{self.name} #{self.version}"
      end

    end
  end
end