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

data/app/models/mdm/event.rb

@@ -1,17 +1,61 @@
+# Records framework events to the database.
 class Mdm::Event < ActiveRecord::Base
     
   #
   # 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
   #
@@ -23,6 +67,9 @@ class Mdm::Event < ActiveRecord::Base
   # Serializations
   #
 
+  # {#name}-specific information about this event.
+  #
+  # @return [Hash]
   serialize :info, MetasploitDataModels::Base64Serializer.new
 
   #

data/app/models/mdm/exploit_attempt.rb

@@ -1,51 +1,100 @@
+# An attempt to exploit {#host}.
 class Mdm::ExploitAttempt < ActiveRecord::Base
   
   #
   # Associations
   #
 
-  # @!attribute host
-  #   Host that was attempted to be exploited.
+  # Host that was attempted to be exploited.
   #
-  #   @return [Mdm::Host]
+  # @return [Mdm::Host]
   belongs_to :host,
              class_name: 'Mdm::Host',
              counter_cache: :exploit_attempt_count,
              inverse_of: :exploit_attempts
 
-  # @!attribute loot
-  #   Loot gathers from the successful exploit.
+  # Loot gathers from the successful exploit.
   #
-  #   @return [Mdm::Loot, nil]
+  # @return [Mdm::Loot, nil]
   belongs_to :loot,
              class_name: 'Mdm::Loot',
              inverse_of: :exploit_attempt
 
-  # @!attribute service
-  #   The service being exploited on {#host}.
+  # The service being exploited on {#host}.
   #
-  #   @return [Mdm::Service, nil]
+  # @return [Mdm::Service, nil]
   belongs_to :service,
              class_name: 'Mdm::Service',
              inverse_of: :exploit_attempts
 
-  # @!attribute session
-  #   The session that was established when this attempt was successful.
+  # The session that was established when this attempt was successful.
   #
-  #   @return [Mdm::Session]
-  #   @return [nil] if session was not established.
+  # @return [Mdm::Session]
+  # @return [nil] if session was not established.
   belongs_to :session,
              class_name: 'Mdm::Session',
              inverse_of: :exploit_attempt
 
-  # @!attribute vuln
-  #   The vulnerability that was attempted to be exploited.
+  # The vulnerability that was attempted to be exploited.
   #
-  #   @return [Mdm::Vuln, nil]
+  # @return [Mdm::Vuln, nil]
   belongs_to :vuln,
              class_name: 'Mdm::Vuln',
              inverse_of: :exploit_attempts
 
+  #
+  # Attributes
+  #
+
+  # @!attribute attempted_at
+  #   When the attempt was made.
+  #
+  #   @return [DateTime]
+
+  # @!attribute exploited
+  #   Whether the attempt was successful.
+  #
+  #   @return [true] attempt was successful.
+  #   @return [false] attempt was not successful.
+
+  # @!attribute fail_detail
+  #   A more verbose reason (compared to {#fail_reason} for the failure.
+  #
+  #   @return [String, nil]
+
+  # @!attribute fail_reason
+  #   Summary of why the attempt failed if {#exploited} is `false`.  For more details see {#fail_detail}.
+  #
+  #   @return [String, nil]
+
+  # @!attribute host_id
+  #   Foreign key to look up {#host}.
+  #
+  #   @return [Integer]
+
+  # @!attribute  module
+  #   The full name of the exploit module that made the attempt.
+  #
+  #   @return [String]
+  #   @todo Remove deprecated Mdm::Exploit#module (MSP-9281)
+
+  # @!attribute port
+  #   The port on {#host} which the exploit was attempted.
+  #
+  #   @return [Integer]
+  #   @todo Mdm::ExploitAttempt#port and Mdm::ExploitAttempt#proto are obsolete and should be removed (MSP-9284)
+
+  # @!attribute proto
+  #   The protocol name used on {#port}.
+  #
+  #   @return [String]
+  #   @todo Mdm::ExploitAttempt#port and Mdm::ExploitAttempt#proto are obsolete and should be removed (MSP-9284)
+
+  # @!attribute username
+  #   Name of user that made the attempt.  May be an {Mdm::User#name} or a system username.
+  #
+  #   @return [String]
+
   #
   # Validations
   #

data/app/models/mdm/exploited_host.rb

@@ -1,15 +1,42 @@
+# @deprecated use {Mdm::ExploitAttempt} instead.
+#
+# When a {#host} or {#service} on a {#host} is exploited.
 class Mdm::ExploitedHost < ActiveRecord::Base
   #
   # Associations
   #
 
+  # The host that was exploited.
   belongs_to :host,
              class_name: 'Mdm::Host',
              inverse_of: :exploited_hosts
 
+  # The service on {#host} that was exploited.
   belongs_to :service,
              class_name: 'Mdm::Service',
              inverse_of: :exploited_hosts
 
+  #
+  # Attributes
+  #
+
+  # @!attribute name
+  #   Name of exploit.
+  #
+  #   @return [String]
+
+  # @!attribute payload
+  #   {Mdm::Module::Class#full_name Full name of the payload module} used to exploit the {#host} or {#service} on
+  #   {#host}.
+  #
+  #   @return [String]
+
+  # @!attribute session_uuid
+  #   UUID of local session.
+  #
+  #   @return [String]
+  #   @deprecated Sessions no longer have UUIDs.  They have {Mdm::Session#local_id} that reflects the in-memory
+  #     Msf::Session ID and an in-database {Mdm::Session#id}.
+
   Metasploit::Concern.run(self)
 end

data/app/models/mdm/host_detail.rb

@@ -1,13 +1,57 @@
+# Details supplied by Nexpose about a {Mdm::Host host}.
 class Mdm::HostDetail < ActiveRecord::Base
   #
   # Associations
   #
 
+  # Host that this detail is about.
   belongs_to :host,
              class_name: 'Mdm::Host',
              counter_cache: :host_detail_count,
              inverse_of: :host_details
 
+  #
+  # Attributes
+  #
+
+  # @!attribute host_id
+  #   The foreign key used to look up {#host}.
+  #
+  #   @return [Integer]
+
+  # @!attribute nx_console_id
+  #   The ID of the Nexpose console.
+  #
+  #   @return [Integer]
+
+  # @!attribute nx_device_id
+  #   The ID of the Device in Nexpose.
+  #
+  #   @return [Integer]
+
+  # @!attribute nx_risk_score
+  #   Risk score assigned by Nexpose.  Useful to ordering hosts to determine which host to target first in metasploit.
+  #
+  #   @return [Float]
+
+  # @!attribute nx_scan_template
+  #   The template used by Nexpose to perform the scan on the {#nx_site_name site} on {#host}.
+  #
+  #   @return [String]
+
+  # @!attribute nx_site_importance
+  #   The importance of scanning the {#nx_site_name site} running on {#host} according to Nexpose.
+  #
+  #   @return [String]
+
+  # @!attribute nx_site_name
+  #   Name of site running on {#host} according to Nexpose.
+  #
+  #   @return [String]
+
+  # @!attribute src
+  #    @return [String]
+
   #
   # Validations
   #

data/app/models/mdm/host_tag.rb

@@ -1,3 +1,4 @@
+# Join model between {Mdm::Host} and {Mdm::Tag}.
 class Mdm::HostTag < ActiveRecord::Base
   self.table_name = "hosts_tags"
 
@@ -5,20 +6,16 @@ class Mdm::HostTag < ActiveRecord::Base
   # Associations
   #
 
-  # @!attribute host
-  #   Host with {#tag}.
+  # Host with {#tag}.
   #
-  #   @todo MSP-2723
-  #   @return [Mdm::Host]
+  # @todo MSP-2723
   belongs_to :host,
              class_name: 'Mdm::Host',
              inverse_of: :hosts_tags
 
-  # @!attribute tag
-  #   Tag on {#host}.
+  # Tag on {#host}.
   #
-  #   @todo MSP-2723
-  #   @return [Mdm::Tag]
+  # @todo MSP-2723
   belongs_to :tag,
              class_name: 'Mdm::Tag',
              inverse_of: :hosts_tags
@@ -44,6 +41,7 @@ class Mdm::HostTag < ActiveRecord::Base
     tag.destroy_if_orphaned
   end
 
+  # switch back to public for load hooks
   public
 
   Metasploit::Concern.run(self)

data/app/models/mdm/listener.rb

@@ -1,21 +1,73 @@
+# A listener spawned by a {#task} that is waiting for connection on {#address}:{#port}.
 class Mdm::Listener < ActiveRecord::Base
   
   #
   # Associations
   #
 
+  # Task that spawned this listener.
   belongs_to :task,
              class_name: 'Mdm::Task',
              inverse_of: :listeners
 
+  # Workspace which controls this listener.
   belongs_to :workspace,
              class_name: 'Mdm::Workspace',
              inverse_of: :listeners
 
+  #
+  # Attributes
+  #
+
+  # @!attribute address
+  #   The IP address to which the listener is bound.
+  #
+  #   @return [String]
+
+  # @!attribute created_at
+  #   When this listener was created.  Not necessarily when it started listening.
+  #
+  #   @return [DateTime]
+
+  # @!attribute enabled
+  #   Whether listener is listening on {#address}:{#port}.
+  #
+  #   @return [true] listener is listening.
+  #   @return [false] listener is not listening.
+
+  # @!attribute macro
+  #   {Mdm::Macro#name Name of macro} run when a connect is made to the listener.
+  #
+  #   @return [String]
+
+  # @!attribute owner
+  #   The name of the user that setup this listener.
+  #
+  #   @return [String]
+  #   @see Mdm::User#username
+
+  # @!attribute payload
+  #   Reference name of the payload module that is sent when a connection is made to the listener.
+  #
+  #   @return [String]
+
+  # @!attribute port
+  #   Port on {#address} that listener is listening.
+  #
+  #   @return [Integer]
+
+  # @!attribute updated_at
+  #   The last time this listener was updated.
+  #
+  #   @return [DateTime]
+
   #
   # Serializations
   #
 
+  # Options used to spawn this listener.
+  #
+  # @return [Hash]
   serialize :options, MetasploitDataModels::Base64Serializer.new
 
   #

data/app/models/mdm/macro.rb

@@ -1,12 +1,54 @@
+# Macro of {#actions} to run at once.
 class Mdm::Macro < ActiveRecord::Base
   extend MetasploitDataModels::SerializedPrefs
 
+  #
+  # Attributes
+  #
+
+  # @!attribute created_at
+  #   When this macro was created.
+  #
+  #   @return [DateTime]
+
+  # @!attribute description
+  #   Long description of what the macro does.
+  #
+  #   @return [String]
+
+  # @!attribute  name
+  #   The name of this macro.
+  #
+  #   @return [String]
+
+  # @!attribute owner
+  #   {Mdm::User#username Name of user} that owns this macro.
+  #
+  #   @return [String]
+
+  # @!attribute updated_at
+  #   When this macro was last updated.
+  #
+  #   @return [DateTime]
+
   #
   # Serialization
   #
 
+  # Actions run by this macro.
+  #
+  # @return [Array<Hash{Symbol=>Object}>] Array of action hashes.  Each action hash is have key :module with value
+  #   of an {Mdm::Module::Detail#fullname} and and key :options with value of options used to the run the module.
   serialize :actions, MetasploitDataModels::Base64Serializer.new
+
+  # Preference for this macro, shared across all actions.
+  #
+  # @return [Hash]
   serialize :prefs, MetasploitDataModels::Base64Serializer.new
+
+  # The maximum number of seconds that this macro is allowed to run.
+  #
+  # @return [Integer]
   serialized_prefs_attr_accessor :max_time
 
   #