ronin 0.3.0 → 1.0.0.pre1

data/lib/ronin/email_address.rb

@@ -0,0 +1,133 @@
+#
+# Ronin - A Ruby platform for exploit development and security research.
+#
+# Copyright (c) 2006-2010 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/user_name'
+require 'ronin/host_name'
+require 'ronin/model'
+
+require 'dm-timestamps'
+
+module Ronin
+  class EmailAddress
+
+    include Model
+
+    # The primary key of the email address
+    property :id, Serial
+
+    # The user-name component of the email address
+    belongs_to :user_name, :unique => :user_host
+
+    # The host-name component of the email address
+    belongs_to :host_name, :unique => :user_host
+
+    # Tracks when the email address was created at.
+    timestamps :created_at
+
+    #
+    # Parses an email address.
+    #
+    # @param [String] email
+    #   The email address to parse.
+    #
+    # @return [EmailAddress]
+    #   A new or previously saved email address resource.
+    #
+    # @raise [RuntimeError]
+    #   The email address did not have a user name or a host name.
+    #
+    # @since 1.0.0
+    #
+    def EmailAddress.parse(email)
+      user, host = email.strip.split('@',2)
+
+      if user.empty?
+        raise("email address #{email.dump} must have a user name")
+      end
+
+      if host.empty?
+        raise("email address #{email.dump} must have a host name")
+      end
+
+      return EmailAddress.first_or_new(
+        :user_name => UserName.first_or_new(:name => user),
+        :host_name => HostName.first_or_new(:address => host)
+      )
+    end
+
+    #
+    # The user of the email address.
+    #
+    # @return [String]
+    #   The user name.
+    #
+    # @since 1.0.0
+    #
+    def user
+      self.user_name.name if self.user_name
+    end
+
+    #
+    # The host of the email address.
+    #
+    # @return [String]
+    #   The host name.
+    #
+    # @since 1.0.0
+    #
+    def host
+      self.host_name.address if self.host_name
+    end
+
+    #
+    # Converts the email address into a String.
+    #
+    # @return [String]
+    #   The raw email address.
+    #
+    # @since 1.0.0
+    #
+    def to_s
+      "#{self.user_name}@#{self.host_name}"
+    end
+
+    #
+    # Splats the email address into multiple variables.
+    #
+    # @return [Array]
+    #   The user-name and the host-name within the email address.
+    #
+    # @example
+    #   email = EmailAddress.parse('alice@example.com')
+    #   user, host = email
+    #   
+    #   user
+    #   # => "alice"
+    #   host
+    #   # => "example.com"
+    #
+    # @since 1.0.0
+    #
+    def to_ary
+      [self.user_name.name, self.host_name.address]
+    end
+
+  end
+end

data/lib/ronin/engine/buildable.rb

@@ -0,0 +1,125 @@
+#
+# Ronin - A Ruby platform for exploit development and security research.
+#
+# Copyright (c) 2006-2010 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/engine/exceptions/not_built'
+require 'ronin/engine/verifiable'
+
+module Ronin
+  module Engine
+    module Buildable
+      include Verifiable
+
+      #
+      # Initializes the buildable engine.
+      #
+      # @param [Hash] attributes
+      #   Additional attributes for the engine.
+      #
+      # @since 1.0.0
+      #
+      def initialize(attributes={})
+        super(attributes)
+
+        @build_blocks = []
+        @built = false
+      end
+
+      #
+      # Determines whether the engine has been built.
+      #
+      # @return [Boolean]
+      #   Specifies whether the engine is built.
+      #
+      # @since 1.0.0
+      #
+      def built?
+        @built == true
+      end
+
+      #
+      # Builds the engine.
+      #
+      # @param [Hash] options
+      #   Additional options to also use as parameters.
+      #
+      # @yield []
+      #   The given block will be called after the engine has been built.
+      #
+      # @see #build
+      #
+      # @since 1.0.0
+      #
+      def build!(options={})
+        self.params = options
+        print_debug "#{engine_name} #{self} parameters: #{self.params.inspect}"
+
+        print_info "Building #{engine_name} #{self} ..."
+
+        @built = false
+        @build_blocks.each { |block| block.call() }
+        @built = true
+
+        print_info "#{engine_name} #{self} built!"
+
+        yield if block_given?
+        return self
+      end
+
+      #
+      # Verifies that the engine has been built and is properly configured.
+      #
+      # @return [true]
+      #   The engine has been verified.
+      #
+      # @raise [NotBuilt]
+      #   The engine has not been built, and cannot be verified.
+      #
+      # @see #verify
+      #
+      # @since 1.0.0
+      #
+      def verify!
+        unless built?
+          raise(NotBuilt,"cannot verify an unbuilt #{engine_name}")
+        end
+
+        super
+      end
+
+      protected
+
+      #
+      # Registers a given block to be called when the engine is built.
+      #
+      # @yield []
+      #   The given block will be called when the engine is being built.
+      #
+      # @return [Engine]
+      #   The engine.
+      #
+      # @since 1.0.0
+      #
+      def build(&block)
+        @build_blocks << block
+        return self
+      end
+    end
+  end
+end

data/lib/ronin/engine/class_methods.rb

@@ -0,0 +1,133 @@
+#
+# Ronin - A Ruby platform for exploit development and security research.
+#
+# Copyright (c) 2006-2010 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 Engine
+    module ClassMethods
+      #
+      # Finds and loads all matching Ronin Engines.
+      #
+      # @param [Hash] options
+      #   Query options.
+      #
+      # @option options [String] :name
+      #   The name to search for.
+      #
+      # @option options [String] :describing
+      #   The description to search for.
+      #
+      # @option options [String] :version
+      #   The version to search for.
+      #
+      # @option options [String] :license
+      #   The license to search for.
+      #
+      # @return [Array<Engine>]
+      #   The Ronin Engine with the matching attributes.
+      #
+      # @since 1.0.0
+      #
+      def load_all(options={})
+        resources = custom_query(options)
+        
+        resources.each { |resource| resource.load_original! }
+        return resources
+      end
+
+      #
+      # Finds and loads a specific Ronin Engine.
+      #
+      # @param [Hash] options
+      #   Query options.
+      #
+      # @option options [String] :name
+      #   The name to search for.
+      #
+      # @option options [String] :describing
+      #   The description to search for.
+      #
+      # @option options [String] :version
+      #   The version to search for.
+      #
+      # @option options [String] :license
+      #   The license to search for.
+      #
+      # @return [Array<Engine>]
+      #   The Ronin Engine with the matching attributes.
+      #
+      # @since 1.0.0
+      #
+      def load_first(options={})
+        if (resource = custom_query(options).first)
+          resource.load_original!
+        end
+
+        return resource
+      end
+
+      protected
+
+      #
+      # Creates a custom query for the Ronin Engine.
+      #
+      # @param [Hash] options
+      #   Query options.
+      #
+      # @option options [String] :name
+      #   The name to search for.
+      #
+      # @option options [String] :describing
+      #   The description to search for.
+      #
+      # @option options [String] :version
+      #   The version to search for.
+      #
+      # @option options [String] :license
+      #   The license to search for.
+      #
+      # @return [DataMapper::Collection]
+      #   The custom query for the Ronin Engine.
+      #
+      # @since 1.0.0
+      #
+      def custom_query(options)
+        query = all
+
+        if options.has_key?(:name)
+          query = query.named(options.delete(:name))
+        end
+
+        if options.has_key?(:describing)
+          query = query.describing(options.delete(:describing))
+        end
+
+        if options.has_key?(:version)
+          query = query.revision(options.delete(:version))
+        end
+
+        if options.has_key?(:license)
+          query = query.licensed_under(options.delete(:license))
+        end
+
+        return query.all(options)
+      end
+    end
+  end
+end

data/lib/ronin/engine/deployable.rb

@@ -0,0 +1,180 @@
+#
+# Ronin - A Ruby platform for exploit development and security research.
+#
+# Copyright (c) 2006-2010 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/engine/exceptions/deploy_failed'
+require 'ronin/engine/verifiable'
+
+module Ronin
+  module Engine
+    module Deployable
+      include Verifiable
+
+      #
+      # Initializes the deployable engine.
+      #
+      # @param [Hash] attributes
+      #   Additional attributes for the engine.
+      #
+      # @since 1.0.0
+      #
+      def initialize(attributes={})
+        super(attributes)
+
+        @deploy_blocks = []
+        @deployed = false
+
+        @evacuate_blocks = []
+        @evacuated = false
+      end
+
+      #
+      # Determines whether the engine was deployed.
+      #
+      # @return [Boolean]
+      #   Specifies whether the engine was previously deployed.
+      #
+      # @since 1.0.0
+      #
+      def deployed?
+        @deployed == true
+      end
+
+      #
+      # Verifies then deploys the exploit. If a payload has been set,
+      # the payload will also be deployed.
+      #
+      # @yield []
+      #   If a block is given, it will be passed the deployed engine.
+      #
+      # @return [Engine]
+      #   The deployed engine.
+      #
+      # @see deploy
+      #
+      # @since 1.0.0
+      #
+      def deploy!
+        verify!
+
+        print_info "Deploying #{engine_name} #{self} ..."
+
+        @deployed = false
+        @deploy_blocks.each { |block| block.call() }
+        @deployed = true
+        @evacuated = false
+
+        print_info "#{engine_name} #{self} deployed!"
+
+        yield if block_given?
+        return self
+      end
+
+      #
+      # Determines whether the engine was evacuated.
+      #
+      # @return [Boolean]
+      #   Specifies whether the engine has been evacuated.
+      #
+      # @since 1.0.0
+      #
+      def evacuated?
+        @evacuated == true
+      end
+
+      #
+      # Evacuates the deployed engine.
+      #
+      # @yield []
+      #   If a block is given, it will be called before the engine is
+      #   evacuated.
+      #
+      # @return [Engine]
+      #   The evacuated engine.
+      #
+      # @see #evacuate
+      #
+      # @since 1.0.0
+      #
+      def evacuate!
+        yield if block_given?
+
+        print_info "Evauating #{engine_name} #{self} ..."
+
+        @evacuated = false
+        @evacuate_blocks.each { |block| block.call() }
+        @evacuated = true
+        @deployed = false
+
+        print_info "#{engine_name} #{self} evacuated."
+        return self
+      end
+
+      protected
+
+      #
+      # Indicates the deployment of the exploit has failed.
+      #
+      # @raise [DeployFailed]
+      #   The deployment of the exploit failed.
+      #
+      # @since 1.0.0
+      #
+      def deploy_failed!(message)
+        raise(DeployFailed,message)
+      end
+
+      #
+      # Registers a given block to be called when the engine is being
+      # deployed.
+      #
+      # @yield []
+      #   The given block will be called when the engine is being
+      #   deployed.
+      #
+      # @return [Engine]
+      #   The engine.
+      #
+      # @since 1.0.0
+      #
+      def deploy(&block)
+        @deploy_blocks << block
+        return self
+      end
+
+      #
+      # Registers a given block to be called when the engine is being
+      # evacuated.
+      #
+      # @yield []
+      #   The given block will be called when the engine is being
+      #   evacuated.
+      #
+      # @return [Engine]
+      #   The engine.
+      #
+      # @since 1.0.0
+      #
+      def evacuate(&block)
+        @evacuate_blocks.unshift(block)
+        return self
+      end
+    end
+  end
+end

data/lib/ronin/engine/engine.rb

@@ -0,0 +1,69 @@
+#
+# Ronin - A Ruby platform for exploit development and security research.
+#
+# Copyright (c) 2006-2010 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/engine/class_methods'
+require 'ronin/engine/instance_methods'
+require 'ronin/model/model'
+require 'ronin/model/has_name'
+require 'ronin/model/has_description'
+require 'ronin/model/has_version'
+require 'ronin/model/has_license'
+require 'ronin/model/has_authors'
+require 'ronin/model/cacheable'
+require 'ronin/ui/output/helpers'
+
+require 'parameters'
+
+module Ronin
+  module Engine
+    include UI::Output::Helpers
+
+    def self.included(base)
+      base.send :include, Engine::InstanceMethods,
+                          Model,
+                          Model::HasName,
+                          Model::HasDescription,
+                          Model::HasVersion,
+                          Model::HasLicense,
+                          Model::HasAuthors,
+                          Model::Cacheable,
+                          Parameters
+
+      base.send :extend, ClassMethods
+    end
+
+    # 
+    # Loads a engine from a file.
+    #
+    # @param [String] path
+    #   The path to the file.
+    #
+    # @return [Engine]
+    #   The loaded engine.
+    #
+    # @see Model::Cacheable.load_from
+    #
+    # @since 1.0.0
+    #
+    def Engine.load_from(path)
+      Model::Cacheable.load_from(path)
+    end
+  end
+end

data/lib/ronin/{rpc/exceptions/response_missing.rb → engine/exceptions/deploy_failed.rb}

@@ -1,7 +1,7 @@
 #
 # Ronin - A Ruby platform for exploit development and security research.
 #
-# Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2010 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
@@ -19,8 +19,8 @@
 #
 
 module Ronin
-  module RPC
-    class ResponseMissing < StandardError
+  module Engine
+    class DeployFailed < RuntimeError
     end
   end
 end

data/lib/ronin/{rpc/exceptions/not_implemented.rb → engine/exceptions/not_built.rb}

@@ -1,7 +1,7 @@
 #
 # Ronin - A Ruby platform for exploit development and security research.
 #
-# Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2010 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
@@ -19,8 +19,8 @@
 #
 
 module Ronin
-  module RPC
-    class NotImplemented < RuntimeError
+  module Engine
+    class NotBuilt < RuntimeError
     end
   end
 end

data/lib/ronin/{platform/exceptions/overlay_cached.rb → engine/exceptions/verification_failed.rb}

@@ -1,7 +1,7 @@
 #
 # Ronin - A Ruby platform for exploit development and security research.
 #
-# Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2010 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
@@ -19,8 +19,8 @@
 #
 
 module Ronin
-  module Platform
-    class OverlayCached < StandardError
+  module Engine
+    class VerificationFailed < RuntimeError
     end
   end
 end