metasploit_data_models 0.7.0 → 0.11.2

data/app/models/mdm/{module_mixin.rb → module/mixin.rb}

@@ -1,11 +1,11 @@
-class Mdm::ModuleMixin < ActiveRecord::Base
+class Mdm::Module::Mixin < ActiveRecord::Base
   self.table_name = 'module_mixins'
 
   #
   # Associations
   #
 
-  belongs_to :module_detail, :class_name => 'Mdm::ModuleDetail'
+  belongs_to :detail, :class_name => 'Mdm::Module::Detail'
 
   #
   # Mass Assignment Security
@@ -17,7 +17,7 @@ class Mdm::ModuleMixin < ActiveRecord::Base
   # Validation
   #
 
-  validates :module_detail, :presence => true
+  validates :detail, :presence => true
   validates :name, :presence => true
 
   ActiveSupport.run_load_hooks(:mdm_module_mixin, self)

data/app/models/mdm/{module_platform.rb → module/platform.rb}

@@ -1,11 +1,11 @@
-class Mdm::ModulePlatform < ActiveRecord::Base
+class Mdm::Module::Platform < ActiveRecord::Base
   self.table_name = 'module_platforms'
 
   #
   # Associations
   #
 
-  belongs_to :module_detail, :class_name => 'Mdm::ModuleDetail'
+  belongs_to :detail, :class_name => 'Mdm::Module::Detail'
 
   #
   # Mass Assignment Security
@@ -17,7 +17,7 @@ class Mdm::ModulePlatform < ActiveRecord::Base
   # Validations
   #
 
-  validates :module_detail, :presence => true
+  validates :detail, :presence => true
   validates :name, :presence => true
 
   ActiveSupport.run_load_hooks(:mdm_module_platform, self)

data/app/models/mdm/module/ref.rb

@@ -0,0 +1,48 @@
+# External references to the vulnerability exploited by this module.
+class Mdm::Module::Ref < ActiveRecord::Base
+  self.table_name = 'module_refs'
+
+  #
+  # Associations
+  #
+
+  # @!attribute [rw] detail
+  #   The root of the module metadata tree.
+  #
+  #   @return [Mdm::Module::Detail]
+  belongs_to :detail, :class_name => 'Mdm::Module::Detail'
+
+  # @!attribute [r] refs
+  #   References with the same name attached to {Mdm::Vuln Mdm::Vulns}.
+  #
+  #   @return [Array<Mdm::Ref>]
+	has_many :refs,
+					 :class_name => 'Mdm::Ref',
+					 :foreign_key => :name,
+					 :primary_key => :name
+
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] name
+  #   Designation for external reference.  May include a prefix for the authority, such as 'CVE-', in which case the
+  #   rest of the name is the designation assigned by that authority.
+  #
+  #   @return [String]
+
+  #
+  # Mass Assignment Security
+  #
+
+  attr_accessible :name
+
+  #
+  # Validations
+  #
+
+  validates :detail, :presence => true
+  validates :name, :presence => true
+
+  ActiveSupport.run_load_hooks(:mdm_module_ref, self)
+end

data/app/models/mdm/{module_target.rb → module/target.rb}

@@ -1,11 +1,11 @@
-class Mdm::ModuleTarget < ActiveRecord::Base
+class Mdm::Module::Target < ActiveRecord::Base
   self.table_name = 'module_targets'
 
   #
   # Associations
   #
 
-  belongs_to :module_detail, :class_name => 'Mdm::ModuleDetail'
+  belongs_to :detail, :class_name => 'Mdm::Module::Detail'
 
   #
   # Mass Assignment Security
@@ -18,8 +18,8 @@ class Mdm::ModuleTarget < ActiveRecord::Base
   # Validators
   #
 
+  validates :detail, :presence => true
   validates :index, :presence => true
-  validates :module_detail, :presence => true
   validates :name, :presence => true
 
   ActiveSupport.run_load_hooks(:mdm_module_target, self)

data/app/models/mdm/note.rb

@@ -1,17 +1,68 @@
+# Data gathered or derived from the {#host} or {#service} such as its {#ntype fingerprint}.
 class Mdm::Note < ActiveRecord::Base
   #
-  # Callbacks
+  # Associations
   #
 
-  after_save :normalize
+  # @!attribute [rw] host
+  #   The host to which this note is attached.
+  #
+  #   @return [Mdm::Host] if note is attached to an {Mdm::Host}.
+  #   @return [nil] if note is attached to an {Mdm::Service}.
+  belongs_to :host, :class_name => 'Mdm::Host', :counter_cache => :note_count
 
+  # @!attribute [rw] service
+  #   The service to which this note is attached.
   #
-  # Relations
+  #   @return [Mdm::Service] if note is attached to an {Mdm::Service}.
+  #   @return [nil] if not is attached to an {Mdm::Host}.
+  belongs_to :service, :class_name => 'Mdm::Service'
+
+  # @!attribute [rw] workspace
+  #   The workspace in which the {#host} or {#service} exists.
   #
+  #   @return [Mdm::Workspace]
+  belongs_to :workspace, :class_name => 'Mdm::Workspace'
 
-  belongs_to :workspace, :class_name => "Mdm::Workspace"
-  belongs_to :host, :class_name => "Mdm::Host", :counter_cache => :note_count
-  belongs_to :service, :class_name => "Mdm::Service"
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] created_at
+  #   When the note was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute [rw] critical
+  #   Whether this note is critical or not.
+  #
+  #   @return [Boolean]
+
+  # @!attribute [rw] data
+  #   A Hash of data about the {#host} or {#service}.
+  #
+  #   @return [Hash]
+
+  # @!attribute [rw] ntype
+  #   The type of note.  Usually a dot-separateed name like 'host.updated.<foo>'.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] seen
+  #   Whether any user has seen this note.
+  #
+  #   @return [Boolean]
+
+  # @!attribute [rw] updated_at
+  #   The last time the note was updated.
+  #
+  #   @return [DateTime]
+
+  #
+  # Callbacks
+  #
+
+  after_save :normalize
 
   #
   # Scopes
@@ -38,6 +89,10 @@ class Mdm::Note < ActiveRecord::Base
 
   private
 
+  # {Mdm::Host::OperatingSystemNormalization#normalize_os Normalizes the host operating system} if the note is a
+  # {#ntype fingerprint}.
+  #
+  # @return [void]
   def normalize
     if data_changed? and ntype =~ /fingerprint/
       host.normalize_os

data/app/models/mdm/ref.rb

@@ -1,14 +1,52 @@
+# An external vulnerability reference for vulnerabilities that aren't part of a module.  {Mdm::Module::Ref} should be
+# used whenever possible and Mdm::Ref should only be used when the vulnerability is from an import and can't be
+# correlated to a module and its {Mdm::Module::Detail}.
 class Mdm::Ref < ActiveRecord::Base
   #
-  # Relations
+  # Associations
   #
 
+  # @!attribute [r] module_refs
+  #   {Mdm::Module::Ref Mdm::Module::Refs} with the same name as this ref.
+  #
+  #   @return [Array<Mdm::Module::Ref>]
+	has_many :module_refs,
+					 :class_name => 'Mdm::Module::Ref',
+					 :foreign_key => :name,
+					 :primary_key => :name
+
+  # @!attribute [rw] vulns_refs
+  #   Join model to {Mdm::Vuln Mdm::Vulns}.  Use {#vulns} to get the actual {Mdm::Vuln Mdm::Vulns}.
+  #
+	#   @todo https://www.pivotaltracker.com/story/show/48915453
+  #   @return [Array<Mdm::VulnRef>]
   has_many :vulns_refs, :class_name => 'Mdm::VulnRef'
 
   #
   # Through :vuln_refs
   #
+
+  # @!attribute [rw] vulns
+  #   Vulnerabilities referenced by this reference.
+  #
+  #   @return [Array<Mdm::Vuln>]
   has_many :vulns, :class_name => 'Mdm::Vuln', :through => :vulns_refs
 
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] name
+  #   Designation for external reference.  May include a prefix for the authority, such as 'CVE-', in which case the
+  #   rest of the name is the designation assigned by that authority.
+  #
+  #   @return [String]
+
+  #
+  # Mass Assignment Security
+  #
+
+  attr_accessible :name
+
   ActiveSupport.run_load_hooks(:mdm_ref, self)
 end

data/app/models/mdm/service.rb

@@ -1,34 +1,108 @@
+# A service, such as an ssh server or web server, running on a {#host}.
 class Mdm::Service < ActiveRecord::Base
-  #
-  # Callbacks
-  #
-
-  after_save :normalize_host_os
-
   #
   # CONSTANTS
   #
 
+  # Valid values for {#state}.
   STATES = ['open', 'closed', 'filtered', 'unknown']
 
   #
-  # Relations
+  # Associations
   #
 
+  # @!attribute [rw] creds
+  #   Credentials gathered from this service.
+  #
+  #   @return [Array<Mdm::Cred>]
   has_many :creds, :dependent => :destroy, :class_name => 'Mdm::Cred'
+
+  # @!attribute [rw] exploited_hosts
+  #   @todo https://www.pivotaltracker.com/story/show/48993731
+  #   @return [Array<Mdm::ExploitHost>]
   has_many :exploited_hosts, :dependent => :destroy, :class_name => 'Mdm::ExploitedHost'
+
+  # @!attribute [rw] host
+  #   The host on which this service runs.
+  #
+  #   @return [Mdm::Host]
   belongs_to :host, :class_name => 'Mdm::Host', :counter_cache => :service_count
+
+  # @!attribute [rw] notes
+  #   Notes about this service.
+  #
+  #   @return [Array<Mdm::Note>]
   has_many :notes, :dependent => :destroy, :class_name => 'Mdm::Note'
+
+  # @!attribute [rw] vulns
+  #   Vulnerabilities found in this service.
+  #
+  #   @return [Array<Mdm::Vuln>]
   has_many :vulns, :dependent => :destroy, :class_name => 'Mdm::Vuln'
+
+  # @!attribute [rw] web_sites
+  #   Web sites running on top of this service.
+  #
+  #   @return [Array<Mdm::WebSite>]
   has_many :web_sites, :dependent => :destroy, :class_name => 'Mdm::WebSite'
 
   #
   # Through :web_sites
   #
+
+  # @!attribute [r] web_pages
+  #   Web pages in the {#web_sites} on top of this service.
+  #
+  #   @return [Array<Mdm::WebPages>]
   has_many :web_pages, :through => :web_sites, :class_name => 'Mdm::WebPage'
+
+  # @!attribute [r] web_forms
+  #   Form in the {#web_sites} on top of this service.
+  #
+  #   @return [Array<Mdm::WebForm>]
   has_many :web_forms, :through => :web_sites, :class_name => 'Mdm::WebForm'
+
+  # @!attribute [r] web_vulns
+  #   Vulnerabilities found in the {#web_sites} on top of this service.
+  #
+  #   @return [Array<Mdm::WebVuln>]
   has_many :web_vulns, :through => :web_sites, :class_name => 'Mdm::WebVuln'
 
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] info
+  #   Additional information about the service that does not fit in the {#name} or {#proto}.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] port
+  #   The port on which this service runs on the {#host}.
+  #
+  #   @return [Integer]
+
+  # @!attribute [rw] name
+  #    The name of the service.
+  #
+  #    @return [String]
+
+  # @!attribute [rw] proto
+  #   The protocol used by this service
+  #
+  #   @return [String]
+
+  # @!attribute [rw] state
+  #   Whether this service is opened, closed, filtered, or in an unknown state.
+  #
+  #   @return [String] element of {STATES}.
+
+  #
+  # Callbacks
+  #
+
+  after_save :normalize_host_os
+
   #
   # Scopes
   #
@@ -45,6 +119,10 @@ class Mdm::Service < ActiveRecord::Base
           ])
   }
 
+  # {Mdm::Host::OperatingSystemNormalization#normalize_os Normalizes the host operating system} whenever {#info} has
+  # changed.
+  #
+  # @return [void]
   def normalize_host_os
     if info_changed?
       host.normalize_os

data/app/models/mdm/session.rb

@@ -1,23 +1,109 @@
+# A session opened on a {#host} using an {#via_exploit exploit} and controlled through a {#via_payload payload} to
+# connect back to the local host using meterpreter or a cmd shell.
 class Mdm::Session < ActiveRecord::Base
   #
-  # Callbacks
+  # Associations
   #
 
-  before_destroy :stop
-
+  # @!attribute [rw] events
+  #   Events that occurred when this session was open.
   #
-  # Relations
-  #
-
+  #   @return [Array<Mdm::Event>]
   has_many :events, :class_name => 'Mdm::SessionEvent', :order => 'created_at', :dependent => :delete_all
+
+  # @!attribute [rw] host
+  #   {Mdm::Host Host} on which this session was opened.
+  #
+  #   @return [Mdm::Host]
   belongs_to :host, :class_name => 'Mdm::Host'
+
+  # @!attribute [rw] routes
+  #   Routes tunneled throug this session.
+  #
+  #   @return [Array<Mdm::Route>]
   has_many :routes, :class_name => 'Mdm::Route', :dependent => :delete_all
 
   #
   # Through :host
   #
+
+  # @!attribute [r] workspace
+  #   The workspace in which this session exists.
+  #
+  #   @return [Mdm::Workspace]
   has_one :workspace, :through => :host, :class_name => 'Mdm::Workspace'
 
+  #
+  # Attributes
+  #
+
+  # @!attribute [rw] closed_at
+  #   When the session was closed on {#host}.
+  #
+  #   @return [DateTime]
+
+  # @!attribute [rw] close_reason
+  #   Why the session was closed.  Used to differentiate between user killing it local and the session being killed on
+  #   the remote end.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] datastore
+  #   Options for {#via_exploit exploit} and {#via_payload} modules.
+  #
+  #   @return [Hash]
+
+  # @!attribute [rw] desc
+  #   Description of session.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] last_seen
+  #   The last time the session was checked to see that it was still open.
+  #
+  #   @return [DateTime]
+
+  # @!attribute [rw] local_id
+  #   The ID number of the in-memory session.
+  #
+  #   @return [Integer]
+
+  # @!attribute [rw] opened_at
+  #   When the session was opened on {#host}.
+  #
+  #   @return [DateTime]
+
+  # @!attribute [rw] platform
+  #   The {#host} platform.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] port
+  #   The remote port on which this session is running on {#host}.
+  #
+  #   @return [Integer]
+
+  # @!attribute [rw] stype
+  #   The type of the session.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] via_exploit
+  #   The {Mdm::Module::Detail#fullname full name} of the exploit module that opened this session.
+  #
+  #   @return [String]
+
+  # @!attribute [rw] via_payload
+  #   The {Mdm::Module::Detail#fullname full name} if the payload module that's running this session.
+  #
+  #   @return [String]
+
+  #
+  # Callbacks
+  #
+
+  before_destroy :stop
+
   #
   # Scopes
   #
@@ -32,12 +118,20 @@ class Mdm::Session < ActiveRecord::Base
 
   serialize :datastore, ::MetasploitDataModels::Base64Serializer.new
 
+  # Returns whether the session can be upgraded to a meterpreter session from a shell session on Windows.
+  #
+  # @return [true] if {#platform} is some version of Windows and {#stype} is `'shell'`.
+  # @return [false] otherwise.
   def upgradeable?
     (self.platform =~ /win/ and self.stype == 'shell')
   end
 
   private
 
+  # Stops and closes the session.
+  #
+  # @todo https://www.pivotaltracker.com/story/show/49026497
+  # @return [void]
   def stop
     c = Pro::Client.get rescue nil
     # ignore exceptions (XXX - ideally, stopped an already-stopped session wouldn't throw XMLRPCException)