ronin-exploits 0.2.1 → 0.3.0

data/lib/ronin/payloads/helpers.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,9 +17,7 @@
 # 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/payloads/helpers/file_system'
-require 'ronin/payloads/helpers/shell'
+require 'ronin/payloads/helpers/chained'
 require 'ronin/payloads/helpers/rpc'

data/lib/ronin/payloads/helpers/chained.rb

@@ -0,0 +1,61 @@
+require 'ronin/payloads/has_payload'
+
+module Ronin
+  module Payloads
+    module Helpers
+      module Chained
+        include HasPayload
+
+        #
+        # Chains the payload to another payload.
+        #
+        # @param [Payload] sub_payload
+        #   The payload chained to this payload.
+        #
+        # @return [Payload]
+        #   The chained payload.
+        #
+        def chain(sub_payload)
+          self.payload = sub_payload
+        end
+
+        #
+        # Builds the chained payload first, then the payload.
+        #
+        # @see Payload#build!
+        #
+        def build!(options={},&block)
+          @payload.build!() if @payload
+
+          return super(options,&block)
+        end
+
+        #
+        # Verifies the built payload and deploys the payload. After the
+        # payload has been deployed, the chained payload will then be
+        # deployed.
+        #
+        # @yield [(payload)]
+        #   If a block is given, the chained payload will be passed to the
+        #   block.
+        #
+        # @yieldparam [Payload] payload
+        #   The chained payload.
+        #
+        # @return [Payload]
+        #   The chained payload.
+        #
+        # @see Payload#deploy!
+        #
+        def deploy!(&block)
+          if @payload
+            super()
+            return @payload.deploy!(&block)
+          end
+
+          return super(&block)
+        end
+      end
+    end
+  end
+end

data/lib/ronin/payloads/helpers/rpc.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,45 +17,54 @@
 # 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/payloads/helpers/exceptions/not_implemented'
+require 'ronin/payloads/exceptions/not_implemented'
 
 module Ronin
   module Payloads
     module Helpers
-      module RPC
-        def self.included(base)
-          base.module_eval do
-            #
-            # Exposes the method with the specified _name_.
-            #
-            def self.expose_method(name)
-              define_method(name) do |*arguments|
-                call_method(name,*arguments)
-              end
-            end
-          end
-        end
-
+      module Rpc
+        #
+        # Calls a specific method with additional arguments.
+        #
+        # @param [Symbol, String] method
+        #   The method name to call.
+        #
+        # @param [Array] arguments
+        #   The arguments to use when calling the method.
+        #
+        # @return [Object]
+        #   The result of the method call.
         #
-        # Calls the specified _method_ with the given _arguments_.
-        # Returns the return-value of the method-call.
+        # @since 0.3.0
         #
         def call_method(method,*arguments)
           raise(NotImplemented,"the call method is unimplemented",caller)
         end
 
         #
-        # Evaluates the specified _code_.
+        # Evaluates code.
+        #
+        # @param [String] code
+        #   The code to evaluate.
+        #
+        # @return [Object]
+        #   The result of the code evaluation.
+        #
+        # @since 0.3.0
         #
         def eval(code)
           call_method(:eval,code)
         end
 
         #
-        # Exits with the given _status_.
+        # Exits the process.
+        #
+        # @param [Integer] status
+        #   The status to exit with.
+        #
+        # @since 0.3.0
         #
         def exit(status=0)
           call_method(:exit,status)
@@ -68,6 +76,8 @@ module Ronin
         # Provides transparent access to remote methods using the
         # specified _name_ and given _arguments_.
         #
+        # @since 0.3.0
+        #
         def method_missing(name,*arguments,&block)
           name = name.to_s
 

data/lib/ronin/payloads/nops.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/payloads/asm_payload'
@@ -27,6 +25,13 @@ module Ronin
   module Payloads
     class Nops < ASMPayload
 
+      #
+      # Creates a new Ronin::Payloads::Nops object using the given _block_.
+      #
+      #   ronin_nops do
+      #     ...
+      #   end
+      #
       contextify :ronin_nops
 
     end

data/lib/ronin/payloads/payload.rb

@@ -1,5 +1,4 @@
 #
-#--
 # Ronin Exploits - A Ruby library for Ronin that provides exploitation and
 # payload crafting functionality.
 #
@@ -18,23 +17,21 @@
 # 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/payloads/exceptions/unknown_helper'
-require 'ronin/payloads/license'
-require 'ronin/payloads/arch'
-require 'ronin/payloads/os'
 require 'ronin/payloads/payload_author'
 require 'ronin/payloads/control'
+require 'ronin/cacheable'
 require 'ronin/model/targets_arch'
 require 'ronin/model/targets_os'
 require 'ronin/model/has_name'
 require 'ronin/model/has_description'
 require 'ronin/model/has_version'
 require 'ronin/model/has_license'
-require 'ronin/ui/diagnostics'
-require 'ronin/cacheable'
+require 'ronin/controls/behaviors'
+require 'ronin/ui/output/helpers'
+require 'ronin/extensions/kernel'
 
 require 'parameters'
 
@@ -50,18 +47,27 @@ module Ronin
       include Model::HasLicense
       include Model::TargetsArch
       include Model::TargetsOS
-      include UI::Diagnostics
+      include Controls::Behaviors
+      include UI::Output::Helpers
 
+      #
+      # Creates a new Ronin::Payloads::Payload object using the given
+      # _block_.
+      #
+      #   ronin_payload do
+      #     ...
+      #   end
+      #
       contextify :ronin_payload
 
       # Primary key of the payload
       property :id, Serial
 
       # Author(s) of the payload
-      has n, :authors, :class_name => 'Ronin::Payloads::PayloadAuthor'
+      has n, :authors, :model => 'Ronin::Payloads::PayloadAuthor'
 
       # Controls the payload provides
-      has n, :controls
+      has n, :controls, :model => 'Ronin::Payloads::Control'
 
       # Validations
       validates_present :name
@@ -70,13 +76,18 @@ module Ronin
       # The exploit to deploy with
       attr_accessor :exploit
 
-      # The built and encoded payload
-      attr_accessor :payload
+      # The raw payload
+      attr_accessor :raw_payload
 
       #
-      # Creates a new Payload object with the given _attributes_. If a
-      # _block_ is given, it will be passed the newly created Payload
-      # object.
+      # Creates a new Payload object.
+      #
+      # @param [Array] attributes
+      #   Additional attributes to initialize the payload with.
+      #
+      # @yield []
+      #   If a block is given, it will be evaluated in the newly created
+      #   Payload object.
       #
       def initialize(attributes={},&block)
         super(attributes)
@@ -90,66 +101,103 @@ module Ronin
       end
 
       #
-      # Adds a new PayloadAuthor with the given _attributes_. If a _block_
-      # is given, it will be passed to the newly created PayloadAuthor
-      # object.
+      # Finds all payloads written by a specific author.
       #
-      #   author :name => 'Anonymous',
-      #          :email => 'anon@example.com',
-      #          :organization => 'Anonymous LLC'
+      # @param [String] name
+      #   The name of the author.
       #
-      def author(attributes={},&block)
-        self.authors << PayloadAuthor.new(attributes,&block)
+      # @return [Array<Payload>]
+      #   The payload written by the author.
+      #
+      def self.written_by(name)
+        all(self.authors.name.like => "%#{name}%")
       end
 
       #
-      # Adds a new Control to the payload that controls the specified
-      # _behaviors_.
+      # Finds all payloads written for a specific organization.
       #
-      #   controlling :code_exec.
-      #               :file_read,
-      #               :file_write,
-      #               :file_create
+      # @param [String] name
+      #   The name of the organization.
       #
-      def controlling(*behaviors)
-        behaviors.each do |behavior|
-          self.controls << Control.new(
-            :behavior => Vuln::Behavior[behavior]
-          )
-        end
+      # @return [Array<Payload>]
+      #   The payloads written for the organization.
+      #
+      def self.written_for(name)
+        all(self.authors.organization.like => "%#{name}%")
       end
 
       #
-      # Returns the behaviors controlled by the payload.
+      # Adds a new author to the payload.
+      #
+      # @param [Hash] attributes
+      #   Additional attributes to create the PayloadAuthor object with.
+      #
+      # @yield [author]
+      #   If a block is given, it will be passed the newly created author
+      #   object.
+      #
+      # @yieldparam [PayloadAuthor] author
+      #   The author object tied to the payload.
       #
-      def behaviors
-        self.controls.map { |control| control.behavior }
+      # @example
+      #   author :name => 'Anonymous',
+      #          :email => 'anon@example.com',
+      #          :organization => 'Anonymous LLC'
+      #
+      def author(attributes={},&block)
+        self.authors << PayloadAuthor.new(attributes,&block)
       end
 
       #
-      # Returns +true+ if the payload is built, returns +false+ otherwise.
+      # @return [Boolean]
+      #   Specifies whether the payload is built.
       #
       def built?
         @built == true
       end
 
       #
-      # Performs a clean build of the payload with the given _params_.
-      # If a _block_ is given, it will be passed the built and encoded
-      # payload.
+      # Builds the payload.
+      #
+      # @param [Hash] options
+      #   Additional options to build the payload with and use as
+      #   parameters.
+      #
+      # @yield [payload]
+      #   If a block is given, it will be yielded the result of the
+      #   payload building.
+      #
+      # @yieldparam [String] payload
+      #   The built payload.
+      #
+      # @return [String]
+      #   The built payload.
       #
       def build!(options={},&block)
         self.params = options
 
+        print_debug "Payload parameters: #{self.params.inspect}"
+
         @built = false
-        @payload = ''
+        @raw_payload = ''
+
+        print_info "Building payload ..."
 
         build()
 
+        print_info "Payload built!"
+
         @built = true
 
-        block.call(@payload) if block
-        return @payload
+        if block
+          if block.arity == 1
+            block.call(self)
+          else
+            block.call()
+          end
+        end
+
+        return self
       end
 
       #
@@ -157,73 +205,75 @@ module Ronin
       # deployed.
       #
       def verify!
+        print_info "Verifying payload ..."
+
         verify
+
+        print_info "Payload verified!"
       end
 
       #
-      # Returns +true+ if the payload has previously been deployed,
-      # returns +false+ otherwise.
+      # @return [Boolean]
+      #   Specifies whether the payload has previously been deployed.
       #
       def deployed?
         @deployed == true
       end
 
       #
-      # Verifies the built payload and deploys the payload. If a _block_
-      # is given, it will be passed the deployed payload object. If 
-      # an exploit is given, it will be called with the given _options_
-      # and the built payload before the payload is deployed.
+      # Verifies the built payload and deploys the payload.
+      #
+      # @yield [payload]
+      #   If a block is given, it will be passed the deployed payload.
+      #
+      # @yieldparam [Payload] payload
+      #   The deployed payload.
       #
-      def deploy!(options={},&block)
+      def deploy!(&block)
         # verify the payload
         verify!
 
-        if @exploit
-          # build, verify and deploy the exploit with the built payload
-          @exploit.call(options.merge(:payload => @payload))
-        end
-
+        print_info "Deploying payload ..."
         @deployed = false
 
         deploy()
 
+        print_info "Payload deployed!"
         @deployed = true
         
-        block.call(self) if block
-        return self
-      end
-
-      #
-      # Builds the payload with the given _options_ and deploys it with
-      # the given _block_. If a _block_ is given, it will be passed the
-      # deployed payload object.
-      #
-      # _options_ may contain the following keys:
-      # <tt>:exploit</tt>:: The exploit object to use with the payload.
-      #
-      def call(options={},&block)
-        if options[:exploit]
-          # set the exploit if one is given
-          @exploit = options.delete(:exploit)
+        if block
+          if block.arity == 1
+            block.call(self)
+          else
+            block.call()
+          end
         end
 
-        # build the payload
-        build!(options)
-
-        # deploy the payload
-        return deploy!(options,&block)
+        return self
       end
 
       #
-      # Returns the name and version of the payload.
+      # Converts the payload to a String.
+      #
+      # @return [String]
+      #   The name and version of the payload.
       #
       def to_s
-        "#{self.name} #{self.version}"
+        if (self.name && self.version)
+          "#{self.name} #{self.version}"
+        elsif self.name
+          self.name
+        elsif self.version
+          self.version
+        end
       end
 
       #
       # Inspects the contents of the payload.
       #
+      # @return [String]
+      #   The inspected payload.
+      #
       def inspect
         str = "#{self.class}: #{self}"
         str << " #{self.params.inspect}" unless self.params.empty?
@@ -235,11 +285,20 @@ module Ronin
 
       #
       # Extends the payload with the helper module defined in
-      # Ronin::Payloads::Helpers that has the similar specified
-      # _name_. If no module can be found within
-      # Ronin::Payloads::Helpers with the similar _name_, an
-      # UnknownHelper exception will be raised.
+      # Ronin::Payloads::Helpers that has the similar name.
+      #
+      # @param [Symbol, String] name
+      #   The snake-case name of the payload helper to load and extend the
+      #   payload with.
+      #
+      # @return [true]
+      #   The payload helper was successfully loaded.
+      #
+      # @raise [UnknownHelper]
+      #   No valid helper module could be found or loaded with the similar
+      #   name.
       #
+      # @example
       #   helper :shell
       #
       def helper(name)
@@ -247,7 +306,7 @@ module Ronin
         module_name = name.to_const_string
 
         begin
-          require File.join('ronin','payloads','helpers',name)
+          require_within File.join('ronin','payloads','helpers'), name
         rescue Gem::LoadError => e
           raise(e)
         rescue ::LoadError