ronin-exploits 0.1.1 → 0.2.0

data/lib/ronin/exploits/exceptions/target_unspecified.rb

@@ -0,0 +1,29 @@
+#
+#--
+# 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
+#++
+#
+
+module Ronin
+  module Exploits
+    class TargetUnspecified < RuntimeError
+    end
+  end
+end

data/lib/ronin/exploits/exceptions/unknown_helper.rb

@@ -0,0 +1,29 @@
+#
+#--
+# 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
+#++
+#
+
+module Ronin
+  module Exploits
+    class UnknownHelper < RuntimeError
+    end
+  end
+end

data/lib/ronin/exploits/exploit.rb

@@ -21,21 +21,31 @@
 #++
 #
 
-require 'ronin/exploits/requirement'
-require 'ronin/exploits/impact'
+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/exploit_author'
+require 'ronin/exploits/target'
+require 'ronin/exploits/allow'
+require 'ronin/payloads/payload'
 require 'ronin/vuln/behavior'
-require 'ronin/objectify'
+require 'ronin/cacheable'
 require 'ronin/has_license'
 
+require 'parameters'
+require 'chars/char_set'
+
 module Ronin
   module Exploits
     class Exploit
 
-      include Objectify
+      include Parameters
+      include Cacheable
       include HasLicense
 
-      objectify :ronin_exploit
+      contextify :ronin_exploit
       
       # Primary key of the exploit
       property :id, Serial
@@ -49,30 +59,63 @@ module Ronin
       # Description of the exploit
       property :description, Text
 
+      # 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, :class_name => 'ExploitAuthor'
+      has n, :authors, :class_name => 'Ronin::Exploits::ExploitAuthor'
 
-      # The requirements of the exploit
-      has n, :requirements
+      # Behaviors that the exploit allows
+      has n, :allows
 
-      # Impact of the exploit
-      has n, :impact, :class_name => 'Impact'
+      # Targets for the exploit
+      has n, :targets
 
       # Validations
       validates_present :name
       validates_is_unique :version, :scope => [:name]
 
+      # Exploit target
+      attr_accessor :target
+
       # Exploit payload
       attr_accessor :payload
 
+      # Characters to restrict
+      attr_reader :restricted_chars
+
+      # Encoders to run on the payload
+      attr_reader :encoders
+
+      # The encoded payload
+      attr_reader :encoded_payload
+
       #
       # Creates a new Exploit object with the given _attributes_.
       #
       def initialize(attributes={},&block)
         super(attributes)
 
+        @target = nil
         @built = false
 
+        @restricted_chars = Chars::CharSet.new
+        @encoders = []
+
         instance_eval(&block) if block
       end
 
@@ -103,35 +146,117 @@ module Ronin
       # If a _block_ is given, it will be passed to the newly created
       # ExploitAuthor object.
       #
+      #   author :name => 'Anonymous',
+      #          :email => 'anon@example.com',
+      #          :organization => 'Anonymous LLC'
+      #
       def author(attributes={},&block)
-        self.authors << ExploitAuthor.new(
-          attributes.merge(:exploit => self),
-          &block
-        )
+        self.authors << ExploitAuthor.new(attributes,&block)
       end
 
       #
-      # Adds a new Requirement for the specified _behavior_.
+      # Adds a new Allow object granting the specified _behavior_.
       #
-      def requires(behavior)
-        self.requirements << Requirement.new(
-          :behavior => behavior,
-          :exploit => self
-        )
+      #   allowing :code_exec
+      #
+      def allowing(behavior)
+        self.allows << Allow.new(:behavior => Vuln::Behavior[behavior])
+      end
 
-        return self
+      #
+      # Adds a new Target with the given _attributes_ and _block_.
+      #
+      #   targeting do |target|
+      #     target.arch :i686
+      #     target.os :name => 'Linux'
+      #   end
+      #
+      def targeting(attributes={},&block)
+        self.targets << Target.new(attributes,&block)
       end
 
       #
-      # Adds a new Impact granting the specified _behavior_.
+      # Adds the given _chars_ to the restricted list of characters.
+      #
+      #   restrict 0x00, "\n"
+      #   # => #<Chars::CharSet: {"\0", "\n"}>
       #
-      def allows(behavior)
-        self.impact << Impact.new(
-          :behavior => behavior,
-          :exploit => self
-        )
+      def restrict(*chars)
+        @restricted_chars += chars
+      end
 
-        return self
+      #
+      # Adds the specified _encoder_ to the list of encoders to use on the
+      # payload.
+      #
+      def encode_with(encoder)
+        @encoders << encoder
+      end
+
+      #
+      # Returns the Array of targeted architectures.
+      #
+      def targeted_archs
+        self.targets.map { |target| target.arch }.compact
+      end
+
+      #
+      # Returns the Array of targeted OSes.
+      #
+      def targeted_oses
+        self.targets.map { |target| target.os }.compact
+      end
+
+      #
+      # Returns the Array of targeted Products.
+      #
+      def targeted_products
+        self.targets.map { |target| target.product }.compact
+      end
+
+      #
+      # Explicitly selects the first target that matches the specified
+      # _block_.
+      #
+      #   select_target { |target| target.arch == Arch.i686 }
+      #
+      def select_target(&block)
+        @target = self.targets.first(&block)
+      end
+
+      #
+      # Returns the current target.
+      #
+      def target
+        @target ||= self.targets.first
+      end
+
+      #
+      # Returns the currently targeted architecture.
+      #
+      def arch
+        target.arch if target
+      end
+
+      #
+      # Returns the currently targeted OS.
+      #
+      def os
+        target.os if target
+      end
+
+      #
+      # Returns the currently targeted Product.
+      #
+      def product
+        target.product if target
+      end
+
+      #
+      # Returns the behaviors allowed by the exploit.
+      #
+      def behaviors
+        self.allows.map { |allow| allow.behavior }
       end
 
       #
@@ -150,21 +275,31 @@ module Ronin
       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.
+      # Builds and encodes the current payload, returning the encoded
+      # payload in String form.
       #
-      def vulnerable?
-        nil
-      end
+      def encode_payload!
+        @encoded_payload = ''
 
-      #
-      # Default builder method.
-      #
-      def builder
+        if @payload
+          if @payload.class.include?(Parameters)
+            @payload.params = self.params
+          end
+
+          if @payload.kind_of?(Payloads::Payload)
+            @encoded_payload = @payload.build!
+          else
+            @encoded_payload = @payload.to_s
+          end
+
+          @encoders.each do |encoder|
+            if (new_payload = encoder.call(@encoded_payload))
+              @encoded_payload = new_payload
+            end
+          end
+        end
+
+        return @encoded_payload
       end
 
       #
@@ -180,87 +315,205 @@ module Ronin
       # 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
+      def build!(options={})
+        if options[:payload]
+          @payload ||= options.delete(:payload)
         end
 
+        self.params = options
+
         @built = false
 
-        result = builder
+        encode_payload!
+        result = build
 
         @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
+      def verify!
         unless built?
           raise(ExploitNotBuilt,"cannot deploy an unbuilt exploit",caller)
         end
 
-        verifier
+        verify
         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
+      # deploy method. If the exploit has not been previously built, an
       # ExploitNotBuilt exception will be raised.
       #
-      def deploy(&block)
-        verify
+      def deploy!(&block)
+        verify!
 
-        if (@payload && @payload.kind_of?(Payloads::Payload))
-          deployer()
+        if @payload.kind_of?(Payloads::Payload)
+          deploy()
 
-          return @payload.deploy(&block)
+          return @payload.deploy!(&block)
         else
-          return deployer(&block)
+          return deploy(&block)
         end
       end
 
       #
-      # Builds, deploys and then cleans the exploit with the given _options_.
+      # Builds the exploit with the given _options_, then deploys the
+      # exploit with the given _block_.
       #
-      def exploit(options={},&block)
-        build(options)
+      def exploit!(options={},&block)
+        build!(options)
 
-        return deploy(&block)
+        return deploy!(&block)
       end
 
       #
-      # Returns the built exploit.
+      # Returns the name and version of the exploit.
       #
       def to_s
         "#{self.name} #{self.version}"
       end
 
+      protected
+
+      #
+      # Extends the exploit with the helper module defined in
+      # Ronin::Exploits::Helpers that has the similar specified
+      # _name_. If no module can be found within
+      # Ronin::Exploits::Helpers with the similar _name_, an
+      # UnknownHelper exception will be raised.
+      #
+      #   helper :buffer_overflow
+      #
+      def helper(name)
+        name = name.to_s
+        module_name = name.to_const_string
+
+        begin
+          require File.join('ronin','exploits','helpers',name)
+        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
+      end
+
+      #
+      # Verifies that a target has been selected. If a target has not been
+      # selected, a TargetUnspecified exception will be raised, otherwise
+      # +true+ will be returned.
+      #
+      def verify_target!
+        if target.nil?
+          raise(TargetUnspecified,"no suitable target provided",caller)
+        end
+
+        return true
+      end
+
+      #
+      # Verifies that the selected target has an arch property.
+      # If the selected target does not have an arch property, a
+      # TargetDataMissing exception will be raised, otherwise
+      # +true+ will be return.
+      #
+      def verify_arch!
+        if arch.nil?
+          raise(TargetDataMissing,"no suitable arch was provided",caller)
+        end
+      end
+
+      #
+      # Verifies that the selected target has an os property.
+      # If the selected target does not have an os property, a
+      # TargetDataMissing exception will be raised, otherwise
+      # +true+ will be return.
+      #
+      def verify_os!
+        if os.nil?
+          raise(TargetDataMissing,"no suitable os was provided",caller)
+        end
+      end
+
+      #
+      # Verifies that the selected target has an product property.
+      # If the selected target does not have an product property, a
+      # TargetDataMissing exception will be raised, otherwise
+      # +true+ will be return.
+      #
+      def verify_product!
+        if product.nil?
+          raise(TargetDataMissing,"no suitable product was provided",caller)
+        end
+      end
+
+      #
+      # Returns +true+ if the specified _text_ contains any restricted
+      # characters, returns +false+ otherwise.
+      #
+      def is_restricted?(text)
+        text.each_byte do |b|
+          return true if @restricted_chars.include?(b)
+        end
+
+        return false
+      end
+
+      #
+      # Raises a RestrictedChar exception if the specified _text_ contains
+      # any restricted characters, returns +true+ otherwise.
+      #
+      def verify_restricted!(text)
+        found = @restricted_chars.select { |char|
+          text.include?(char)
+        }.map { |char| char.dump }
+
+        unless found.empty?
+          raise(RestrictedChar,"restricted characters #{found.join(', ')} was detected in #{text.dump}",caller)
+        end
+
+        return true
+      end
+
+      #
+      # Default build method.
+      #
+      def build
+      end
+
+      #
+      # Default exploit verify method.
+      #
+      def verify
+      end
+
+      #
+      # Default exploit deploy method, passes the exploit object to the
+      # given _block_ by default.
+      #
+      def deploy(&block)
+        block.call(self) if block
+      end
+
     end
   end
 end