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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8786462afa4886795f010d8d1932ed02af472907
-  data.tar.gz: 54bb9201b29cf04d859e05094e265761ef80ada4
+  metadata.gz: 56925093d1b65f879700c5e36663b600fcc41535
+  data.tar.gz: aec5a56a97bd5afeb1b5e51502b2b11e0f5ae1f3
 SHA512:
-  metadata.gz: 8dacbe23f336c1bd3b56ca69feea5bcd133aa427e88562f7a23b25b060c8a2f1f5c3ae268b96c8dbd87de6234d7ac33f4cc69bb5a53710e39477e50c90870115
-  data.tar.gz: 19443fc84ba571a7cc3fc0a3da5975ec597060cbd4c345c356012fc6e99a6151e0313d3309ee7bca5c493337428a93862542e4ec2f5e1e72b1e53fb98197dc0e
+  metadata.gz: ba9146272ae101f2f4e15546334d7a50ca0e1a74cb2150376582be992b3b0ec2bf13d01642fdbac98ab88ea9d01eabd18df1769b06bdb841da1623d879452e56
+  data.tar.gz: 2bb46180f0879fb0f222ba384a84be59c48574b62e2aca3b9182e95e1703890b0f15c4a8f324a4a7f2f4bdd38114c7bb004594f026184b244a73c62f005dedaf

data/.rspec

@@ -1,3 +1,3 @@
+--color
 --format documentation
---colour
---drb
+--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/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Next Release
+
+* Enhancements
+* Bug Fixes
+* Deprecations
+* Incompatible Changes

data/CONTRIBUTING.md

@@ -25,19 +25,18 @@ issue tracking software.
 
 ### `PRERELEASE`
 
-1. Update `PRERELEASE` to match the `SUMMARY` in the branch name.  If you branched from `master`, and [version.rb](lib/metasploit_data_models/version.rb) does not have `PRERELEASE` defined, then adding the following lines after `PATCH`: 
+1. Update `PRERELEASE` to match the `SUMMARY` in the branch name.  If you branched from `master`, and [version.rb](lib/metasploit_data_models/version.rb) does not have `PRERELEASE` defined, then adding the following lines after `PATCH`:
 ```
-# The prerelease version, scoped to the {PATCH} version number.
+# The prerelease version, scoped to the {MAJOR}, {MINOR}, and {PATCH} version number.
 PRERELEASE = '<SUMMARY>'
 ```
 2. `rake spec`
 3.  Verify the specs pass, which indicates that `PRERELEASE` was updated correctly.
 4. Commit the change `git commit -a`
 
-
 ### Your changes
 
-Make your changes or however many commits you like, commiting each with `git commit`.
+Make your changes or however many commits you like, committing each with `git commit`.
 
 ### Pre-Pull Request Testing
 
@@ -46,12 +45,12 @@ Make your changes or however many commits you like, commiting each with `git com
 
 ### Push
 
-Push your branch to your fork on gitub: `git push push TYPE/ISSUE/SUMMARY`
+Push your branch to your fork on github: `git push TYPE/ISSUE/SUMMARY`
 
 ### Pull Request
 
 * [Create new Pull Request](https://github.com/rapid7/metasploit_data_models/compare/)
-* Add a Verification Steps comment
+* Add a Verification Steps to the description comment
 
 ```
 # Verification Steps
@@ -62,11 +61,12 @@ Push your branch to your fork on gitub: `git push push TYPE/ISSUE/SUMMARY`
 - [ ] `rake spec`
 - [ ] VERIFY no failures
 ```
+
 You should also include at least one scenario to manually check the changes outside of specs.
 
 * Add a Post-merge Steps comment
 
-The 'Post-merge Steps' are a reminder to the reviewer of the Pull Request of how to update the [`PRERELEASE`](lib/metasploit_data_models/version.rb) so that [version_spec.rb](spec/lib/metasploit_data_models/version_spec.rb) passes on the target branch after the merge.
+The 'Post-merge Steps' are a reminder to the reviewer of the Pull Request of how to update the [`PRERELEASE`](lib/metasploit_data_models/version.rb) so that [version_spec.rb](spec/lib/metasploit_data_models/version.rb_spec.rb) passes on the target branch after the merge.
 
 DESTINATION is the name of the destination branch into which the merge is being made.  SOURCE_SUMMARY is the SUMMARY from TYPE/ISSUE/SUMMARY branch name for the SOURCE branch that is being made.
 
@@ -106,7 +106,7 @@ Perform these steps prior to pushing to DESTINATION or the build will be broke o
 - [ ] Change `PRERELEASE` from `SOURCE_SUMMARY` to `DESTINATION_SUMMARY` to match the branch (DESTINATION) summary (DESTINATION_SUMMARY)
 
 ## Gem build
-- [ ] gem build *.gemspec
+- [ ] gem build metasploit_data_models.gemspec
 - [ ] VERIFY the prerelease suffix has change on the gem.
 
 ## RSpec
@@ -118,47 +118,5 @@ Perform these steps prior to pushing to DESTINATION or the build will be broke o
 - [ ] `git push origin DESTINATION`
 ```
 
-* Add a 'Release Steps' comment
-
-The 'Release Steps' are a reminder to the reviewer of the Pull Request of how to release the gem.
-
-```
-# Release
-
-Complete these steps on DESTINATION
-
-## Version
-
-### Compatible changes
-
-If the change are compatible with the previous branch's API, then increment [`PATCH`](lib/metasploit_data_models/version.rb).
-
-### Incompatible changes
-
-If your changes are incompatible with the previous branch's API, then increment
-[`MINOR`](lib/metasploit_data_models/version.rb) and reset [`PATCH`](lib/metasploit_data_models/version.rb) to `0`.
-
-- [ ] Following the rules for [semantic versioning 2.0](http://semver.org/spec/v2.0.0.html), update
-[`MINOR`](lib/metasploit_data_models/version.rb) and [`PATCH`](lib/metasploit_data_models/version.rb) and commit the changes.
-
-## JRuby
-- [ ] `rvm use jruby@metasploit_data_models`
-- [ ] `rm Gemfile.lock`
-- [ ] `bundle install`
-- [ ] `rake release`
-
-## MRI Ruby
-- [ ] `rvm use ruby-2.1@metasploit_data_models`
-- [ ] `rm Gemfile.lock`
-- [ ] `bundle install`
-- [ ] `rake release`
-```
-
-### Downstream dependencies
-
-When releasing new versions, the following projects may need to be updated:
-
-* [metasploit-credential](https://github.com/rapid7/metasploit-credential)
-* [metasploit-framework](https://github.com/rapid7/metasploit-framework)
-* [metasploit-pro-ui](https://github.com/rapid7/pro/tree/master/ui)
-* [metasploit-pro-engine](https://github.com/rapid7/pro/tree/master/engine)
+To update the [CHANGELOG.md](CHANGELOG.md) with the merged changes or release the merged code see
+[RELEASING.md](RELEASING.md)

data/Gemfile

@@ -4,9 +4,9 @@ source "https://rubygems.org"
 gemspec
 
 group :development do
-  gem 'metasploit-erd', '1.0.0.pre.rails.pre.4.0'
+  gem 'metasploit-erd', '~> 1.0'
   # embed ERDs on index, namespace Module and Class<ActiveRecord::Base> pages
-  gem 'yard-metasploit-erd', '1.0.0.pre.rails.pre.4.0'
+  gem 'yard-metasploit-erd', '~> 1.0'
 end
 
 # used by dummy application
@@ -18,7 +18,7 @@ group :development, :test do
   gem 'factory_girl', '>= 4.1.0'
   # auto-load factories from spec/factories
   gem 'factory_girl_rails'
-  
+
   rails_version_constraint = [
       '>= 4.0.9',
       '< 4.1.0'
@@ -35,11 +35,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/RELEASING.md

@@ -0,0 +1,88 @@
+# Releasing
+
+These steps can be added to the Pull Request description's task list to remind the reviewer of how to release the
+gem.
+
+```
+# Release
+
+Complete these steps on DESTINATION
+
+## [CHANGELOG.md](CHANGELOG.md)
+
+### Terminology
+
+* "Enhancements" are widdening the API, such as by adding new classes or methods.
+* "Bug Fixes" are fixes to the implementation that do not affect the public API.  If the public API is affected then
+  the change should be listed as both a "Bug Fix" and either an "Enhancement" or "Incompatible Change" depending on how
+  the bug was fixed.
+* "Deprecations" are changes to the implementation that cause deprecation warnings to be issued for APIs which will be
+  removed in a future major release.  "Deprecations" are usually accompanied by an Enhancement that creates a new API
+  that is meant to be used in favor of the deprecated API.
+* "Incompatbile Changes" are the removal of classes or methods or new required arguments or setup that shrink the API.
+  It is best practice to make a "Deprecation" for the API prior to its removal.
+
+### Task List
+
+- [ ] Generate the list of changes since the last release: `git log v<LAST_MAJOR>.<LAST_MINOR>.<LAST_PATCH>..HEAD`
+- [ ] For each commit in the release, find the corresponding PR by search for the commit on Github.
+- [ ] For each PR, determine whether it is an Enhancement, Bug Fix, Deprecation, and/or Incompatible Change.  A PR can
+      be in more than one category, in which case it should be listed in each category it belongs, but with a category
+      specific description of the change.
+- [ ] Add an item to each category's list in the following format: `[#<PR>](https://github.com/rapid7/metasploit_data_models/pull/<PR>) <consumer summary> - [@<github_user>](https://github.com/<github_user>)`
+      `consumer_summary` should be a summary of the Enhancement, Bug Fix, Deprecation, or Incompatible Change from a
+      downstream consumer's of the library's perspective.  `github_user` should be Github handle of the author of the
+      PR.
+- [ ] If you added any Deprecations or Incompatible Changes, then adding upgrading information to
+      [UPGRADING.md](UPGRADING.md)
+
+## `VERSION`
+
+The entries in the [CHANGELOG.md](CHANGELOG.md) can be used to help determine how the `VERSION` should be bumped.
+
+### Bug fixes
+
+If the [CHANGELOG.md](CHANGELOG.md) contains only Bug Fixes for the Next Release, then increment
+[`PATCH`](lib/metasploit_data_models/version.rb).
+
+### Compatible API changes
+
+If the [CHANGELOG.md](CHANGELOG.md) contains any Enhancements or Deprecations, then increment
+[`MINOR`](lib/metasploit_data_models/version.rb) and reset [`PATCH`](lib/metasploit_data_models/version.rb) to `0`.
+
+### Incompatible API changes
+
+If the [CHANGELOG.md](CHANGELOG.md) contains any Incompatible Change, then increment [`MAJOR`](lib/metasploit_data_models/version.rb) and
+reset [`MINOR`](lib/metasploit_data_models/version.rb and [`PATCH`](lib/metasploit_data_models/version.rb) to `0`.
+
+## Setup [CHANGELOG.md](CHANGELOG.md) for next release
+
+- [ ] Change `Next Release` section name at the top of [CHANGELOG.md](CHANGELOG.md) to match the current `VERSION`.
+- [ ] Add a new `Next Release` section above the `VERSION`'s section you just renamed:
+<pre>
+# Next Release
+
+* Enhancements
+* Bug Fixes
+* Deprecations
+* Incompatible Changes
+</pre>
+
+## Release to rubygems.org
+
+## jruby
+- [ ] `rvm use jruby@metasploit_data_models`
+- [ ] `rm Gemfile.lock`
+- [ ] `bundle install`
+- [ ] `rake release`
+
+## ruby-2.1
+- [ ] `rvm use ruby-2.1@metasploit_data_models`
+- [ ] `rm Gemfile.lock`
+- [ ] `bundle install`
+- [ ] `rake release`
+```
+
+### Downstream dependencies
+
+There are currently no known downstream dependencies

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/UPGRADING.md

@@ -0,0 +1 @@
+No Deprecations or Incompatible Changes have been introduced at this time

data/app/models/mdm/api_key.rb

@@ -1,14 +1,54 @@
+# 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
   #
   # 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,46 +1,111 @@
+# @deprecated Use metasploit-credential's `Metasploit::Credential::Core`.
+#
+# A credential captured from a {#service}.
 class Mdm::Cred < ActiveRecord::Base
   #
-  # Associations
+  # CONSTANTS
   #
 
-  # @!attribute [rw] servce
-  #   The service this cred is for
+  # 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',
+      'SMB hash' => 'smb_hash',
+      'SSH private key' => 'ssh_key',
+      'SSH public key' => 'ssh_pubkey'
+  }
+
+  #
+  #
+  # 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
-  
+
   #
-  # CONSTANTS
+  # 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
   #
-  KEY_ID_REGEX = /([0-9a-fA-F:]{47})/
-  PTYPES = {
-      'read/write password' => 'password_rw',
-      'read-only password' => 'password_ro',
-      'SMB hash' => 'smb_hash',
-      'SSH private key' => 'ssh_key',
-      'SSH public key' => 'ssh_pubkey'
-  }
 
   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)