metasploit_data_models 0.17.3 → 0.18.0.pre.compatibility

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MzNkMmMwMGZkMTQ0NzU2ODE5NWRjMjdjMDM3MTRhNGYxMWFkNjdiMQ==
+    YzFjM2E3OTA2OGRhM2RiYTgxZTBiMTViYWU3ODBlOTRlMzFkYmUxNg==
   data.tar.gz: !binary |-
-    MmZkYmE1ODdiYWY2ZTRlYzkxNWUyNWJmOGU5MjMyMWEwMzFjNDcxNg==
+    ZjIyNmQwMGJlODQxMjA1Njg3YWQyZmY4NWI5NGIzOTNhYTI5ZDI0NA==
 SHA512:
   metadata.gz: !binary |-
-    OWM0NDdmZTQ2OTdiOWI2YjQ5OGFmOThlYzE2M2FhZWEwYjQ1MzU1OTI1N2Rm
-    NmE3OTViMWY0YTg2YmNkMzAyYmJjZDY1MDM1MzI1MjNmMWE1N2JkNzZmMTE0
-    N2RjMTdjYWNkYzI3ODhlOTU0Mzg0NWYyY2YxMzg4ODNjMmI0NzU=
+    NWI5MjUyNTVkZGNkMjM5MmZjNjU2ZWYxMGRjZTUzOGFlMTMwZjA4ZGI2Mzlk
+    OWMxMTc4OThlYmYwNzM0MmM2OTMzY2FlNDY0ODdjMWUwMjhiNTY1M2U4ZGM0
+    ZDY5ZWU2Y2FiNmMxNzQ4ODJmZjcwYmMxZDhmZjAwZmU0NTkyMGI=
   data.tar.gz: !binary |-
-    MDc5NDJjYTFkMTdjNTkzOGZhMGM1NjE2YWU0NTA2YTM3Yjg5ZjNkNWRkY2Ri
-    NTIwMmRmNDdiMTg3MzMyYTI5MGJlODliYjFmZTFhZTEyZDc4OWVlZjIwNmQ0
-    YjM2ZmVlYzQwNzhlZmUzNDBkMjA4MzA3NmEwMjBhMDk2MGY3MTI=
+    NWFmZWFhMTc2NDMyYTQ5YzE3YzRhMWJjMjM4N2MyNDViNmJlMmU2OTJkYTM4
+    NWQ2YjYxOWUwMDBkNjgwZTE1YTY0YmU2ZGVmMGE2NWZkZmMzODkwNTAwOGVl
+    MjQwZGQxNTBlOWM2NWIzZDlkZGRhN2RkMzA5NDc0NWM0MmMwYWE=

data/CONTRIBUTING.md

@@ -0,0 +1,164 @@
+# Contributing
+
+## Forking
+
+[Fork this repository](https://github.com/rapid7/metasploit_data_models/fork)
+
+## Branching
+
+Branch names follow the format `TYPE/ISSUE/SUMMARY`.  You can create it with `git checkout -b TYPE/ISSUE/SUMMARY`.
+
+### `TYPE`
+
+`TYPE` can be `bug`, `chore`, or `feature`.
+
+### `ISSUE`
+
+`ISSUE` is either a [Github issue](https://github.com/rapid7/metasploit_data_models/issues) or an issue from some other
+issue tracking software.
+
+### `SUMMARY`
+
+`SUMMARY` is is short summary of the purpose of the branch composed of lower case words separated by '-' so that it is a valid `PRERELEASE` for the Gem version.
+
+## Changes
+
+### `PRERELEASE`
+
+1. Update `PRERELEASE` to match the `SUMMARY` in the branch name.  If you branched from `master`, and [version.rb](lib/metasploit_data_models/version.rb) does not have `PRERELEASE` defined, then adding the following lines after `PATCH`: 
+```
+# The prerelease version, scoped to the {PATCH} version number.
+PRERELEASE = '<SUMMARY>'
+```
+2. `rake spec`
+3.  Verify the specs pass, which indicates that `PRERELEASE` was updated correctly.
+4. Commit the change `git commit -a`
+
+
+### Your changes
+
+Make your changes or however many commits you like, commiting each with `git commit`.
+
+### Pre-Pull Request Testing
+
+1. Run specs one last time before opening the Pull Request: `rake spec`
+2. Verify there was no failures.
+
+### Push
+
+Push your branch to your fork on gitub: `git push push TYPE/ISSUE/SUMMARY`
+
+### Pull Request
+
+* [Create new Pull Request](https://github.com/rapid7/metasploit_data_models/compare/)
+* Add a Verification Steps comment
+
+```
+# Verification Steps
+
+- [ ] `bundle install`
+
+## `rake spec`
+- [ ] `rake spec`
+- [ ] VERIFY no failures
+```
+You should also include at least one scenario to manually check the changes outside of specs.
+
+* Add a Post-merge Steps comment
+
+The 'Post-merge Steps' are a reminder to the reviewer of the Pull Request of how to update the [`PRERELEASE`](lib/metasploit_data_models/version.rb) so that [version_spec.rb](spec/lib/metasploit_data_models/version_spec.rb) passes on the target branch after the merge.
+
+DESTINATION is the name of the destination branch into which the merge is being made.  SOURCE_SUMMARY is the SUMMARY from TYPE/ISSUE/SUMMARY branch name for the SOURCE branch that is being made.
+
+When merging to `master`:
+
+```
+# Post-merge Steps
+
+Perform these steps prior to pushing to master or the build will be broke on master.
+
+## Version
+- [ ] Edit `lib/metasploit_data_models/version.rb`
+- [ ] Remove `PRERELEASE` and its comment as `PRERELEASE` is not defined on master.
+
+## Gem build
+- [ ] gem build *.gemspec
+- [ ] VERIFY the gem has no '.pre' version suffix.
+
+## RSpec
+- [ ] `rake spec`
+- [ ] VERIFY version examples pass without failures
+
+## Commit & Push
+- [ ] `git commit -a`
+- [ ] `git push origin master`
+```
+
+When merging to DESTINATION other than `master`:
+
+```
+# Post-merge Steps
+
+Perform these steps prior to pushing to DESTINATION or the build will be broke on DESTINATION.
+
+## Version
+- [ ] Edit `lib/metasploit_data_models/version.rb`
+- [ ] Change `PRERELEASE` from `SOURCE_SUMMARY` to `DESTINATION_SUMMARY` to match the branch (DESTINATION) summary (DESTINATION_SUMMARY)
+
+## Gem build
+- [ ] gem build *.gemspec
+- [ ] VERIFY the prerelease suffix has change on the gem.
+
+## RSpec
+- [ ] `rake spec`
+- [ ] VERIFY version examples pass without failures
+
+## Commit & Push
+- [ ] `git commit -a`
+- [ ] `git push origin DESTINATION`
+```
+
+* Add a 'Release Steps' comment
+
+The 'Release Steps' are a reminder to the reviewer of the Pull Request of how to release the gem.
+
+```
+# Release
+
+Complete these steps on DESTINATION
+
+## Version
+
+### Compatible changes
+
+If the change are compatible with the previous branch's API, then increment [`PATCH`](lib/metasploit_data_models/version.rb).
+
+### Incompatible changes
+
+If your changes are incompatible with the previous branch's API, then increment
+[`MINOR`](lib/metasploit_data_models/version.rb) and reset [`PATCH`](lib/metasploit_data_models/version.rb) to `0`.
+
+- [ ] Following the rules for [semantic versioning 2.0](http://semver.org/spec/v2.0.0.html), update
+[`MINOR`](lib/metasploit_data_models/version.rb) and [`PATCH`](lib/metasploit_data_models/version.rb) and commit the changes.
+
+## JRuby
+- [ ] `rvm use jruby@metasploit_data_models`
+- [ ] `rm Gemfile.lock`
+- [ ] `bundle install`
+- [ ] `rake release`
+
+## MRI Ruby
+- [ ] `rvm use ruby-1.9.3@metasploit_data_models`
+- [ ] `rm Gemfile.lock`
+- [ ] `bundle install`
+- [ ] `rake release`
+```
+
+### Downstream dependencies
+
+When releasing new versions, the following projects may need to be updated:
+
+* [metasploit-credential](https://github.com/rapid7/metasploit-credential)
+* [metasploit-framework](https://github.com/rapid7/metasploit-framework)
+* [metasploit-pro-ui](https://github.com/rapid7/pro/tree/master/ui)
+* [metasploit-pro-engine](https://github.com/rapid7/pro/tree/master/engine)

data/README.md

@@ -40,8 +40,8 @@ different on_load name, which is just the class name converted to an underscored
 
 ### Metasploit Framework
 
-In Metasploit Framework, `MetasploitDataModels.require_models` is called by the `Msf::DbManager` to use the data models
-only if the user wants to use the database.
+In Metasploit Framework, `MetasploitDataModels::Engine` is loaded, but the data models are only if the user wants to use
+the database.
 
 ### Elsewhere
 
@@ -58,3 +58,7 @@ Give it a path to a working MSF database.yml file for full
 ActiveRecord-based access to your data.
 
 __Note:__ "development" mode is hardcoded into the console currently.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)

data/app/models/mdm/host.rb

@@ -481,6 +481,24 @@ class Mdm::Host < ActiveRecord::Base
 
   search_attribute :name,
                    type: :string
+  search_attribute :os_flavor,
+                   type: :string
+  search_attribute :os_name,
+                   type: :string
+  search_attribute :os_sp,
+                   type: :string
+
+  #
+  # Search Withs
+  #
+
+  search_with MetasploitDataModels::Search::Operator::Multitext,
+              name: :os,
+              operator_names: [
+                  :os_name,
+                  :os_flavor,
+                  :os_sp
+              ]
 
   #
   # Instance Methods

data/app/models/mdm/service.rb

@@ -176,6 +176,12 @@ class Mdm::Service < ActiveRecord::Base
           ])
   }
 
+  #
+  #
+  # Search
+  #
+  #
+
   #
   # Search Attributes
   #
@@ -183,6 +189,12 @@ class Mdm::Service < ActiveRecord::Base
   search_attribute :name,
                    type: :string
 
+  #
+  # Search Withs
+  #
+
+  search_with MetasploitDataModels::Search::Operator::Port::List
+
   #
   # Validations
   #
@@ -204,4 +216,3 @@ class Mdm::Service < ActiveRecord::Base
 
   Metasploit::Concern.run(self)
 end
-

data/app/models/metasploit_data_models/search/operation/port/number.rb

@@ -0,0 +1,25 @@
+# Search operation on an attribute that holds a port number and is being searched with a single Integer port number.
+class MetasploitDataModels::Search::Operation::Port::Number < Metasploit::Model::Search::Operation::Integer
+  #
+  # CONSTANTS
+  #
+
+  # The number of bits in a port number
+  BITS = 16
+  # The maximum port number
+  MAXIMUM = (1 << BITS) - 1
+  # The minimum port number
+  MINIMUM = 0
+
+  # The range of valid port numbers from {MINIMUM} to {MAXIMUM}, inclusive.
+  RANGE = (MINIMUM..MAXIMUM)
+
+  #
+  # Validations
+  #
+
+  validates :value,
+            inclusion: {
+                in: RANGE
+            }
+end

data/app/models/metasploit_data_models/search/operation/port/range.rb

@@ -0,0 +1,79 @@
+# Search operation on an attribute that holds a port number and is being search with a range of port numbers.  The
+# range is specified as `<min>-<max>` with `<min>` being less than `<max>` and both being within
+# {MetasploitDataModels::Search::Operation::Port::Range the valid port range}.
+class MetasploitDataModels::Search::Operation::Port::Range < MetasploitDataModels::Search::Operation::Range
+  #
+  # Validations
+  #
+
+  validate :ports
+
+  #
+  # Instance Methods
+  #
+
+  # Sets `#value` to a range of ports.
+  #
+  # @param formatted_value [#to_s] '\d+-\d+'
+  def value=(formatted_value)
+    super(formatted_value)
+
+    # could not be a `Range` if super conversion failed
+    # setters return the argument, not the return value from the method, so access `#value` directly
+    if value.is_a? Range
+      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.
+        integer_begin = Integer(value.begin.to_s)
+        integer_end = Integer(value.end.to_s)
+      rescue ArgumentError
+        # setter returned is ignored in MRI, but do it anyway for other implementation
+        @value
+      else
+        @value = Range.new(integer_begin, integer_end)
+      end
+    else
+      # setter returned is ignored in MRI, but do it anyway for other implementation
+      # return unconvertible value from `super`
+      @value
+    end
+  end
+
+  private
+
+  # @note `#value` should be check to be a `Range` before calling {#port}.
+  #
+  # Validate that either `Range#begin` or `Range#end` is a valid port number in `#value`
+  #
+  # @param extreme [:begin, :end] Which extreme of the `Range` in `value` to validate.
+  # @return [void]
+  def port(extreme)
+    extreme_value = value.send(extreme)
+
+    if extreme_value.is_a? Integer
+      unless MetasploitDataModels::Search::Operation::Port::Number::RANGE.cover?(extreme_value)
+        errors.add(
+            :value,
+            :port_range_extreme_inclusion,
+            extreme: extreme,
+            extreme_value: extreme_value,
+            maximum: MetasploitDataModels::Search::Operation::Port::Number::MAXIMUM,
+            minimum: MetasploitDataModels::Search::Operation::Port::Number::MINIMUM
+        )
+      end
+    else
+      errors.add(:value, :port_range_extreme_not_an_integer, extreme: extreme, extreme_value: extreme_value)
+    end
+  end
+
+  # Validates that the `Range#begin` and `Range#end` of `#value` are valid port numbers.
+  #
+  # @return [void]
+  def ports
+    if value.is_a? Range
+      [:begin, :end].each do |extreme|
+        port(extreme)
+      end
+    end
+  end
+end

data/app/models/metasploit_data_models/search/operation/range.rb

@@ -0,0 +1,56 @@
+# Search operation on a `Range`.
+class MetasploitDataModels::Search::Operation::Range < Metasploit::Model::Search::Operation::Base
+  #
+  # CONSTANTS
+  #
+
+  # Separates beginning from end of the range.
+  SEPARATOR = '-'
+
+  #
+  # Validation
+  #
+
+  validate :ordered
+  validate :range
+
+  #
+  # Instance Methods
+  #
+
+  # Sets `#value` to a `Range` composed by separating `formatted_value` by `-`.
+  #
+  # @param formatted_value [#to_s]
+  # @return [Range<String>]
+  def value=(formatted_value)
+    range_arguments = formatted_value.to_s.split(SEPARATOR, 2)
+
+    begin
+      @value = Range.new(*range_arguments)
+    rescue ArgumentError
+      @value = formatted_value
+    end
+
+    @value
+  end
+
+  private
+
+  # Validates that `#value` is a `Range` with `Range#begin` less than or equal to `Range#begin`
+  #
+  # @return [void]
+  def ordered
+    if value.is_a?(Range) && value.begin > value.end
+      errors.add(:value, :order, begin: value.begin.inspect, end: value.end.inspect)
+    end
+  end
+
+  # Validates that `#value` is a `Range`
+  #
+  # @return [void]
+  def range
+    unless value.is_a? Range
+      errors.add(:value, :range)
+    end
+  end
+end

data/app/models/metasploit_data_models/search/operator/multitext.rb

@@ -0,0 +1,73 @@
+require 'shellwords'
+
+# Searches multiple text fields by breaking up the formatted value into words and doing text search for each word across
+# each operator named in {#operator_names}.
+class MetasploitDataModels::Search::Operator::Multitext < Metasploit::Model::Search::Operator::Group::Intersection
+  #
+  # Attributes
+  #
+
+  # @!attribute name
+  #   The name of this operator.
+  #
+  #   @return [Symbol]
+  attr_accessor :name
+
+  # @!attribute operator_names
+  #   The name of the operators to search across.
+  #
+  #   @return [Array<Symbol>]
+  attr_writer :operator_names
+
+  #
+  # Validations
+  #
+
+  validates :operator_names,
+            length: {
+                minimum: 2
+            }
+  validates :name,
+            presence: true
+
+  #
+  # Instance Methods
+  #
+
+  # Breaks `formatted_value` into words using `Shellwords.split`.  Each word is then searched across all {#operators},
+  # where any operator can match for that word.  The search for multiple multiple is intersected, so that additional
+  # words can refine the search.
+  #
+  # @param formatted_value [#to_s]
+  # @return [Array<Metasploit::Model::Search::Operation::Group::Union>] Unions to be intersected.
+  def children(formatted_value)
+    words = Shellwords.split formatted_value.to_s
+
+    words.map { |word|
+      child_operators = operators.map { |operator|
+        operator.operate_on(word)
+      }
+
+      Metasploit::Model::Search::Operation::Group::Union.new(
+          children: child_operators,
+          operator: self
+      )
+    }
+  end
+
+  # The name of the operators to search for each word.
+  #
+  # @return [Array<Symbol>] Default to `[]`
+  def operator_names
+    @operator_names ||= []
+  end
+
+  # Operators with {#operator_names}.
+  #
+  # @return [Array<Metasploit::Model::Search::Operator::Base>]
+  def operators
+    @operators ||= operator_names.map { |operator_name|
+      operator(operator_name)
+    }
+  end
+end