metasploit-model 0.25.7 → 0.26.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MzQ5ZTQ5ZTE0OWUyM2ZjMmYyNTNkM2NjNDgxZDE2YjkwMjg2OWYxMw==
+    YzE5ZmE5MjgxN2RlZjhlMDk1NTM1OTcwYjZiZWRjMmRiOWI5ZDQ1Ng==
   data.tar.gz: !binary |-
-    OWEyNjhlMmQwYzkwMzAyY2U1M2Q5MmNlNTAzOGFmYjQzYmE0YjlmYQ==
+    NmJjYTg0NWIwZGIxNzUyZGMwYmUyOTVlMzdlMGNmNGU5MDNkNjJiMQ==
 SHA512:
   metadata.gz: !binary |-
-    YzE0OTc5MGM1MDM0MmI5MTBmM2U3Y2U2NjZkY2Q5Y2FkNjM2ZGM1YWViZTgx
-    ZjllODJiMGIwOTQyNGNiNTEzNTZiMzRiNjk3NWE1ZjkxOGE4NTU4NDk3NjA1
-    NDhiNjI2NTMyYzBjZWE1NTJkMTZhM2IyNDRhZDZlNTQ4MGE1MmI=
+    MTNhYzY1MWNiNTNkNWY0ODBkZGMzNDMxN2JiYjA4YTlkNzg4Mzg3ZTRiNWI2
+    YTVmOGY1YWI1ZTVkZDdkMDJkN2M1NzU0ZGUzMmVkNDBiMThlZGVhMTg3MmRh
+    ZmQwZDI0NGJlYWRhMTQ3YTg5MDFiNmVlNDNiYjZjMzAwZWI4MjM=
   data.tar.gz: !binary |-
-    NGZmNDQxZTczOWJiMTA4ZmU2ODgwOWEwNTViNjBiY2YyNjMyNGZkYTRmNjIy
-    ODA2NDRlOThlMzNiODU4NGU4Y2IzMzlkZmVmNDE4N2E0YTM1ZTc2NTk0NjM5
-    YTA4NTY2YTU2ZWZhYmIwNmFlNWYyNmRiMDk2NzBlM2Q2YzhhMTM=
+    OWJmNTc3ZGM2MmJmZjUwNjJlZTUzZTI0NTY1ZjRjZWVhNWNkYWFiODQ4YjAz
+    OGJlZjM4ZDI5NjJkODI5MjdlOTEzZDVjYTI2YmRkMGJmMjNjMDUzOTM3NTVh
+    YTUyODRhMDViOWJiODg0Zjc5ZDI0NmQxYTg3M2VlNmEwNzdhNzA=

data/app/models/metasploit/model/search/operation/association.rb

@@ -0,0 +1,57 @@
+# An operation with a {Metasploit::Model::Search::Operator::Association} for
+# {Metasploit::Model::Search::Operation::Base#operator} that wraps a {#source_operation} produced by the
+# {Metasploit::Model::Search::Operator::Association#source_operator}.  This allows an arbitrary number of associations
+# to be changed together until a non-association operation is found that actually validates the value.
+class Metasploit::Model::Search::Operation::Association < Metasploit::Model::Search::Operation::Base
+  #
+  # Attributes
+  #
+
+  # @!attribute source_operation
+  #   The operation from the {Metasploit::Model::Search::Operator::Association#source_operator}.
+  #
+  #   @return [Metasploit::Model::Search::Operation::Base]
+  attr_accessor :source_operation
+
+  #
+  #
+  # Validations
+  #
+  #
+
+  #
+  # Validation Methods
+  #
+
+  validate :source_operation_valid
+
+  #
+  # Attribute Validations
+  #
+
+  validates :source_operation,
+            presence: true
+
+  #
+  # Instance Methods
+  #
+
+  # Explicitly remove value attribute so code that depends on the old behavior will break so downstream developers know
+  # to update their code to use source_operation.
+  undef_method :value
+  undef_method :value=
+
+  private
+
+  # Validates that {#source_operation} is valid.
+  #
+  # @return [void]
+  def source_operation_valid
+    # presence validation handles errors when nil
+    if source_operation
+      unless source_operation.valid?
+        errors.add(:source_operation, :invalid)
+      end
+    end
+  end
+end

data/app/models/metasploit/model/search/operator/association.rb

@@ -1,43 +1,53 @@
 # A search operator declared with
 # {Metasploit::Model::Search::Association::ClassMethods#search_association search_association}.
-class Metasploit::Model::Search::Operator::Association < Metasploit::Model::Search::Operator::Single
+class Metasploit::Model::Search::Operator::Association < Metasploit::Model::Search::Operator::Base
   #
   # Attributes
   #
 
   # @!attribute [rw] association
-  #   The association on which {Metasploit::Model::Search::Operator::Attribute#attribute} is declared searchable.
+  #   The association on which {#source_operator} was declared.
   #
   #   @return [Symbol] association on {Metasploit::Model::Search::Operator::Base#klass klass}.
   attr_accessor :association
 
-  # @!attribute [rw] attribute_operator
-  #   The {Metasploit::Model::Search::Operator::Attribute operator} as declared on the {#association} class.
+  # @!attribute [rw] source_operator
+  #   The {Metasploit::Model::Search::Operator::Base operator} as declared on the {#association} class.
   #
-  #   @return [Metasploit::Model::Search::Operator::Attribute]
-  attr_accessor :attribute_operator
+  #   @return [Metasploit::Model::Search::Operator::Base]
+  attr_accessor :source_operator
 
   #
   # Validations
   #
 
   validates :association, :presence => true
-  validates :attribute_operator, :presence => true
+  validates :source_operator, :presence => true
 
   #
   # Methods
   #
 
-  delegate :attribute,
-           :attribute_set,
-           :help,
-           :type,
-           :to => :attribute_operator
+  delegate :help,
+           to: :source_operator
 
   # The name of this operator.
   #
-  # @return [String] <association>.<attribute>
+  # @return [String] <association>.<source_operator.name>
   def name
-    @name ||= "#{association}.#{attribute}".to_sym
+    @name ||= "#{association}.#{source_operator.name}".to_sym
+  end
+
+  # Creates a {Metasploit::Model::Search::Operation::Association} to wrap the original operation returned by
+  #   {#source_operator}'s `#operate_on`.
+  #
+  # @param formatted_value [#to_s] Formatted value to pass to {#source_operator}.
+  # @return [Metasploit::Model::Search::Operation::Association] Association operation with the original operation from
+  #   {#source_operator} operating on `formatted_value`.
+  def operate_on(formatted_value)
+    Metasploit::Model::Search::Operation::Association.new(
+        operator: self,
+        source_operation: source_operator.operate_on(formatted_value)
+    )
   end
 end

data/app/models/metasploit/model/search/operator/base.rb

@@ -1,7 +1,23 @@
-# @abstract Declare search operators using {Metasploit::Model::Search::ClassMethods#search_attribute} and include
-#   operators from associations with {Metasploit::Model::Search::ClassMethods#search_association}.
+# Instead of writing an operator completely from scratch, you can subclass
+# {Metasploit::Model::Search::Operator::Base}.
+#
+#     class MyOperator < Metasploit::Model::Search::Operator::Base
+#       # Name of this operator.  The name of the operator is matched to the string before the ':' in a formatted
+#       # operation.
+#       #
+#       # @return [Symbol]
+#       def name
+#         # ...
+#       end
+#
+#       # Creates a one or more operations based on `formatted_value`.
+#       #
+#       # @return [#operator, Array<#operator>] Operation with this operator as the operation's `operator`.
+#       def operate_on(formatted_value)
+#         # ...
+#       end
+#     end
 #
-# A search operator.
 class Metasploit::Model::Search::Operator::Base < Metasploit::Model::Base
   include ActiveModel::Validations
   include Metasploit::Model::Search::Operator::Help

data/app/models/metasploit/model/search/operator/single.rb

@@ -1,4 +1,24 @@
-# @abstract Operator that only returns a single operation from {#operate_on}.
+# If all you want do is customize the name and operation `Class` that your custom operator class returns from
+# `#operate_on`, then you can subclass {Metasploit::Model::Search::Operator::Single} instead of
+# {Metasploit::Model::Search::Operator::Base}.
+#
+#     class MyOperator < Metasploit::Model::Search::Operator::Single
+#       # Name of this operator.  The name of the operator is matched to the string before the ':' in a formatted
+#       # operation.
+#       #
+#       # @return [Symbol]
+#       def name
+#         # ...
+#       end
+#
+#       # `Class.name` of `Class` returned from {Metasploit::Model::Search::Operator::Single#operate_on}.
+#       #
+#       # @return [String] a `Class.name`
+#       def operation_class_name
+#         # ...
+#       end
+#     end
+#
 class Metasploit::Model::Search::Operator::Single < Metasploit::Model::Search::Operator::Base
   #
   # CONSTANTS

data/app/models/metasploit/model/search/query.rb

@@ -1,4 +1,23 @@
-# A search query on a {#klass}.  Parses query from {#formatted} string.
+# Once {Metasploit::Model::Search::Operator search operators} are {Metasploit::Model::Search defined}, a formatted
+# query, composed of space separated formatted operation, `<operator.name>:<formatted_value>`, can be parsed to
+# produce a validatable query.
+#
+#     query = Metasploit::Model::Search::Query.new(
+#       formatted: 'parts.number:1 parts.number:2 parts.uuid:EX,QR'
+#     )
+#
+# Operations using the same operator are unioned together, while operations with different operator are intersected
+# together, so the above formatted query can be thought of as
+# `(parts.number:1 || parts.number:2) && parts.uuid:EX,QR`.
+#
+# # Results
+#
+# Once a {Metasploit::Model::Search::Query} is defined, it needs to be converted to a data store specific visitor.
+#
+# Visitors for `ActiveRecord` are defined in
+# {http://rubydoc.info/gems/metasploit_data_models/MetasploitDataModels/Search/Visitor MetasploitDataModels::Search::Visitor}.
+#
+# If you want to define your own visitors, you can subclass {Metasploit::Model::Visitation::Visitor}.
 class Metasploit::Model::Search::Query < Metasploit::Model::Base
   #
   # Attributes

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

@@ -0,0 +1,130 @@
+module Metasploit
+  module Model
+    module Association
+      # Functions for turning a compact tree of compact as passed to
+      # {Metasploit::Model::Search::Association::ClassMethods#search_associations} into an expanded
+      # {Metasploit::Model::Search::Association::ClassMethods#search_association_tree}.
+      module Tree
+        # Expands a `compact` association into an expanded association tree.
+        #
+        # @param compact [Array, Hash{Symbol => Array,Hash,Symbol}, Symbol] a compact association as passed to
+        #   {Metasploit::Model::Search::Association::ClassMethods#search_associations}.
+        # @return [Hash{Symbol => Hash,nil}]
+        def self.expand(compact)
+          case compact
+            when Array
+              compact.reduce({}) { |hash, association|
+                hash.merge(expand(association))
+              }
+            when Hash
+              child_by_parent = compact
+
+              child_by_parent.each_with_object({}) { |(parent, child), hash|
+                hash[parent] = expand(child)
+              }
+            when Symbol
+              association = compact
+
+              {association => nil}
+          end
+        end
+
+        # @note Unlike `Hash#deep_merge`, `second_expanded`'s values aren't favored over `first`'s values.  Instead whichever
+        #   side is present is used and if both `first` and `second_expanded` are present, then their `Hash#key`s' values are
+        #   recursively merged.
+        #
+        # Merges two expanded association trees.
+        #
+        # @param first_expanded [nil, Hash{Symbol => nil,Hash}] An expanded association tree as from {expand}
+        # @param second_expanded [nil, Hash{Symbol => nil,Hash}] An expanded association tree as from {expand}
+        # @return [nil, Hash{Symbol => nil,Hash}] a new expanded association tree.
+        def self.merge(first_expanded, second_expanded)
+          if first_expanded.nil? && second_expanded.nil?
+            nil
+          elsif !first_expanded.nil? && second_expanded.nil?
+            first_expanded
+          elsif first_expanded.nil? && !second_expanded.nil?
+            second_expanded
+          else
+            first_keys = first_expanded.keys
+            key_set = Set.new(first_keys)
+
+            second_keys = second_expanded.keys
+            key_set.merge(second_keys)
+
+            key_set.each_with_object({}) do |key, merged|
+              first_child = first_expanded[key]
+              second_child = second_expanded[key]
+
+              merged[key] = merge(first_child, second_child)
+            end
+          end
+        end
+
+        # Calculates association operators for the `expanded` association tree.
+        #
+        # @param expanded [Hash{Symbol => Hash,nil}, nil] An expanded association tree.
+        # @param options [Hash{Symbol => Class}]
+        # @option options [Class, #reflect_on_association] :class The `Class` on which the top-level key associations in
+        #   `expanded` are declared.
+        # @return [Array<Metasploit::Model::Search::Operator::Association>]
+        def self.operators(expanded, options={})
+          expanded ||= {}
+
+          options.assert_valid_keys(:class)
+          klass = options.fetch(:class)
+
+          expanded.flat_map { |parent_association, child_tree|
+            reflection = reflect_on_association_on_class(parent_association, klass)
+            association_class = reflection.klass
+
+            association_search_with_operators = association_class.search_with_operator_by_name.each_value
+
+            child_tree_operators = operators(
+                child_tree,
+                class: reflection.klass
+            )
+
+            [association_search_with_operators, child_tree_operators].flat_map { |enumerator|
+              enumerator.map { |source_operator|
+                Metasploit::Model::Search::Operator::Association.new(
+                    association: parent_association,
+                    klass: klass,
+                    source_operator: source_operator
+                )
+              }
+            }
+          }
+        end
+
+        private
+
+        # Return the association reflection for `association` on `klass`.
+        #
+        # @param association [Symbol] name of an association on `klass`.
+        # @param klass [#reflect_on_association] `Class` on which `association` is declared.
+        # @return [#klass] Association reflection that can give the `#klass` pointed to by the association.
+        # @raise [Metasploit::Model::Association::Error] if `association` is not declared on `klass`.
+        # @raise [NameError] if `klass` does not respond to `reflect_on_association`.
+        def self.reflect_on_association_on_class(association, klass)
+          begin
+            reflection = klass.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: klass,
+                      name: association
+                  )
+          end
+
+          reflection
+        end
+      end
+    end
+  end
+end

data/lib/metasploit/model/search.rb

@@ -2,6 +2,65 @@ 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.
+    #
+    # # Operators
+    #
+    # Search operators define how to search against a given `Class`.
+    #
+    # ## Attributes
+    #
+    # Boolean, `Date`, `Integer`, and `String` attributes can be searched with
+    # {Metasploit::Model::Search::Attribute::ClassMethods#search_attribute search_attribute}.  `Integer` and `String`
+    # attributes can be further restricted to a defined `Set` of values.
+    #
+    #     class Part
+    #       include Metasploit::Model::Search
+    #
+    #       search_attribute :part,
+    #                        :integer
+    #     end
+    #
+    # The above defines the `:part` operator on `Part`.
+    #
+    # ## Custom search operators
+    #
+    # If a search operator does not directly correspond to an attribute or a the attribute needs custom validation, then
+    # a custom {Metasploit::Model::Search::Operator operator class} can be setup as the search operator
+    #
+    #     class Search::Operator::UUID
+    #       def name
+    #         :uuid
+    #       end
+    #     end
+    #
+    #     class Part
+    #       include Metasploit::Model::Search
+    #
+    #       search_with Search::Operator::UUID
+    #     end
+    #
+    # The above defines the `:uuid` operator on `Part`.
+    #
+    # ## Associations
+    #
+    # Search operators registered with
+    # {Metasploit::Model::Search::Attribute::ClassMethods#search_attribute search_attribute} or
+    # {Metasploit::Model::Search::With::ClassMethods#search_with search_with} on an associated `Class` can be searched
+    # with {Metasploit::Model::Search::Association::ClassMethods#search_association}:
+    #
+    #     class Widget
+    #       include Metasploit::Model::Search
+    #
+    #       # declare parts association
+    #
+    #       search_association :parts
+    #     end
+    #
+    # The above will define the `:'parts.number'` and `:'parts.uuid'` operator on `Widget`.
+    #
+    # # Queries
+    #
+    # {include:Metasploit::Model::Search::Query}
     module Search
       extend ActiveSupport::Concern
 
@@ -25,33 +84,8 @@ module Metasploit
               @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
+            search_association_operators.each do |operator|
+              @search_operator_by_name[operator.name] = operator
             end
           end