Land #57, ERDs in YARD docs

.yardopts

@@ -1,4 +1,4 @@
 --markup markdown
+--plugin yard-metasploit-erd
 --protected
 {app,lib}/**/*.rb
-db/migrate/*.rb

Gemfile

@@ -3,6 +3,11 @@ source "http://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
   # supplies factories for producing model instance for specs
@@ -12,7 +17,7 @@ group :development, :test do
   gem 'factory_girl_rails'
   # rails is only used for the dummy application in spec/dummy
   # restrict from rails 4.0 as it requires protected_attributes gem and other changes for compatibility
-  # @see https://www.pivotaltracker.com/story/show/52309083
+  # @see MSP-2971
   gem 'rails', '>= 3.2', '< 4.0.0'
   # Used to create fake data
   gem "faker"

app/models/mdm/client.rb

@@ -2,7 +2,9 @@ class Mdm::Client < ActiveRecord::Base
   #
   # Relations
   #
-  belongs_to :host, :class_name => 'Mdm::Host'
+  belongs_to :host,
+             class_name: 'Mdm::Host',
+             inverse_of: :clients
 
   ActiveSupport.run_load_hooks(:mdm_client, self)
 end

app/models/mdm/cred.rb

@@ -19,13 +19,18 @@ class Mdm::Cred < ActiveRecord::Base
   #   The service this cred is for
   #
   #   @return [Mdm::Service]
-  belongs_to :service, :class_name => "Mdm::Service"
+  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>]
-  has_many :task_creds, :dependent => :destroy, :class_name => "Mdm::TaskCred"
+  has_many :task_creds,
+           class_name: 'Mdm::TaskCred',
+           dependent: :destroy,
+           inverse_of: :cred
 
   # @!attribute [rw] tasks
   #   Tasks that touched this service

app/models/mdm/event.rb

@@ -3,8 +3,13 @@ class Mdm::Event < ActiveRecord::Base
   # Relations
   #
 
-  belongs_to :host, :class_name => 'Mdm::Host'
-  belongs_to :workspace, :class_name => 'Mdm::Workspace'
+  belongs_to :host,
+             class_name: 'Mdm::Host',
+             inverse_of: :events
+
+  belongs_to :workspace,
+             class_name: 'Mdm::Workspace',
+             inverse_of: :events
 
   #
   # Scopes

app/models/mdm/exploit_attempt.rb

@@ -1,8 +1,49 @@
 class Mdm::ExploitAttempt < ActiveRecord::Base
   #
-  # Relations
+  # Associations
   #
-  belongs_to :host, :class_name => 'Mdm::Host', :counter_cache => :exploit_attempt_count
+
+  # @!attribute host
+  #   Host that was attempted to be exploited.
+  #
+  #   @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.
+  #
+  #   @return [Mdm::Loot, nil]
+  belongs_to :loot,
+             class_name: 'Mdm::Loot',
+             inverse_of: :exploit_attempt
+
+  # @!attribute service
+  #   The service being exploited on {#host}.
+  #
+  #   @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.
+  #
+  #   @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.
+  #
+  #   @return [Mdm::Vuln, nil]
+  belongs_to :vuln,
+             class_name: 'Mdm::Vuln',
+             inverse_of: :exploit_attempts
 
   #
   # Validations

app/models/mdm/exploited_host.rb

@@ -3,8 +3,13 @@ class Mdm::ExploitedHost < ActiveRecord::Base
   # Relations
   #
 
-  belongs_to :host, :class_name => 'Mdm::Host'
-  belongs_to :service, :class_name => 'Mdm::Service'
+  belongs_to :host,
+             class_name: 'Mdm::Host',
+             inverse_of: :exploited_hosts
+
+  belongs_to :service,
+             class_name: 'Mdm::Service',
+             inverse_of: :exploited_hosts
 
   ActiveSupport.run_load_hooks(:mdm_exploited_host, self)
 end

app/models/mdm/host.rb

@@ -57,83 +57,122 @@ class Mdm::Host < ActiveRecord::Base
   #   Users connected to this host
   #
   #   @return [Array<Mdm::Client>]
-  has_many :clients, class_name: 'Mdm::Client', dependent: :destroy
+  has_many :clients,
+           class_name: 'Mdm::Client',
+           dependent: :destroy,
+           inverse_of: :host
+
+  # @!attribute events
+  #   Events that occurred on this host.
+  #
+  #   @return [ActiveRecord::Relation<Mdm::Event>]
+  has_many :events,
+           class_name: 'Mdm::Event',
+           dependent: :destroy,
+           inverse_of: :host
 
   # @!attribute [rw] task_hosts
   #   Details about what Tasks touched this host
   #
   #   @return [Array<Mdm::TaskHost>]
-  has_many :task_hosts, :dependent => :destroy, :class_name => 'Mdm::TaskHost'
-
-  # @!attribute [rw] tasks
-  #   Tasks that touched this service
-  #
-  #   @return [Array<Mdm::Task>]
-  has_many :tasks, :through => :task_hosts, :class_name => 'Mdm::Task'
+  has_many :task_hosts,
+           class_name: 'Mdm::TaskHost',
+           dependent: :destroy,
+           inverse_of: :host
 
   # @!attribute [rw] exploit_attempts
   #   Attempts to run exploits against this host.
   #
   #   @return [Array<Mdm::ExploitAttempt]
   has_many :exploit_attempts,
-           :class_name => 'Mdm::ExploitAttempt',
-           :dependent => :destroy
-
-  # @!attribute [rw] exploited_hosts
-  #   @todo https://www.pivotaltracker.com/story/show/48993731
-  #   @return [Array<Mdm::ExploitedHost>]
-  has_many :exploited_hosts, :class_name => 'Mdm::ExploitedHost', :dependent => :destroy
+           class_name: 'Mdm::ExploitAttempt',
+           dependent: :destroy,
+           inverse_of: :host
+
+  # @!attribute exploited_hosts
+  #   @todo MSP-2732
+  #   @return [ActiveRecord::Relation<Mdm::ExploitedHost>]
+  has_many :exploited_hosts,
+           class_name: 'Mdm::ExploitedHost',
+           dependent: :destroy,
+           inverse_of: :host
 
   # @!attribute [rw] host_details
   #   @return [Array<Mdm::HostDetail>]
-  has_many :host_details, :class_name => 'Mdm::HostDetail', :dependent => :destroy
+  has_many :host_details,
+           class_name: 'Mdm::HostDetail',
+           dependent: :destroy,
+           inverse_of: :host
 
-  # @!attribute [rw] hosts_tags
+  # @!attribute hosts_tags
   #   A join model between {Mdm::Tag} and {Mdm::Host}.  Use {#tags} to get the actual {Mdm::Tag Mdm::Tags} on this host.
-  #   {#hosts_tags} are cleaned up in a before_destroy: {#cleanup_tags}.
   #
-  #   @todo https://www.pivotaltracker.com/story/show/48923201
-  #   @return [Array<Mdm::HostTag>]
-  has_many :hosts_tags, :class_name => 'Mdm::HostTag'
+  #   @todo MSP-2723
+  #   @return [ActiveRecord::Relation<Mdm::HostTag>]
+  has_many :hosts_tags,
+           class_name: 'Mdm::HostTag',
+           dependent: :destroy,
+           inverse_of: :host
 
-  # @!attribute [rw] loots
+  # @!attribute loots
   #   Loot gathered from the host with {Mdm::Loot#created_at newest loot} first.
   #
-  #   @todo https://www.pivotaltracker.com/story/show/48991525
-  #   @return [Array<Mdm::Loot>]
-  has_many :loots, :class_name => 'Mdm::Loot', :dependent => :destroy, :order => 'loots.created_at DESC'
+  #   @todo MSP-3065
+  #   @return [ActiveRecord::Relation<Mdm::Loot>]
+  has_many :loots,
+           class_name: 'Mdm::Loot',
+           dependent: :destroy,
+           inverse_of: :host,
+           order: 'loots.created_at DESC'
 
   # @!attribute [rw] notes
   #   Notes about the host entered by a user with {Mdm::Note#created_at oldest notes} first.
   #
   #   @return [Array<Mdm::Note>]
-  has_many :notes, :class_name => 'Mdm::Note', :dependent => :delete_all, :order => 'notes.created_at'
+  has_many :notes,
+           class_name: 'Mdm::Note',
+           inverse_of: :host,
+           dependent: :delete_all,
+           order: 'notes.created_at'
 
   # @!attribute [rw] services
   #   The services running on {Mdm::Service#port ports} on the host with services ordered by {Mdm::Service#port port}
   #   and {Mdm::Service#proto protocol}.
   #
   #   @return [Array<Mdm::Service>]
-  has_many :services, :class_name => 'Mdm::Service', :dependent => :destroy, :order => 'services.port, services.proto'
+  has_many :services,
+           class_name: 'Mdm::Service',
+           dependent: :destroy,
+           inverse_of: :host,
+           order: 'services.port, services.proto'
 
   # @!attribute [rw] sessions
   #   Sessions that are open or previously were open on the host ordered by {Mdm::Session#opened_at when the session was
   #   opened}
   #
   #   @return [Array<Mdm::Session]
-  has_many :sessions, :class_name => 'Mdm::Session', :dependent => :destroy, :order => 'sessions.opened_at'
+  has_many :sessions,
+           class_name: 'Mdm::Session',
+           dependent: :destroy,
+           inverse_of: :host,
+           order: 'sessions.opened_at'
 
   # @!attribute [rw] vulns
   #   Vulnerabilities found on the host.
   #
   #   @return [Array<Mdm::Vuln>]
-  has_many :vulns, :class_name => 'Mdm::Vuln', :dependent => :delete_all
+  has_many :vulns,
+           class_name: 'Mdm::Vuln',
+           dependent: :delete_all,
+           inverse_of: :host
 
   # @!attribute [rw] workspace
   #   The workspace in which this host was found.
   #
   #   @return [Mdm::Workspace]
-  belongs_to :workspace, :class_name => 'Mdm::Workspace'
+  belongs_to :workspace,
+             class_name: 'Mdm::Workspace',
+             inverse_of: :hosts
 
   #
   # Through host_tags
@@ -162,7 +201,10 @@ class Mdm::Host < ActiveRecord::Base
   #
   #   @return [Array<Mdm::Note>]
   #   @see #services
-  has_many :service_notes, :class_name => 'Mdm::Note', :through => :services
+  has_many :service_notes,
+           class_name: 'Mdm::Note',
+           source: :notes,
+           through: :services
 
   # @!attribute [r] web_sites
   #   {Mdm::WebSite Web sites} running on top of {#services} on this host.
@@ -171,6 +213,18 @@ class Mdm::Host < ActiveRecord::Base
   #   @see services
   has_many :web_sites, :class_name => 'Mdm::WebSite', :through => :services
 
+  #
+  # through: :task_hosts
+  #
+
+  # @!attribute tasks
+  #   Tasks that touched this service
+  #
+  #   @return [ActiveRecord::Relation<Mdm::Task>]
+  has_many :tasks,
+           class_name: 'Mdm::Task',
+           through: :task_hosts
+
 	#
 	# Through vulns
 	#
@@ -351,12 +405,6 @@ class Mdm::Host < ActiveRecord::Base
   #
   #   @return [Integer]
 
-  #
-  # Callbacks
-  #
-
-  before_destroy :cleanup_tags
-
   #
   # Nested Attributes
   # @note Must be declared after relations being referenced.
@@ -423,18 +471,6 @@ def attribute_locked?(attr)
     n && n.data[:locked]
   end
 
-  # Destroys any {Mdm::Tag Mdm::Tags} that will have no {Mdm::Tag#hosts} left after this host is deleted.
-  #
-  # @return [void]
-  def cleanup_tags
-    # No need to keep tags with no hosts
-    tags.each do |tag|
-      tag.destroy if tag.hosts == [self]
-    end
-    # Clean up association table records
-    Mdm::HostTag.delete_all("host_id = #{self.id}")
-  end
-
   # This is replicated by the IpAddressValidator class. Had to put it here as well to avoid
   # SQL errors when checking address uniqueness.
   #

app/models/mdm/host_detail.rb

@@ -3,7 +3,10 @@ class Mdm::HostDetail < ActiveRecord::Base
   # Relations
   #
 
-  belongs_to :host, :class_name => 'Mdm::Host', :counter_cache => :host_detail_count
+  belongs_to :host,
+             class_name: 'Mdm::Host',
+             counter_cache: :host_detail_count,
+             inverse_of: :host_details
 
   #
   # Validations