Round 2 of documentation

Author: wchen-r7

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

@@ -57,7 +57,7 @@ def login(user,pass)
   # Calls an API.
   #
   # @param [String] meth The RPC API to call.
-  # @param [Array] args The arguments to pass.
+  # @param [Array<string>] 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.

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

@@ -82,7 +82,7 @@ def rpc_logout(token)
   # Returns a list of authentication tokens.
   #
   # @return [Hash] A hash that contains a list of authentication tokens.
-  #  * 'tokens' [Array] An array of tokens.
+  #  * 'tokens' [Array<string>] An array of tokens.
   # @example Here's how you would use this from the client:
   #  # This returns something like:
   #  # {"tokens"=>["TEMPf5I4Ec8cBEKVD8D7xtIbTXWoKapP", "TEMPtcVmMld8w74zo0CYeosM3iXW0nJz"]}

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

@@ -18,7 +18,7 @@ def rpc_list
     res
   end
 
-  # Returns a job.
+  # Stops a job.
   #
   # @param [Fixnum] jid Job ID.
   # @raise [Msf::RPC::Exception] A 500 response indicating an invalid job ID was given.

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

@@ -4,30 +4,86 @@ module Msf
 module RPC
 class RPC_Module < RPC_Base
 
+  # Returns a list of exploit names.
+  #
+  # @return [Hash] A list of exploit names.
+  #  * 'modules' [Array] Exploit names, for example: ['windows/wins/ms04_045_wins']
+  # @example Here's how you would use this from the client:
+  #  rpc.call('module.exploits')
   def rpc_exploits
     { "modules" => self.framework.exploits.keys }
   end
 
+
+  # Returns a list of auxiliary module names.
+  #
+  # @return [Hash] A list of auxiliary module names.
+  #  * 'modules' [Array] Auxiliary module names, for example: ['vsploit/pii/web_pii']
+  # @example Here's how you would use this from the client:
+  #  rpc.call('module.auxiliary')
   def rpc_auxiliary
     { "modules" => self.framework.auxiliary.keys }
   end
 
+
+  # Returns a list of payload module names.
+  #
+  # @return [Hash] A list of payload module names.
+  #  * 'modules' [Array] 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')
   def rpc_payloads
     { "modules" => self.framework.payloads.keys }
   end
 
+
+  # Returns a list of encoder module names.
+  #
+  # @return [Hash] A list of encoder module names.
+  #  * 'modules' [Array] Encoder module names, for example: ['x86/unicode_upper']
+  # @example Here's how you would use this from the client:
+  #  rpc.call('module.encoders')
   def rpc_encoders
     { "modules" => self.framework.encoders.keys }
   end
 
+
+  # Returns a list of NOP module names.
+  #
+  # @return [Hash] A list of NOP module names.
+  #  * 'modules' [Array] NOP module names, for example: ['x86/single_byte']
+  # @example Here's how you would use this from the client:
+  #  rpc.call('module.nops')
   def rpc_nops
     { "modules" => self.framework.nops.keys }
   end
 
+
+  # Returns a list of post module names.
+  #
+  # @return [Hash] A list of post module names.
+  #  * 'modules' [Array] Post module names, for example: ['windows/wlan/wlan_profile']
+  # @example Here's how you would use this from the client:
+  #  rpc.call('module.post')
   def rpc_post
     { "modules" => self.framework.post.keys }
   end
 
+
+  # Returns the metadata of the module.
+  #
+  # @param [String] mtype Module type. Supported types include (case-sensitive):
+  #                       * exploit
+  #                       * auxiliary
+  #                       * post
+  #                       * nop
+  #                       * 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.
+  # @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')
   def rpc_info(mtype, mname)
     m = _find_module(mtype,mname)
     res = {}
@@ -74,6 +130,14 @@ def rpc_info(mtype, mname)
   end
 
 
+  # Returns the compatible payloads for a specific exploit.
+  #
+  # @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.
+  #  * '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')
   def rpc_compatible_payloads(mname)
     m   = _find_module('exploit',mname)
     res = {}
@@ -85,6 +149,15 @@ def rpc_compatible_payloads(mname)
     res
   end
 
+
+  # Returns the compatible sessions for a specific post module.
+  #
+  # @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.
+  #  * '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')
   def rpc_compatible_sessions(mname)
     m   = _find_module('post',mname)
     res = {}
@@ -93,6 +166,17 @@ def rpc_compatible_sessions(mname)
     res
   end
 
+
+  # Returns the compatible target-specific payloads for an exploit.
+  #
+  # @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.
+  #  * '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)
+  #  rpc.call('module.target_compatible_payloads', 'windows/smb/ms08_067_netapi', 1)
   def rpc_target_compatible_payloads(mname, target)
     m   = _find_module('exploit',mname)
     res = {}
@@ -105,6 +189,21 @@ def rpc_target_compatible_payloads(mname, target)
     res
   end
 
+
+  # Returns the module's datastore options.
+  #
+  # @param [String] mtype Module type. Supported types include (case-sensitive):
+  #                       * exploit
+  #                       * auxiliary
+  #                       * post
+  #                       * nop
+  #                       * payload
+  # @param [String] mname Module name. For example: 'windows/wlan/wlan_profile'.
+  # @raise [Msf::RPC::Exception] Module not found (either wrong type or name).
+  # @return [Hash] The module's datastore options. This will actually give you each option's
+  #                data type, requirement state, basic/advanced type, description, default value, etc.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('module.options', 'exploit', 'windows/smb/ms08_067_netapi')
   def rpc_options(mtype, mname)
     m = _find_module(mtype,mname)
     res = {}
@@ -131,6 +230,24 @@ def rpc_options(mtype, mname)
     res
   end
 
+
+  # Executes a module.
+  #
+  # @param [String] mtype Module type. Supported types include (case-sensitive):
+  #                       * exploit
+  #                       * auxiliary
+  #                       * post
+  #                       * payload
+  # @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]
+  #  * 'job_id' [Fixnum] Job ID.
+  #  * 'uuid' [String] UUID.
+  # @example Here's how you would use this from the client:
+  #  # Starts a windows/meterpreter/reverse_tcp on port 6669
+  #  opts = {'LHOST' => '0.0.0.0', 'LPORT'=>6669, 'PAYLOAD'=>'windows/meterpreter/reverse_tcp'}
+  #  rpc.call('module.execute', 'exploit', 'multi/handler', opts)
   def rpc_execute(mtype, mname, opts)
     mod = _find_module(mtype,mname)
     case mtype
@@ -146,11 +263,43 @@ def rpc_execute(mtype, mname, opts)
 
   end
 
+
+  # Returns a list of encoding formats.
+  #
+  # @return [Array] Encoding foramts.
+  # @example Here's how you would use this from the client:
+  #  rpc.call('module.encode_formats')
   def rpc_encode_formats
     # Supported formats
     Msf::Simple::Buffer.transform_formats + Msf::Util::EXE.to_executable_fmt_formats
   end
 
+
+  # Encoders data with an encoder.
+  #
+  # @param [String] data Data to encode.
+  # @param [encoder] encoder Encoder module name. For example: 'x86/single_byte'.
+  # @param [Hash] options Encoding options, such as:
+  #  * 'format' [String] Encoding format.
+  #  * 'badchars' [String] Bad characters.
+  #  * 'platform' [String] Platform.
+  #  * 'arch' [String] Architecture.
+  #  * 'ecount' [Fixnum] Number of times to encode.
+  #  * 'inject' [TrueClass] To enable injection.
+  #  * 'template' [String] The template file (an executable).
+  #  * 'template_path' [String] Template path.
+  #  * 'addshellcode' [String] Custom shellcode.
+  # @raise [Msf::RPC::Exception] Invalid format (Error 500).
+  # @raise [Msf::RPC::Exception] Failure to encode (Error 500).
+  # @return The encoded data
+  #  * '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:
+  #  # unsigned char buf[] =
+  #  # "\xba\x9e\xb5\x91\x66\xdb\xd2\xd9\x74\x24\xf4\x5f\x29\xc9\xb1"
+  #  # "\x01\x31\x57\x15\x03\x57\x15\x83\xc7\x04\xe2\x6b\xf4\xd0\x27";
+  #  result = rpc.call('module.encode', 'AAAA', 'x86/shikata_ga_nai', {'format'=>'c'})
+  #  puts result['encoded']
   def rpc_encode(data, encoder, options)
     # Load supported formats
     supported_formats = Msf::Simple::Buffer.transform_formats + Msf::Util::EXE.to_executable_fmt_formats