Round 5 of documentation

Author: wchen-r7

lib/msf/core/rpc/v10/client.rb

@@ -64,7 +64,10 @@ def login(user,pass)
   #                       * A missing token (your client needs to authenticate).
   #                       * A unexpected response from the server, such as a timeout or unexpected HTTP code.
   # @raise [Msf::RPC::ServerException] The RPC service returns an error.
-  # @return [Hash] The API response.
+  # @return [Hash] The API response. It contains the following keys:
+  #  * 'version' [String] Framework version.
+  #  * 'ruby' [String] Ruby version.
+  #  * 'api' [String] API version.
   # @example
   #  # This will return something like this:
   #  # {"version"=>"4.11.0-dev", "ruby"=>"2.1.5 x86_64-darwin14.0 2014-11-13", "api"=>"1.0"}

lib/msf/core/rpc/v10/rpc_auth.rb

@@ -17,7 +17,7 @@ class RPC_Auth < RPC_Base
   # @param [String] pass The password.
   # @raise [Msf::RPC::Exception] Something is wrong while authenticating, you can possibly get:
   #                              * 401 Failed authentication.
-  # @return [Hash] A hash indicating a successful login.
+  # @return [Hash] A hash indicating a successful login, it contains the following keys:
   #  * 'result' [String] A successful message: 'success'.
   #  * 'token' [String] A token for the authentication.
   # @example Here's how you would use this from the client:
@@ -61,7 +61,7 @@ def rpc_login_noauth(user,pass)
   # @raise [Msf::RPC::Exception] An error indicating a failed deauthentication, including:
   #                              * 500 Invalid authentication token.
   #                              * 500 Permanent authentication token.
-  # @return [Hash] A hash indiciating the action was successful.
+  # @return [Hash] A hash indiciating the action was successful. It contains the following key:
   #  * 'result' [String] The successful message: 'success'
   # @example Here's how you would use this from the client:
   #  # This returns something like:
@@ -81,7 +81,7 @@ def rpc_logout(token)
 
   # Returns a list of authentication tokens.
   #
-  # @return [Hash] A hash that contains a list of authentication tokens.
+  # @return [Hash] A hash that contains a list of authentication tokens. It contains the following key:
   #  * 'tokens' [Array<string>] An array of tokens.
   # @example Here's how you would use this from the client:
   #  # This returns something like:
@@ -104,7 +104,7 @@ def rpc_token_list
   # Adds a new token to the database.
   #
   # @param [String] token A unique token.
-  # @return [Hash] A hash indicating the action was successful.
+  # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] The successful message: 'success'
   # @example Here's how you would use this from the client:
   #  rpc.call('auth.token_add', 'UNIQUE_TOKEN')
@@ -131,6 +131,7 @@ def rpc_token_add(token)
   # Generates a unique token, and automatically saved to the database.
   #
   # @return [Hash] A hash indicating the action was successful, also the new token.
+  #                It contains the following keys:
   #  * 'result' [String] The successful message: 'success'
   #  * 'token' [String] A new token.
   # @example Here's how you would use this from the client:
@@ -160,7 +161,7 @@ def rpc_token_generate
   # Removes a token from the database.
   #
   # @param [String] token The token to delete.
-  # @return [Hash] A hash indicating the action was successful.
+  # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] The successful message: 'success'
   # @example Here's how you would use this from the client:
   #  rpc.call('auth.token_remove', 'TEMPtcVmMld8w74zo0CYeosM3iXW0nJz')

lib/msf/core/rpc/v10/rpc_console.rb

@@ -18,7 +18,7 @@ def initialize(*args)
   # Creates a new framework console.
   #
   # @param [Hash] opts See Msf::Ui::Web::Driver#create_console
-  # @return [Hash] Information about the new console, such as:
+  # @return [Hash] Information about the new console. It contains the following keys:
   #  * 'id' [Fixnum] The console's ID.
   #  * 'prompt' [String] The framework prompt (example: 'msf > ')
   #  * 'busy' [TrueClass] The console's busy state, or
@@ -38,7 +38,7 @@ def rpc_create(opts={})
   # Returns a list of framework consoles.
   #
   # @return [Hash] Console information.
-  #  * 'consoles' [Array<Hash>] consoles, each element is another hash that includes:
+  #  * 'consoles' [Array<Hash>] consoles, each element is a hash that includes:
   #    * 'id' [Fixnum] The console's ID
   #    * 'prompt' [String] The framework prompt (example: 'msf > ')
   #    * 'busy' [TrueClass] The console's busy state, or
@@ -62,7 +62,8 @@ def rpc_list
   #
   # @param [Fixnum] cid Framework console ID.
   # @return [Hash] A result indicating whether the action was successful or not.
-  #  * 'result' [String] Either 'success' or 'failure'.
+  #                It contains the following key:
+  #                * 'result' [String] Either 'success' or 'failure'.
   # @example Here's how you would use this from the client:
   #  rpc.call('console.destroy', 1)
   def rpc_destroy(cid)

lib/msf/core/rpc/v10/rpc_core.rb

@@ -46,7 +46,7 @@ def rpc_getg(var)
   #
   # @param [String] var The hash key of the global datastore option.
   # @param [String] val The value of the global datastore option.
-  # @return [Hash] A hash indicating the action was successful.
+  # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] The successful message: 'success'
   # @example Here's how you would use this from the client:
   #  rpc.call('core.setg', 'MyGlobal', 'foobar')
@@ -59,7 +59,7 @@ def rpc_setg(var, val)
   # Unsets a global datastore option.
   #
   # @param [String] var The global datastore option.
-  # @return [Hash] A hash indicating the action was successful.
+  # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] The successful message: 'success'
   # @example Here's how you would use this from the client:
   #  rpc.call('core.unsetg', 'MyGlobal')
@@ -71,7 +71,7 @@ def rpc_unsetg(var)
 
   # Saves current framework settings.
   #
-  # @return [Hash] A hash indicating the action was successful.
+  # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] The successful message: 'success'
   # @example Here's how you would use this from the client:
   #  rpc.call('core.save')
@@ -83,7 +83,7 @@ def rpc_save
 
   # Reloads framework modules. This will take some time to complete.
   #
-  # @return [Hash] Module stats:
+  # @return [Hash] Module stats that contain the following keys:
   #  * 'exploits' [Fixnum] The number of exploits reloaded.
   #  * 'auxiliary' [Fixnum] The number of auxiliary modules reloaded.
   #  * 'post' [Fixnum] The number of post modules reloaded.
@@ -101,7 +101,7 @@ def rpc_reload_modules
   # Adds a new module path.
   #
   # @param [String] path The new path to load.
-  # @return [Hash] Module stats:
+  # @return [Hash] Module stats that contain the following keys:
   #  * 'exploits' [Fixnum] The number of exploits loaded.
   #  * 'auxiliary' [Fixnum] The number of auxiliary modules loaded.
   #  * 'post' [Fixnum] The number of post modules loaded.
@@ -118,7 +118,7 @@ def rpc_add_module_path(path)
 
   # Returns the module stats.
   #
-  # @return [Hash] Module stats:
+  # @return [Hash] Module stats that contain the following keys:
   #  * 'exploits' [Fixnum] The number of exploits.
   #  * 'auxiliary' [Fixnum] The number of auxiliary modules.
   #  * 'post' [Fixnum] The number of post modules.
@@ -140,7 +140,12 @@ def rpc_module_stats
 
   # Returns a list of framework threads.
   #
-  # @return [Hash] A collection of threads such as: 'status', 'critical', 'name', 'started'
+  # @return [Hash] A collection of threads. Each key is the thread ID, and the value is another hash
+  #                that contains the following:
+  #                * 'status' [String] Thread status.
+  #                * 'critical' [Boolean] Thread is critical.
+  #                * 'name' [String] Thread name.
+  #                * 'started' [String] Timestamp of when the thread started.
   # @example Here's how you would use this from the cient:
   #  # You will get something like this:
   #  # {0=>{"status"=>"sleep", "critical"=>false, "name"=>"StreamServerListener", "started"=>"2015-04-21 15:25:49 -0500"}}
@@ -163,7 +168,7 @@ def rpc_thread_list
   # Kills a framework thread.
   #
   # @param [Fixnum] tid The thread ID to kill.
-  # @return [Hash] A hash indicating the action was successful.
+  # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] A successful message: 'success'
   # @example Here's how you would use this from the client:
   #  rpc.call('core.thread_kill', 10)

lib/msf/core/rpc/v10/rpc_db.rb

@@ -140,7 +140,7 @@ def rpc_create_cracked_credential(xopts)
   # Creates a credential.
   #
   # @param [Hash] xopts Credential options. (See #create_credential Documentation)
-  # @return [Hash] Credential data.
+  # @return [Hash] Credential data. It contains the following keys:
   #  * :username [String] Username saved.
   #  * :private [String] Password saved.
   #  * :private_type [String] Password type.
@@ -211,6 +211,23 @@ def rpc_invalidate_login(xopts)
     invalidate_login(opts)
   end
 
+
+  # Returns login credentials from a specific workspace.
+  #
+  # @param [Hash] xopts Options.
+  # @option xopts [String] :workspace Name of the workspace.
+  # @return [Hash] Credentials with the following hash key:
+  #  * 'creds' [Array<Hash>] An array of credentials. Each hash in the array will have the following:
+  #                          * 'user' [String] Username.
+  #                          * 'pass' [String] Password.
+  #                          * 'updated_at' [Fixnum] Last updated at.
+  #                          * 'type' [String] Password type.
+  #                          * 'host' [String] Host.
+  #                          * 'port' [Fixnum] Port.
+  #                          * 'proto' [String] Protocol.
+  #                          * 'sname' [String] Service name.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('db.creds', {})
   def rpc_creds(xopts)
     ::ActiveRecord::Base.connection_pool.with_connection {
       ret = {}
@@ -247,6 +264,27 @@ def rpc_creds(xopts)
     }
   end
 
+
+  # Returns information about hosts.
+  #
+  # @param [Hash] xopts Options.
+  # @option xopts [String] :workspace Name of the workspace.
+  # @return [Hash] Host information that starts with the following hash key:
+  #  * 'hosts' [Array<Hash>] An array of hosts. Each hash in the array will have the following:
+  #                          * 'created_at' [Fixnum] Creation date.
+  #                          * 'address' [String] IP address.
+  #                          * 'mac' [String] MAC address.
+  #                          * 'name' [String] Computer name.
+  #                          * 'state' [String] Host's state.
+  #                          * 'os_name' [String] Name of the operating system.
+  #                          * 'os_flavor' [String] OS flavor.
+  #                          * 'os_sp' [String] Service pack.
+  #                          * 'os_lang' [String] OS language.
+  #                          * 'updated_at' [Fixnum] Last updated at.
+  #                          * 'purpose' [String] Host purpose (example: server)
+  #                          * 'info' [String] Additional information about the host.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('db.hosts', {})
   def rpc_hosts(xopts)
   ::ActiveRecord::Base.connection_pool.with_connection {
     opts, wspace = init_db_opts_workspace(xopts)

lib/msf/core/rpc/v10/rpc_job.rb

@@ -5,7 +5,8 @@ class RPC_Job < RPC_Base
 
   # Returns a list of jobs.
   #
-  # @return [Hash] A list of jobs (IDs and names)
+  # @return [Hash] A list of jobs (IDs and names).
+  #                Each key is the job ID, and each value is the job name.
   # @example Here's how you would use this from the client:
   #  # This will return ('0' is the job ID):
   #  # {"0"=>"Exploit: windows/browser/ms14_064_ole_code_execution"
@@ -22,7 +23,7 @@ def rpc_list
   #
   # @param [Fixnum] jid Job ID.
   # @raise [Msf::RPC::Exception] A 500 response indicating an invalid job ID was given.
-  # @return [Hash] A hash indicating the action was successful.
+  # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] A successful message: 'success'
   # @example Here's how you would use this from the client:
   #  rpc.call('job.stop', 0)
@@ -37,7 +38,7 @@ def rpc_stop(jid)
   #
   # @param [Fixnum] jid Job ID.
   # @raise [Msf::RPC::Exception] A 500 response indicating an invalid job ID was given.
-  # @return [Hash] A hash that contains information about the job, such as the following (and maybe more)
+  # @return [Hash] A hash that contains information about the job, such as the following (and maybe more):
   #  * 'jid' [Fixnum] The Job ID.
   #  * 'name' [String] The name of the job.
   #  * 'start_time' [Fixnum] The start time.

lib/msf/core/rpc/v10/rpc_module.rb

@@ -6,7 +6,7 @@ class RPC_Module < RPC_Base
 
   # Returns a list of exploit names.
   #
-  # @return [Hash] A list of exploit names.
+  # @return [Hash] A list of exploit names. It contains the following key:
   #  * 'modules' [Array<string>] Exploit names, for example: ['windows/wins/ms04_045_wins']
   # @example Here's how you would use this from the client:
   #  rpc.call('module.exploits')
@@ -17,7 +17,7 @@ def rpc_exploits
 
   # Returns a list of auxiliary module names.
   #
-  # @return [Hash] A list of auxiliary module names.
+  # @return [Hash] A list of auxiliary module names. It contains the following key:
   #  * 'modules' [Array<string>] Auxiliary module names, for example: ['vsploit/pii/web_pii']
   # @example Here's how you would use this from the client:
   #  rpc.call('module.auxiliary')
@@ -28,7 +28,7 @@ def rpc_auxiliary
 
   # Returns a list of payload module names.
   #
-  # @return [Hash] A list of payload module names.
+  # @return [Hash] A list of payload module names. It contains the following key:
   #  * 'modules' [Array<string>] Payload module names, for example: ['windows/x64/shell_reverse_tcp']
   # @example Here's how you would use this from the client:
   #  rpc.call('module.payloads')
@@ -39,7 +39,7 @@ def rpc_payloads
 
   # Returns a list of encoder module names.
   #
-  # @return [Hash] A list of encoder module names.
+  # @return [Hash] A list of encoder module names. It contains the following key:
   #  * 'modules' [Array<string>] Encoder module names, for example: ['x86/unicode_upper']
   # @example Here's how you would use this from the client:
   #  rpc.call('module.encoders')
@@ -50,7 +50,7 @@ def rpc_encoders
 
   # Returns a list of NOP module names.
   #
-  # @return [Hash] A list of NOP module names.
+  # @return [Hash] A list of NOP module names. It contains the following key:
   #  * 'modules' [Array<string>] NOP module names, for example: ['x86/single_byte']
   # @example Here's how you would use this from the client:
   #  rpc.call('module.nops')
@@ -61,7 +61,7 @@ def rpc_nops
 
   # Returns a list of post module names.
   #
-  # @return [Hash] A list of post module names.
+  # @return [Hash] A list of post module names. It contains the following key:
   #  * 'modules' [Array<string>] Post module names, for example: ['windows/wlan/wlan_profile']
   # @example Here's how you would use this from the client:
   #  rpc.call('module.post')
@@ -80,7 +80,7 @@ def rpc_post
   #                       * payload
   # @param [String] mname Module name. For example: 'windows/wlan/wlan_profile'.
   # @raise [Msf::RPC::Exception] Module not found (either the wrong type or name).
-  # @return [Hash] The module's metadata.
+  # @return [Hash] The module's metadata. The exact keys you will get depends on the module.
   # @example Here's how you would use this from the client:
   #  # This gives us the metadata of ms08_067_netapi
   #  rpc.call('module.info', 'exploit', 'windows/smb/ms08_067_netapi')
@@ -134,7 +134,7 @@ def rpc_info(mtype, mname)
   #
   # @param [String] mname Exploit module name. For example: 'windows/smb/ms08_067_netapi'.
   # @raise [Msf::RPC::Exception] Module not found (wrong name).
-  # @return [Hash] The exploit's compatible payloads.
+  # @return [Hash] The exploit's compatible payloads. It contains the following key:
   #  * 'payloads' [Array<string>] A list of payloads. For example: ['generic/custom']
   # @example Here's how you would use this from the client:
   #  rpc.call('module.compatible_payloads', 'windows/smb/ms08_067_netapi')
@@ -154,7 +154,7 @@ def rpc_compatible_payloads(mname)
   #
   # @param [String] mname Post module name. For example: 'windows/wlan/wlan_profile'.
   # @raise [Msf::RPC::Exception] Module not found (wrong name).
-  # @return [Hash] The post module's compatible sessions.
+  # @return [Hash] The post module's compatible sessions. It contains the following key:
   #  * 'sessions' [Array<Fixnum>] A list of session IDs.
   # @example Here's how you would use this from the client:
   #  rpc.call('module.compatible_sessions', 'windows/wlan/wlan_profile')
@@ -172,7 +172,7 @@ def rpc_compatible_sessions(mname)
   # @param [String] mname Exploit module name. For example: 'windows/smb/ms08_067_netapi'
   # @param [Fixnum] target A specific target the exploit module provides.
   # @raise [Msf::RPC::Exception] Module not found (wrong name).
-  # @return [Hash] The exploit's target-specific payloads.
+  # @return [Hash] The exploit's target-specific payloads. It contains the following key:
   #  * 'payloads' [Array<string>] A list of payloads.
   # @example Here's how you would use this from the client:
   #  # Find all the compatible payloads for target 1 (Windows 2000 Universal)
@@ -241,7 +241,7 @@ def rpc_options(mtype, mname)
   # @param [String] mname Module name. For example: 'windows/smb/ms08_067_netapi'.
   # @param [Hash] opts Options for the module (such as datastore options).
   # @raise [Msf::RPC::Exception] Module not found (either wrong type or name).
-  # @return [Hash]
+  # @return [Hash] It contains the following keys:
   #  * 'job_id' [Fixnum] Job ID.
   #  * 'uuid' [String] UUID.
   # @example Here's how you would use this from the client:
@@ -292,7 +292,7 @@ def rpc_encode_formats
   # @raise [Msf::RPC::Exception] Error could be one of these:
   #                              * 500 Invalid format
   #                              * 500 Failure to encode
-  # @return The encoded data
+  # @return The encoded data. It contains the following key:
   #  * 'encoded' [String] The encoded data in the format you specify.
   # @example Here's how you would use this from the client:
   #  # This will encode 'AAAA' with shikata_ga_nai, and prints the following: