metasploit_data_models 0.24.1 → 0.24.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1ac9c58f2799f6dcb7e997a8a328d585daf4c3e4
-  data.tar.gz: 13c3f4938ac23baf1c6d15a89f32f6b1f78d01e2
+  metadata.gz: 69de2fe8a5805a58e1cdea1f81a91fec6f1e6c07
+  data.tar.gz: 72b931c04092bd416f05f315ef0195284f853e3f
 SHA512:
-  metadata.gz: 20bcf96f7f4ce0794ec99f0408432d3768a966ca982f5d85c5a107806ca50c5cbad2217be893aeeb41941db21abdcd73a439335331d67625a99360c1cd1e37a2
-  data.tar.gz: eedd216995f5ed8e7dab6453a6372f0dac7419ef54be71edb3bca75993da99e5f836ca71190b963bb2afb66d6a9afebbcaf97d535665206f8c45c74ab0f9273b
+  metadata.gz: 91aeed44b44b4bfddb5afa95e8f2aef188f2c32de6a37961804e6f4c15298de3aa24e3f9c9aff36f6f2a11a3cb7e60ef13889c86d3a676a8652016374c64cbcd
+  data.tar.gz: 81f0ee91a1eba059de5f20bd2105b35e8323999a6e0b7b8337d12c8d58546474c9387052e66649706c889e10958f22cef559ff63c88b1c2528c6b7e5280971ee

data/.rspec

@@ -1,3 +1,3 @@
---format nested
---colour
---drb
+--color
+--format documentation
+--require spec_helper

data/.travis.yml

@@ -1,3 +1,8 @@
+addons:
+  postgresql: '9.3'
+before_install:
+  # graphviz for yard-metasploit-erd
+  - sudo apt-get install graphviz
 before_script:
   - cp spec/dummy/config/database.yml.travis spec/dummy/config/database.yml
   - bundle exec rake db:setup
@@ -5,6 +10,4 @@ cache: bundler
 language: ruby
 rvm:
   - 2.1
-sudo: false
-addons:
-  postgresql: '9.3'
+script: bundle exec rake spec yard

data/Gemfile

@@ -3,11 +3,6 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in metasploit_data_models.gemspec
 gemspec
 
-group :development do
-  # embed ERDs on index, namespace Module and Class<ActiveRecord::Base> pages
-  gem 'yard-metasploit-erd', '~> 0.0.2'
-end
-
 # used by dummy application
 group :development, :test do
   # Upload coverage reports to coveralls.io
@@ -32,11 +27,9 @@ group :test do
   gem 'shoulda-matchers'
   # code coverage of tests
   gem 'simplecov', :require => false
-  # @todo Update specs for rspec 3.0.0 compatibility and remove this gem in favor of just rspec-rails
-  gem 'rspec-core', '< 3.0.0'
   # need rspec-rails >= 2.12.0 as 2.12.0 adds support for redefining named subject in nested context that uses the
   # named subject from the outer context without causing a stack overflow.
-  gem 'rspec-rails', '>= 2.12.0'
+  gem 'rspec-rails', '~> 3.2'
   # used for building markup for webpage factories
   gem 'builder'
 end

data/Rakefile

@@ -42,6 +42,29 @@ else
   task :default => :spec
 end
 
+# Use find_all_by_name instead of find_by_name as find_all_by_name will return pre-release versions
+gem_specification = Gem::Specification.find_all_by_name('metasploit-yard').first
+
+if gem_specification
+  Dir[File.join(gem_specification.gem_dir, 'lib', 'tasks', '**', '*.rake')].each do |rake|
+    load rake
+  end
+
+  #
+  # Eager load before yard docs so that ActiveRecord::Base subclasses are loaded for yard-metasploit-erd
+  #
+
+  task 'yard:doc' => :eager_load
+
+  task eager_load: :environment do
+    Rails.application.eager_load!
+  end
+else
+  puts "metasploit-yard not in bundle, so can't setup yard tasks. " \
+       "To run yard ensure to install the development group."
+  print_without = true
+end
+
 if print_without
   puts "Bundle currently installed '--without #{Bundler.settings.without.join(' ')}'."
   puts "To clear the without option do `bundle install --without ''` (the --without flag with an empty string) or " \

data/app/models/mdm/api_key.rb

@@ -1,13 +1,53 @@
+# API key to access the RPC.
 class Mdm::ApiKey < ActiveRecord::Base
   #
-  # Validators
+  # Attributes
+  #
+
+  # @!attribute [rw] created_at
+  #   When this API Key was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute [rw] token
+  #   The API Key to authenicate to the RPC.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] updated_at
+  #   The last time this API Key was updated.
+  #
+  #   @return [DateTime]
+
+  #
+  #
+  # Validations
+  #
+  #
+
+  #
+  # Method Validations
   #
 
   validate :supports_api
+
+  #
+  # Attribute Validations
+  #
+
   validates :token, :presence => true, :length => { :minimum => 8 }
 
+  #
+  # Instance Methods
+  #
+
   protected
 
+
+  # Validates whether License supports API.
+  #
+  # @return [void]
+  # @todo MSP-2724
   def supports_api
     license = License.get
 

data/app/models/mdm/client.rb

@@ -1,10 +1,50 @@
+# Client used for `report_client` in metasploit-framework Metasploit Modules.
 class Mdm::Client < ActiveRecord::Base
   #
-  # Relations
+  # Associations
   #
+
+  # {Mdm::Host} from which this client connected.
   belongs_to :host,
              class_name: 'Mdm::Host',
              inverse_of: :clients
 
+  #
+  # Attributes
+  #
+
+  # @!attribute created_at
+  #   When this client was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute updated_at
+  #   When this client was last updated.
+  #
+  #   @return [DateTime]
+
+  #
+  # @!group User Agent
+  #
+
+  # @!attribute ua_name
+  #   Parsed name from {#ua_string user agent string}
+  #
+  #   @return [String]
+
+  # @!attribute ua_string
+  #   Raw user agent string from client browser
+  #
+  #   @return [String]
+
+  # @!attribute ua_ver
+  #   Version of user agent.
+  #
+  #   @return [String]
+
+  #
+  # @!endgroup
+  #
+
   Metasploit::Concern.run(self)
 end

data/app/models/mdm/cred.rb

@@ -1,8 +1,15 @@
+# @deprecated Use metasploit-credential's `Metasploit::Credential::Core`.
+#
+# A credential captured from a {#service}.
 class Mdm::Cred < ActiveRecord::Base
   #
   # CONSTANTS
   #
+
+  # Checks if {#proof} is an SSH Key in {#ssh_key_id}.
   KEY_ID_REGEX = /([0-9a-fA-F:]{47})/
+
+  # Maps {#ptype_human} to {#ptype}.
   PTYPES = {
       'read/write password' => 'password_rw',
       'read-only password' => 'password_ro',
@@ -12,35 +19,93 @@ class Mdm::Cred < ActiveRecord::Base
   }
 
   #
-  # Relations
   #
-
-  # @!attribute [rw] servce
-  #   The service this cred is for
+  # Associations
   #
-  #   @return [Mdm::Service]
+  #
+
+  # The {Mdm::Service} this Cred is for.
   belongs_to :service,
              class_name: 'Mdm::Service',
              inverse_of: :creds
 
-  # @!attribute [rw] task_creds
-  #   Details about what Tasks touched this cred
-  #
-  #   @return [Array<Mdm::TaskCred>]
+  # Joins {#tasks} to this Cred.
   has_many :task_creds,
            class_name: 'Mdm::TaskCred',
            dependent: :destroy,
            inverse_of: :cred
 
-  # @!attribute [rw] tasks
-  #   Tasks that touched this service
   #
-  #   @return [Array<Mdm::Task>]
+  # through: :task_creds
+  #
+
+  # Tasks that touched this service
   has_many :tasks, :through => :task_creds
 
+  #
+  # Attributes
+  #
+
+  # @!attribute active
+  #   Whether the credential is active.
+  #
+  #   @return [false] if a captured credential cannot be used to log into {#service}.
+  #   @return [true] otherwise
+
+  # @!attribute created_at
+  #   When this credential was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute pass
+  #   Pass of credential.
+  #
+  #   @return [String, nil]
+
+  # @!attribute proof
+  #   Proof of credential capture.
+  #
+  #   @return [String]
+
+  # @!attribute ptype
+  #   Type of {#pass}.
+  #
+  #   @return [String]
+
+  # @!attribute source_id
+  #   Id of source of this credential.
+  #
+  #   @return [Integer, nil]
+
+  # @!attribute source_type
+  #   Type of source with {#source_id}.
+  #
+  #   @return [String, nil]
+
+  # @!attribute updated_at
+  #   The last time this credential was updated.
+  #
+  #   @return [DateTime]
+
+  # @!attribute user
+  #   User name of credential.
+  #
+  #   @return [String, nil]
+
+  #
+  # Callbacks
+  #
+
   after_create :increment_host_counter_cache
   after_destroy :decrement_host_counter_cache
 
+  #
+  # Instance methods
+  #
+
+  # Humanized {#ptype}.
+  #
+  # @return [String, nil]
   def ptype_human
     humanized = PTYPES.select do |k, v|
       v == ptype
@@ -49,13 +114,24 @@ class Mdm::Cred < ActiveRecord::Base
     humanized ? humanized : ptype
   end
 
-  # Returns its key id. If this is not an ssh-type key, returns nil.
+  # Returns SSH Key ID.
+  #
+  # @return [String] SSH Key Id if ssh-type key and {#proof} matches {KEY_ID_REGEX}.
+  # @return [nil] otherwise
   def ssh_key_id
     return nil unless self.ptype =~ /^ssh_/
     return nil unless self.proof =~ KEY_ID_REGEX
     $1.downcase # Can't run into NilClass problems.
   end
 
+  # Returns whether `other`'s SSH private key or public key matches.
+  #
+  # @return [false] if `other` is not same class as `self`.
+  # @return [false] if {#ptype} does not match.
+  # @return [false] if {#ptype} is neither `"ssh_key"` nor `"ssh_pubkey"`.
+  # @return [false] if {#ssh_key_id} is `nil`.
+  # @return [false] if {#ssh_key_id} does not match.
+  # @return [true] if {#ssh_key_id} matches.
   def ssh_key_matches?(other_cred)
     return false unless other_cred.kind_of? self.class
     return false unless self.ptype == other_cred.ptype
@@ -70,14 +146,16 @@ class Mdm::Cred < ActiveRecord::Base
     matches.include?(self) and matches.include?(other_cred)
   end
 
-  # Returns all keys with matching key ids, including itself
-  # If this is not an ssh-type key, always returns an empty array.
+  # Returns all keys with matching key ids, including itself.
+  #
+  # @return [ActiveRecord::Relation<Mdm::Cred>] ssh_key and ssh_pubkey creds with matching {#ssh_key_id}.
   def ssh_keys
     (self.ssh_private_keys | self.ssh_public_keys)
   end
 
-  # Returns all private keys with matching key ids, including itself
-  # If this is not an ssh-type key, always returns an empty array.
+  # Returns all private keys with matching {#ssh_key_id}, including itself.
+  #
+  # @return [ActiveRecord::Relation<Mdm::Cred>] ssh_key creds with matching {#ssh_key_id}.
   def ssh_private_keys
     return [] unless self.ssh_key_id
     matches = self.class.all(
@@ -86,8 +164,9 @@ class Mdm::Cred < ActiveRecord::Base
     matches.select {|c| c.workspace == self.workspace}
   end
 
-  # Returns all public keys with matching key ids, including itself
-  # If this is not an ssh-type key, always returns an empty array.
+  # Returns all public keys with matching {#ssh_key_id}, including itself.
+  #
+  # @return [ActiveRecord::Relation<Mdm::Cred>] ssh_pubkey creds with matching {#ssh_key_id}.
   def ssh_public_keys
     return [] unless self.ssh_key_id
     matches = self.class.all(
@@ -97,20 +176,29 @@ class Mdm::Cred < ActiveRecord::Base
   end
 
   # Returns its workspace
+  #
+  # @return [Mdm::Workspace]
   def workspace
     self.service.host.workspace
   end
 
   private
 
+  # Decrements {Mdm::Host#cred_count}.
+  #
+  # @return [void]
   def decrement_host_counter_cache
     Mdm::Host.decrement_counter("cred_count", self.service.host_id)
   end
 
+  # Increments {Mdm::Host#cred_count}.
+  #
+  # @return [void]
   def increment_host_counter_cache
     Mdm::Host.increment_counter("cred_count", self.service.host_id)
   end
 
+  # Switch back to public for load hooks.
   public
 
   Metasploit::Concern.run(self)

data/app/models/mdm/event.rb

@@ -1,16 +1,60 @@
+# Records framework events to the database.
 class Mdm::Event < ActiveRecord::Base
   #
-  # Relations
+  # Associations
   #
 
+  # Host on which this event occurred.
+  #
+  # @return [Mdm::Host]
+  # @return [nil] if event did not occur on a host.
   belongs_to :host,
              class_name: 'Mdm::Host',
              inverse_of: :events
 
+  # {Mdm::Workspace} in which this event occured.  If {#host} is present, then this will match
+  # {Mdm::Host#workspace `host.workspace`}.
   belongs_to :workspace,
              class_name: 'Mdm::Workspace',
              inverse_of: :events
 
+  #
+  # Attributes
+  #
+
+  # @!attribute created_at
+  #   When this event was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute critical
+  #   Indicates if the event is critical.
+  #
+  #   @return [false] event is not critical.
+  #   @return [true] event is critical.
+
+  # @!attribute  name
+  #   Name of the event, such as 'module_run'.
+  #
+  #   @return [String]
+
+  # @!attribute seen
+  #   Whether a user has seen these events.
+  #
+  #   @return [false] if the event has not been seen.
+  #   @return [true] if any user has seen the event.
+
+  # @!attribute  updated_at
+  #   The last time this event was updated.
+  #
+  #   @return [DateTime]
+
+  # @!attribute username
+  #   Name of user that triggered the event.  Not necessarily a {Mdm::User#username}, as {#username} may be set to
+  #   the username of the user inferred from `ENV` when using metasploit-framework.
+  #
+  #   @return [String]
+
   #
   # Scopes
   #
@@ -22,6 +66,9 @@ class Mdm::Event < ActiveRecord::Base
   # Serializations
   #
 
+  # {#name}-specific information about this event.
+  #
+  # @return [Hash]
   serialize :info, MetasploitDataModels::Base64Serializer.new
 
   #