metasploit_data_models 1.0.0.pre.rails.pre.4.0b → 1.0.0

data/app/models/metasploit_data_models/automatic_exploitation/match_result.rb

@@ -1,27 +1,44 @@
+# The result of {#run running} a {#match}.
 class MetasploitDataModels::AutomaticExploitation::MatchResult < ActiveRecord::Base
+  #
+  # CONSTANTS
+  #
 
   # Running associated exploit did NOT create a session
   FAILED = "failed"
   # Running associated exploit created a session
   SUCCEEDED = "succeeded"
 
+  # Valid values for {#state}
   VALID_STATES = [FAILED, SUCCEEDED]
 
   #
-  # ASSOCIATIONS
+  # Associations
   #
 
+  # A {MetasploitDataModels::AutomaticExploitation::Match#module_detail Metasploit Module} matched to
+  # {MetasploitDataModels::AutomaticExploitation::Match#matchable Mdm::Host or Mdm::Service}.
   belongs_to :match,
              class_name: 'MetasploitDataModels::AutomaticExploitation::Match',
              inverse_of: :match_results,
              dependent: :destroy
 
+  # A mass automatic exploitation run.
   belongs_to :run,
              inverse_of: :match_results,
              class_name: 'MetasploitDataModels::AutomaticExploitation::Run'
 
   #
-  # VALIDATIONS
+  # Attributes
+  #
+
+  # @!attribute state
+  #   Whether the {#run} of {#match} succeeded.
+  #
+  #   @return ['failed', 'succeeded']
+
+  #
+  # Validations
   #
 
   # must be present and one of allowable values
@@ -30,10 +47,14 @@ class MetasploitDataModels::AutomaticExploitation::MatchResult < ActiveRecord::B
             inclusion: VALID_STATES
 
   #
-  # SCOPES
+  # Scopes
   #
-  scope :succeeded, lambda { where(state:"succeeded") }
+
+  # Runs of {#match} that failed
   scope :failed, lambda { where(state:"failed") }
 
+  # Runs of {#match} that succeeded
+  scope :succeeded, lambda { where(state:"succeeded") }
+
   Metasploit::Concern.run(self)
 end

data/app/models/metasploit_data_models/automatic_exploitation/match_set.rb

@@ -1,22 +1,33 @@
+# A set of {#matches automatic exploitation matches}.
 class MetasploitDataModels::AutomaticExploitation::MatchSet < ActiveRecord::Base
+  #
+  # Associations
+  #
 
+  # Runs of this set of {#matches}.
   has_many :runs,
            class_name: "MetasploitDataModels::AutomaticExploitation::Run",
            inverse_of: :match_set
 
+  # Matches in this set.
   has_many :matches,
            class_name: "MetasploitDataModels::AutomaticExploitation::Match",
            inverse_of: :match_set,
            dependent: :destroy
 
-  belongs_to :workspace,
-             inverse_of: :automatic_exploitation_match_sets,
-             class_name: "Mdm::Workspace"
-
+  # User that created this match set.
   belongs_to :user,
              inverse_of: :automatic_exploitation_match_sets,
              class_name: "Mdm::User"
 
+  # Workspace in which this match set exists.
+  belongs_to :workspace,
+             inverse_of: :automatic_exploitation_match_sets,
+             class_name: "Mdm::Workspace"
+
+  #
+  # Validations
+  #
 
   validates :user,
             presence: true

data/app/models/metasploit_data_models/automatic_exploitation/run.rb

@@ -1,25 +1,29 @@
+# Runs a {#match_set set of matches} to produce {#match_results results}.
 class MetasploitDataModels::AutomaticExploitation::Run < ActiveRecord::Base
   #
-  # ASSOCIATIONS
+  # Associations
   #
+
+  # Results of each match in {#match_set}.
   has_many :match_results,
            class_name:'MetasploitDataModels::AutomaticExploitation::MatchResult',
            inverse_of: :run,
            dependent: :destroy
 
+  # Set of matches to run
   belongs_to :match_set,
              class_name: 'MetasploitDataModels::AutomaticExploitation::MatchSet',
              inverse_of: :runs
 
+  # User that initiated this run.
   belongs_to :user,
              class_name: "Mdm::User",
              inverse_of: :automatic_exploitation_runs
 
+  # Workspace in which this run was performed.
   belongs_to :workspace,
              class_name: "Mdm::Workspace",
              inverse_of: :automatic_exploitation_runs
 
-
-
   Metasploit::Concern.run(self)
 end

data/app/models/metasploit_data_models/ip_address/v4/segmented.rb

@@ -67,7 +67,7 @@ class MetasploitDataModels::IPAddress::V4::Segmented < Metasploit::Model::Base
   #
   # @return [Regexp]
   def self.regexp
-    unless @regexp
+    unless instance_variable_defined? :@regexp
       separated_segment_count = SEGMENT_COUNT - 1
 
       @regexp = %r{

data/app/models/metasploit_data_models/module_run.rb

@@ -34,7 +34,7 @@ class MetasploitDataModels::ModuleRun < ActiveRecord::Base
   #   @return [String]
 
   # @!attribute [rw] fail_reason
-  #   One of the values of the constants in {Msf::Module::Failure}
+  #   One of the values of the constants in `Msf::Module::Failure`
   #   @return [String]
 
   # @!attribute [rw] module_name

data/app/models/metasploit_data_models/search/visitor/where.rb

@@ -32,7 +32,7 @@ class MetasploitDataModels::Search::Visitor::Where
     }
   end
 
-  visit *EQUALITY_OPERATION_CLASS_NAMES do |operation|
+  visit(*EQUALITY_OPERATION_CLASS_NAMES) do |operation|
     attribute = attribute_visitor.visit operation.operator
 
     attribute.eq(operation.value)

data/app/validators/ip_format_validator.rb

@@ -1,6 +1,10 @@
 require "ipaddr"
 
+# Validates that attribute is a valid IPv4 or IPv6 address.
 class IpFormatValidator < ActiveModel::EachValidator
+  # Validates that `attribute`'s `value` on `object` is a valid IPv4 or IPv6 address.
+  #
+  # @return [void]
   def validate_each(object, attribute, value)
     error_message_block = lambda{ object.errors[attribute] << " must be a valid IPv4 or IPv6 address" }
     begin

data/app/validators/parameters_validator.rb

@@ -1,9 +1,21 @@
 # Validates that attribute's value is Array<Array(String, String)> which is the only valid type signature for serialized
 # parameters.
 class ParametersValidator < ActiveModel::EachValidator
+  #
+  # CONSTANTS
+  #
+
   # Sentence explaining the valid type signature for parameters.
   TYPE_SIGNATURE_SENTENCE = 'Valid parameters are an Array<Array(String, String)>.'
 
+  #
+  # Instance Methods
+  #
+
+  # Validates that `attribute`'s `value` on `record` is `Array<Array(String, String)>` which is the only valid type
+  # signature for serialized parameters.
+  #
+  # @return [void]
   def validate_each(record, attribute, value)
     if value.is_a? Array
       value.each_with_index do |element, index|

data/app/validators/password_is_strong_validator.rb

@@ -1,12 +1,21 @@
+# Validates that
 class PasswordIsStrongValidator < ActiveModel::EachValidator
+  #
+  # CONSTANTS
+  #
+
+  # Known passwords that should NOT be allowed and should be considered weak.
   COMMON_PASSWORDS = %w{
       password pass root admin metasploit
       msf 123456 qwerty abc123 letmein monkey link182 demo
       changeme test1234 rapid7
     }
 
+  # Special characters that are considered to strength passwords and are required once in a strong password.
   SPECIAL_CHARS = %q{!@"#$%&'()*+,-./:;<=>?[\\]^_`{|}~ }
 
+  # Validates that the `attribute`'s `value` on `record` contains letters, numbers, and at least one special character
+  # without containing the `record.username`, any {COMMON_PASSWORDS} or repetition.
   def validate_each(record, attribute, value)
     return if value.blank?
 
@@ -34,7 +43,7 @@ class PasswordIsStrongValidator < ActiveModel::EachValidator
   end
 
   def contains_username?(username, password)
-    password =~ /#{username}/i
+    !!(password =~ /#{username}/i)
   end
 
   def is_common_password?(password)

data/lib/mdm/host/operating_system_normalization.rb

@@ -185,15 +185,6 @@ module Mdm::Host::OperatingSystemNormalization
     # Merge and normalize the best match to the host object
     apply_match_to_host(match) if match
 
-    # Handle cases where the flavor contains the base name (legacy parsing, etc)
-    # TODO: Remove this once we are sure it is no longer needed
-    if host.os_name && host.os_flavor && host.os_flavor.index(host.os_name)
-      dlog("Host #{host.address.to_s} has os_flavor that contains os_name")
-      dlog("os_flavor: #{host.os_flavor}")
-      dlog("os_name: #{host.os_name}")
-      host.os_flavor = host.os_flavor.gsub(host.os_name, '').strip
-    end
-
     # Set some sane defaults if needed
     host.os_name ||= 'Unknown'
     host.purpose ||= 'device'
@@ -201,6 +192,10 @@ module Mdm::Host::OperatingSystemNormalization
     host.save if host.changed?
   end
 
+  # Recog matches for the `s` service.
+  #
+  # @param s [Mdm::Service]
+  # @return [Array<Hash>] Keys will be host, service, and os attributes
   def recog_matches_for_service(s)
     #
     # We assume that the service.info field contains certain types of probe
@@ -242,6 +237,9 @@ module Mdm::Host::OperatingSystemNormalization
     matches
   end
 
+  # Recog matches for the fingerprint in `note`.
+  #
+  # @return [Array<Hash>] Keys will be host, service, and os attributes
   def recog_matches_for_note(note)
     # Skip notes that are missing the correct structure or have been blacklisted
     return [] if not validate_fingerprint_data(note)
@@ -302,7 +300,6 @@ module Mdm::Host::OperatingSystemNormalization
       # name collision seems silly.
       return false
     else
-      dlog("Could not validate fingerprint data: #{fp.inspect}")
       return false
     end
   end

data/lib/metasploit_data_models.rb

@@ -26,6 +26,7 @@ require 'metasploit_data_models/version'
 
 autoload :Mdm, 'mdm'
 
+# Core database models for metasploit-framework.
 module MetasploitDataModels
   extend ActiveSupport::Autoload
 
@@ -38,6 +39,9 @@ module MetasploitDataModels
   autoload :Search
   autoload :SerializedPrefs
 
+  # The root directory of `metasploit_data_models` gem in both development and gem installs.
+  #
+  # @return [Pathname]
   def self.root
     unless instance_variable_defined? :@root
       lib_pathname = Pathname.new(__FILE__).dirname

data/lib/metasploit_data_models/automatic_exploitation.rb

@@ -0,0 +1,25 @@
+# Namespace for automatic exploitation.  Automatic exploitation
+# {MetasploitDataModels::AutomaticExploitation::Match matches}
+# {MetasploitDataModels::AutomaticExploitation::Match#matchable services or vulnerbatility} with the
+# {MetasploitDataModels::AutomaticExploitation::Match#module_detail Metasploit Module} that can exploit the service or
+# vulnerability.  These matches are grouped into a {MetasploitDataModels::AutomaticExploitation::MatchSet a set} that
+# can be {MetasploitDataModels::AutomaticExploitation::Run run} multiple times.
+module MetasploitDataModels::AutomaticExploitation
+  extend ActiveSupport::Autoload
+
+  autoload :Match
+  autoload :MatchResult
+  autoload :MatchSet
+  autoload :Run
+
+  #
+  # Module Methods
+  #
+
+  # The prefix of the `ActiveRecord::Base#table_name` of subclasses in this namespace.
+  #
+  # @return [String]
+  def self.table_name_prefix
+    'automatic_exploitation_'
+  end
+end

data/lib/metasploit_data_models/engine.rb

@@ -1,5 +1,7 @@
 require 'rails'
 
+# `Rails::Engine` that exposes MetasploitDataModel's `ActiveRecord::Base` subclasses and automatically loads its
+# `FactoryGirl` factories, sequences, and traits.
 class MetasploitDataModels::Engine < Rails::Engine
   # @see http://viget.com/extend/rails-engine-testing-with-rspec-capybara-and-factorygirl
   config.generators do |g|

data/lib/metasploit_data_models/serialized_prefs.rb

@@ -1,4 +1,10 @@
+# Allows attributes to be extracted and written to key of serialized `Hash` `prefs`.
 module MetasploitDataModels::SerializedPrefs
+  # Setup each arg in `args` as the name of an attribute embedded in the `prefs` `Hash`.  Defines `#<arg>` and
+  # `#<arg>=(value)` methods like standard `attr_accessor`.
+  #
+  # @param args [Array<Symbol>] The names of the attributes to store in the `prefs` `Hash`.
+  # @return [void]
   def serialized_prefs_attr_accessor(*args)
     args.each do |method_name|
 

data/lib/metasploit_data_models/version.rb

@@ -1,20 +1,29 @@
 module MetasploitDataModels
   # Holds components of {VERSION} as defined by {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0}.
   module Version
+    #
+    # CONSTANTS
+    #
+
     # The major version number.
     MAJOR = 1
     # The minor version number, scoped to the {MAJOR} version number.
     MINOR = 0
-    # The patch number, scoped to the {MAJOR} and {MINOR} version numbers.
+    # The patch version number, scoped to the {MAJOR} and {MINOR} version numbers.
     PATCH = 0
-    # The prerelease version, scoped to the {MAJOR}, {MINOR}, and {PATCH} version numbers.
-    PRERELEASE = 'rails-4.0b'
 
-    # The full version string, including the {MAJOR}, {MINOR}, {PATCH}, and optionally, the `PRERELEASE` in the
+    #
+    # Module Methods
+    #
+
+    # The full version string, including the {MetasploitDataModels::Version::MAJOR},
+    # {MetasploitDataModels::Version::MINOR}, {MetasploitDataModels::Version::PATCH}, and optionally, the
+    # `MetasploitDataModels::Version::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
-    #   other than master.
+    # @return [String] '{MetasploitDataModels::Version::MAJOR}.{MetasploitDataModels::Version::MINOR}.{MetasploitDataModels::Version::PATCH}'
+    #   on master. '{MetasploitDataModels::Version::MAJOR}.{MetasploitDataModels::Version::MINOR}.{MetasploitDataModels::Version::PATCH}-PRERELEASE'
+    #   on any branch other than master.
     def self.full
       version = "#{MAJOR}.#{MINOR}.#{PATCH}"
 
@@ -25,8 +34,22 @@ module MetasploitDataModels
       version
     end
 
+    # The full gem version string, including the {MetasploitDataModels::Version::MAJOR},
+    # {MetasploitDataModels::Version::MINOR}, {MetasploitDataModels::Version::PATCH}, and optionally, the
+    # `MetasploitDataModels::Version::PRERELEASE` in the
+    # {http://guides.rubygems.org/specification-reference/#version RubyGems versioning} format.
+    #
+    # @return [String] '{MetasploitDataModels::Version::MAJOR}.{MetasploitDataModels::Version::MINOR}.{MetasploitDataModels::Version::PATCH}'
+    #   on master.  '{MetasploitDataModels::Version::MAJOR}.{MetasploitDataModels::Version::MINOR}.{MetasploitDataModels::Version::PATCH}.PRERELEASE'
+    #   on any branch other than master.
+    def self.gem
+      full.gsub('-', '.pre.')
+    end
   end
 
-  # @see Version.full
+  # (see Version.gem)
+  GEM_VERSION = Version.gem
+
+  # (see Version.full)
   VERSION = Version.full
 end

data/metasploit_data_models.gemspec

@@ -29,6 +29,13 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 2.1'
 
   # ---- Dependencies ----
+  s.add_development_dependency 'metasploit-version', '~> 0.1.3'
+  # documentation
+  s.add_development_dependency 'metasploit-yard', '~> 1.0'
+  s.add_development_dependency 'yard-activerecord', '~> 0.0.14'
+  # embed ERDs on index, namespace Module and Class<ActiveRecord::Base> pages
+  s.add_development_dependency 'yard-metasploit-erd', '~> 0.1.0'
+
   s.add_development_dependency 'rake'
 
   # documentation
@@ -41,8 +48,8 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency 'activerecord', *rails_version_constraints
   s.add_runtime_dependency 'activesupport', *rails_version_constraints
-  s.add_runtime_dependency 'metasploit-concern', '1.0.0.pre.rails.pre.4.0'
-  s.add_runtime_dependency 'metasploit-model', '1.0.0.pre.rails.pre.4.0'
+  s.add_runtime_dependency 'metasploit-concern', '~> 1.0'
+  s.add_runtime_dependency 'metasploit-model', '~> 1.0'
   s.add_runtime_dependency 'railties', *rails_version_constraints
 
   # os fingerprinting

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

@@ -1,5 +1,3 @@
-require 'spec_helper'
-
-describe Mdm::ApiKey do
+RSpec.describe Mdm::ApiKey, type: :model do
   it_should_behave_like 'Metasploit::Concern.run'
 end

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

@@ -1,11 +1,9 @@
-require 'spec_helper'
-
-describe Mdm::Client do
+RSpec.describe Mdm::Client, type: :model do
 
   it_should_behave_like 'Metasploit::Concern.run'
 
   context 'associations' do
-    it { should belong_to(:host).class_name('Mdm::Host') }
+    it { is_expected.to belong_to(:host).class_name('Mdm::Host') }
   end
 
   context '#destroy' do
@@ -23,21 +21,21 @@ describe Mdm::Client do
   context 'factory' do
     it 'should be valid' do
       client = FactoryGirl.build(:mdm_client)
-      client.should be_valid
+      expect(client).to be_valid
     end
   end
 
   context 'database' do
     context 'columns' do
-      it { should have_db_column(:host_id).of_type(:integer)}
-      it { should have_db_column(:ua_string).of_type(:string).with_options(:null => false) }
-      it { should have_db_column(:ua_name).of_type(:string) }
-      it { should have_db_column(:ua_ver).of_type(:string) }
+      it { is_expected.to have_db_column(:host_id).of_type(:integer)}
+      it { is_expected.to have_db_column(:ua_string).of_type(:string).with_options(:null => false) }
+      it { is_expected.to have_db_column(:ua_name).of_type(:string) }
+      it { is_expected.to have_db_column(:ua_ver).of_type(:string) }
     end
 
     context 'timestamps' do
-      it { should have_db_column(:created_at).of_type(:datetime) }
-      it { should have_db_column(:updated_at).of_type(:datetime) }
+      it { is_expected.to have_db_column(:created_at).of_type(:datetime) }
+      it { is_expected.to have_db_column(:updated_at).of_type(:datetime) }
     end
 
   end