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

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

@@ -0,0 +1,60 @@
+# A search operator declared with
+# {Metasploit::Model::Search::Attribute::ClassMethods#search_attribute search_attribute}.
+class Metasploit::Model::Search::Operator::Attribute < Metasploit::Model::Search::Operator::Single
+  #
+  # CONSTANTS
+  #
+
+  # The valid {#type types}.
+  TYPES = [
+      :boolean,
+      :date,
+      :integer,
+      {
+          set: :integer
+      },
+      {
+          set: :string
+      },
+      :string
+  ]
+
+  #
+  # Attributes
+  #
+
+  # @!attribute [r] attribute
+  #   The attribute on {Metasploit::Model::Search::Operator::Base#klass klass} that is searchable.
+  #
+  #   @return [Symbol] the attribute name
+  attr_accessor :attribute
+
+  # @!attribute [r] type
+  #   The type of {#attribute}.
+  #
+  #   @return [Symbol] Value from {TYPES}.
+  attr_accessor :type
+
+  #
+  # Validations
+  #
+
+  validates :attribute, :presence => true
+  validates :type,
+            :inclusion => {
+                :in => TYPES
+            }
+
+  #
+  # Methods
+  #
+
+  # Set for {#attribute} as provided by {Metasploit::Model::Search::Operator::Base#klass #klass}.
+  #
+  # @return [Enumerable, #include?]
+  def attribute_set
+    klass.send("#{attribute}_set")
+  end
+
+  alias_method :name, :attribute
+end

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

@@ -0,0 +1,34 @@
+# @abstract Declare search operators using {Metasploit::Model::Search::ClassMethods#search_attribute} and include
+#   operators from associations with {Metasploit::Model::Search::ClassMethods#search_association}.
+#
+# A search operator.
+class Metasploit::Model::Search::Operator::Base < Metasploit::Model::Base
+  include ActiveModel::Validations
+  include Metasploit::Model::Search::Operator::Help
+
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] klass
+  #   The class on which this operator is usable.
+  #
+  #   @return [Class]
+  attr_accessor :klass
+
+  #
+  # Validations
+  #
+
+  validates :klass, :presence => true
+
+  # @abstract subclass and derive operator name from attributes of subclass.
+  #
+  # Name of this operator.
+  #
+  # @return [String]
+  # @raise [NotImplementedError]
+  def name
+    raise NotImplementedError
+  end
+end

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

@@ -0,0 +1,40 @@
+# An operator that delegates to another operator(s).
+class Metasploit::Model::Search::Operator::Delegation < Metasploit::Model::Search::Operator::Base
+  #
+  # Methods
+  #
+
+  # @note Can't be called `name` because it would alias `Class#name`.
+  #
+  # Name of this operator.
+  #
+  # @return [String]
+  def self.operator_name
+    @operator_name ||= name.demodulize.underscore.to_sym
+  end
+
+  # Name of operator.
+  #
+  # @return (see operator_name)
+  def name
+    @name ||= self.class.operator_name
+  end
+
+  protected
+
+  # Finds operator with the given name on {Metasploit::Model::Search::Operator::Base#klass}.
+  #
+  # @param formatted_operator [#to_sym] Name of operator.
+  # @return [Metasploit::Model::Search::Operator::Base] if operator with `formatted_operator` for
+  #   {Metasploit::Model::Search::Operator::Base#name} exists for {Metasploit::Model::Search::Operator::Base#klass}.
+  def operator(formatted_operator)
+    name = formatted_operator.to_sym
+    operator = klass.search_operator_by_name[name]
+
+    unless operator
+      raise ArgumentError, "No operator with name #{name.inspect} on #{klass}"
+    end
+
+    operator
+  end
+end

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

@@ -0,0 +1,27 @@
+# Emulates the deprecated `app` operator by converting it to the union of `authors.name:<value>`,
+# `email_addresses.local<value before '@'>`, and `email_addresses.domain:<value before '@'>` in {#operate_on}.
+class Metasploit::Model::Search::Operator::Deprecated::App < Metasploit::Model::Search::Operator::Delegation
+  #
+  # CONSTANTS
+  #
+
+  # Maps values passed to deprecated `app` operator to the equivalent value for the `stance` operator.
+  STANCE_BY_APP = {
+      'client' => 'passive',
+      'server' => 'aggressive'
+  }
+
+  #
+  # Methods
+  #
+
+  # Converts `app:client` to `stance:passive` and `app:server` to `stance:aggressive`.
+  #
+  # @return [Metasploit::Model::Search::Operation::Base]
+  def operate_on(formatted_value)
+    stance_value = STANCE_BY_APP[formatted_value]
+    stance_operator = operator('stance')
+
+    stance_operator.operate_on(stance_value)
+  end
+end

data/app/models/metasploit/model/search/operator/deprecated/author.rb

@@ -0,0 +1,33 @@
+# Operator that emulates the behavior of 'author' operator that could search `Mdm::Module::Detail` by making
+# {Metasploit::Model::Search::Operation::Union} between `authors.name`, `email_addresss.domain`, and
+# `email_addresses.local`.
+class Metasploit::Model::Search::Operator::Deprecated::Author < Metasploit::Model::Search::Operator::Union
+  # Turns author:<formatted_value> into Array of authors.name:<formatted_value>,
+  # email_addresses.domain:<formatted_value>, and email_addresses.local:<formatted_value> operations.  If there is an
+  # '@' in `formatted_value`, then the portion of `formatted_value` before the '@' is used for `email_addresses.local`
+  # and the portion of `formatted_value` after the '@' is used for `email_addresses.domain`.
+  #
+  # @param formatted_value [String] value after ':' in formatted operation.
+  # @return [Array<Metasploit::Model::Search::Operation::Base>]
+  def children(formatted_value)
+    operations = []
+
+    authors_name_operator = operator('authors.name')
+    operations << authors_name_operator.operate_on(formatted_value)
+
+    if formatted_value.include? '@'
+      local, domain = formatted_value.split('@', 2)
+    else
+      domain = formatted_value
+      local = formatted_value
+    end
+
+    email_address_domain_operator = operator('email_addresses.domain')
+    operations << email_address_domain_operator.operate_on(domain)
+
+    email_addresses_local_operator = operator('email_addresses.local')
+    operations << email_addresses_local_operator.operate_on(local)
+
+    operations
+  end
+end

data/app/models/metasploit/model/search/operator/deprecated/authority.rb

@@ -0,0 +1,43 @@
+# Operator for the direct, single authority reference search.  Translates `<abbreviation>:<designation>` to
+# `authorities.abbreviation:<abbreviation> references.designation:<designation>`.
+class Metasploit::Model::Search::Operator::Deprecated::Authority < Metasploit::Model::Search::Operator::Delegation
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] abbreviation
+  #   Value passed to `authorities.abbreviation` operator
+  #
+  #   @return [String]
+  attr_accessor :abbreviation
+
+  #
+  # Validations
+  #
+
+  validates :abbreviation,
+            :presence => true
+
+  #
+  # Methods
+  #
+
+  alias_method :name, :abbreviation
+
+  # Returns list of operations that search for the authority with {#abbreviation} and `formatted_value` for reference
+  # designation.
+  #
+  # @return [Array<Metasploit::Model::Search::Operation::Base>] authorities.abbreviation:<abbreviation>
+  #   references.designation:<formatted_value>
+  def operate_on(formatted_value)
+    operations = []
+
+    authorities_abbreviation_operator = operator('authorities.abbreviation')
+    operations << authorities_abbreviation_operator.operate_on(abbreviation)
+
+    references_designation_operator = operator('references.designation')
+    operations << references_designation_operator.operate_on(formatted_value)
+
+    operations
+  end
+end

data/app/models/metasploit/model/search/operator/deprecated/platform.rb

@@ -0,0 +1,45 @@
+# Translates `<name>:<value>` to the union of `platforms.name:<value>` and `targets.name:<value>` in order to support
+# the `os` and `platform` operators.
+class Metasploit::Model::Search::Operator::Deprecated::Platform < Metasploit::Model::Search::Operator::Union
+  #
+  # CONSTANTS
+  #
+
+  # Formatted operators that should be part of {#children} for this union.
+  FORMATTED_OPERATORS = [
+      'platforms.fully_qualified_name',
+      'targets.name'
+  ]
+
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] name
+  #   Name of this operator
+  #
+  #   @return [Symbol]
+  attr_accessor :name
+
+  #
+  # Validations
+  #
+
+  validates :name,
+            :presence => true
+
+  #
+  # Methods
+  #
+
+  # Array of `platforms.fully_qualified_name:<formatted_value>` and `targets.name:<formatted_value>` operations.
+  #
+  # @param formatted_value [String] value parsed from formatted operation.
+  # @return [Array<Metasploit::Model::Search::Operation::Base>]
+  def children(formatted_value)
+    FORMATTED_OPERATORS.collect { |formatted_operator|
+      association_operator = operator(formatted_operator)
+      association_operator.operate_on(formatted_value)
+    }
+  end
+end

data/app/models/metasploit/model/search/operator/deprecated/ref.rb

@@ -0,0 +1,50 @@
+# Translates `ref:<value>` to union of `authorities.abbreviation:<value>`, `references.designation:<value>`, and
+# `references.designation:<value>`.
+class Metasploit::Model::Search::Operator::Deprecated::Ref < Metasploit::Model::Search::Operator::Union
+  # Array of `authorities.abbreviation:<formatted_value>`, `references.designation:<formatted_value>`, and
+  # `references.url:<formatted_value>`.  If `formatted_value` contains a '-' then the portion of `formatted_value`
+  # before '-' is treated is passed to `authorities.abbreviation` and the portion of `formatted_value` after '-' is
+  # treated is passed to `references.designation`.  If the portion of `formatted_value` before the '-'
+  # case-insensitively matches 'URL', then `authorities.abbreviation` and `references.designation` is not used and the
+  # portion of `formatted_value` after the '-' is passed to `references.url`.  If any portion of the parsed
+  # `formatted_value` is blank, then the corresponding child operation will not be in the returned Array.
+  #
+  # @param formatted_value [String] value parsed from formatted operation.
+  # @return [Array<Metasploit::Model::Search::Operation::Base>]
+  def children(formatted_value)
+    if formatted_value.include? '-'
+      head, tail = formatted_value.split('-', 2)
+
+      if head.casecmp('URL') == 0
+        # URL is not a valid abbreviation
+        abbreviation = nil
+        designation = nil
+        url = tail
+      else
+        abbreviation = head
+        designation = tail
+        url = nil
+      end
+    else
+      abbreviation = formatted_value
+      designation = formatted_value
+      url = formatted_value
+    end
+
+    operations = []
+
+    unless abbreviation.blank?
+      operations << operator('authorities.abbreviation').operate_on(abbreviation)
+    end
+
+    unless designation.blank?
+      operations << operator('references.designation').operate_on(designation)
+    end
+
+    unless url.blank?
+      operations << operator('references.url').operate_on(url)
+    end
+
+    operations
+  end
+end

data/app/models/metasploit/model/search/operator/deprecated/text.rb

@@ -0,0 +1,32 @@
+# Search the equivalent of the text fields from `Mdm::Module::Detail` and its associations, making a union of
+# `description`, `name`, `actions.name`, `architectures.abbreviation`, `platform`, and `ref`.
+class Metasploit::Model::Search::Operator::Deprecated::Text < Metasploit::Model::Search::Operator::Union
+  #
+  # CONSTANTS
+  #
+
+  # Names of operators that are unioned together for {Metasploit::Model::Search::Operator::Union#operate_on}.
+  OPERATOR_NAMES = [
+      'description',
+      'name',
+      'actions.name',
+      'architectures.abbreviation',
+      # platforms.name or targets.name
+      'platform',
+      # authors.name, references.designation, or references.url are handled by
+      # {Metasploit::Model::Search::Operator::Deprecated::Ref} to reuse its special parsing of the old
+      # <abbreviation OR 'URL'>-<designation or url> format.
+      'ref',
+  ]
+
+  # `description`, `name`, `actions.name`, `architectures.abbreviation`, `platform`, and `ref`.
+  #
+  # @param formatted_value [String] value parsed from formatted operation
+  # @return [Array<Metasploit::Model::Search::Operation::Base>]
+  def children(formatted_value)
+    OPERATOR_NAMES.collect { |operator_name|
+      named_operator = operator(operator_name)
+      named_operator.operate_on(formatted_value)
+    }
+  end
+end

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

@@ -0,0 +1,44 @@
+# Operator used when the formatted operator name does not match a class's operators.
+class Metasploit::Model::Search::Operator::Null < Metasploit::Model::Search::Operator::Single
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] name
+  #   The name of this operator that was not the name of a search operator for
+  #   {Metasploit::Model::Search::Operator::Base#klass}.
+  #
+  #   @return [Symbol]
+  attr_accessor :name
+
+  #
+  # Validations
+  #
+
+  validate :name_invalid
+
+  # Null operators do not have a type since the attribute is unknown.
+  #
+  # @return [nil]
+  def type
+    nil
+  end
+
+  protected
+
+  # Null operation Class.
+  #
+  # @return [Class] {Metasploit::Model::Search::Operation::Null}
+  def operation_class
+    Metasploit::Model::Search::Operation::Null
+  end
+
+  private
+
+  # Always records an error that name is not an operator name
+  #
+  # @return [void]
+  def name_invalid
+    errors.add(:name, :unknown)
+  end
+end

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

@@ -0,0 +1,98 @@
+# @abstract Operator that only returns a single operation from {#operate_on}.
+class Metasploit::Model::Search::Operator::Single < Metasploit::Model::Search::Operator::Base
+  #
+  # CONSTANTS
+  #
+
+  # Separator between parent and child module/class names.
+  MODULE_SEPARATOR = '::'
+  # Name of namespace module for operations returned from {#operation_class} and used by {#operate_on}.
+  OPERATION_NAMESPACE_NAME = "Metasploit::Model::Search::Operation"
+
+  #
+  # Methods
+  #
+
+  # The constant name for the given type.
+  #
+  # @param type [Symbol, Hash]
+  # @return [String]
+  def self.constant_name(type)
+    case type
+      when Hash
+        if type.length < 1
+          raise ArgumentError, "Cannot destructure a Hash without entries"
+        end
+
+        if type.length > 1
+          raise ArgumentError, "Cannot destructure a Hash with multiple entries"
+        end
+
+        partial_types = type.first
+        partial_constant_names = partial_types.collect { |partial_type|
+          constant_name(partial_type)
+        }
+
+        partial_constant_names.join(MODULE_SEPARATOR)
+      when Symbol
+        type.to_s.camelize
+      else
+        raise ArgumentError, "Can only convert Hashes and Symbols to constant names, not #{type.inspect}"
+    end
+  end
+
+  # Creates an {Metasploit::Model::Search::Operation::Base operation} of the correct type for this operator's {#type}.
+  #
+  # @param formatted_value [String] the unparsed value passed to this operator in {Metasploit::Model::Search::Query
+  #   a formatted search query}.
+  # @return [Metasploit::Model::Search::Operation::Base] instance of {#operation_class}.
+  def operate_on(formatted_value)
+    operation_class.new(
+        :value => formatted_value,
+        :operator => self
+    )
+  end
+
+  # @abstract subclass and derive operator type.
+  #
+  # Type of the attribute.
+  #
+  # @return [Symbol]
+  # @raise [NotImplementedError]
+  def type
+    raise NotImplementedError
+  end
+
+  protected
+
+  # The {#type}-specific {Metasploit::Model::Search::Operation::Base} subclass.
+  #
+  # @return [Class<Metasploit::Model::Search::Operation::Base>]
+  # @raise (see #operation_class_name)
+  def operation_class
+    unless instance_variable_defined? :@operation_class
+      @operation_class = operation_class_name.constantize
+    end
+
+    @operation_class
+  end
+
+  # The name of the {#type}-specific {Metasploit::Model::Search::Operation::Base} subclass.
+  #
+  # @return [String]
+  # @raise [ArgumentError]
+  def operation_class_name
+    unless instance_variable_defined? :@operation_class_name
+      unless type
+        raise ArgumentError, "#{self.class}##{__method__} cannot be derived for #{name} operator because its type is nil"
+      end
+
+      partial_constant_names = [OPERATION_NAMESPACE_NAME]
+      partial_constant_names << self.class.constant_name(type)
+
+      @operation_class_name = partial_constant_names.join(MODULE_SEPARATOR)
+    end
+
+    @operation_class_name
+  end
+end