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

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

@@ -0,0 +1,33 @@
+# Operator that {#operate_on produces} {Metasploit::Model::Search::Operation::Union union operations}.
+class Metasploit::Model::Search::Operator::Union < Metasploit::Model::Search::Operator::Delegation
+  #
+  # Methods
+  #
+
+  # {Metasploit::Model::Search::Operation::Union#children}.
+  #
+  # @param formatted_value [String] value parsed from formatted operation
+  # @return [Array<Metasploit::Model::Search::Operation::Base>]
+  def children(formatted_value)
+    raise NotImplementedError
+  end
+
+  # Unions children operating on `formatted_value`.
+  #
+  # @param formatted_value [String] value parsed from formatted operation.
+  # @return [Metasploit::Model::Search::Operation::Union] Union will not contain {#children} that are invalid.
+  def operate_on(formatted_value)
+    children = self.children(formatted_value)
+
+    # filter children for validity as valid values for one child won't necessarily be valid values for another child.
+    # this is specifically a problem with Metasploit::Model::Search::Operation::Set as no partial matching is allowed,
+    # but can also be a problem with string vs integer operations.
+    valid_children = children.select(&:valid?)
+
+    Metasploit::Model::Search::Operation::Union.new(
+        :children => valid_children,
+        :operator => self,
+        :value => formatted_value
+    )
+  end
+end

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

@@ -0,0 +1,171 @@
+# A search query on a {#klass}.  Parses query from {#formatted} string.
+class Metasploit::Model::Search::Query < Metasploit::Model::Base
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] formatted
+  #   Query string containing space separated <operator>:<value> pairs.
+  #
+  #   @return [String]
+  attr_accessor :formatted
+
+  # @!attribute [rw] formatted_operations
+  #   @note If using `Shellwords.shellsplit` to pre-parse the query, set {#formatted_operations} instead of rejoining
+  #     the shell words with `.join(" ")` and setting {#formatted} as `Shellwords.shellsplit` strips embedded quotes,
+  #     so quoted spaces will not be handled correctly if joining and setting {#formatted}.
+  #
+  #   {#formatted} broken up into individual operation (<operator>:<value>) Strings.
+  attr_writer :formatted_operations
+
+  # @!attribute [rw] klass
+  #   The klass that is being searched.
+  #
+  #   @return [Class, #search_operator_by_name]
+  attr_accessor :klass
+
+  # @!attribute [rw] operations
+  #   The parsed operations in this query.
+  #
+  #   @return [Array<Metasploit::Model::Search::Operation::Base>] An Array of operations.
+  attr_writer :operations
+
+  #
+  # Validations
+  #
+
+  validates :klass, :presence => true
+
+  validates :operations,
+            :length => {
+                :minimum => 1
+            }
+  # validate recursive so misnamed operators or bad values for operator's types cause the query to be invalid as a whole
+  validate :operations_valid
+
+  #
+  # Methods
+  #
+
+  # Parses {#formatted} into a list of formatted operation composed of <formatted_operator>:<formatted_value> Strings.
+  # <formatted_value> may be quoted
+  #
+  # @param formatted [String] a String composed of space-separated <formatted_operator>:<formatted_value>
+  #   operations.  <formatted_value> may be quoted using the shell quoting rules.
+  # @return [Array<String>] Array of formatted operation.
+  # @see Shellwords.shellsplit
+  def self.formatted_operations(formatted)
+    Shellwords.shellsplit(formatted.to_s)
+  end
+
+  # {#formatted} broken up into individual operation (<operator>:<value>) Strings.
+  #
+  # @return [Array<String>]
+  def formatted_operations
+    @formatted_operations ||= self.class.formatted_operations(formatted)
+  end
+
+  # Parses {#formatted} to create search operations that can validate if the
+  # {Metasploit::Model::Search::Operation::Base#value value} is correct the operation's
+  # {Metasploit::Model::Search::Operation::Base#operator operator's} type.
+  #
+  # @return [Array<Metasploit::Model::Search::Operation::Base>] an Array of operation parsed from {#formatted}.
+  def operations
+    unless instance_variable_defined? :@operations
+      @operations = formatted_operations.flat_map { |formatted_operation|
+        Metasploit::Model::Search::Operation.parse(
+            :formatted_operation => formatted_operation,
+            :query => self
+        )
+      }
+    end
+
+    @operations
+  end
+
+  # @note Query is validated before grouping the operations as {Metasploit::Model::Search::Operation::Null operation
+  # using unknown operators} with the same name should not be grouped together when processing this query into an actual
+  # search of record and/or models.
+  #
+  # Groups {#operations} together by {Metasploit::Model::Search::Operation::Base#operator}.
+  #
+  # @return [Hash{Metasploit::Model::Search::Operator::Base => Metasploit::Model::Search::Operation::Base}] Maps
+  #   operator to all its operations.
+  # @raise [Metasploit::Model::Invalid] if query is invalid due to invalid operations.
+  def operations_by_operator
+    unless instance_variable_defined? :@operations_by_operator
+      valid!
+
+      @operations_by_operator = operations.group_by(&:operator)
+    end
+
+    @operations_by_operator ||= operations.group_by(&:operator)
+  end
+
+  # Converts formatted operator extracted from formatted operation to its {Metasploit::Model::Search::Operator::Base}
+  # instance.
+  #
+  # @param formatted_operator [#to_sym] formatted operator as parsed from formatted operation.
+  # @return [Metasploit::Model::Search::Operation::Base] a type-specific search operation if there is an
+  #   {Metasploit::Model::Search::Operator::Base#name} on {#klass} that matches `formatted_operator`.
+  # @return [Metasploit::Model::Search::Operator::Null] if there is not an operator with
+  #   {Metasploit::Model::Search::Operator::Base#name} on {#klass} that matches `formatted_operator`.
+  def parse_operator(formatted_operator)
+    operator_name = formatted_operator.to_sym
+    operator = klass.search_operator_by_name[operator_name]
+
+    unless operator
+      operator = Metasploit::Model::Search::Operator::Null.new(:name => operator_name)
+    end
+
+    operator
+  end
+
+  # Groups {#operations} together by {Metasploit::Model::Search::Operation::Base#operator} into
+  # {Metasploit::Model::Search::Group::Union unions} that are
+  # {Metasploit::Model::Search::Group::Intersection intersected}.
+  #
+  # @return [Metasploit::Model::Search::Group::Intersection<Metasploit::Model::Search::Group::Union<Metasploit::Model::Search::Operation::Base>>]
+  def tree
+    unless instance_variable_defined? :@tree
+      unions = operations_by_operator.collect do |_operator, operations|
+        Metasploit::Model::Search::Group::Union.new(:children => operations)
+      end
+
+      @tree = Metasploit::Model::Search::Group::Intersection.new(:children => unions)
+    end
+
+    @tree
+  end
+
+  # Returns a new query with all {#operations} on the given `operator` removed.
+  #
+  # @param operator [Metasploit::Model::Search::Operator::Base] an operator that should be removed from this query.
+  # @return [Metasploit::Model:Search::Query] a new query if `operator` is a key in {#operations_by_operator}; otherwise
+  #   this query.
+  def without_operator(operator)
+    operations = operations_by_operator[operator]
+
+    if operations
+      filtered_operations = self.operations - operations
+
+      self.class.new(
+          klass: klass,
+          operations: filtered_operations
+      )
+    else
+      self
+    end
+  end
+
+  private
+
+  # Validates that all {#operations} are valid.
+  #
+  # @return [void]
+  def operations_valid
+    unless operations.all?(&:valid?)
+      errors.add(:operations, :invalid)
+    end
+  end
+end

data/app/models/metasploit/model/spec/template.rb

@@ -0,0 +1,273 @@
+# Processes {EXTENSION '.rb.erb'} templates to create {Metasploit::Model::Module::Ancestor#contents} that contain the
+# same metadata as the {Metasploit::Model::Module::Ancestor},
+# {Metasploit::Model::Module::Class}, {Metasploit::Model::Module::Instance} and associations for those contents.  This
+# ensures that when the {Metasploit::Model::Module::Ancestor#contents} are loaded in metasploit-framework, the same
+# metadata instances are derived from the contents ensuring idempotency of the contents and metadata parsing loop.
+class Metasploit::Model::Spec::Template < Metasploit::Model::Base
+  extend ActiveModel::Callbacks
+  include ActiveModel::Validations::Callbacks
+
+  #
+  # CONSTANTS
+  #
+
+  # Regular expression to parse file from backtrace line
+  BACKTRACE_FILE_REGEXP = /(?<file>.*):\d+:in .*/
+  # Trim mode for ERB templates so that lines using <%- -%> will be trimmed of new lines
+  EXPLICIT_TRIM_MODE = '-'
+  # File extension for templates.
+  EXTENSION = '.rb.erb'
+
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] destination_pathname
+  #   The pathname where to {#write} the template results.
+  #
+  #   @return [String]
+  attr_accessor :destination_pathname
+
+  # @!attribute [rw] locals
+  #   Local variables to exposed to partials.
+  #
+  #   @return [Hash{Symbol => Object}]
+  attr_accessor :locals
+
+  # @!attribute [rw] overwrite
+  #   Whether to overwrite a pre-existing file.
+  #
+  #   @return [Boolean]
+  attr_accessor :overwrite
+
+  # @!attribute [rw] search_pathnames
+  #   Pathnames to search for partials.  First item is search first, etc.
+  #
+  #   @return [Array<Pathname>]
+  attr_accessor :search_pathnames
+
+  # @!attribute [rw] source_relative_name
+  #   Name of template under {#search_pathnames} without {EXTENSION} similar to how to refer to partials.
+  #
+  #   @return [String]
+  attr_accessor :source_relative_name
+
+
+  #
+  # Callbacks
+  #
+
+  before_validation :search_real_pathnames
+
+  #
+  # Validations
+  #
+
+  validates :destination_pathname,
+            presence: true
+  validates :overwrite,
+            inclusion: {
+                in: [
+                    false,
+                    true
+                ]
+            }
+  validates :search_pathnames,
+            length: {
+                minimum: 1
+            }
+  validates :source_pathname,
+            presence: true
+
+  #
+  # Methods
+  #
+
+  # Converts the `partial_relative_path` to a real (absolute) pathname that can be passed to {#result} by finding the
+  # corresponding file in the {#search_pathnames}.
+  #
+  # @param partial_relative_path [String] partial path name as used in Rails, so no search_pathname prefix and no '_'
+  #   or file extension in the basename.
+  # @return (see #find_pathname)
+  def partial_pathname(partial_relative_path)
+    partial_relative_pathname = Pathname.new(partial_relative_path)
+    relative_directory = partial_relative_pathname.dirname
+    raw_basename = partial_relative_pathname.basename
+    partial_basename = "_#{raw_basename}#{EXTENSION}"
+    relative_pathname = relative_directory.join(partial_basename)
+
+    find_pathname(relative_pathname)
+  end
+
+  # Renders partial in templates.
+  #
+  # @param partial_relative_path [String] relative path to partial without extension and no leading '_' to match
+  #   Rails convention.
+  # @param options (see #result)
+  # @option (see #result)
+  # @return [String, nil] result of rendering partial.
+  def render(partial_relative_path, options={})
+    pathname = partial_pathname(partial_relative_path)
+    result(pathname, options)
+  end
+
+  # Renders the super template of the current template by searching for the template of the same name under super
+  # {#search_pathnames} (those that have a higher index).
+  #
+  # @return [String, nil] result of rendering super partial.
+  # @raise [IOError] if super template can't be found on super search pathnames.
+  # @raise [RegexpError] if file can't be parsed from backtrace.
+  def render_super
+    super_pathname = nil
+    backtrace = caller
+    match = BACKTRACE_FILE_REGEXP.match(backtrace[0])
+
+    if match
+      real_path = match[:file]
+      current_search_pathname_found = false
+      relative_pathname = nil
+
+      search_pathnames.each do |search_pathname|
+        # find the current index
+        unless current_search_pathname_found
+          if real_path.starts_with?(search_pathname.to_path)
+            current_search_pathname_found = true
+
+            real_pathname = Pathname.new(real_path)
+            relative_pathname = real_pathname.relative_path_from(search_pathname)
+          end
+          # then switch to finding the next (super) index
+        else
+          real_pathname = search_pathname.join(relative_pathname)
+
+          if real_pathname.exist?
+            super_pathname = real_pathname
+            break
+          end
+        end
+      end
+
+      unless super_pathname
+        raise IOError, "Couldn't find super template"
+      end
+    else
+      raise RegexpError, "Can't parse file from backtrace to determine current search path"
+    end
+
+    result(super_pathname)
+  end
+
+  # @note Must be an instance method
+  # @param pathname [Pathname] pathname to template
+  # @param options [Hash{Symbol => Object}]
+  # @option options [Hash{Symbol => Object}] :locals Maps name of locals to their value for this result.  Can override
+  #   {#locals}.
+  def result(pathname, options={})
+    options.assert_valid_keys(:locals)
+
+    if pathname
+      content = pathname.read
+      safe_level = nil
+      template = ERB.new content, safe_level, EXPLICIT_TRIM_MODE
+      template.filename = pathname.to_path
+
+      erb_binding = binding.dup
+      locals = self.locals || {}
+      result_locals = options[:locals] || {}
+      merged_locals = locals.merge(result_locals)
+
+      merged_locals.each do |name, value|
+        erb_binding.eval("#{name} = nil; lambda { |value| #{name} = value }").call(value)
+      end
+
+      # use current binding to allow templates to call {#render} and then use {#method_missing} to allow access to
+      # locals
+      template.result(erb_binding)
+    else
+      ''
+    end
+  end
+
+  class << self
+    # The root of all relative {#search_pathnames}.  By changing {root} you can use your own set of templates.
+    #
+    # @return [Pathname] Defaults to 'spec/support/templates/metasploit/model' under Metasploit::Model.root.
+    def root
+      @@root ||= Metasploit::Model.root.join('spec', 'support', 'templates', 'metasploit', 'model')
+    end
+
+    # Sets the {#root} pathname for all {#search_pathnames}, including those on subclasses.
+    #
+    # @param root [Pathname]
+    # @return [Pathname]
+    def root=(root)
+      @@root = root
+    end
+  end
+
+  # Converts {#source_relative_name} to a real (absolute) pathname.
+  #
+  # @return (see #find_pathname)
+  def source_pathname
+    unless instance_variable_defined? :@source_pathname
+      relative_path = "#{source_relative_name}#{EXTENSION}"
+      @source_pathname = find_pathname(relative_path)
+    end
+
+    @source_pathname
+  end
+
+  # Writes result of template to {#destination_pathname}.
+  #
+  # @return [void]
+  # @raise [Metasploit::Model::Spec::PathnameCollision] if {#overwrite} is false and {#destination_pathname} already
+  #   exists.
+  def write
+    unless overwrite
+      Metasploit::Model::Spec::PathnameCollision.check!(destination_pathname)
+    end
+
+    result = self.result(source_pathname)
+
+    # make directory
+    destination_pathname.parent.mkpath
+
+    destination_pathname.open('wb') do |f|
+      f.write(result)
+    end
+  end
+
+  private
+
+  # Finds relative_path under {#search_pathnames}
+  #
+  # @return [Pathname] if relative_path exists under a search path.
+  # @return [nil] if `relative_path` does not exist under a search path.
+  def find_pathname(relative_path)
+    found_pathname = nil
+
+    search_pathnames.each do |search_pathname|
+      real_pathname = search_pathname.join(relative_path)
+
+      if real_pathname.exist?
+        found_pathname = real_pathname
+        break
+      end
+    end
+
+    found_pathname
+  end
+
+  # Makes sure all {#search_pathnames} are real (absolute).  Relative pathnames are resolved against {root}.
+  #
+  # @return [void]
+  def search_real_pathnames
+    search_pathnames.collect! { |search_pathname|
+      if search_pathname.relative?
+        self.class.root.join(search_pathname)
+      else
+        search_pathname
+      end
+    }
+  end
+end