ronin-exploits 0.2.1 → 0.3.0

data/lib/ronin/ui/command_line/commands/payloads.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,6 @@
 # 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/ui/command_line/command'
@@ -32,38 +30,95 @@ module Ronin
       module Commands
         class Payloads < Command
 
-          def defaults
-            @query = {}
-          end
+          desc "payloads [options]", "Lists the available Payloads"
+          method_option :database, :type => :string, :default => Database.config, :aliases => '-D'
+          method_option :name, :type => :string, :aliases => '-n'
+          method_option :version, :type => :string, :aliases => '-v'
+          method_option :describing, :stype => :string, :aliases => '-d'
+          method_option :license, :type => :string, :aliases => '-l'
+          method_option :arch, :type => :string, :aliases => '-a'
+          method_option :os, :type => :string, :aliases => '-o'
+          method_option :verbose, :type => :boolean, :aliases => '-v'
 
-          def define_options(opts)
-            opts.usage = '[options]'
+          def default
+            Database.setup(options[:database])
 
-            opts.options do
-              opts.on('-D','--database URI','The URI for the database') do |uri|
-                Database.config = uri.to_s
-              end
+            payloads = Ronin::Payloads::Payload.all
 
-              opts.on('-n','--name NAME','Search for payloads with the similar NAME') do |name|
-                @query[:name.like] = name.to_s
-              end
+            if options[:name]
+              payloads = payloads.named(options[:name])
+            end
 
-              opts.on('-v','--version VERSION','Search for payloads with the similar VERSION') do |version|
-                @query[:version.like] = version.to_s
-              end
+            if options[:version]
+              payloads = payloads.revision(options[:version])
+            end
+
+            if options[:describing]
+              payloads = payloads.describing(options[:describing])
             end
-          end
 
-          def arguments(*args)
-            Database.setup
+            if options[:license]
+              payloads = payloads.licensed_under(options[:license])
+            end
 
-            payloads = Ronin::Payloads::Payload.all(@query)
+            if options[:arch]
+              payloads = payloads.targeting_arch(options[:arch])
+            end
+
+            if options[:os]
+              payloads = payloads.targeting_os(options[:os])
+            end
 
             if payloads.empty?
-              fail("could not find similar payloads")
+              print_error "Could not find similar payloads"
+              exit -1
+            end
+
+            if options.verbose?
+              payloads.each { |payload| print_payload(payload) }
+            else
+              indent do
+                payloads.each { |payload| puts payload }
+              end
             end
+          end
+
+          protected
+
+          def print_payload(payload)
+            attributes = payload.humanize_attributes(
+              :exclude => [:description]
+            )
+            attributes['Arch'] = payload.arch if payload.arch
+            attributes['OS'] = payload.os if payload.os
+
+            print_hash(attributes, :title => "Payload: #{payload}")
+
+            indent do
+              if payload.description
+                puts "Description:\n\n"
+                indent do
+                  payload.description.each_line { |line| puts line }
+                end
+                puts "\n"
+              end
 
-            payloads.each { |payload| puts "  #{payload.name}" }
+              unless payload.authors.empty?
+                payload.authors.each do |author|
+                  print_hash(author.humanize_attributes, :title => 'Author')
+                end
+              end
+
+              unless payload.behaviors.empty?
+                print_array(payload.behaviors, :title => 'Controls')
+              end
+
+              attempt { payload.load_original! }
+
+              unless payload.params.empty?
+                print_array(payload.params.values, :title => 'Parameters')
+              end
+            end
           end
 
         end

data/lib/ronin/vuln/behavior.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,7 +17,6 @@
 # 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/extensions/meta'
@@ -48,7 +46,10 @@ module Ronin
       validates_is_unique :name
 
       #
-      # Returns the name of the behavior.
+      # Converts the behavior to a String.
+      #
+      # @return [String]
+      #   The name of the behavior.
       #
       def to_s
         @name.to_s
@@ -57,35 +58,107 @@ module Ronin
       protected
 
       #
-      # Defines a new builtin Behavior with the specified _name_ and the
-      # given _description_.
+      # Defines a new builtin Behavior.
+      #
+      # @param [Symbol, String] name
+      #   The name of the behavior to predefine.
+      #
+      # @param [String] description
+      #   The description of the behavior.
+      #
+      # @example Defining a builtin Behavior
+      #   Behavior.predefine :command_exec, "Arbitrary command execution"
       #
-      def self.define(name,description=nil)
+      # @example Retrieving a predefined behavior
+      #   Behavior.command_exec
+      #
+      def self.predefine(name,description=nil)
         super(name,:name => name.to_s, :description => description)
       end
 
-      define :memory_read, "The ability to read memory"
-      define :memory_write, "The ability to write to memory"
-      define :file_create, "Arbitrary file creation"
-      define :file_read, "The ability to read from a file"
-      define :file_write, "The ability to write to a file"
-      define :file_modify, "The ability to modify an existing file"
-      define :file_ownership, "The ability to change ownership of an existing file"
-      define :file_mtime, "The ability to change the modification timestamp of a file"
-      define :file_ctime, "The ability to change the creation timestamp of a file"
-      define :socket_redirect, "The ability to redirect a socket's connection"
-      define :socket_connect, "The ability to create a network socket"
-      define :socket_listen, "The ability to listen on a network socket"
-      define :socket_read, "The ability to read from a network socket"
-      define :socket_write, "The ability to write to a network socket"
-      define :code_exec, "Arbitrary code execution"
-      define :command_exec, "Arbitrary command execution"
-      define :auth_bypass, "Authentication by-pass"
-      define :priv_escalation, "Privilege escalation"
-      define :exhaust_memory, "Exhaust freely available memory"
-      define :exhaust_disk, "Exhaust freely available disk-space"
-      define :exhaust_bandwidth, "Exhaust available bandwidth"
-      define :exahust_cpu, "Exhaust CPU performance"
+      # The ability to read memory
+      predefine :memory_read, "The ability to read memory"
+
+      # The ability to write to memory
+      predefine :memory_write, "The ability to write to memory"
+
+      # The ability to execute from memory
+      predefine :memory_exec, "The ability to execute memory"
+
+      # The ability to create files
+      predefine :file_create, "Arbitrary file creation"
+
+      # The ability to read files
+      predefine :file_read, "The ability to read from a file"
+
+      # The ability to write to a file
+      predefine :file_write, "The ability to write to a file"
+
+      # The ability to modify existing files
+      predefine :file_modify, "The ability to modify an existing file"
+
+      # The ability to change ownership on files
+      predefine :file_ownership, "The ability to change ownership of an existing file"
+
+      # The ability to change the modification time on files
+      predefine :file_mtime, "The ability to change the modification timestamp of a file"
+
+      # The ability to change the creation time on files
+      predefine :file_ctime, "The ability to change the creation timestamp of a file"
+
+      # The ability to create directories
+      predefine :dir_create, "The ability to create a directory"
+
+      # The ability to list the contents of directories
+      predefine :dir_listing, "The ability to list the contents of a directory"
+
+      # The ability to redirect socket connections
+      predefine :socket_redirect, "The ability to redirect a socket's connection"
+
+      # The ability to create socket connections
+      predefine :socket_connect, "The ability to create a network socket"
+
+      # The ability to listen on a socket
+      predefine :socket_listen, "The ability to listen on a network socket"
+
+      # The ability to read from a socket
+      predefine :socket_read, "The ability to read from a network socket"
+
+      # The ability to write to a socket
+      predefine :socket_write, "The ability to write to a network socket"
+
+      # The ability to execute code
+      predefine :code_exec, "Arbitrary code execution"
+
+      # The ability to execute commands
+      predefine :command_exec, "Arbitrary command execution"
+
+      # The ability to bypass authentication
+      predefine :auth_bypass, "Authentication by-pass"
+
+      # The ability to gain privileges
+      predefine :gain_privileges, "Gain privileges"
+
+      # The ability to drop privileges
+      predefine :drop_privileges, "Drop privileges"
+
+      # The ability to safely exit a running program
+      predefine :exit_program, "Exit program"
+
+      # The ability to crash a running program
+      predefine :crash_program, "Crash program"
+
+      # The ability to exhaust available memory
+      predefine :exhaust_memory, "Exhaust freely available memory"
+
+      # The ability to exhaust available disk space
+      predefine :exhaust_disk, "Exhaust freely available disk-space"
+
+      # The ability to exhaust available network bandwidth
+      predefine :exhaust_bandwidth, "Exhaust available bandwidth"
+
+      # The ability to exhaust CPU access
+      predefine :exhaust_cpu, "Exhaust CPU performance"
 
     end
   end

data/spec/controls/behaviors_examples.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+shared_examples_for "controls behaviors" do
+  it "should have a model to represent the controled behaviors" do
+    @controler.control_model.include?(Ronin::Model).should == true
+  end
+
+  it "should not have any controled behaviors by default" do
+    @controler.controls.should be_empty
+  end
+
+  it "should specify what behaviors to be controled" do
+    @controler.control :memory_read, :memory_write
+
+    @controler.behaviors.should == [:memory_read, :memory_write]
+  end
+
+  it "should extend a control module if on exists for the behavior" do
+    @controler.control :command_exec
+
+    @controler.behaviors.should == [:command_exec]
+    @controler.kind_of?(Ronin::Controls::Helpers::CommandExec).should == true
+  end
+
+  it "should not extend a control module if none exist for the behavior" do
+    @controler.control :exhaust_memory
+
+    @controler.behaviors.should == [:exhaust_memory]
+  end
+
+  it "should load the control modules for the behaviors" do
+    @controler.control :command_exec
+    @controler.cache!
+
+    cached = @controler.class.load_first(:name => @controler.name)
+    cached.kind_of?(Ronin::Controls::Helpers::CommandExec).should == true
+  end
+end

data/spec/exploits/exploit_spec.rb

@@ -2,12 +2,17 @@ require 'ronin/exploits/exploit'
 
 require 'spec_helper'
 require 'helpers/objects'
+require 'controls/behaviors_examples'
 
 describe Exploits::Exploit do
   before(:each) do
-    @exploit = load_exploit('test')
+    @exploit = load_exploit('simple')
+    @payload = load_payload('simple')
+    @controler = @exploit
   end
 
+  it_should_behave_like "controls behaviors"
+
   it "should require a name attribute" do
     exp2 = Exploits::Exploit.new
     exp2.should_not be_valid
@@ -36,19 +41,6 @@ describe Exploits::Exploit do
     third_exp.should be_valid
   end
 
-  it "should not have any allowances by default" do
-    @exploit.allows.should be_empty
-  end
-
-  it "should specify the behaviors allowed by the exploit" do
-    @exploit.allowing :memory_read, :memory_write
-
-    @exploit.behaviors.should == [
-      Vuln::Behavior[:memory_read],
-      Vuln::Behavior[:memory_write]
-    ]
-  end
-
   it "should allow for the extending of Helper modules" do
     @exploit.instance_eval { helper :padding }.should == true
   end
@@ -76,8 +68,20 @@ describe Exploits::Exploit do
     }.should == true
   end
 
-  it "should allow the explicit selection of a target" do
-    @exploit.select_target { |target| target.arch == Arch.i686 }
+  it "should allow the selection of a target by index" do
+    @exploit.use_target!(1)
+
+    @exploit.target.arch.should == Arch.i386
+  end
+
+  it "should allow the selection of a target that matches a block" do
+    @exploit.use_target! { |target| target.arch == Arch.i386 }
+
+    @exploit.target.arch.should == Arch.i386
+  end
+
+  it "should select the first target if nothing is passed to use_target!" do
+    @exploit.use_target!()
 
     @exploit.target.arch.should == Arch.i686
   end
@@ -104,15 +108,110 @@ describe Exploits::Exploit do
     @exploit.product.version.should == '1.5'
   end
 
+  it "should set the payloads exploit when setting the payload" do
+    @payload.exploit.should be_nil
+
+    @exploit.payload = @payload
+    @payload.exploit.should == @exploit
+  end
+
+  it "should be able to set the payload to nil" do
+    @exploit.payload = @payload
+    @exploit.payload = nil
+
+    @exploit.payload.should be_nil
+  end
+
+  it "should set the payload and the exploit of the payload to nil" do
+    @exploit.payload = @payload
+    @exploit.payload = nil
+
+    @payload.exploit.should be_nil
+  end
+
+  it "should specify the additional behaviors controlled by the payload" do
+    @payload.control :code_exec
+    @payload.control :command_exec
+    @exploit.control :code_exec
+
+    @exploit.payload = @payload
+
+    @exploit.behaviors.should == [:code_exec, :command_exec]
+  end
+
+  it "should build a raw payload" do
+    @exploit.payload = @payload
+    @exploit.build_payload!
+
+    @exploit.raw_payload.should == 'code.func'
+  end
+
+  it "should pass options to the payload when building the raw payload" do
+    @exploit.payload = @payload
+    @exploit.build_payload!(:custom => 'test')
+
+    @exploit.raw_payload.should == 'code.test'
+  end
+
+  it "should default raw_payload to an empty String, if payload is nil" do
+    @exploit.payload = nil
+    @exploit.build_payload!
+
+    @exploit.raw_payload.should == ''
+  end
+
+  it "should not reset raw_payload, if payload is nil" do
+    @exploit.payload = nil
+    @exploit.raw_payload = 'data'
+
+    @exploit.build_payload!
+    @exploit.raw_payload.should == 'data'
+  end
+
+  it "should have no payload encoders by default" do
+    @exploit.encoders.should be_empty
+  end
+
+  it "should accept blocks as payload encoders" do
+    @exploit.raw_payload = 'data'
+
+    @exploit.encode_payload do |payload|
+      payload.capitalize
+    end
+
+    @exploit.encode_payload!
+    @exploit.encoded_payload.should == 'Data'
+  end
+
+  it "should accept an object with an #encode method" do
+    @exploit.raw_payload = 'data'
+    @exploit.encode_payload(Payloads::Encoders::Encoder.new)
+
+    @exploit.encode_payload!
+    @exploit.encoded_payload.should == 'data'
+  end
+
+  it "should not accept objects without an #encode method" do
+    lambda {
+      @exploit.encode_payload(Object.new)
+    }.should raise_error(RuntimeError)
+  end
+
+  it "should accept either a payload encoder object or a block" do
+    lambda {
+      @exploit.encode_payload()
+    }.should raise_error(ArgumentError)
+  end
+
   it "should encode a String payload" do
-    @exploit.payload = 'data'
+    @exploit.raw_payload = 'data'
 
     @exploit.encode_payload!
     @exploit.encoded_payload.should == 'data'
   end
 
   it "should encode a String using encoders" do
-    @exploit.payload = 'data'
+    @exploit.raw_payload = 'data'
     @exploit.encoders << lambda { |payload| payload.upcase }
 
     @exploit.encode_payload!
@@ -120,7 +219,7 @@ describe Exploits::Exploit do
   end
 
   it "should ignore payload encoders which return nil" do
-    @exploit.payload = 'data'
+    @exploit.raw_payload = 'data'
     @exploit.encoders << lambda { |payload| nil }
 
     @exploit.encode_payload!
@@ -133,8 +232,20 @@ describe Exploits::Exploit do
     @exploit.should be_built
   end
 
-  it "should return the result of the builder" do
-    @exploit.build!.should == 'result'
+  it "should pass the built exploit to a given block" do
+    @exploit.build! do |exploit|
+      exploit.should be_built
+    end
+  end
+
+  it "should respect the arity of blocks passed to build!" do
+    @exploit.build! do
+      @exploit.should be_built
+    end
+  end
+
+  it "should return the built exploit" do
+    @exploit.build!.should be_built
   end
 
   it "should require the exploit is built before being deployed" do
@@ -149,11 +260,54 @@ describe Exploits::Exploit do
     end
   end
 
+  it "should respect the arity of blocks passed to deploy!" do
+    @exploit.build!
+
+    @exploit.deploy! do
+      @exploit.should be_deployed
+    end
+  end
+
+  it "should deploy the payload after deploying the exploit" do
+    @exploit.payload = @payload
+    @payload.should_not be_deployed
+
+    @exploit.build!
+    @exploit.deploy! do |exploit|
+      exploit.payload.should be_deployed
+    end
+  end
+
+  it "should build and deploy the exploit when exploited" do
+    @exploit.exploit!
+
+    @exploit.should be_built
+    @exploit.should be_deployed
+  end
+
+  it "should not deploy during a dry-run of the exploit" do
+    @exploit.exploit!(:dry_run => true)
+
+    @exploit.should be_built
+    @exploit.should_not be_deployed
+  end
+
   it "should return the name and the version when calling to_s" do
-    @exploit.to_s.should == 'test 0.2'
+    @exploit.to_s.should == 'simple 0.2'
   end
 
   it "should have a custom inspect method" do
-    @exploit.inspect.should == '#<Ronin::Exploits::Exploit: test 0.2>'
+    @exploit.inspect.should == '#<Ronin::Exploits::Exploit: simple 0.2>'
+  end
+
+  it "should pass missing methods to the payload" do
+    @exploit.payload = @payload
+    @exploit.some_control.should == 'control data'
+  end
+
+  it "should not pass missing methods, if payload is nil" do
+    lambda {
+      @exploit.some_control
+    }.should raise_error(NoMethodError)
   end
 end