metasploit-model 0.24.1.pre.semantic.pre.versioning.pre.2.pre.0

data/lib/metasploit/model/search.rb

@@ -0,0 +1,63 @@
+module Metasploit
+  module Model
+    # DSL to define associations and attributes that can be searched.  Making an association searchable, will expose
+    # the attributes that association's class defined as searchable.
+    module Search
+      extend ActiveSupport::Concern
+
+      include Metasploit::Model::Search::Association
+      include Metasploit::Model::Search::Attribute
+      include Metasploit::Model::Search::With
+
+      # Allows operators registered with {Metasploit::Model::Search::Association::ClassMethods#search_association} and
+      # {Metasploit::Model::Search::Attribute::ClassMethods#search_attribute} to be looked up by name.
+      module ClassMethods
+        # Collects all search attributes from search associations and all attributes from this class to show the valid
+        # search operators to search.
+        #
+        # @return [Hash{Symbol => Metasploit::Model::Search::Operator}] Maps
+        #   {Metasploit::Model::Search::Operator::Base#name} to {Metasploit::Model::Search::Operator::Base#name}.
+        def search_operator_by_name
+          unless instance_variable_defined? :@search_operator_by_name
+            @search_operator_by_name = {}
+
+            search_with_operator_by_name.each_value do |operator|
+              @search_operator_by_name[operator.name] = operator
+            end
+
+            search_association_set.each do |association|
+              begin
+                reflection = reflect_on_association(association)
+              rescue NameError
+                raise NameError,
+                      "#{self} does not respond to reflect_on_association.  " \
+                      "It can be added to ActiveModels by including Metasploit::Model::Association into the class."
+              end
+
+              unless reflection
+                raise Metasploit::Model::Association::Error.new(:model => self, :name => association)
+              end
+
+              association_class = reflection.klass
+
+              # don't use search_operator_by_name as association operators on operators won't work
+              association_class.search_with_operator_by_name.each_value do |with_operator|
+                # non-attribute operators on association are assumed not to work
+                if with_operator.respond_to? :attribute
+                  association_operator = Metasploit::Model::Search::Operator::Association.new(
+                      :association => association,
+                      :attribute_operator => with_operator,
+                      :klass => self
+                  )
+                  @search_operator_by_name[association_operator.name] = association_operator
+                end
+              end
+            end
+          end
+
+          @search_operator_by_name
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/search/association.rb

@@ -0,0 +1,32 @@
+module Metasploit
+  module Model
+    module Search
+      # Registers associations that can be searched.
+      module Association
+        extend ActiveSupport::Concern
+
+        # Adds {#search_association} DSL to make {Metasploit::Model::Search::Operator::Association association search
+        # operators}.
+        module ClassMethods
+          # Registers association for search.
+          #
+          # @param association [#to_sym] name of association to search.
+          # @return [void]
+          def search_association(association)
+            search_association_set.add(association.to_sym)
+          end
+
+          # Set of all associations that are searchable.
+          #
+          # @example Adding association to search
+          #   search_association :things
+          #
+          # @return [Set<Symbol>]
+          def search_association_set
+            @search_association_set ||= Set.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/search/attribute.rb

@@ -0,0 +1,51 @@
+module Metasploit
+  module Model
+    module Search
+      # Registers attributes that can be searched.
+      module Attribute
+        extend ActiveSupport::Concern
+
+        include Metasploit::Model::Search::With
+
+        # Adds {#search_attribute} DSL to make {Metasploit::Model::Search::Operator::Attribute attribute search
+        # operators}.
+        module ClassMethods
+          # Registers attribute for search.  Help for the operator supports i18n.
+          #
+          # @example defining help
+          #    # lib/metasploit/model/module/instance.rb
+          #    module Metasploit::Model::Module::Instance
+          #      include Metasploit::Model::Search
+          #
+          #      included do
+          #        search_attribute :description, :type => :string
+          #      end
+          #    end
+          #
+          #    # config/locales/en.yml
+          #    en:
+          #      metasploit:
+          #        model:
+          #          module:
+          #            instance:
+          #              search_attribute:
+          #                description:
+          #                  help: "A long, paragraph description of what the module does."
+          #
+          # @param attribute [#to_sym] name of attribute to search.
+          # @param options [Hash{Symbol => String}]
+          # @option options [Symbol] :type The type of the attribute.  Used to determine how to parse the search values
+          #   and which modifiers are supported.
+          # @return (see Metasploit::Model::Search::With::ClassMethods#search_with)
+          # @raise [Metasploit::Model::Invalid] unless attribute is present
+          # @raise [Metasploit::Model::Invalid] unless :type is present
+          def search_attribute(attribute, options={})
+            search_with Metasploit::Model::Search::Operator::Attribute,
+                        :attribute => attribute,
+                        :type => options[:type]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/search/operation.rb

@@ -0,0 +1,31 @@
+module Metasploit
+  module Model
+    module Search
+      # Namespace for search operations.  {parse} acts as a factory to parse a `String` and return a type-specific
+      # operation.
+      module Operation
+        # @param options [Hash{Symbol => Object}]
+        # @option options [Metasploit::Module::Search::Query] :query The query that the parsed operation is a part.
+        # @option options [String] :formatted_operation A '<operator>:<value>' string.
+        # @return [Metasploit::Model::Search::Operation::Base, Array<Metasploit::Model::Search::Operation::Base>]
+        #   operation(s) parsed from the formatted operation.
+        # @raise [KeyError] unless :formatted_operation is given.
+        # @raise [KeyError] unless :query is given.
+        def self.parse(options={})
+          formatted_operation = options.fetch(:formatted_operation)
+          query = options.fetch(:query)
+
+          formatted_operator, formatted_value = formatted_operation.split(':', 2)
+          operator = query.parse_operator(formatted_operator)
+
+          # formatted_value will be nil if formatted_operation did not contain a ':', it should be treated the same
+          # as nothing after the ':'.
+          formatted_value ||= ''
+          operation_or_operations = operator.operate_on(formatted_value)
+
+          operation_or_operations
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/search/operation/integer/value.rb

@@ -0,0 +1,33 @@
+# Concerns type casting of a raw value to an `Integer`.
+module Metasploit::Model::Search::Operation::Integer::Value
+  #
+  # Attributes
+  #
+
+  # @!attribute [r] value_before_type_cast
+  #   The formatted version of {#value} before it was type cast when calling {#value=}.
+  #
+  #   @return [Object]
+  attr_reader :value_before_type_cast
+
+  #
+  # Methods
+  #
+
+  # Sets {Metasploit::Model::Search::Operation::Base#value} by type casting String to Integer.
+  #
+  # @param formatted_value [#to_s]
+  # @return [Integer] if `formatted_value` contains only an Integer#to_s
+  # @return [#to_s] `formatted_value` if it does not contain an Integer#to_s
+  def value=(formatted_value)
+    @value_before_type_cast = formatted_value
+
+    begin
+      # use Integer() instead of String#to_i as String#to_i will ignore trailing letters (i.e. '1two' -> 1) and turn all
+      # string without an integer in it to 0.
+      @value = Integer(formatted_value.to_s)
+    rescue ArgumentError
+      @value = formatted_value
+    end
+  end
+end

data/lib/metasploit/model/search/operation/string/value.rb

@@ -0,0 +1,14 @@
+# Concerns type casting of a raw value to a `String`.
+module Metasploit::Model::Search::Operation::String::Value
+  #
+  # Methods
+  #
+
+  # Sets {Metasploit::Model::Search::Operation::Base#value} by type casting to a String.
+  #
+  # @param formatted_value [#to_s]
+  # @return [String]
+  def value=(formatted_value)
+    @value = formatted_value.to_s
+  end
+end

data/lib/metasploit/model/search/operator.rb

@@ -0,0 +1,10 @@
+module Metasploit
+  module Model
+    module Search
+      # Namespace for search operators
+      module Operator
+
+      end
+    end
+  end
+end

data/lib/metasploit/model/search/operator/help.rb

@@ -0,0 +1,47 @@
+module Metasploit
+  module Model
+    module Search
+      module Operator
+        # Methods to lookup help text for an operator with a given `#name` registered to a given `#klass`.
+        module Help
+          # @note This uses I18n.translate along with {Metasploit::Model::Translation#search_i18n_scope},
+          #   the value is not cached to support changing the I18n.locale and getting the correct help message for that
+          #   locale.
+          #
+          # The help for this operator.
+          #
+          # @see https://github.com/rails/rails/blob/6c2810b8ed692004dca43e554982cdfdb8517b80/activemodel/lib/active_model/errors.rb#L408-L435
+          def help
+            defaults = []
+            klass_i18n_scope = klass.i18n_scope
+
+            klass.lookup_ancestors.each do |ancestor|
+              # a specific operator for a given Class#ancestors member
+              defaults << :"#{klass_i18n_scope}.ancestors.#{ancestor.model_name.i18n_key}.search.operator.names.#{name}.help"
+            end
+
+            operator_class = self.class
+            operator_i18n_scope = operator_class.i18n_scope
+
+            operator_class.lookup_ancestors.each do |ancestor|
+              # a specific name for a given operator
+              defaults << :"#{operator_i18n_scope}.search.operator.ancestors.#{ancestor.model_name.i18n_key}.names.#{name}.help"
+              # a specific operator class
+              defaults << :"#{operator_i18n_scope}.search.operator.ancestors.#{ancestor.model_name.i18n_key}.help"
+            end
+
+            # use first default as key because it is most specific default, that is closest to klass.
+            key = defaults.shift
+            options = {
+                default: defaults,
+                model: klass.model_name.human,
+                name: name
+            }
+
+            ::I18n.translate(key, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/search/with.rb

@@ -0,0 +1,40 @@
+module Metasploit
+  module Model
+    module Search
+      # Generalizes operators from attributes to anything directly registered as an operator on a class.
+      module With
+        extend ActiveSupport::Concern
+
+        # Defines `search_with` DSL, which is a lower-level way than search_attribute to add operators.  `search_with`
+        # allows instance of arbitrary operator_classes to be registered in {#search_with_operator_by_name}.
+        module ClassMethods
+          # Declares that this class should be search with an instance of the given `operator_class`.
+          #
+          # @param operator_class [Class<Metasploit::Model::Search::Operator::Base>] a class to initialize.
+          # @param options [Hash] Options passed to `operator_class.new` along with `{:klass => self}`, so that the
+          #   `operator_class` instance knows it was registered as search this class.
+          # @return [Metasploit::Model::Search::Operator::Base]
+          # @raise (see Metasploit::Model::Base#invalid!)
+          def search_with(operator_class, options={})
+            merged_operations = options.merge(
+                :klass => self
+            )
+            operator = operator_class.new(merged_operations)
+            operator.valid!
+
+            search_with_operator_by_name[operator.name] = operator
+          end
+
+          # Operators registered with {#search_with}.
+          #
+          # @return [Hash{Symbol => Metasploit::Model::Search::Operator::Base}] Maps
+          #   {Metasploit::Model::Search::Operator::Base#name} keys to {Metasploit::Model::Search::Operator::Base#name}
+          #   values.
+          def search_with_operator_by_name
+            @search_with_operator_by_name ||= {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/spec.rb

@@ -0,0 +1,140 @@
+require 'rspec/core/shared_example_group'
+
+module Metasploit
+  module Model
+    # Helper methods for running specs for metasploit-model.
+    module Spec
+      extend Metasploit::Model::Spec::TemporaryPathname
+      # without this, Module.shared_examples_for will be used and RSpec will count shared_examples created with
+      # {shared_examples_for} to not be declared at the top-level.
+      extend RSpec::Core::SharedExampleGroup::TopLevelDSL
+
+      # Defines a shared examples for a `Module` under the {Metasploit::Model} namespace.  This `Module` is assumed to
+      # be a mixin that can be mixed into an ActiveModel in metasploit-framework or an ActiveRecord in
+      # metasploit_data_models.  Shared examples declared using this method get access to boiler plate methods used
+      # for all the {Metasploit::Model} mixin `Modules`:
+      #
+      #   * <relative_variable_name>_class
+      #   * <relative_variable_name>_factory
+      #   * factory_namespace
+      #   * relative_variable_name
+      #   * #<relative_variable_name>_class
+      #   * #<relative_variable_name>_factory
+      #
+      # @example boiler plate methods for Module::Ancestor
+      #   # defined shared example's name will be 'Metasploit::Model::Module::Ancestor', but you only need to give the
+      #   # name relative to 'Metasploit::Model'.
+      #   Metasploit::Model::Spec.shared_examples_for 'Module::Ancestor' do
+      #     module_ancestor_class # '<namespace_name>::Module::Ancestor'
+      #     module_ancestor_factory # '<factory_namespace>_module_ancestor'
+      #     factory_namespace # namespace_name converted to underscore with / replaced by _
+      #     relative_variable_name # 'module_ancestor'
+      #
+      #     let(:base_class) do # automatically defined for you
+      #       module_ancestor_class # same as class method module_ancestor_class
+      #     end
+      #
+      #     context 'factories' do # have to define this yourself since not all mixins use factories.
+      #       context module_ancestor_factory do # using class method
+      #         subject(module_ancestor_factory) do # using class method
+      #           FactoryGirl.build(module_ancestor_factory) # using instance method
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @example Using shared example
+      #   describe Metasploit::Model::Module::Ancestor do
+      #     it_should_behave_like 'Metasploit::Model::Module::Ancestor',
+      #                           namespace_name: 'Dummy'
+      #   end
+      #
+      # @param relative_name [String] name relative to 'Metasploit::Model' prefix.  For example, to declare
+      #   'Metasploit::Model::Module::Ancestor' shared example, `relative_name` would be just 'Module::Ancestor'.
+      # @yield Body of shared examples.
+      # @yieldreturn [void]
+      # @return [void]
+      def self.shared_examples_for(relative_name, &block)
+        fully_qualified_name = "Metasploit::Model::#{relative_name}"
+
+        relative_variable_name = relative_name.underscore.gsub('/', '_')
+        class_method_name = "#{relative_variable_name}_class"
+        factory_method_name = "#{relative_variable_name}_factory"
+
+        # capture block to pass to super so that source_location can be overridden to be block's source_location so that
+        # errors are reported correctly from RSpec.
+        wrapper = ->(options={}) {
+          options.assert_valid_keys(:namespace_name)
+          namespace_name = options.fetch(:namespace_name)
+
+          class_name = "#{namespace_name}::#{relative_name}"
+
+          #
+          # Singleton methods to emulate local variable used to define examples and lets
+          #
+
+          define_singleton_method(class_method_name) do
+            class_name.constantize
+          end
+
+          define_singleton_method(factory_method_name) do
+            "#{factory_namespace}_#{relative_variable_name}"
+          end
+
+          define_singleton_method(:factory_namespace) do
+            namespace_name.underscore.gsub('/', '_')
+          end
+
+          define_singleton_method(:namespace_name) do
+            namespace_name
+          end
+
+          define_singleton_method(:relative_variable_name) do
+            relative_variable_name
+          end
+
+          #
+          # Defines to emulate local variable used inside lets
+          #
+
+          define_method(class_method_name) do
+            self.class.send(class_method_name)
+          end
+
+          define_method(factory_method_name) do
+            self.class.send(factory_method_name)
+          end
+
+          #
+          # Default subject uses factory
+          #
+
+          subject(relative_variable_name) do
+            FactoryGirl.build(send(factory_method_name))
+          end
+
+          #
+          # lets
+          #
+
+          let(:base_class) do
+            self.class.send(class_method_name)
+          end
+
+          it_should_behave_like 'Metasploit::Model::Translation',
+                                metasploit_model_ancestor: fully_qualified_name.constantize
+
+          module_eval(&block)
+        }
+
+        # Delegate source_location so that RSpec will report block's source_location as the declaration location of
+        # the shared location instead of this method.
+        wrapper.define_singleton_method(:source_location) do
+          block.source_location
+        end
+
+        super(fully_qualified_name, &wrapper)
+      end
+    end
+  end
+end