metasploit_data_models 0.18.1 → 0.19.0

data/lib/metasploit_data_models/ip_address/range.rb

@@ -0,0 +1,181 @@
+# Common behavior for ranges under {MetasploitDataModels::IPAddress}, including ranges of addresses and segments.
+module MetasploitDataModels::IPAddress::Range
+  # so that translations for error messages can be filed under metasploit_data_models/ip_address/range
+  extend ActiveModel::Naming
+  extend ActiveSupport::Concern
+
+  #
+  # CONSTANTS
+  #
+
+  # Separator between the {#begin} and {#end} in the formatted value.
+  SEPARATOR = '-'
+
+  #
+  # Attributes
+  #
+
+  # @!attribute value
+  #   The range.
+  #
+  #   @return [Range<Object, Objectr>] Range with {ClassMethods#extreme_class} instances for `Range#begin` and
+  #     `Range#end`.
+  #   @return [String] if `formatted_value` cannot be parsed into a Range.
+  attr_reader :value
+
+  included do
+    include ActiveModel::Validations
+
+    #
+    #
+    # Validations
+    #
+    #
+
+    #
+    # Validation Methods
+    #
+
+    validate :extremes_valid
+    validate :order
+
+    #
+    # Validation Attributes
+    #
+
+    validates :begin,
+              presence: true
+    validates :end,
+              presence: true
+
+  end
+
+
+  # Class methods added to the including `Class`.
+  module ClassMethods
+    # @note Call {#extremes} first to set {#extreme_class_name}.
+    #
+    # Regular expression that matches a string exactly when it contains an IP address range with the correct
+    # {#extreme_class}.
+    #
+    # @return [Regexp] {#regexp} pinned with `'\A'` and `'\z'` to the whole `String`.
+    def match_regexp
+      @match_regexp ||= /\A#{regexp}\z/
+    end
+
+    # @note Call {#extremes} first to set {#extreme_class_name}.
+    #
+    # The `Class` for each extreme (`Range#begin` and `Range#end`) of the range.
+    #
+    # @return [Class]
+    def extreme_class
+      @extreme_class ||= extreme_class_name.constantize
+    end
+
+    # The name of {#extreme_class}.
+    #
+    # @return [String] `Class#name` passed to :class_name key when {#extremes} was called.
+    # @return [nil] if {#extremes} has not been called.
+    def extreme_class_name
+      @extreme_class_name
+    end
+
+    # Sets {#extreme_class_name}.
+    #
+    # @example Setting extremes class name
+    #   extremes class_name: 'MetasploitDataModels::IPAddress::V4::Single'
+    #
+    # @param options [Hash{Symbol => String}]
+    # @option options [String] :class_name {#extreme_class_name}.
+    # @return [void]
+    def extremes(options={})
+      options.assert_valid_keys(:class_name)
+
+      @extreme_class_name = options.fetch(:class_name)
+    end
+
+    # @note Call {#extremes} first to set {#extreme_class_name}.
+    #
+    # Regular expression match a {SEPARATOR} separated range with {#extreme_class} parseable `Range#begin` and
+    # `Range#end`.
+    #
+    # @return [Regexp]
+    def regexp
+      @regexp ||= /#{extreme_class.regexp}#{SEPARATOR}#{extreme_class.regexp}/
+    end
+  end
+
+  #
+  # Instance Methods
+  #
+
+  # Begin of segment range.
+  #
+  # @return [MetasploitDataModels::IPAddress::V4::NMAP::Segment::Number] if {#value} is a `Range`.
+  # @return [nil] if {#value} is not a `Range`.
+  def begin
+    if value.respond_to? :begin
+      value.begin
+    end
+  end
+
+  # End of segment range.
+  #
+  # @return [MetasploitDataModels::IPAddress::V4::NMAP::Segment::Number] if {#value} is a `Range`.
+  # @return [nil] if {#value} is not a `Range`.
+  def end
+    if value.respond_to? :end
+      value.end
+    end
+  end
+
+  # This range as a string.  Equivalent to the original `formatted_value` passed to {#value}.
+  #
+  # @return [String]
+  def to_s
+    "#{self.begin}#{SEPARATOR}#{self.end}"
+  end
+
+  # Sets {#value} by breaking up the range into its begin and end Integers.
+  #
+  # @param formatted_value [#to_s]
+  # @return [Range<Integer, Integer>] if {SEPARATOR} is used and both extremes are Integers.
+  # @return [#to_s] `formatted_value` if it could not be converted
+  def value=(formatted_value)
+    formatted_extremes = formatted_value.to_s.split(SEPARATOR, 2)
+
+    extremes = formatted_extremes.map { |formatted_extreme|
+      self.class.extreme_class.new(value: formatted_extreme)
+    }
+
+    begin
+      @value = Range.new(*extremes)
+    rescue ArgumentError
+      @value = formatted_value
+    end
+  end
+
+  private
+
+  # Validates that {#begin} and {#end} are valid.
+  #
+  # @return [void]
+  def extremes_valid
+    [:begin, :end].each do |extreme_name|
+      extreme_value = send(extreme_name)
+
+      unless extreme_value.respond_to?(:valid?) && extreme_value.valid?
+        errors.add(extreme_name, :invalid)
+      end
+    end
+  end
+
+  # Validates that {#begin} is `<=` {#end}.
+  #
+  # @return [void]
+  def order
+    if self.begin && self.end && self.begin > self.end
+      errors.add(:value, :order, begin: self.begin, end: self.end)
+    end
+  end
+end

data/lib/metasploit_data_models/match/child.rb

@@ -0,0 +1,48 @@
+# Adds a {#match match class method} to the extending class.  The extending class must define `MATCH_REGEXP`.
+#
+# @example Define `match` class method
+#   class MetasploitDataModels::Format
+#     extend MetasploitDataModels::Match::Child
+#
+#     #
+#     # CONSTANTS
+#     #
+#
+#     # Regular expression {MetasploitDataModels::Match#match} must match against.
+#     MATCH_REGEXP = /\A...\z/
+#   end
+#
+#   # a `MetasploitDataModels::Format` because `'123'` matches `MetasploitDataModels::Format::MATCH_REGEXP`
+#   instance = MetapsloitDataModels::Format.match('123')
+#   # `nil` because string `'12'` doesn't match `MetasploitDataModels::Format::MATCH_REGEXP`
+#   no_instance = MetasploitDataModels::Format.match('12')
+#
+module MetasploitDataModels::Match::Child
+  # Creates a new instance of the extending class if `MATCH_REGEXP`, defined on the extending class, matches
+  # `formatted_value`.
+  #
+  # @param formatted_value [#to_s]
+  def match(formatted_value)
+    instance = nil
+
+    if match_regexp.match(formatted_value)
+      instance = new(value: formatted_value)
+    end
+
+    instance
+  end
+
+  # Regular expression to match against for {#match}.
+  #
+  # @return [Regexp] Defaults to {#regexp} pinned with `\A` and `\z`.
+  def match_regexp
+    @match_regexp ||= /\A#{regexp}\z/
+  end
+
+  # Regular expression to match child as part of {MetasploitDataModels::Match::Parent}.
+  #
+  # @return [Regexp] Default to `REGEXP` from the extending `Class`.
+  def regexp
+    self::REGEXP
+  end
+end

data/lib/metasploit_data_models/match/parent.rb

@@ -0,0 +1,103 @@
+# Uses classes that extend {MetasploitDataModels::Match::Child}
+#
+# @example Add match_child to class.
+#   class Parent
+#     include MetasploitDataModels::Match::Parent
+#
+#     match_children_named %w{FirstChild SecondChild}
+#   end
+module MetasploitDataModels::Match::Parent
+  extend ActiveSupport::Concern
+
+  # @example Declaring children classes
+  #   class FirstChild < Metasploit::Model::Base
+  #     extend MetasploitDataModels::Match::Child
+  #
+  #     #
+  #     # CONSTANTS
+  #     #
+  #
+  #     # Matches a range.
+  #     MATCH_REGEXP = /\A\d+-\d+\z/
+  #
+  #     #
+  #     # Attributes
+  #     #
+  #
+  #     # @!attribute value
+  #     #   The range
+  #     #
+  #     attr_accessor :value
+  #   end
+  #
+  #   class SecondChild < Metasploit::Model::Base
+  #     extend MetasploitDataModels::Match::Child
+  #
+  #     #
+  #     # CONSTANTS
+  #     #
+  #
+  #     # Matches a range.
+  #     MATCH_REGEXP = /\A\d+\z/
+  #
+  #     #
+  #     # Attributes
+  #     #
+  #
+  #     # @!attribute value
+  #     #   The range
+  #     #
+  #     attr_accessor :value
+  #   end
+  #
+  #   class Parent
+  #     include MetasploitDataModels::Match::Parent
+  #
+  #     match_children_named %w{FirstChild SecondChild}
+  #   end
+  module ClassMethods
+    # `Class#name` for classes that extend {MetasploitDataModels::Match::Child} and should be tested using `match`.
+    #
+    # @return [Array<String>]
+    def match_child_names
+      @match_child_names ||= []
+    end
+
+    # `Class`es on which to call `match` in {MetasploitDataModels::Match::Parent#match_child}
+    #
+    # @return [Array<String>]
+    def match_children
+      @match_children ||= match_child_names.map(&:constantize)
+    end
+
+    # @note `Class`es named `class_names`
+    # Register the given `class_names` as `Class#name`s for children classes for
+    # {MetasploitDataModels::Match::Parent#match_child}.
+    #
+    # @return [Array<String>] class_names`
+    def match_children_named(class_names)
+      @match_child_names = class_names
+    end
+  end
+
+  #
+  # Instance Methods
+  #
+
+  # @param formatted_value [#to_s] A formatted value for the child's `#value`.
+  # @return [Object] instance of the first of {ClassMethods#match_children} that matches the `formatted_value`.
+  # @return [nil] if no {ClassMethods#match_children} matches the `formatted_value`.
+  def match_child(formatted_value)
+    child = nil
+
+    self.class.match_children.each do |child_class|
+      child = child_class.match(formatted_value)
+
+      if child
+        break
+      end
+    end
+
+    child
+  end
+end

data/lib/metasploit_data_models/version.rb

@@ -4,14 +4,14 @@ module MetasploitDataModels
     # The major version number.
     MAJOR = 0
     # The minor version number, scoped to the {MAJOR} version number.
-    MINOR = 18
+    MINOR = 19
     # The patch number, scoped to the {MINOR} version number.
-    PATCH = 1
+    PATCH = 0
 
-    # The full version string, including the {MAJOR}, {MINOR}, {PATCH}, and optionally, the {PRERELEASE} in the
+    # The full version string, including the {MAJOR}, {MINOR}, {PATCH}, and optionally, the `PRERELEASE` in the
     # {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0} format.
     #
-    # @return [String] '{MAJOR}.{MINOR}.{PATCH}' on master.  '{MAJOR}.{MINOR}.{PATCH}-{PRERELEASE}' on any branch
+    # @return [String] '{MAJOR}.{MINOR}.{PATCH}' on master.  '{MAJOR}.{MINOR}.{PATCH}-PRERELEASE' on any branch
     #   other than master.
     def self.full
       version = "#{MAJOR}.#{MINOR}.#{PATCH}"

data/metasploit_data_models.gemspec

@@ -30,7 +30,8 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rake'
 
   # documentation
-  s.add_development_dependency 'yard'
+  # @note 0.8.7.4 has a bug where attribute writers show up as undocumented
+  s.add_development_dependency 'yard', '< 0.8.7.4'
   # debugging
   s.add_development_dependency 'pry'
 

data/spec/app/models/mdm/cred_spec.rb

@@ -83,14 +83,63 @@ describe Mdm::Cred do
   end
 
   context 'methods' do
+    #
+    # lets
+    #
+
+    let(:host) {
+      FactoryGirl.create(
+          :mdm_host,
+          workspace: workspace
+      )
+    }
+
+    let(:other_service) {
+      FactoryGirl.create(
+          :mdm_service,
+          host: host
+      )
+    }
+
+    let(:service) {
+      FactoryGirl.create(
+          :mdm_service,
+          host: host
+      )
+    }
+
+    let(:ssh_key) {
+      FactoryGirl.create(
+          :mdm_cred,
+          pass: '/path/to/keyfile',
+          proof: "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a",
+          ptype: 'ssh_key',
+          service: service,
+          user: 'msfadmin'
+      )
+    }
+
+    let(:ssh_pubkey) {
+      FactoryGirl.create(
+          :mdm_cred,
+          pass: '/path/to/keyfile',
+          proof: "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a",
+          ptype: 'ssh_pubkey',
+          service: service,
+          user: 'msfadmin'
+      )
+    }
+
+    let(:workspace) {
+      FactoryGirl.create(:mdm_workspace)
+    }
+
+    #
+    # Callbacks
+    #
+
     before(:all) do
       Mdm::Workspace.any_instance.stub(:valid_ip_or_range? => true)
-      workspace =  FactoryGirl.create(:mdm_workspace)
-      host = FactoryGirl.create(:mdm_host, :workspace => workspace)
-      @svc1 = FactoryGirl.create(:mdm_service, :host => host)
-      @svc2 = FactoryGirl.create(:mdm_service, :host => host)
-      @cred1 = FactoryGirl.create(:mdm_cred, :service => @svc1, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_key', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
-      @pubkey = FactoryGirl.create(:mdm_cred, :service => @svc1, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_pubkey', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
     end
 
     context '#ptype_human' do
@@ -140,79 +189,163 @@ describe Mdm::Cred do
 
     context '#ssh_key_matches?' do
       it 'should return true if the ssh_keys match' do
-        cred2 = FactoryGirl.create(:mdm_cred, :service => @svc2, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_key', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
-        cred2.ssh_key_matches?(@cred1).should == true
+        other_ssh_key = FactoryGirl.create(
+            :mdm_cred,
+            pass: '/path/to/keyfile',
+            proof: 'KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a',
+            ptype: 'ssh_key',
+            service: other_service,
+            user: 'msfadmin'
+        )
+
+        expect(other_ssh_key.ssh_key_matches?(ssh_key)).to eq(true)
       end
 
       it 'should return false if passed something other than a cred' do
-        @cred1.ssh_key_matches?(@svc1).should == false
+        expect(ssh_key.ssh_key_matches?(service)).to eq(false)
       end
 
       it 'should return false if the ptypes do not match' do
-        cred2 = FactoryGirl.create(:mdm_cred, :service => @svc2, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_pubkey', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
-        cred2.ssh_key_matches?(@cred1).should == false
+        different_ptype = FactoryGirl.create(
+            :mdm_cred,
+            pass: '/path/to/keyfile',
+            proof: 'KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a',
+            ptype: 'ssh_pubkey',
+            service: other_service,
+            user: 'msfadmin'
+        )
+
+        expect(different_ptype.ssh_key_matches?(ssh_key)).to eq(false)
       end
 
       it 'should return false if the key ids do not match' do
-        cred2 = FactoryGirl.create(:mdm_cred, :service => @svc2, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_pubkey', :proof => "KEY=66:d4:22:6e:88:d6:74:A1:44:3e:d6:d5:AA:89:73:8b")
-        cred2.ssh_key_matches?(@cred1).should == false
+        different_proof = FactoryGirl.create(
+            :mdm_cred,
+            pass: '/path/to/keyfile',
+            proof: 'KEY=66:d4:22:6e:88:d6:74:A1:44:3e:d6:d5:AA:89:73:8b',
+            ptype: 'ssh_pubkey',
+            service: other_service,
+            user: 'msfadmin'
+        )
+
+        expect(different_proof.ssh_key_matches?(ssh_key)).to eq(false)
       end
 
       it 'should behave the same for public keys as private keys' do
-        pubkey2 = FactoryGirl.create(:mdm_cred, :service => @svc1, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_pubkey', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
-        pubkey3 = FactoryGirl.create(:mdm_cred, :service => @svc1, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_pubkey', :proof => "KEY=66:d4:22:6e:88:d6:74:A1:44:3e:d6:d5:AA:89:73:8b")
-        pubkey2.ssh_key_matches?(@pubkey).should == true
+        pubkey2 = FactoryGirl.create(:mdm_cred, :service => service, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_pubkey', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
+        pubkey3 = FactoryGirl.create(:mdm_cred, :service => service, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_pubkey', :proof => "KEY=66:d4:22:6e:88:d6:74:A1:44:3e:d6:d5:AA:89:73:8b")
+        pubkey2.ssh_key_matches?(ssh_pubkey).should == true
         pubkey2.ssh_key_matches?(pubkey3).should == false
       end
 
       it 'should always return false for non ssh key creds' do
-        cred2 = FactoryGirl.create(:mdm_cred, :service => @svc2, :ptype => 'password', :user => 'msfadmin', :pass => 'msfadmin' )
-        cred3 = FactoryGirl.create(:mdm_cred, :service => @svc2, :ptype => 'password', :user => 'msfadmin', :pass => 'msfadmin' )
+        cred2 = FactoryGirl.create(:mdm_cred, :service => other_service, :ptype => 'password', :user => 'msfadmin', :pass => 'msfadmin' )
+        cred3 = FactoryGirl.create(:mdm_cred, :service => other_service, :ptype => 'password', :user => 'msfadmin', :pass => 'msfadmin' )
         cred2.ssh_key_matches?(cred3).should == false
       end
     end
 
     context '#ssh_keys' do
-      before(:all) do
-        @cred2 = FactoryGirl.create(:mdm_cred, :service => @svc2, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_key', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
+      #
+      # lets
+      #
+
+      let(:other_ssh_key) {
+        FactoryGirl.create(
+            :mdm_cred,
+            pass: '/path/to/keyfile',
+            proof: 'KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a',
+            ptype: 'ssh_key',
+            service: other_service,
+            user: 'msfadmin'
+        )
+      }
+
+      #
+      # Callbacks
+      #
+
+      before(:each) do
+        ssh_key
+        ssh_pubkey
       end
+
       it 'should return all ssh private keys with a matching id' do
-        @cred2.ssh_keys.should include(@cred1)
+        other_ssh_key.ssh_keys.should include(ssh_key)
       end
 
       it 'should return all ssh public keys with a matching id' do
-        @cred2.ssh_keys.should include(@pubkey)
+        other_ssh_key.ssh_keys.should include(ssh_pubkey)
       end
     end
 
     context '#ssh_private_keys' do
-      before(:all) do
-        @cred2 = FactoryGirl.create(:mdm_cred, :service => @svc2, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_key', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
+      #
+      # lets
+      #
+
+      let(:other_ssh_key) {
+        FactoryGirl.create(
+            :mdm_cred,
+            pass: '/path/to/keyfile',
+            proof: 'KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a',
+            ptype: 'ssh_key',
+            service: other_service,
+            user: 'msfadmin',
+        )
+      }
+
+      #
+      # Callbacks
+      #
+
+      before(:each) do
+        ssh_key
+        ssh_pubkey
       end
 
       it 'should return ssh private keys with matching ids' do
-        @cred2.ssh_private_keys.should include(@cred1)
+        other_ssh_key.ssh_private_keys.should include(ssh_key)
       end
 
       it 'should not return ssh public keys with matching ids' do
-        @cred2.ssh_private_keys.should_not include(@pubkey)
+        other_ssh_key.ssh_private_keys.should_not include(ssh_pubkey)
       end
     end
 
     context '#ssh_public_keys' do
-      before(:all) do
-        @cred2 = FactoryGirl.create(:mdm_cred, :service => @svc2, :user => 'msfadmin', :pass => '/path/to/keyfile', :ptype => 'ssh_key', :proof => "KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a")
+      #
+      # lets
+      #
+
+      let(:other_ssh_key) {
+        FactoryGirl.create(
+            :mdm_cred,
+            pass: '/path/to/keyfile',
+            proof: 'KEY=57:c3:11:5d:77:c5:63:90:33:2d:c5:c4:99:78:62:7a',
+            ptype: 'ssh_key',
+            service: other_service,
+            user: 'msfadmin'
+        )
+      }
+
+      #
+      # Callbacks
+      #
+
+      before(:each) do
+        ssh_key
+        ssh_pubkey
       end
 
       it 'should not return ssh private keys with matching ids' do
-        @cred2.ssh_public_keys.should_not include(@cred1)
+        other_ssh_key.ssh_public_keys.should_not include(ssh_key)
       end
 
       it 'should return ssh public keys with matching ids' do
-        @cred2.ssh_public_keys.should include(@pubkey)
+        other_ssh_key.ssh_public_keys.should include(ssh_pubkey)
       end
     end
-
   end
 
   context 'factory' do