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

data/app/models/mdm/wmap_request.rb

@@ -1,4 +1,89 @@
+# Request sent to a {Mdm::WmapTarget}.  WMAP is a plugin to metasploit-framework.
 class Mdm::WmapRequest < ActiveRecord::Base
+  #
+  #
+  # Attributes
+  #
+  #
+
+  # @!attribute address
+  #   IP address of {#host} to which this request was sent.
+  #
+  #   @return [String]
+
+  # @!attribute body
+  #   Body of this request.
+  #
+  #   @return [String]
+
+  # @!attribute created_at
+  #   When this request was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute headers
+  #   Headers sent as part of this request.
+  #
+  #   @return [String]
+
+  # @!attribute host
+  #   Name of host to which this request was sent.
+  #
+  #   @return [String]
+
+  # @!attribute meth
+  #   HTTP Method (or VERB) used for request.
+  #
+  #   @return [String]
+
+  # @!attribute path
+  #   Path portion of URL for this request.
+  #
+  #   @return [String]
+
+  # @!attribute port
+  #   Port at {#address} to which this request was sent.
+  #
+  #   @return [Integer]
+
+  # @!attribute query
+  #   Query portion of URL for this request.
+  #
+  #   @return [String]
+
+  # @!attribute ssl
+  #   Version of SSL to use.
+  #
+  #   @return [Integer]
+
+  # @!attribute updated_at
+  #   The last time this request was updated.
+  #
+  #   @return [DateTime]
+
+  #
+  # @!group Response
+  #
+
+  # @!attribute respcode
+  #   HTTP status code sent in response to this request from server.
+  #
+  #   @return [String]
+
+  # @!attribute resphead
+  #   Headers sent in response from server.
+  #
+  #   @return [String]
+
+  # @!attribute response
+  #   Response sent from server.
+  #
+  #   @return [String]
+
+  #
+  # @!endgroup
+  #
+
   Metasploit::Concern.run(self)
 
   #

data/app/models/mdm/wmap_target.rb

@@ -1,4 +1,44 @@
+# WMAP target. WMAP is a plugin to metasploit-framework.
 class Mdm::WmapTarget < ActiveRecord::Base
+  #
+  # Attributes
+  #
+
+  # @!attribute address
+  #   IP address of {#host}.
+  #
+  #   @return [String]
+
+  # @!attribute created_at
+  #   When this target was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute host
+  #   Name of this target.
+  #
+  #   @return [String]
+
+  # @!attribute port
+  #   Port on this target to send {Mdm::WmapRequest requests}.
+  #
+  #   @return [Integer]
+
+  # @!attribute selected
+  #   Whether this target should be sent requests.
+  #
+  #   @return [Integer]
+
+  # @!attribute ssl
+  #   Version of SSL to use when sending requests to this target.
+  #
+  #   @return [Integer]
+
+  # @!attribute updated_at
+  #   The last time this target was updated.
+  #
+  #   @return [DateTime]
+
   Metasploit::Concern.run(self)
 
   #

data/app/models/mdm/workspace.rb

@@ -1,11 +1,6 @@
+# Workspace to separate different collections of {#hosts}.  Can be used to separate pentests against different networks
+# or different clients as reports are normally generated against all records in a workspace.
 class Mdm::Workspace < ActiveRecord::Base
-  
-  #
-  # Callbacks
-  #
-
-  before_save :normalize
-
   #
   # CONSTANTS
   #
@@ -13,36 +8,121 @@ class Mdm::Workspace < ActiveRecord::Base
   DEFAULT = 'default'
 
   #
-  # Relations
+  # Associations
   #
 
+  # Automatic exploitation runs against this workspace.
   has_many :automatic_exploitation_runs,
            class_name: 'MetasploitDataModels::AutomaticExploitation::Run',
            inverse_of: :workspace
 
+  # Automatic exploitation match sets generated against {#hosts} and {#services} in this workspace.
   has_many :automatic_exploitation_match_sets,
            class_name: 'MetasploitDataModels::AutomaticExploitation:MatchSet',
            inverse_of: :workspace
 
+  # @deprecated Use `Mdm::Workspace#core_credentials` defined by `Metasploit::Credential::Engine` to get
+  #   `Metasploit::Credential::Core`s gathered from this workspace's {#hosts} and {#services}.
+  #
+  # Creds gathered from this workspace's {#hosts} and {#services}.
   has_many :creds, :through => :services, :class_name => 'Mdm::Cred'
+
+  # Events that occurred in this workspace.
   has_many :events, :class_name => 'Mdm::Event'
+
+  # Hosts in this workspace.
   has_many :hosts, :dependent => :destroy, :class_name => 'Mdm::Host'
+
+  # Listeners running for this workspace.
   has_many :listeners, :dependent => :destroy, :class_name => 'Mdm::Listener'
+
+  # Notes about this workspace.
   has_many :notes, :class_name => 'Mdm::Note'
+
+  # User that owns this workspace and has full permissions within this workspace even if they are not an
+  # {Mdm::User#admin administrator}.
   belongs_to :owner, :class_name => 'Mdm::User', :foreign_key => 'owner_id'
-  has_many :tasks, -> { order('created_at DESC') }, :dependent => :destroy, :class_name => 'Mdm::Task'
-  has_and_belongs_to_many :users, -> { uniq }, :join_table => 'workspace_members', :class_name => 'Mdm::User'
+
+  # Tasks run inside this workspace.
+  has_many :tasks,
+           -> { order('created_at DESC') },
+           class_name: 'Mdm::Task',
+           dependent: :destroy
+
+  # Users that are allowed to use this workspace.  Does not necessarily include all users, as an {Mdm::User#admin
+  # administrator} can access any workspace, even ones where they are not a member.
+  has_and_belongs_to_many :users,
+                          -> { uniq },
+                          class_name: 'Mdm::User',
+                          join_table: 'workspace_members'
 
   #
-  # Through :hosts
+  # through: :hosts
   #
+
+  # Social engineering campaign or browser autopwn clients from {#hosts} in this workspace.
   has_many :clients, :through => :hosts, :class_name => 'Mdm::Client'
+
+  # Hosts exploited in this workspace.
   has_many :exploited_hosts, :through => :hosts, :class_name => 'Mdm::ExploitedHost'
+
+  # Loot gathered from {#hosts} in this workspace.
   has_many :loots, :through => :hosts, :class_name => 'Mdm::Loot'
+
+  # Services running on {#hosts} in this workspace.
+  has_many :services,
+           class_name: 'Mdm::Service',
+           foreign_key: :service_id,
+           through: :hosts
+
+  # Vulnerabilities found on {#hosts} in this workspace.
   has_many :vulns, :through => :hosts, :class_name => 'Mdm::Vuln'
-  has_many :services, :through => :hosts, :class_name => 'Mdm::Service', :foreign_key => 'service_id'
+
+  # Sessions opened on {#hosts} in this workspace.
   has_many :sessions, :through => :hosts, :class_name => 'Mdm::Session'
 
+  #
+  # Attributes
+  #
+
+  # @!attribute boundary
+  #   Comma separated list of IP ranges (in various formats) and IP addresses that users of this workspace are allowed
+  #   to interact with if {#limit_to_network} is `true`.
+  #
+  #   @return [String]
+
+  # @!attribute description
+  #   Long description (beyond {#name}) that explains the purpose of this workspace.
+  #
+  #   @return [String]
+
+  # @!attribute limit_to_network
+  #   Whether {#boundary} is respected.
+  #
+  #   @return [false] do not limit interactions to {#boundary}.
+  #   @return [true] limit interactions to {#boundary}.
+
+  # @!attribute name
+  #   Name of this workspace.
+  #
+  #   @return [String]
+
+  # @!attribute created_at
+  #   When this workspace was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute updated_at
+  #   The last time this workspace was updated.
+  #
+  #   @return [DateTime]
+
+  #
+  # Callbacks
+  #
+
+  before_save :normalize
+
   #
   # Validations
   #
@@ -52,10 +132,15 @@ class Mdm::Workspace < ActiveRecord::Base
   validate :boundary_must_be_ip_range
 
   #
-  # If limit_to_network is disabled, this will always return true.
-  # Otherwise, return true only if all of the given IPs are within the project
-  # boundaries.
+  # Instance Methods
   #
+
+  # If {#limit_to_network} is disabled, this will always return `true`. Otherwise, return `true` only if all of the
+  # given IPs are within the project {#boundary boundaries}.
+  #
+  # @param ips [String] IP range(s)
+  # @return [true] if actions on ips are allowed.
+  # @return [false] if actions are not allowed on ips.
   def allow_actions_on?(ips)
     return true unless limit_to_network
     return true unless boundary
@@ -72,10 +157,18 @@ class Mdm::Workspace < ActiveRecord::Base
     return allowed
   end
 
+  # Validates that {#boundary} is {#valid_ip_or_range? a valid IP address or IP address range}.
+  #
+  # @return [void]
   def boundary_must_be_ip_range
     errors.add(:boundary, "must be a valid IP range") unless valid_ip_or_range?(boundary)
   end
 
+  # @deprecated Use `Mdm::Workspace#credential_cores` when `Metasploit::Credential::Engine` is installed to get
+  #    `Metasploit::Credential::Core`s.  Use `Mdm::Service#logins` when `Metasploit::Credential::Engine` is installed to
+  #    get `Metasploit::Credential::Login`s.
+  #
+  # @return [ActiveRecord::Relation<Mdm::Cred>]
   def creds
     Mdm::Cred.find(
       :all,
@@ -84,30 +177,52 @@ class Mdm::Workspace < ActiveRecord::Base
     )
   end
 
+  # Returns default {Mdm::Workspace}.
+  #
+  # @return [Mdm::Workspace]
   def self.default
     where(name: DEFAULT).first_or_create
   end
 
+  # Whether this is the {default} workspace.
+  #
+  # @return [true] if this is the {default} workspace.
+  # @return [false] if this is not the {default} workspace.
   def default?
     name == DEFAULT
   end
 
+  # @deprecated Use `workspace.credential_cores.each` when `Metasploit::Credential::Engine` is installed to enumerate
+  #   `Metasploit::Credential::Core`s.  Use `service.logins.each` when `Metasploit::Credential::Engine` is installed to
+  #   enumerate `Metasploit::Credential::Login`s.
   #
-  # This method iterates the creds table calling the supplied block with the
-  # cred instance of each entry.
+  # Enumerates each element of {#creds}.
   #
+  # @yield [cred]
+  # @yieldparam cred [Mdm::Cred] Cred associated with {#hosts a host} or {#services a service} in this workspace.
+  # @yieldreturn [void]
+  # @return [void]
   def each_cred(&block)
     creds.each do |cred|
       block.call(cred)
     end
   end
 
+  # Enumerates each element of {#host_tags}.
+  #
+  # @yield [tag]
+  # @yieldparam tag [Mdm::Tag] a tag on {#hosts}.
+  # @yieldreturn [void]
+  # @return [void]
   def each_host_tag(&block)
     host_tags.each do |host_tag|
       block.call(host_tag)
     end
   end
 
+  # Tags on {#hosts}.
+  #
+  # @return [ActiveRecord::Relation<Mdm::Tag>]
   def host_tags
     Mdm::Tag.find(
       :all,
@@ -116,6 +231,9 @@ class Mdm::Workspace < ActiveRecord::Base
     )
   end
 
+  # Web forms found on {#web_sites}.
+  #
+  # @return [ActiveRecord::Relation<Mdm::WebForm>]
   def web_forms
     query = <<-EOQ
           SELECT DISTINCT web_forms.*
@@ -128,6 +246,10 @@ class Mdm::Workspace < ActiveRecord::Base
     Mdm::WebForm.find_by_sql(query)
   end
 
+
+  # Web pages  found on {#web_sites}.
+  #
+  # @return [ActiveRecord::Relation<Mdm::WebPage>]
   def web_pages
     query = <<-EOQ
           SELECT DISTINCT web_pages.*
@@ -140,6 +262,9 @@ class Mdm::Workspace < ActiveRecord::Base
     Mdm::WebPage.find_by_sql(query)
   end
 
+  # Web sites running on {#services}.
+  #
+  # @return [ActiveRecord::Relation<Mdm::WebSite>]
   def web_sites
     query = <<-EOQ
           SELECT DISTINCT web_sites.*
@@ -151,6 +276,9 @@ class Mdm::Workspace < ActiveRecord::Base
     Mdm::WebSite.find_by_sql(query)
   end
 
+  # Web vulnerability found on {#web_sites}.
+  #
+  # @return [ActiveRecord::Relation<Mdm::WebVuln>]
   def web_vulns
     query = <<-EOQ
           SELECT DISTINCT web_vulns.*
@@ -163,6 +291,9 @@ class Mdm::Workspace < ActiveRecord::Base
     Mdm::WebVuln.find_by_sql(query)
   end
 
+  # Web forms on {#web_sites}.
+  #
+  # @return [ActiveRecord::Relation<Mdm::WebForm>]
   def unique_web_forms
     query = <<-EOQ
           SELECT DISTINCT web_forms.web_site_id, web_forms.path, web_forms.method, web_forms.query
@@ -175,6 +306,11 @@ class Mdm::Workspace < ActiveRecord::Base
     Mdm::WebForm.find_by_sql(query)
   end
 
+  # {#unique_web_forms} hosted on `addrs`.
+  #
+  # @param addrs [Array<IPAddr, String>] {Mdm::Host#address} for the {Mdm::Service#host} for the {Mdm::WebSite#service}
+  #   for the {Mdm::WebForm#web_site}.
+  # @return [Array<Mdm::WebForm>]
   def web_unique_forms(addrs=nil)
     forms = unique_web_forms
     if addrs
@@ -185,10 +321,17 @@ class Mdm::Workspace < ActiveRecord::Base
 
   private
 
+  # Strips {#boundary}.
+  #
+  # @return [void]
   def normalize
     boundary.strip! if boundary
   end
 
+  # Returns whether `string` is a valid IP address or IP address range.
+  #
+  # @return [true] if valid IP address or IP address range.
+  # @return [false] otherwise.
   def valid_ip_or_range?(string)
     begin
       Rex::Socket::RangeWalker.new(string)

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

@@ -1,39 +1,29 @@
+# Matches {#matchable} {Mdm::Service} or {Mdm::Vuln} to a {#module_detail Metasploit Module} that can exploit it.
 class MetasploitDataModels::AutomaticExploitation::Match < ActiveRecord::Base
-
   #
   # Associations
   #
 
-  # @!attribute matchable
-  #   A (polymorphic) "matchable" entity like a {Mdm::Vuln} or {Mdm::Service}
+  # A (polymorphic) "matchable" entity like a {Mdm::Vuln} or {Mdm::Service}
   #
-  #   @return [Mdm::Vuln, Mdm::Service]
+  # @return [Mdm::Service, Mdm::Vuln]
   belongs_to :matchable, polymorphic: true
 
-  # @!attribute module_detail
-  #   The MSF module that this match connects to
-  #
-  #   @return [Mdm::Module::Detail]
-  belongs_to :module_detail,
-             class_name: 'Mdm::Module::Detail',
-             foreign_key: :module_fullname,
-             primary_key: :fullname
-
-  # @!attribute match_set
-  #   The {MatchSet} this match is part of
-  #
-  #   @return [MetasploitDataModels::AutomaticExploitation::MatchResult]
+  # The {MatchSet} this match is part of
   has_many :match_results,
-             class_name: 'MetasploitDataModels::AutomaticExploitation::MatchResult',
-             inverse_of: :match
+           class_name: 'MetasploitDataModels::AutomaticExploitation::MatchResult',
+           inverse_of: :match
 
-  # @!attribute match_set
-  #   The {MatchSet} this match is part of
-  #
-  #   @return [MetasploitDataModels::AutomaticExploitation::MatchSet]
+  # The {MatchSet} this match is part of
   belongs_to :match_set,
              class_name: 'MetasploitDataModels::AutomaticExploitation::MatchSet',
              inverse_of: :matches
 
+  # The Metasploit Module that this match connects to
+  belongs_to :module_detail,
+             class_name: 'Mdm::Module::Detail',
+             foreign_key: :module_fullname,
+             primary_key: :fullname
+
   Metasploit::Concern.run(self)
 end