First round of RPC API documentation

Resolve rapid7#5209

Author: wchen-r7

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

@@ -12,9 +12,18 @@ module RPC
 
 class Client
 
-  attr_accessor :token, :info
+  # @return [String] A login token.
+  attr_accessor :token
 
+  # @return [Hash] Login information.
+  attr_accessor :info
 
+
+  # Initializes the RPC client to connect to: https://127.0.0.1:3790 (TLS1)
+  #
+  # @param [Hash] info Information needed for the initialization.
+  # @option info [String] :token A token used by the client.
+  # @return [void]
   def initialize(info={})
     self.info = {
       :host => '127.0.0.1',
@@ -29,6 +38,12 @@ def initialize(info={})
   end
 
 
+  # Logs in by calling the 'auth.login' API.
+  #
+  # @param [String] user Username.
+  # @param [String] pass Password.
+  # @raise RuntimeError Indicating a failed authentication.
+  # @return [TrueClass] Indicating a successful login.
   def login(user,pass)
     res = self.call("auth.login", user, pass)
     unless (res && res['result'] == "success")
@@ -38,8 +53,20 @@ def login(user,pass)
     true
   end
 
-  # Prepend the authentication token as the first parameter
-  # of every call except auth.login. Requires the
+
+  # Calls an API.
+  #
+  # @param [String] meth The RPC API to call.
+  # @param [Array] args The arguments to pass.
+  # @raise [RuntimeError] Something is wrong while calling the remote API, including:
+  #                       * 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.
+  # @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"}
+  #  rpc.call('core.version')
   def call(meth, *args)
     unless meth == "auth.login"
       unless self.token
@@ -84,6 +111,10 @@ def call(meth, *args)
     end
   end
 
+
+  # Closes the client.
+  #
+  # @return [void]
   def close
     if @cli && @cli.conn?
       @cli.close

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

@@ -8,6 +8,11 @@ module RPC
 class Exception < RuntimeError
   attr_accessor :code, :message
 
+  # Initializes Exception.
+  #
+  # @param [Fixnum] code An error code.
+  # @param [String] message An error message.
+  # @return [void]
   def initialize(code, message)
     self.code    = code
     self.message = message
@@ -18,6 +23,13 @@ def initialize(code, message)
 class ServerException < RuntimeError
   attr_accessor :code, :error_message, :error_class, :error_backtrace
 
+  # Initializes ServerException.
+  #
+  # @param [Fixnum] code An error code.
+  # @param [String] error_message An error message.
+  # @param [Exception] error_class An error class.
+  # @param [Array] error_backtrace A backtrace of the error.
+  # @return [void]
   def initialize(code, error_message, error_class, error_backtrace)
     self.code          = code
     self.error_message = error_message

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

@@ -11,8 +11,20 @@ class RPC_Auth < RPC_Base
 rescue ::LoadError
 end
 
+  # Handles client authentication.
+  #
+  # @param [String] user The username.
+  # @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.
+  #  * 'result' [String] A successful message: 'success'.
+  #  * 'token' [String] A token for the authentication.
+  # @example Here's how you would use this from the client:
+  #  # This returns something like the following:
+  #  # {"result"=>"success", "token"=>"TEMPyp1N40NK8GM0Tx7A87E6Neak2tVJ"}
+  #  rpc.call('auth.login_noauth', 'username', 'password')
   def rpc_login_noauth(user,pass)
-
     if not (user.kind_of?(::String) and pass.kind_of?(::String))
       error(401, "Login Failed")
     end
@@ -42,6 +54,19 @@ def rpc_login_noauth(user,pass)
     { "result" => "success", "token" => token }
   end
 
+
+  # Handles client deauthentication.
+  #
+  # @param [String] token The user's token to log off.
+  # @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.
+  #  * 'result' [String] The successful message: 'success'
+  # @example Here's how you would use this from the client:
+  #  # This returns something like:
+  #  # {"result"=>"success"}
+  #  rpc.call('auth.logout', 'TEMPyp1N40NK8GM0Tx7A87E6Neak2tVJ')
   def rpc_logout(token)
     found = self.service.tokens[token]
     error("500", "Invalid Authentication Token") if not found
@@ -53,6 +78,15 @@ def rpc_logout(token)
     { "result" => "success" }
   end
 
+
+  # Returns a list of authentication tokens.
+  #
+  # @return [Hash] A hash that contains a list of authentication tokens.
+  #  * 'tokens' [Array] An array of tokens.
+  # @example Here's how you would use this from the client:
+  #  # This returns something like:
+  #  # {"tokens"=>["TEMPf5I4Ec8cBEKVD8D7xtIbTXWoKapP", "TEMPtcVmMld8w74zo0CYeosM3iXW0nJz"]}
+  #  rpc.call('auth.token_list')
   def rpc_token_list
     res = self.service.tokens.keys
     begin
@@ -66,6 +100,14 @@ def rpc_token_list
     { "tokens" => res }
   end
 
+
+  # Adds a new token to the database.
+  #
+  # @param [String] token A unique token.
+  # @return [Hash] A hash indicating the action was successful.
+  #  * 'result' [String] The successful message: 'success'
+  # @example Here's how you would use this from the client:
+  #  rpc.call('auth.token_add', 'UNIQUE_TOKEN')
   def rpc_token_add(token)
     db = false
     begin
@@ -85,6 +127,14 @@ def rpc_token_add(token)
     { "result" => "success" }
   end
 
+
+  # Generates a unique token, and automatically saved to the database.
+  #
+  # @return [Hash] A hash indicating the action was successful, also the new token.
+  #  * 'result' [String] The successful message: 'success'
+  #  * 'token' [String] A new token.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('auth.token_generate')
   def rpc_token_generate
     token = Rex::Text.rand_text_alphanumeric(32)
     db = false
@@ -106,6 +156,14 @@ def rpc_token_generate
     { "result" => "success", "token" => token }
   end
 
+
+  # Removes a token from the database.
+  #
+  # @param [String] token The token to delete.
+  # @return [Hash] A hash indicating the action was successful.
+  #  * 'result' [String] The successful message: 'success'
+  # @example Here's how you would use this from the client:
+  #  rpc.call('auth.token_remove', 'TEMPtcVmMld8w74zo0CYeosM3iXW0nJz')
   def rpc_token_remove(token)
     db = false
     begin

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

@@ -5,13 +5,22 @@ module RPC
 class RPC_Base
   attr_accessor :framework, :service, :tokens, :users
 
+  # Initializes framework, service, tokens, and users
+  #
+  # return [void]
   def initialize(service)
     self.service   = service
     self.framework = service.framework
     self.tokens    = service.tokens
     self.users     = service.users
   end
 
+  # Raises an Msf::RPC Exception.
+  #
+  # @param [Fixnum] code The error code to raise.
+  # @param [String] message The error message.
+  # @raise [Msf::RPC::Exception]
+  # @return [void]
   def error(code, message)
     raise Msf::RPC::Exception.new(code, message)
   end

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

@@ -7,11 +7,24 @@ module Msf
 module RPC
 class RPC_Console < RPC_Base
 
+  # Initializes the RPC console
+  #
+  # @return [Msf::Ui::Web::Driver]
   def initialize(*args)
     super
     @console_driver = Msf::Ui::Web::Driver.new(:framework => framework)
   end
 
+  # Creates a new framework console.
+  #
+  # @param [Hash] opts (Optional) See Msf::Ui::Web::Driver#create_console
+  # @return [Hash] Information about the new console, such as:
+  #  * 'id' [Fixnum] The console's ID.
+  #  * 'prompt' [String] The framework prompt (example: 'msf > ')
+  #  * 'busy' [TrueClass] The console's busy state, or
+  #  * 'busy' [FalseClass] The console's busy state.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('console.create')
   def rpc_create(opts={})
     cid = @console_driver.create_console(opts)
     {
@@ -21,6 +34,17 @@ def rpc_create(opts={})
     }
   end
 
+
+  # Returns a list of framework consoles.
+  #
+  # @return [Hash] Console information.
+  #  * 'consoles' [Array] consoles, each element is another hash that includes:
+  #    * 'id' [Fixnum] The console's ID
+  #    * 'prompt' [String] The framework prompt (example: 'msf > ')
+  #    * 'busy' [TrueClass] The console's busy state, or
+  #    * 'busy' [FalseClass] The console's busy state.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('console.list')
   def rpc_list
     ret = []
     @console_driver.consoles.each_key do |cid|
@@ -33,13 +57,36 @@ def rpc_list
     {'consoles' => ret}
   end
 
+
+  # Deletes a framework console.
+  #
+  # @param [Fixnum] cid Framework console ID.
+  # @return [Hash] A result indicating whether the action was successful or not.
+  #  * '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)
     cid = cid.to_s
     return { 'result' => 'failure' } if not @console_driver.consoles[cid]
     res = @console_driver.destroy_console(cid)
     { 'result' => res ? 'success' : 'failure' }
   end
 
+
+  # Returns the framework console output.
+  #
+  # @param [Fixnum] cid Framework console ID.
+  # @return [Hash] There are two different hashes you might get:
+  #
+  #  If the console ID is invalid, you will get a hash like the following:
+  #  * 'result' [String] A value that says 'failure'.
+  #  If the console ID is valid, you will get a hash like the following:
+  #  * 'data' [String] The output the framework console produces (example: the banner)
+  #  * 'prompt' [String] The framework prompt (example: 'msf > ')
+  #  * 'busy' [TrueClass] The console's busy state, or
+  #  * 'busy' [FalseClass] The console's busy state.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('console.read', 1)
   def rpc_read(cid)
     cid = cid.to_s
     return { 'result' => 'failure' } if not @console_driver.consoles[cid]
@@ -50,25 +97,77 @@ def rpc_read(cid)
     }
   end
 
+
+  # Sends an input (such as a command) to the framework console.
+  #
+  # @param [Fixnum] cid Framework console ID.
+  # @param [String] data User input.
+  # @return [Hash] There are two different hashes you might get:
+  #
+  #  If the console ID is invalid, you will get a hash like the following:
+  #  * 'result' [String] A value that says 'failure'.
+  #  If the console ID is invalid, you will get a hash like the following:
+  #  * 'wrote' [Fixnum] Number of bytes sent.
+  # @note Remember to add a newline (\\r\\n) at the end of input, otherwise
+  #       the console will not do anything. And you will need to use the
+  #       #rpc_read method to retrieve the output again.
+  # @example Here's how you would use this from the client:
+  #  # This will show the current module's options.
+  #  rpc.call('console.write', 4, "show options\r\n")
   def rpc_write(cid, data)
     cid = cid.to_s
     return { 'result' => 'failure' } if not @console_driver.consoles[cid]
     { "wrote" => @console_driver.write_console(cid, data || '') }
   end
 
+
+  # Returns the tab-completed version of your input (such as a module path).
+  #
+  # @param [Fixnum] cid Framework console ID.
+  # @param [String] line Command.
+  # @return [Hash] There are two different hashes you might get:
+  #
+  #  If the console ID is invalid, you will get a hash like the following:
+  #  * 'result' [String] A value that says 'failure'.
+  #  If the console ID is valid, you will get a hash like the following:
+  #  * 'tabs' [String] The tab-completed version of the command.
+  # @example Here's how you would use this from the client:
+  #  # This will return:
+  #  # {"tabs"=>["use exploit/windows/smb/ms08_067_netapi"]}
+  #  rpc.call('console.tabs', 4, "use exploit/windows/smb/ms08_067_")
   def rpc_tabs(cid, line)
     cid = cid.to_s
     return { 'result' => 'failure' } if not @console_driver.consoles[cid]
     { "tabs" => @console_driver.consoles[cid].tab_complete(line) }
   end
 
+
+  # Kills a framework session.
+  #
+  # @param [Fixnum] cid Framework console ID.
+  # @return [Hash] There are two different hashes you might get:
+  #
+  #  If the console ID is invalid, you will get a hash like the following:
+  #  * 'result' [String] A value that says 'failure'.
+  #  If the console ID is valid, you will get the following that indicates the action was successful.
+  #  * 'result' [String] A value that says 'success'.
   def rpc_session_kill(cid)
     cid = cid.to_s
     return { 'result' => 'failure' } if not @console_driver.consoles[cid]
     @console_driver.consoles[cid].session_kill
     { 'result' => 'success' }
   end
 
+
+  # Detaches a framework session.
+  #
+  # @param [Fixnum] cid Framework console ID.
+  # @return [Hash] There are two different hashes you might get:
+  #
+  # If the console ID is invalid, you will get a hash like the following:
+  # * 'result' [String] A value that says 'failure'.
+  # If the console ID is valid, you will get the following that indicates the action was successful.
+  # * 'result' [String] A value that says 'success'.
   def rpc_session_detach(cid)
     cid = cid.to_s
     return { 'result' => 'failure' } if not @console_driver.consoles[cid]